Boilerplate PyPI project.
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).
- Run
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
.
- Run
All the tests.
- Run
tox
to test against all supported Python versions.
- Run
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.