Python Package Project Template

This Cookiecutter template generates a Python project structured for package development. It includes a suite of tools and workflows for high-quality software development and easy package distribution.

Features

• Python Package Setup: Scaffold for creating a Python package.
• Virtual environment: Convenient creation/activation with a single command. Optionally use blazingly fast uv.
• Aux scripts: Optionally Python scripts with Invoke or BASH with Makefile.
• GitHub Actions for CI: Automated workflows for Continuous Integration.
• Publishing to PyPI: Workflow for packaging and distributing your project on PyPI.
• Static Analysis: Pre-configured Flake8, Black, and MyPy checks. Use incredibly fast ruff.
• Coverage Reporting: Code coverage analysis with results published to a separate branch, integrated with Coveralls/Codecov.
• Badges in README: Status badges for CI and coverage.
• Pre-commit Hooks: Pre-configured hooks for code formatting and MyPy checks.
• Dependency Management: Using pip-tools with automated updates in pyproject.toml.
• Version Management: Makefile commands for package version management.
• Documentation: Multilanguage documentation with MkDocs Material, published on GitHub Pages.

How to Use This Template

To create a new project from this template, you'll need to have Cookiecutter installed. If you don't have Cookiecutter installed, you can install it with pipx:

pipx install cookiecutter

Once Cookiecutter is installed, generate your project:

cookiecutter gh:andgineer/cookiecutter-python-package

Follow the prompts to enter your project details.

My personal preference is to create empty project first on GitHub and then clone it to my local machine. Then without entering the project directory

cookiecutter gh:andgineer/cookiecutter-python-package --overwrite-if-exists

Of course the project name you enter should be the same as the name of the repository on GitHub.

This way it creates all the boilerplate in the project directory but leave .git/ you just cloned intact. You can then push the boilerplate created by cookiecutter back to the GitHub.

Post-Generation Setup

After generating your project, perform the following steps:

PyPI Credentials

Set up your PyPI credentials as GitHub Secrets for automated package publishing:

• Go to your GitHub repository's Settings.
• Navigate to 'Secrets'.
  • Add the following secrets: PYPI_USERNAME: Your PyPI username. PYPI_PASSWORD: Your PyPI password.

GitHub Pages

Enable GitHub Pages for your project's documentation:

• Go to your GitHub repository's Settings.
• In the 'Pages' section, set the source to the gh-pages branch.

Optional Configurations

• Coveralls Integration: Activate your project on Coveralls.
• Codecove: press Configure on appropriate project on codecov.io. activate the project in the codecov settings. given on the page CODECOV_TOKEN add to GitHub Secrets.

Alternatively you can use Global upload token in settings - it will work for all projects.

How to use generated project

Docs

Doc autogenerated and published on Github Pages from markdown files in docs folder. Also from docstings autogenerated API reference. See link in README.md.

Dependencies

To create virtualenv run . ./activate.sh in the root of the project (note the first "."). You need uv installed for this.

If you change dependencies in requirements.in or requirements.dev.in run make reqs to update requirements.txt, requirements.dev.txt and pyproject.toml. This also will update dependencies in the virtualenv.

Black & mypy

To activate autoformatting and mypy checks run pre-commit install in the root of the project.

Publishing package in pip

To publish the package on PyPi just set git tag with make ver-feature etc, see make help for details. After that the Github action will publish the package on PyPi and add link to the version into Github release.