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
usingpip
orconda
: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>
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](https://python-poetry.org/docs/managing-environments/).
-
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 usingpoetry
: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 thetests/
directory. Addpytest
andpytest-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
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](https://github.com/c-w/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>
The process for releasing new versions of your package is described in detail in Chapter 7: Releasing and Versioning of the Python Packages book.
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.
A GitHub Actions workflow file won't be included in your package structure.
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
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.
- Triggered on a "push" or merged "pull request" to the