Tools for automation¶

Releasing packages¶

PyPA-Build is used to release packages on PyPi. This is automatically done when a release is published via the github WebGUI. See more details here.

Note that this requires a manual activation of the connection between this repo and PyPi. A guide how to do that can be found here. The workflow is called cd.yml and the environment is called pypi.

Steps for releasing on pypi:

Add a git tag (locally or on github) with the version number like v0.2.4 following semantic versioning semver. If you do this locally, push the tags to github via git push --tags.
Create a release on github using the tag that was just creatd and name the release the same as the tag, e.g. v0.2.4. This will automatically trigger the CD run that publishes to PyPi.

Note that the version numbers in pyprojects.toml and src/poligrain/__init__.py are only set to the version number from the git tag during the build process. Hence, they stay at 0.0.0 in the version in the repo but are correct in the sdist or wheel.

Repository structure and tools¶

Initialization of repo structure via cookiecutter template¶

The repo structure is based on this cookiecutter template and was initialized using cruft to seamlessly apply updates when the template changes.

During initialization with the cookiecutter template poetry was chosen to manage packaging. Many best-practice tools are provides by the templates, e.g. ruff for linting and docs generation via sphinx for ReadTheDocs. For details, please see the info at the website of the template.

Below is a documentation of the changes that have been applied to the repo structure, which hopefully helps us when using the template in an another repo. (Of course we could fork and change the template but that is most likely not worth it since our changes might be few and small.)

Steps taken after repo structure initialization to get build processes going¶

Needed to manually activate ReadTheDoc build process for this repo. Currently the ReadTheDocs processes are running on the account of cchwala.
Connection to PyPi has to be established manually by allowing and configuring the creation of a PyPI project with a “trusted publisher” (see info in section Releasing packages above and in more detail in the pypi docs). This is currently done via the account of cchwala.
Connection to Codecov has to be established manually by installing the codecov App for the OpenSenseAction github organization. Most probably it will not work for other repos without further action. There is at least no need to add any authentication key to the github account and then add it at the CI.yaml file.

Changes to default repo structure¶

None yet.

Solutions for common problems with tools¶

Use `poetry` environment in VSCode¶

In VSCode you can select which Python environment shall be used for code introspection. By default the poetry env that is used by the repo, as it is initialized by the template, is not found by VSCode. There is a solution in this answer on stackoverflow which is just one line of code (if you do this before creating the env with poetry for the first time)

poetry config virtualenvs.in-project true

poetry env list  # shows the name of the current environment
poetry env remove <current environment>
poetry install  # will create a new environment using your updated configuration

if you do this after you have already created the poetry env.