User Guide

This section provides a high-level walk through of building a Python packge using the py-pkgs-cookiecutter template. For a much more detailed example see Python Packages Chapter 3: How to package a Python.

Install cookiecutter using pip or conda:

Pip

pip install cookiecutter

Conda

conda install cookiecutter

Install poetry for your operating system:

OS X / Linux / Bash on Windows

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python -

Windows Powershell

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -

Generate a Python package file and directory structure.
```
cookiecutter https://github.com/py-pkgs/py-pkgs-cookiecutter.git
```
Note: one of the prompts the cookiecutter will ask you is if you want to include GitHub Actions (include_github_actions). This prompt allows to choose whether you want a continuous integration (CI) or continuous integration and continuous deployment (CI/CD) workflow file for use with GitHub Actions. If you choose to add CI or CI/CD please read Continuous integration and continuous deployment.
Create and activate a virtual environment using conda. Read more in Section 3.5.1: Create a virtual environment of the Python Packages book.
```
conda create --name <your-env-name> python=3.9 -y
conda activate <your-env-name>
```
Note

If you don’t create a conda virtual environment, poetry’s will create one for you using venv. You will have to explicitly tell poetry to use this virtual environment when runnings commands by prepending them with poetry run. Read more in the poetry documentation.
Create a repository on GitHub and put your project under local and remote version control (see Section 3.3: Put your package under version control of the Python Packages book for help).
Add Python code to module(s) in the src/ directory. If your project has dependencies, add them using poetry:
```
poetry add <dependency>
```
Install and try out your package in a Python interpreter.
```
poetry install
```
Write tests for your package in module(s) prefixed with test_ in the tests/ directory. Add pytest and pytest-cov as development dependencies and calcualte the coverage of your tests. Read more about testing and code coverage in Section 3.7: Testing your package of the Python Packages book.
```
poetry add --dev pytest pytest-cov
pytest tests/ --cov=<pkg-name>
```
Create documentation for your package. Add the necessary development depencies listed below and then compile and render documentation to HTML. Read more about testing and code coverage in Section 3.8: Package documentation of the Python Packages book.
```
poetry add --dev myst-nb sphinx-autoapi sphinx-rtd-theme
make html --directory docs/
```
Host documentation online with Read the Docs. Read more about hosting on Read the Docs in Section 3.8.5: Hosting documentation online of the Python Packages book. Alternatively, you can host on GitHub Pages using the ghp-import package as follows:
```
poetry add --dev ghp-import
ghp-import -n -p -f docs/_build/html
```
Note

The above command pushes your HTML files to the gh-pages branch of your repo. With the rendered site available at e.g., https://<user-name>.github.io/<repo-name>/. The -n argument includes a .nojekyll file in the branch. -p -f force pushes to the remote. Read more in the ghp-import documentation.
Tag a release of your package using Git and GitHub, or equivalent version control tools. Read more about tagging releases in Section 3.8.5: Tagging a package release with version control of the Python Packages book.
Build sdist and wheel distributions for your package. Read more in Section 3.10: Building and distributing your package of the Python Packages book.
```
poetry build
```

Publish your distributions to TestPyPi and try installing your package.

poetry config repositories.test-pypi https://test.pypi.org/legacy/
poetry publish -r test-pypi
pip install --index-url https://test.pypi.org/simple/ <pkg-name>

Publish your distributions to PyPi. Your package can now be installed by anyone using pip.
```
poetry publish
pip install <pkg-name>
```

Releasing new versions of your package

The process for releasing new versions of your package is described in detail in Chapter 7: Releasing and Versioning of the Python Packages book.

Continuous integration and continuous deployment

One of the prompts the cookiecutter will ask you is if you want to include GitHub Actions (include_github_actions). This prompt allows to choose whether you want a continuous integration (CI) or continuous integration and continuous deployment (CI/CD) workflow file for use with GitHub Actions. The possible responses are described in the following sections. You can read more about CI/CD and these workflow files in Chapter 8: Continuous integration and deployment of the Python Packages book.

No

A GitHub Actions workflow file won’t be included in your package structure.

CI (continuous integration)

A GitHub Actions workflow file for continuous integration will be included in your package structure at .github/workflows/ci.yml. It contains the following features:

Triggered on “push” or “pull request” to the main branch.
Sets up a Ubuntu operating system, checks out your repository, installs Python 3.9, and installs the latest version of poetry.
Installs your package with poetry install
Runs test with pytest tests/
Upload code coverage of tests to Codecov
Builds documentation with sphinx

CI+CD (continuous integration + continuous deployment)

A GitHub Actions workflow file for continuous integration and continuous deployment will be included in your package structure at .github/workflows/ci-cd.yml. It contains the following features:

CI job:
- Same as described above.
CD job:
- Triggered on a “push” or merged “pull request” to the main branch.
- Sets up a Ubuntu operating system, checks out your repository, installs Python 3.9.
- Uses Python Semantic Release (PSR) to automatically bump version numbers based on commit messages. PSR will also update the CHANGELOG, tag a new release of the repository, and build new sdist and wheel distributions ready to upload to PyPI. Read more PSR in Section 8.5.2: Automatically creating a new package version of the Python Packages book.
- Publishes new distributions to TestPyPI. For this to work, you’ll need to log-in to TestPyPI, create an API token, and add the token as a secret called TEST_PYPI_API_TOKEN to your GitHub repository.
- Tests that the new distributions install successfuly from TestPyPI using pip install
- Publishes distributions to PyPI. For this to work, you’ll need to log-in to PyPI, create an API token, and add the token as a secret called PYPI_API_TOKEN to your GitHub repository.