Cookiecutter template for a Python package.
The boilerplate Python project that aims to create facility for maintaining of the package easily. It considering tools for building, testing and distribution.
This template provides a basic structure for an idiomatic Python package with a convenient Makefile-facility and additional helpers.
There are a couple of tools for building, packaging, documentation and so on, that must be installed.
Main tools are:
- GNU sed (
brew install gnu-sedfor macOS),
- ack (optionally),
- Vagrant (optionally),
- virtualenv at global level.
To check availability of main tools just type
Tools for documenting the package:
- Sphinx package (sphinx-build, sphinx-apidoc),
- MacTeX distribution (optionally; pdflatex CLI tool, fonts, styles – for rendering docs in PDF format).
To check availability of documentation tools type
Makefile Targets and Features
Compile Pip requirements from
Auto creation of virtual environment using
Installing package into a virtual environment in so-called "development mode" and removing it later:
# after `make venv` make install # (hard working here) make uninstall
Testing the package using PyTest:
Building and packaging:
# Binary wheel distribution make dist # Build tarball with sources (source distribution) make sdist
Local docker statistics:
# Display system-wide information docker-info # Show all images and containers docker-stats # Same as `stats`, but more details provided docker-statsall
Build and run interactive containers:
# Build image from scratch docker-build # Run temporary container in an interactive mode docker-run
# Clean dangling images docker-clean # Clean built containers docker-distclean # Remove all unused images, built containers and volumes docker-mostlyclean
Render project's documentation using Sphinx:
make apidoc # to create an API documentation make html # or make pdf
Managing Vagrant virtual machines:
# Update the machine within current Vagrant environment make vagrant-update # Start and provision the Vagrant environment make vagrant-up # Connect to the machine via SSH as root make vagrant-ssh # Stop the machine make vagrant-halt # Stop and delete all traces of the machine make vagrant-destroy
# Clean the project's directrory (Python related caches) make clean # Clean the project's build output (Eggs, ditributions, builds) make distclean # Delete almost everything (including Vagrant data and virtual environment) make mostlyclean