easy-as-pypi

Build Status Coverage Status Documentation Status GitHub Release Status PyPI Release Status PyPI Supported Python Versions License Status

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 base pyproject.toml template (named .pyproject.tmpl).

      • Use .pyproject.project.tmpl to add the few bits that are unique to your project, then run bin/update-faithful to generate pyproject.toml for your project.

      • Most of pyproject.toml is already boilerplate — think of pytest options, black options, flake8 options, isort options, as well as poetry 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 run bin/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 the EDITABLE_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 and poetry.lock, as well as using the appropriate pip 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, and twine 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, or pytest.

      • You can also use pyenv and modify the Python version in Makefile 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 running pip 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 and pipx 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.