aequitas-lib 1.0.0

Description:

aequitaslib 1.0.0

Python project template
A simple template of a Python project, with a rigid file structure, and predisposition for unit testing and release on PyPi.
Relevant features

All your project code into a single main package (aequitas-lib/)
All your project tests into a single test package (test/)
Unit testing support via unittest
Automatic testing on all branches via GitHub Actions
Semi-automatic versioning via Git
Packaging support via setuptools
Automatic release on PyPi via GitHub Actions
Docker image support via Dockerfile
Automatic release on DockerHub via GitHub Actions
Support for semi-automatic development environment management via Pyenv
Automatic dependencies updates via Renovate
Automatic conversion of TODO comments into GitHub issues via the alstr/todo-to-issue-action

Project structure
Overview:
<root directory>
├── aequitas-lib/ # main package (should be named after your project)
│ ├── __init__.py # python package marker
│ └── __main__.py # application entry point
├── test/ # test package (should contain unit tests)
├── .github/ # configuration of GitHub CI
│ └── workflows/ # configuration of GitHub Workflows
│ ├── check.yml # runs tests on multiple OS and versions of Python
│ └── deploy.yml # if check succeeds, and the current branch is one of {main, master}, triggers automatic releas on PyPi
├── MANIFEST.in # file stating what to include/exclude in releases
├── LICENSE # license file (Apache 2.0 by default)
├── pyproject.toml # declares build dependencies
├── renovate.json # configuration of Renovate bot, for automatic dependency updates
├── requirements-dev.txt # declares development dependencies
├── requirements.txt # declares runtime dependencies
├── setup.py # configuration of the package to be released on Pypi
└── Dockerfile # configuration of the Docker image to be realsed on Dockerhub

TODO-list for template usage


Use this template to create a new GitHub repository, say aequitas-lib

this name will also be used to identify the package on PyPi

so, we suggest choosing a name which has not been used on PyPi, yet
we also suggest choosing a name which is a valid Python package name (i.e. using_snake_case)





Clone the aequitas-lib repository


Open a shell into your local aequitas-lib directory and run
./rename-template.sh aequitas-lib

This will coherently rename the template's project name with the one chosen by you (i.e. aequitas-lib, in this example)


Commit & push


Ensure you like the Apache 2.0 License. If you don't, change the content of the LICENSE file


Ensure the version reported in .python-version corresponds to the actual Python version you are willing to use to develop your project


Check the Python version and OS tests should be run on in CI, by looking the file .github/workflows/check.yml


Add your runtime dependencies to requirements.txt

and development-only dependencies here requirements-dev.txt



Set your project's release metadata and dependencies by editing setup.py


Change the assignee for pull-requests for automatic dependency updates by editing renovate.json

currently defaults to @gciatto



Add your PyPi credentials as secrets of the GitHub repository

PYPI_USERNAME (resp. PYPI_PASSWORD) for your username (resp. password)
this may require you to register on PyPi first



Generate a GitHub token and add it as a secret of the GitHub repository, named RELEASE_TOKEN

cf. https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic
the token must allow pushing to the repository



Put your main (resp. test) code in aequitas-lib/ (resp. test/)


How to do stuff
Run your code as an application
This will execute the file aequitas-lib/__main__.py:
python -m aequitas-lib

Run unit tests
python -m unittest discover -s test -t .


Tests are automatically run in CI, on all pushes on all branches.
There, tests are executed on multiple OS (Win, Mac, Ubuntu) and on multiple Python versions (from 3.8 to 3.11).

Restore dev dependencies
pip install -r requirements-dev.txt

Release a new version on PyPi

This paragraph is more understandable if the reader has some background about GitFlow

GitHub actions automatically release a new version of aequitas-lib on PyPi whenever commits are pushed on either the main/master or develop branches, as well as when new tags are pushed.
Tags are assumed to consist of semantic versioning strings of the form Major.Minor.Patch where Major, Minor, and Patch are non-negative integers.
So, to release version X.Y.Z, developers must:


tag a commit on the master/main/develop branch, using X.Y.Z as the tag label
git tag -a 'X.Y.Z' -m <a message here describing the version>



push the tag
git push --follow-tags



GitHub Actions will then run tests and, if all of them succeed, release the code on PyPi.
After the release, users will be able to install your code via Pip.



Non-tagged commits pushed on the master/main/develop branch will trigger dev releases.
Dev releases are automatically tagged as X.Y.Y.devN, where

X.Y.Y is the value of the most recent version tag
N is the amount of commits following the most recent version tag