Contributing¶

Thank you for considering contributing to OE Python Template Example!

Setup¶

Create a fork and clone your fork using git clone URL_OF_YOUR_CLONE. Then change into the directory of your local OE Python Template Example repository with cd oe-python-template-example.

If you are one of the committers of https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example you can directly clone via git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template-example.git and cd oe-python-template-example.

Install or update development dependencies using

make install

Directory Layout¶

├── Makefile               # Central entrypoint for build, test, release and deploy
├── noxfile.py             # Noxfile for running tests in multiple python environments and other tasks
├── .pre-commit-config.yaml # Definition of hooks run on commits
├── .github/               # GitHub specific files
│   ├── workflows/         # GitHub Actions workflows
│   ├── prompts/           # Custom prompots for GitHub Copilot
│   └── copilot-instructions.md # Insructions for GitHub Copilot
├── .vscode/               # Recommended VSCode settings and extensions
├── .env                   # Environment variables, on .gitignore
├── .env.example           # Example environment variables
src/oe_python_template_example/  # Source code
├── __init__.py          # Package initialization and
├── utils/*.py           # Infrastructure for logging, sentry, logfire etc.
├── system/*.py          # Module for system management, including service, CLI commands and API operations
├── hello/*.py           # Module for "Hello" functionality, including service, CLI commands and API operations
├── cli.py               # CLI entrypoint with auto-registration of CLI commands of modules
├── api.py               # Webservice API entrypoint with auto-registration of API operations of modules
└── constants.py         # Package specific constants such as major API versions and modules to instrument.
tests/oe_python_template_example/ # Tests
├── **/cli_tests.py      # Verifies the core and module specific CLI commands
├── **/api_tests.py      # Verifies the core and module specific API operations
└── fixtures/            # Fixtures and mock data
docs/                    # Documentation
├── partials/*.md        # Partials to compile README.md,  _main partial included in HTML and PDF documentation
├── ../README.md         # Compiled README.md shown on GitHub
├── source/*.rst         # reStructuredText files used to generate HTML and PDF documentation
├── ../*.md              # Markdown files shown on GitHub and imported by .rst files
├── source/conf.py       # Sphinx configuration used to generate HTML and PDF documentation
├── build/html/*         # Generated HTML documentation as multiple pages
├── build/singlehtml/index.html # HTML documentation as a single page
└── build/latex/oe-python-template-example.pdf # PDF manual - generate with make docs pdf
examples/                # Example code demonstrating use of the project
├── streamlit.py         # Streamlit App, deployed in Streamlit Community Cloud
├── notebook.py          # Marimo notebook
├── notebook.ipynb       # Jupyter notebook
└── script.py            # Minimal script
reports/                 # Compliance reports for auditing
├── junit.xml            # Report of test executions run with pytest
├── mypy_junit.xml       # Report of static typing validation run with mypy
├── coverage.xml         # Test coverage in XML format generated by pytest-cov
├── coverage_html        # Report of test coverage in HTML format
├── licenses.csv         # List of dependencies and their license types
├── licenses.json        # .json file with dependencies their license types
├── licenses_grouped.json  # .json file with dependencies grouped by license type
├── vulnerabilities.json # .json file with vulnerabilities detected in dependencies by pip-audit
└── sbom.json            # Software Bill of Materials in OWASP CycloneDX format

Build, Run and Release¶

Setup project specific development environment¶

make setup

Don’t forget to configure your .env file with the required environment variables.

Notes:

.env.example is provided as a template, use cp .env.example .env and edit .env to create your environment.
.env is excluded from version control, so feel free to add secret values.

Build¶

make        # Runs primary build steps, i.e. formatting, linting, testing, building HTML docs and distribution, auditing
make help   # Shows help with additional build targets, e.g. to build PDF documentation, bump the version to release etc.

Notes:

Primary build steps defined in noxfile.py.
Distribution dumped into dist/
Documentation dumped into docs/build/html/ and docs/build/latex/
Audit reports dumped into reports/

Run the CLI¶

uv run oe-python-template-example # shows help

Commit and Push your changes¶

git add .
git commit -m "feat(user): added new api endpoint to offboard user"
git push

Notes:

pre-commit hooks will run automatically on commit to ensure code quality.
We use the conventional commits format - see the code style guide for the mandatory commit message format.

Publish Release¶

make bump   # Patch release
make minor  # Patch release
make major  # Patch release
make x.y.z  # Targeted release

Notes:

Changelog generated automatically
Publishes to PyPi, Docker Registries, Read The Docs, Streamlit and Auditing services

Advanced usage¶

Developing the GUI¶

To run the GUI in the browser with hot reloading, use the following command:

make gui_watch

Running GitHub CI Workflow locally¶

make act

Notes:

Workflow defined in .github/workflows/*.yml
ci-cd.yml calls all build steps defined in noxfile.py

Docker¶

Build and run the Docker image with plain Docker

# Build from Dockerimage
make docker_build # builds targets all and slim

# Run the CLI
docker run --env THE_VAR=THE_VALUE -t oe-python-template-example --target all --help    # target with all extras
docker run --env THE_VAR=THE_VALUE -t oe-python-template-example --target slim --help   # slim flavor, no extras

Build and run the Docker image with docker compose:

echo "Building the Docker image with docker compose and running CLI..."
docker compose run --build oe-python-template-example --help
echo "Building the Docker image with docker compose and running API container as a daemon ..."
docker compose up --build -d
echo "Waiting for the API server to start..."
sleep 5
echo "Checking health of v1 API ..."
curl http://127.0.0.1:8000/api/v1/healthz
echo ""
echo "Saying hello world with v1 API ..."
curl http://127.0.0.1:8000/api/v1/hello/world
echo ""
echo "Swagger docs of v1 API ..."
curl http://127.0.0.1:8000/api/v1/docs
echo ""
echo "Checking health of v2 API ..."
curl http://127.0.0.1:8000/api/v2/healthz
echo ""
echo "Saying hello world with v1 API ..."
curl http://127.0.0.1:8000/api/v2/hello/world
echo ""
echo "Swagger docs of v2 API ..."
curl http://127.0.0.1:8000/api/v2/docs
echo ""
echo "Shutting down the API container ..."
docker compose down

Notes:

The API service is run based on the slim Docker image. Change in compose.yaml if you need the API service to run on the fat image.

Pinning GitHub Actions¶

pinact run  # See https://dev.to/suzukishunsuke/pin-github-actions-to-a-full-length-commit-sha-for-security-2n7p

Update from Template¶

Update project to latest version of oe-python-template template.

make update_from_template

Pull Request Guidelines¶

Before starting to write code read the code style document for mandatory coding style requirements.
Pre-Commit Hooks: We use pre-commit hooks to ensure code quality. Please install the pre-commit hooks by running uv run pre-commit install. This ensure all tests, linting etc. pass locally before you can commit.
Squash Commits: Before submitting a pull request, please squash your commits into a single commit.
Signed Commits: Use signed commits.
Branch Naming: Use descriptive branch names like feature/your-feature or fix/issue-number.
Testing: Ensure new features have appropriate test coverage.
Documentation: Update documentation to reflect any changes or new features.