Skip to content

User Guide🔗

This is the user guide for the Hypermodern Python Cookiecutter, a Python template based on the Hypermodern Python article series.

If you're in a hurry, check out the quickstart guide and the tutorials.

Introduction🔗

About this project🔗

The |HPC| is a general-purpose template for Python libraries and applications, released under the MIT license and hosted on GitHub[hypermodern python copier].

The main objective of this project template is to enable current best practices through modern Python tooling. Our goals are to:

  • focus on simplicity and minimalism,
  • promote code quality through automation, and
  • provide reliable and repeatable processes,

all the way from local testing to publishing releases.

Projects are created from the template using Copier, a project scaffolding tool built on top of the Jinja template engine.

The project template is centered around the following tools:

  • Poetry for packaging and dependency management
  • Nox for automation of checks and other development tasks
  • GitHub Actions for continuous integration and delivery

Features🔗

Here is a detailed list of features for this Python template:

|HPC|: FOOO

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

Version policy🔗

The |HPC| uses Calendar Versioning with a YYYY.MM.DD versioning scheme.

The current stable release is 2021.11.26.

Installation🔗

System requirements🔗

You need a recent Windows, Linux, Unix, or Mac system with git_ installed.

Note

When working with this template on Windows, configure your text editor or IDE to use only UNIX-style line endings (line feeds).

The project template contains a .gitattributes file which enables end-of-line normalization for your entire working tree. Additionally, the Prettier code formatter converts line endings to line feeds. Windows-style line endings (CRLF) should therefore never make it into your Git repository.

Nonetheless, configuring your editor for line feeds is recommended to avoid complaints from the pre-commit hook for Prettier.

Getting Python (Windows)🔗

If you're on Windows, download the recommended installer for the latest stable release of Python from the official Python website. Before clicking Install now, enable the option to add Python to your PATH environment variable.

Verify your installation by checking the output of the following commands in a new terminal window::

python -VV
py -VV

Both of these commands should display the latest Python version, 3.10.

For local testing with multiple Python versions, repeat these steps for the latest bugfix releases of Python 3.7+, with the following changes:

  • Do not enable the option to add Python to the PATH environment variable.
  • py -VV and python -VV should still display the version of the latest stable release.
  • py -X.Y -VV (e.g. py -3.7 -VV) should display the exact version you just installed.

Note that binary installers are not provided for security releases.

Getting Python (Mac, Linux, Unix)🔗

If you're on a Mac, Linux, or Unix system, use pyenv for installing and managing Python versions. Please refer to the documentation of this project for detailed installation and usage instructions. (The following instructions assume that your system already has bash and curl installed.)

Install pyenv like this:

$ curl https://pyenv.run | bash

Add the following lines to your ~/.bashrc:

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
   eval "$(pyenv virtualenv-init -)"

Install the Python build dependencies for your platform, using one of the commands listed in the official instructions.

Install the latest point release of every supported Python version. This project template supports Python 3.7, 3.8, 3.9, and 3.10.

$ pyenv install 3.7.12
$ pyenv install 3.8.12
$ pyenv install 3.9.9
$ pyenv install 3.10.0

After creating your project (see :ref:below <Creating a project>), you can make these Python versions accessible in the project directory, using the following command:

$ pyenv local 3.10.0 3.9.9 3.8.12 3.7.12

The first version listed is the one used when you type plain python. Every version can be used by invoking python<major.minor>. For example, use python3.7 to invoke Python 3.7.

Requirements🔗

Note

It is recommended to use pipx* to install Python tools which are not specific to a single project. Please refer to the official documentation for detailed installation and usage instructions. If you decide to skip pipx installation, use pip install with the --user option instead.

You need four tools to use this template:

  • Copier to create projects from the template,
  • Poetry to manage packaging and dependencies
  • Nox to automate checks and other tasks
  • nox-poetry for using Poetry in Nox sessions

Install Copier using pipx:

$ pipx install copier

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

$ python install-poetry.py

Install Nox and nox-poetry using pipx:

$ pipx install nox
$ pipx inject nox nox-poetry

Remember to upgrade these tools regularly:

$ pipx upgrade copier
$ pipx upgrade --include-injected nox
$ poetry self update

Project creation🔗

Creating a project🔗

Create a project from this template by pointing Cookiecutter to its GitHub repository <Hypermodern Python Cookiecutter_>. Use the --checkout option with the current stable release <2021.11.26_>:

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

Cookiecutter downloads the template, and asks you a series of questions about project variables, for example, how you wish your project to be named. When you have answered these questions, your project is generated in the current directory, using a subdirectory with the same name as your project.

Here is a complete list of the project variables defined by this template:

Back to top