easy-as-pypi
Boilerplate PyPI project.
Overview
Boilerplate for modern, bathroom-tub-included Python projects.
This project is installable and includes a minimalist Click CLI:
pip install easy-as-pypi
easy-as-pypi
But this project is so much more!
This is living boilerplate.
Use this project to start a new Python project.
Use this project to manage your CI checks.
Use this project to automate your releases.
And keep your project up-to-date with the latest “boilerplate” by running:
bin/update-faithful
Because boilerplate is never static!
Here are the selling points, because we’re all here to make gold:
Modern Poetry and
pyproject.toml
setup.Much of any project’s
pyproject.toml
is already prescribed, like, 90% of your projects’pyproject.toml
is the same between all your projects.So this project generates
pyproject.toml
.It uses a simple template, located at
.pyproject.project.tmpl
, and applies it to a basepyproject.toml
template (named.pyproject.tmpl
).Use
.pyproject.project.tmpl
to add the few bits that are unique to your project, then runbin/update-faithful
to generatepyproject.toml
for your project.Most of
pyproject.toml
is already boilerplate — think ofpytest
options,black
options,flake8
options,isort
options, as well aspoetry install --with
dependencies, like those for testing, or creating docs, etc. — these are usually the same for all of your projects! So why repeat yourself?As such, we consider
pyproject.toml
to be essentially boilerplate — it’s half boilerplate, half project-specific, and generated when you runbin/update-faithful
.
Editable installs.
Run
make develop
to install your project in editable mode, as well as any dependencies that you have sources for locally.This project (the boilerplate) will manage an alternative
.pyproject-editable/pyproject.toml
automatically.Edit
Makefile
to tell it which projects are editable (specifically theEDITABLE_PJS
environ).
Pre-release installs.
Publish pre-release builds to https://test.pypi.org
This project (the boilerplate) manages an alternative
.pyproject-prerelease/pyproject.toml
andpoetry.lock
, as well as using the appropriatepip install --pre
options, so you can test changes to your stack before releasing to PyPI,
All the lints.
Run
make lint
to run all the lints:black
,flake8
,isort
,pydocstyle
,doc8
,linkcheck
,poetry check
, andtwine check
.
All the tests.
Run
tox
to test against all supported Python versions.
All the other dev tasks.
Run
make develop
to create an editable virtualenv (using local sources).Then you can run your app locally, against local sources, by calling
make test
, orpytest
.You can also use
pyenv
and modify the Python version inMakefile
to test against different Python versions, e.g.,:pyenv install -s 3.12 sed -i 's/^VENV_PYVER.*/VENV_PYVER ?= 3.12/' Makefile make develop workon make test
Run
make install
to create a release virtualenv (using PyPI sources), so you can test what end-users will experience (though not the same as publishing to PyPI and runningpip install
, but close).Run
make docs
to generate docs for ReadTheDocs.Run
make coverage
to, ya know, run coverage.Also Babel support, e.g., run
make babel-compile
to localize user messages.
All the CI.
Look under
.github/workflows
for what some might consider an over-engineered GitHub Actions workflow.But that’s really where’s there gold:
When you push a branch, checks run.
When you push a version tag, a release happens.
After checks run, and after a release is published, a “smoke test” runs: Both
pip
andpipx
are called to verify your package is viable.And lemme tell you, Poetry might work, publishing to PyPI might work, but that still doesn’t mean the release works. The smoke test lets you know it works for certain.
And if you maintain multiple projects, the CI job will dispatch and kick-off the release of the next downstream project.
Point being, this is the Python “boilerplate” to end all boilerplate.