cookiecutter-hypermodern-python

Cookiecutter template for a Python package based on the Hypermodern Python article series.

✨📚✨ Read the full documentation

Usage

$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python --checkout=2020.10.15

Features

• Packaging and dependency management with Poetry
• Test automation with Nox
• Linting with pre-commit and Flake8
• Continuous integration with GitHub Actions
• Documentation with Sphinx and Read the Docs
• Automated uploads to PyPI and TestPyPI
• Automated release notes with Release Drafter
• Automated dependency updates with Dependabot
• Code formatting with Black and Prettier
• Testing with pytest
• Code coverage with Coverage.py
• Coverage reporting with Codecov
• Command-line interface with Click
• Static type-checking with mypy
• Runtime type-checking with Typeguard
• Security audit with Bandit and Safety
• Check documentation examples with xdoctest
• Generate API documentation with autodoc and napoleon
• Generate command-line reference with sphinx-click

The template supports Python 3.6, 3.7, 3.8, and 3.9.

Quickstart

Requirements

Install Cookiecutter:

$ pipx install cookiecutter

Install Poetry by downloading and running get-poetry.py:

$ python get-poetry.py

Install Nox and nox-poetry:

$ pipx install nox
$ pipx inject nox nox-poetry

pipx is preferred, but you can also install with pip install --user.

It is recommended to set up Python 3.6, 3.7, 3.8, and 3.9 using pyenv.

Creating a project

Generate a Python project:

$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python \
  --checkout="2020.10.15"

Change to the root directory of your new project, and create a Git repository:

$ git init
$ git add .
$ git commit

Running

Run the command-line interface from the source tree:

$ poetry install
$ poetry run <project>

Run an interactive Python session:

$ poetry install
$ poetry run python

Testing

Run the full test suite:

$ nox

List the available Nox sessions:

$ nox --list-sessions

Install the pre-commit hooks:

$ nox -s pre-commit -- install

Continuous Integration

GitHub

1. Sign up at GitHub.
2. Create an empty repository for your project.
3. Follow the instructions to push an existing repository from the command line.

PyPI

1. Sign up at PyPI.
2. Go to the Account Settings on PyPI, generate an API token, and copy it.
3. Go to the repository settings on GitHub, and add a secret named PYPI_TOKEN with the token you just copied.

TestPyPI

1. Sign up at TestPyPI.
2. Go to the Account Settings on TestPyPI, generate an API token, and copy it.
3. Go to the repository settings on GitHub, and add a secret named TEST_PYPI_TOKEN with the token you just copied.

Codecov

1. Sign up at Codecov.
2. Install their GitHub app.

Read the Docs

1. Sign up at Read the Docs.
2. Import your GitHub repository, using the button Import a Project.
3. Install the GitHub webhook, using the button Add integration on the Integrations tab in the Admin section of your project on Read the Docs.

Releasing

Releases are triggered by a version bump on the default branch. It is recommended to do this in a separate pull request:

1. Switch to a branch.
2. Bump the version using poetry version.
3. Commit and push to GitHub.
4. Open a pull request.
5. Merge the pull request.

The Release workflow performs the following automated steps:

• Build and upload the package to PyPI.
• Apply a version tag to the repository.
• Publish a GitHub Release.

Release notes are populated with the titles and authors of merged pull requests. You can group the pull requests into separate sections by applying labels to them, like this:

Pull Request Label	Section in Release Notes
breaking	💥 Breaking Changes
enhancement	🚀 Features
removal	🔥 Removals and Deprecations
bug	🐞 Fixes
performance	🐎 Performance
testing	🚨 Testing
ci	👷 Continuous Integration
documentation	📚 Documentation
refactoring	🔨 Refactoring
style	💄 Style
dependencies	📦 Dependencies

GitHub creates the bug, enhancement, and documentation labels for you. Dependabot creates the dependencies label. Create the remaining labels when you need them, on the Issues tab of your GitHub repository,