This project contains a Cookiecutter template that allows us to easily build out fully intialized Python packages that are ready for publishing right out of the box. We also add in a whole bunch of tooling to benefit the development experience and promote project sustainability.
First make sure that you have Cookiecutter installed:
$ pip install --user cookiecutter
Then request and execute the template using:
$ cookiecutter gh:stephen-bunn/cookiecutter-python-poetry-project
This will prompt you to enter a couple fields to understand how to generate the project. This template will:
- Setup the full package structure and configuration files as well as create a couple starting
__init__.py
files for the package and the corresponding tests - Initialize a new git repository and point the origin to the correct GitHub route
- Build a local virtual environment with initial package testing and documentaion building dependencies
- Install and initialize environments for necessary pre-commit hooks
- Add all generated files to an initial commit and prompt the user to enter a valid commit message
To learn more about the generated structure and tooling provided in this cookiecutter project template, please read through the provided Python Project Structure documentation.
Because we are trying to build a packaged project, we need to install specific packages in different ways (since Python's package management structure sucks). By following these guidelines, we can ensure that our project doesn't get too bloated and can be easily installable everywhere without having to re-declare dependencies in multiple files.
If you are installing a development dependency, utilize poetry
.
$ poetry add <DEPENDENCY NAME> -D
We have written and included a couple invoke tasks that are used as an abstraction to do many project releated tasks.
You must run the invoke scripts using the poetry run invoke <TASK NAME>
or poetry run inv <TASK NAME>
syntax.
Most of these tasks are pretty self-explanitory.
Be cautious of modifying these tasks to a great extent. Other files and scripts (such as pre-commit hooks) depend on these tasks executing a certain way.
$ poetry run invoke -l
Available tasks:
build Build the project.
clean Clean the project.
profile Run and profile a given Python script.
test Test the project.
docs.build Build docs.
docs.build-news Build towncrier newsfragments.
docs.clean Clean built docs.
docs.view Build and view docs.
package.build Build pacakge source files.
package.check Check built package is valid.
package.clean Clean previously built package artifacts.
package.format Auto format package source files.
package.requirements Generate requirements.txt from Poetry's lock.
package.stub Generate typing stubs for the package.
package.test Run package tests.
package.typecheck Run type checking with generated package stubs.