Mansueto Cookiecutter PyPackage

An opinionated Cookiecutter template to create a new Python package.

The template doesn't give you a lot of functionality per se, and if you're doing an extremely basic task the template might feel more like a constraint than a help. However, using this project might help you down the line when you want to write tests and distribute your project.

Features

By using this template you get:

• CI/CD: bump2version, Github Actions
• Code Style: black, flake8, isort
• Documentation: Sphinx
• CLI: argparse, Click
• Tests: mypy, pytest, pytest-cov, pytest-mock
• Containerization: Docker

How to Use

So let's say that you want to get started with a new project. The first thing you might want to do is to create a new repository. The repository should be blank as all files will be generated by the cookiecutter template.

After you created your empty repository and you are located within the root of the repository locally, you will need to install cookiecutter:

mkdir myproject
cd myproject
pip install -U cookiecutter

Now you will create the template in the local

$ cookiecutter https://github.com/mansueto-institute/cookiecutter-pypackage
full_name [John Doe]: Manuel Martinez
email [[email protected]]: [email protected]
github_username [johndoe]: manmartgarc
project_name [Python Boilerplate]: Best Python Package
project_slug [best_python_package]:
...

After this is done, you should have the same tree in the current directory as this tree.

A Makefile is included that has the following commands.

Directory Structure

If you create a project called python_boilerplate then the following tree will be generated at the top level of the directory from which you run the cookiecutter CLI:

├── AUTHORS.rst
├── CONTRIBUTING.rst
├── HISTORY.rst
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.md
├── docs
│   ├── Makefile
│   ├── authors.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── history.rst
│   ├── index.rst
│   ├── installation.rst
│   ├── make.bat
│   ├── readme.rst
│   └── usage.rst
├── pyproject.toml
├── requirements.txt
├── setup.cfg
├── src
│   └── python_boilerplate
│       ├── __init__.py
│       ├── cli.py
│       └── python_boilerplate.py
└── tests
    ├── __init__.py
    └── test_python_boilerplate.py
.github
├── ISSUE_TEMPLATE.md
├── PULL_REQUEST_TEMPLATE.md
├── dependabot.yaml
└── workflows
    └── build.yml
.editorconfig
.gitignore

Using the MakeFile

The template will create a Makefile that serves as a utility for executing different actions on the Python project.

Running the following will give you information about the Makefile:

$ make
clean                remove all build, test, coverage and Python artifacts
clean-build          remove build artifacts
clean-pyc            remove Python file artifacts
clean-test           remove test and coverage artifacts
lint                 check style with flake8 and black
test                 runs mypy and pytest
docs                 generate Sphinx HTML documentation, including API docs
servedocs            compile the docs watching for changes
release              package and upload a release
dist                 builds source and wheel package
install-dev          installs the packages dev dependencies
install-docs         installs the docs dependencies
install              install the package with the -e flag

To run the tests, you should have the package installed in your local environment; you can of course use conda or venv or any virtual environment solution you like. We install the package by:

make install

Now we can run the linter, tests, docs, etc.

make lint && make test

There are more things that you can do using the Makefile such as creating docs, building source and wheel distributions and releasing the package to PyPI.