31  Packaging: Python

Learning Objectives

  1. Be able to distinguish between essential software package elements (required to make a minimal software package) and those that are not essential but act to improve the user and developer experiences.
  2. Define what a namespace is.
  3. Explain the role of the code within the following software package files:
  • Python
    • pyproject.toml
    • __init__.py
    • docs/*
    • .github/workflows/ci-cd.yml
  1. Explain at a high level how the Cookiecutter project template tool works.
  2. Generate well formatted function and package-level documentation for software packages using available tools (e.g., numpy-style dosctrings and Sphinx in Python)

31.1 Essential Python package files

Using the project layout we recommend for this course, here is a Python package structure with only the most essential files.

pkg
├── pyproject.toml
└── src
    └── pkg
        ├── __init__.py
        └── module.py

What do each of these do?

  • pyproject.toml stores all the metadata and install instructions for the package.

  • The presence of the src directory defines the code that will form the installable version of your package (meaning that users only get this code when they install the package, and that developers must install the package before running their tests).

  • __init__.py tells Python that a directory is a package. They can be left empty, or they can also be used to add objects to the package’s namespace, provide documentation, and/or run other initialization code.

  • module.py (this one can be named something else!) contains the functions you would like to share with your package users.