Developing python projects associated with all use the same structure and workflow. At a later point these will refer to that website for documentation.

Bootstrap the project#

Install and git and poetry


$ git clone
$ cd vcspull

Install packages:

$ poetry install -E "docs test coverage lint format"

Development loop#


pytest is used for tests.

Rerun on file change#

via pytest-watcher (works out of the box):

$ make start

via entr(1) (requires installation):

$ make watch_test

Manual (just the command, please)#

$ poetry run py.test


$ make test

pytest options#

PYTEST_ADDOPTS can be set in the commands below. For more information read for the latest documentation.


$ env PYTEST_ADDOPTS="-verbose" make start

Drop into pdb on first error:

$ env PYTEST_ADDOPTS="-x -s --pdb" make start

If you have ipython installed:

$ env PYTEST_ADDOPTS="--pdbcls=IPython.terminal.debugger:TerminalPdb" \
    make start


sphinx is used for documentation generation. In the future this may change to docusaurus.

Default preview server: http://localhost:8022

Rerun on file change#

sphinx-autobuild will automatically build the docs, it also handles launching a server, rebuilding file changes, and updating content in the browser:

$ cd docs
$ make start

If doing css adjustments:

$ make design

Rebuild docs on file change (requires entr(1)):

$ cd docs
$ make dev

If not GNU Make / no -J support, use two terminals:

$ make watch
$ make serve

Manual (just the command, please)#

$ cd docs


$ make html

Launch server:

$ make serve


flake8 and mypy run via CI in our GitHub Actions. See the configuration in pyproject.toml and setup.cfg.


flake8 provides fast, reliable, barebones styling and linting.


$ poetry run flake8

If you setup manually:

$ flake8
$ make flake8
$ make watch_flake8

requires entr(1).

See [flake8] in setup.cfg.

exclude = .*/,.tox,*.egg,src/vcspull/__*,
select = E,W,F,N
max-line-length = 88
# Stuff we ignore thanks to black:
extend-ignore = E203,W503


mypy is used for static type checking.


$ poetry run mypy .

If you setup manually:

$ mypy .
$ make mypy
$ make watch_mypy

requires entr(1).

See [tool.mypy] in pyproject.toml.

python_version = 3.9
warn_unused_configs = true
files = [
strict = true

Publishing to PyPI#

As of 0.10, poetry handles virtualenv creation, package requirements, versioning, building, and publishing. Therefore there is no or requirements files.

Update __version__ in and pyproject.toml::

git commit -m 'build(vcspull): Tag v0.1.1'
git tag v0.1.1
git push
git push --tags
poetry build
poetry publish