Simple Python Project

Python project using simple setuptools project config; note package data, scripts, entry points, etc, all still work using pyproject.toml per setuptools documentation.

To create a new repository using this template, click the button labeled Use this template and select Create a new repository.

Template repo cleanup

After creating your repository, replace the example project name "simple" with your own:

• change the project name at the top of pyproject.toml
• change the project name in docs/source/conf.py and docs/source/index.rst
• change the author and copyright names in all the doorstop doc and config files, ie
  • find . -name .doorstop.yml and review/edit all files
• then replace all the doorstop content with your own project details
• create more doorstop items as needed, link specific design and test elements back to related Shall statements
• change the author details in pyproject.toml and docs/source/conf.py
• change the package directory name under the src folder
• change the github URL paths in pyproject.toml

Make a badges branch

Create an orphan branch for Pylint and Coverage workflows. In a fresh checkout, run the following commands:

$ git checkout --orphan badges
$ git reset --hard
$ git commit --allow-empty -m "Initializing badges branch"
$ git push origin badges
$ git checkout main

Github workflows and setuptools_scm

This project uses setuptools_scm for dynamic versioning, therefor some of the (github) workflows will look for a git tag to set the version in CI. If there are no tags, this will result in some failed workflow runs. There are several options to make them succeed:

• create a base tag, eg git tag -a 0.0.0
• set SETUPTOOLS_SCM_PRETEND_VERSION to the above value in the workflow env
• disable failing workflows in the Github Actions tab
• delete any workflows you don't need

Github workflows and repo settings

Some of the automation workflows may also fail without some non-default repository settings; the following changes are required to allow these workflows to run.

Go to the repository Settings tab and scroll to the bottom of the General settings and enable these checkboxes under Pull Requests:

• Always suggest updating pull request branches (optional)
• Allow auto-merge (required)
• Automatically delete head branches (optional)

Next, in the left-hand menu under the Settings tab, click Actions, then General, then scroll to Workflow permissions:

• make sure Read repository contents and packages permissions is selected
• enable the Allow GitHub Actions to create and approve pull requests checkbox, then click Save

In addition, the provided dependabot config expects some issue labels, so open the project URL below (using your new project name) and add the following new labels:

https://github.com/<your_name>/<project_name>/issues/labels

• actions
• dependencies
• packaging

Github best practices

Finally, best practices for public repositories should include the following extra features:

• under Advanced Security enable Code Scanning, Dependabot, Private Vulnerability Reporting, and (default) Codeql config
• under Rules => Rulesets add some branch protection rules with required status checks

Dev tools

Local tool dependencies to aid in development; install them for maximum enjoyment.

Doorstop

Initial configurations and first-item doc stubs have been created in the following directories:

$ tree reqs/ docs/swd/ tests/docs/
reqs/
├── .doorstop.yml
└── REQ001.yml
docs/swd/
├── assets
│   ├── .gitkeep
│   └── simple_dependency_graph.svg
├── .doorstop.yml
└── SDD001.md
tests/docs/
├── .doorstop.yml
└── TST001.yml

The doorstop tool has been added to project [dev] "extras" as well as the tox dev and docs environments. Use the "dev" environment for working with doorstop documents, eg:

tox -e dev
source .venv/bin/activate
(.venv) doorstop
building tree...
loading documents...
validating items...
WARNING: SDD: SDD001: unreviewed changes

REQ
│
├── TST
│
└── SDD

Please see the doorstop Quick Start for an overview of the relevant doorstop commands.

Tox

As long as you have git and at least Python 3.8, then you can install and use tox. After cloning the repository, you can run the repo checks with the tox command. It will build a virtual python environment for each installed version of python with all the python dependencies and run the specified commands, eg:

$ git clone https://github.com/sarnold/simple-python-project
$ cd simple-python-project/
$ tox -e py

The above will run the default test command using the (local) default Python version. To specify the Python version and host OS type, run something like:

$ tox -e py311-linux

To build and check the Python package, run:

$ tox -e build,check

Full list of additional tox commands:

• tox -e dev build a python venv and install in editable mode
• tox -e build build the python packages and run package checks
• tox -e check install the wheel package from above
• tox -e lint run pylint (somewhat less permissive than PEP8/flake8 checks)
• tox -e mypy run mypy import and type checking
• tox -e style run flake8 style checks
• tox -e reuse run the reuse lint command and install sbom4python
• tox -e changes generate a new changelog file

To build/lint the api docs, use the following tox commands:

• tox -e docs build the documentation using sphinx and the api-doc plugin
• tox -e ldocs run the Sphinx doc-link checking
• tox -e cdocs run make clean in the docs build

Gitchangelog

We use gitchangelog to generate a changelog and/or release notes, as well as the gitchangelog message format to help it categorize/filter commits for tidier output. Please use the appropriate ACTION modifiers for important changes in Pull Requests.

Pre-commit

This repo is also pre-commit enabled for various linting and format checks. The checks run automatically on commit and will fail the commit (if not clean) with some checks performing simple file corrections.

If other checks fail on commit, the failure display should explain the error types and line numbers. Note you must fix any fatal errors for the commit to succeed; some errors should be fixed automatically (use git status and git diff to review any changes).

See the following sections in the built docs for more information on gitchangelog and pre-commit.

You will need to install pre-commit before contributing any changes; installing it using your system's package manager is recommended, otherwise install with pip into your usual virtual environment using something like:

$ sudo emerge pre-commit  --or--
$ pip install pre-commit

then install it into the repo you just cloned:

$ git clone [email protected]:sarnold/simple-python-project.git
$ cd simple-python-project/
$ pre-commit install

It's usually a good idea to update the hooks to the latest version:

pre-commit autoupdate

SBOM and license info

This project is now compliant with the REUSE Specification Version 3.3, so the corresponding license information for all files can be found in the REUSE.toml configuration file with license text(s) in the LICENSES/ folder.

Related metadata can be (re)generated with the following tools and command examples.

• reuse-tool - REUSE compliance linting and sdist (source files) SBOM generation
• sbom4python - generate SBOM with full dependency chain

Commands

Use tox to create the environment and run the lint command:

$ tox -e reuse                      # --or--
$ tox -e reuse -- spdx > sbom.txt   # generate sdist files sbom

Note you can pass any of the other reuse commands after the -- above.

Use the above environment to generate the full SBOM in text format:

$ source .tox/reuse/bin/activate
$ sbom4python --system --use-pip -o <file_name>.txt

Be patient; the last command above may take several minutes. See the doc links above for more detailed information on the tools and specifications.