Development of protograf

These notes are aimed at those who might be developing the protograf code further, or who just want to use protograf as part of other Python projects.

Coding

↑

In general, follow the Zen of Python — which is much easier to say than do — but also try to follow the style of the code in the rest of the project.

Note, however, that this project “breaks” a few normal conventions:

  • Use of global variables in the proto.py file

  • Extensive use of **kwargs** for the various shapes which means that a user could pass in a key+value setting that simply gets ignored without raising an error; this could be improved by creating numerous subclasses with a more extensive inheritance framework, but these soon start getting tricky to juggle…

  • Use of from protograf import * for running scripts; you could force a user to import only what they need but that makes it really tedious for them, and much harder to do if you’re not a programmer! If you are using this as part of another Python project, then of course you should follow the normal approach of only importing exactly what you need!

Code is formatted using black (https://black.readthedocs.io/) which is triggered as a GitHub action — see the .github/workflows/ directory.

Package Management

↑

Project packaging is handling via poetry (https://python-poetry.org/). You must have installed this before starting development. Follow the guides to setup a virtual environment in which to work.

Poetry Workflow

As you work, you can update the changes locally by running:

poetry install

New package dependencies should be added via:

poetry add MyNewPackage

Or added with a specific version via:

poetry add MyNewPackage^3.1.4

Check existing dependencies via:

poetry show

Upgrade a dependency via:

poetry add MyExistingPackage

Upgrade a dependency to a specific version via:

poetry add MyExistingPackage^3.1.5

Update a patch / feature version (the most common case) via:

poetry version patch

Update a minor version via:

poetry version minor

Update a major version via:

poetry version major

Examples:

command

before

after

poetry version patch

4.1.6

4.1.7

poetry version minor

2.1.4

2.2.0

poetry version major

1.3.2

2.0.0

Releases to pypi

The software includes a GitHub workflow — see the .github/workflows/ directory — which handles pushing new, tagged releases onto https://pypi.org for distribution.

Once all code changes have been made and tested — all examples must run as normal — then a new version can be released.

Follow this process:

  • ☐ Format primary code with black (black --target-version py311 protograf); update the Python version as needed

  • ☐ Finalise release date and notes in CHANGES.txt

  • ☐ Ensure all the examples can be run by using shell script(s) in the examples directory e.g. all.sh or _all.sh

  • ☐ Update the examples.zip file with latest example code (remove all PDFs in examples - except colorset and colorset_svg; and also delete the temp directory)

  • ☐ Update the release in docs/source/conf.py

  • ☐ Update the __version_info__ in _version.py

  • ☐ If working in a branch, now merge changes into master on GitHub

  • ☐ Ensure you are on the master branch and git pull changes

  • ☐ Update the version using poetry e.g. poetry version patch and inspect pyproject.toml to ensure it has changed

  • ☐ Git commit and push all these changes to GitHub

  • ☐ Add a tag that matches the poetry version e.g. git tag 0.1.2

  • ☐ Push tag to GitHub i.e. git push origin --tags

If you check the Actions tab on the GitHub project page, you should now see the workflow in action.

When complete, there should now be an updated version showing, if you do a refresh of the home page of the project at https://pypi.org/project/protograf/

Working with latest

If you’re just interested in installing the latest version via pip, then use:

pip install git+https://github.com/gamesbook/protograf

Or uv pip install git+https://github.com/gamesbook/protograf if using uv.

Documentation

↑

Documentation is written in reStructuredText and hosted on ReadTheDocs at https://app.readthedocs.org/projects/protograf/

Every time you push a commit to GitHub, the documentation workflow — see the .github/workflows/ directory — will trigger a build, which can be accessed here: https://app.readthedocs.org/projects/protograf/builds/

Documentation Notes

Some helpful reStructuredText web resources:

Some useful tools: