Cookiecutter template for Python projects with a focus on long-term maintainability and a reliable setup.

This is the user documentation for the Cookiecutter template.
If you’re a contributor, see: CONTRIBUTING.md
For license information, see the bottom of this document.

cookiecutter-python-package is an opinionated Cookiecutter template for Python projects with a focus on:

• long-term maintainability of the generated project (think decades, not years);

• reliability through step-by-step instructions, enabling users to build, run, and work on the generated project on diverse platforms;

• using the latest Python language and API features; and

• building runnable programs, not libraries.

The template allows you to specify:

• project title, slug, description and version;

• a name for the first module;

• both an author name and a copyright holder name;

• the author’s email address;

• a project license (Apache 2.0 or proprietary license);

• a Python major/minor version;

• whether to include the fire package, which makes it easier to develop a CLI tool;

• whether to include the jupyter package; and

• whether to include the pandas package.

The Cookiecutter template will give you:

• a README.md file with detailed instructions;

• a LICENSE file;

• the root Python package, located at {{ cookiecutter.python_package_name }};

• the first module, located in the root Python package;

• a global settings file that all modules can import;

• a pyproject.toml file and an initial Poetry lockfile;

• a default linter configuration;

• a pytest script and default configuration;

• a Sphinx setup to generate HTML documentation and a manual page;

• a configuration file for Read the Docs;

• a set of poe tasks for running the module scripts, tests and the linter (for details, run poetry run poe tasks);

• a virtual environment with initial dependencies installed and ready to use;

• a .gitattributes file;

• a .gitignore file;

• an .editorconfig file; and

• settings for Visual Studio Code integration.

To use this Cookiecutter template, you need:

1. The Python version manager pyenv.

2. A system-wide Python installation.

3. Cookiecutter version 2.6.0 or newer.

4. The Python dependency manager poetry.

You need the Python version manager pyenv so you can set up your generated package, and to make sure you can always keep that package up and running, regardless of your system Python.

While pyenv doesn’t support Windows, you can use a drop-in replacement called pyenv-win.

To install pyenv-win on Windows, go to github.com/pyenv-win/pyenv-win and follow one of the installation methods.

To install pyenv on Linux or WSL2, first make sure Python 3 is installed. Then follow the Basic GitHub Checkout method described at github.com/pyenv/pyenv.

To install pyenv on macOS, run:

brew install pyenv

To verify your pyenv is working, run:

pyenv --version

Make sure you have Python 3.8 or higher installed on your system and available in your PATH.

To check, run:

python --version

If that fails, try:

python3 --version

Proceed after you’ve confirmed one of those to work.

To install Cookiecutter, follow Cookiecutter’s installation instructions.

You’ll need poetry to manage the generated Python package.

To install Poetry on Windows, use one of the installation methods described in Poetry’s documentation.

If you’re on Linux or WSL2, use your system package manager to install Poetry.

Alternatively, use one of the installation methods described in Poetry’s documentation.

To install Poetry on macOS, run:

brew install poetry

To verify Poetry is working, run:

poetry --version

To run the template generator, make sure you have a working Cookiecutter installation. Then run:

cookiecutter gh:claui/cookiecutter-python-package

If you use cookiecutter-python-package often, you can add to your .cookiecutterrc an abbreviations section like so:

abbreviations:
    python: https://github.com/claui/cookiecutter-python-package.git

Then, to generate a project, run:

cookiecutter python

Copyright (c) 2021 – 2024 Claudia Pellegrino [email protected]

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. For a copy of the License, see LICENSE.

This project may include additional license files other than the Apache License. Those are just there for the template user’s convenience so they can choose a license for their own content. Those licenses may not apply to this project. The only license that applies to this project is the Apache License.