oe-python-template 0.6.25__tar.gz → 0.6.26__tar.gz

{oe_python_template-0.6.25 → oe_python_template-0.6.26}/.copier-answers.yml

@@ -1,4 +1,4 @@
-_commit: v0.6.24-1-g398f37a
+_commit: v0.6.25-1-gfb4e83c
 _src_path: .
 author_email: helmuthva@gmail.com
 author_github_username: helmut-hoffer-von-ankershoffen

{oe_python_template-0.6.25 → oe_python_template-0.6.26}/CHANGELOG.md

@@ -1,6 +1,13 @@
 [🧠 OE Python Template](https://oe-python-template.readthedocs.io/en/latest/)
 
-## [0.6.25](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.6.24..0.6.25) - 2025-03-20
+## [0.6.26](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.6.25..0.6.26) - 2025-03-20
+
+### 📚 Documentation
+
+- Polish - ([f2c9ee5](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/commit/f2c9ee54fa3d18f09dab2c11b293cc237b4e0226))
+
+
+## [0.6.25](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.6.24..v0.6.25) - 2025-03-20
 
 ### 📚 Documentation
 

oe_python_template-0.6.26/CODE_STYLE.md

@@ -0,0 +1,284 @@
+# Code Style
+
+Author: Helmut Hoffer von Ankershoffen (@helmut-hoffer-von-ankershoffen ) - Status: Draft - Created: 2025-03-16 - Updated: 2025-03-16
+
+This document describes the code style used in
+[oe-python-template](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template)
+and derivatives. It defines strict requirements to be followed by all
+contributors - humans and agents - to ensure consistency and readability across
+the codebase.
+
+## Code
+
+We favor readability and maintainability over cleverness and brevity.
+
+1. We always write code that is easy to read, understand, maintain, test,
+  document, deploy, use, integrate, and extend.
+2. We always write code that is efficient and performant, but only if it does not
+  sacrifice readability, maintainability, and testability.
+3. We always write code that is secure and does not introduce vulnerabilities.
+4. We always write code that is portable and does not introduce platform-specific
+  dependencies.
+5. We always write code that is compatible with the Python version indicated in
+  the .python-version file in the root of this repository.
+
+## Naming
+
+We believe that good names are essential for code readability and
+maintainability. A good name is one that is descriptive, unambiguous, and
+meaningful. It should convey the purpose and intent of the code it represents.
+
+1. We take extra care to find proper names for all identifiers, including
+  variables, functions, classes, types, tests, modules, and packages. We prefer
+  descriptive names that clearly indicate the purpose and functionality of the
+  code.
+2. We avoid using abbreviations, acronyms, and jargon unless they are widely
+  understood and accepted in the context of the code. We prefer full words and
+  phrases that are easy to understand.
+3. We avoid using single-letter names, except for loop variables and iterators.
+4. We avoid using generic names like `data`, `info`, `temp`, `foo`, `bar`, etc.
+  These names do not convey any meaning and make the code harder to read and
+  understand.
+5. We avoid using names that are too long or too short. A good name should be
+  concise but descriptive. It should be long enough to convey the purpose and
+  intent of the code, but not so long that it becomes cumbersome to read and
+  write.
+6. We avoid using names that are too similar or too different. A good name should
+  be unique and distinct. It should not be confused with other names in the
+  code. It should not be so different that it becomes hard to remember and
+  recognize.
+
+## Formatting
+
+We use [ruff](https://github.com/astral-sh/ruff) to format Python code
+
+1. The ruff formatter adheres to the
+  [Black](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
+  code style which is [PEP 8](https://www.python.org/dev/peps/pep-0008/)
+  compliant.
+2. The ruff formatter is configured to use a max line length of 120.
+3. The ruff formatter is called by the lint session of nox.
+
+Beyond PEP 8 we adhere to the following naming conventions: We use the following
+conventions for Python code:
+
+1. Class names: `PascalCase` - descriptive nouns that clearly indicate purpose.
+2. Function/method names: `snake_case` - verb phrases that describe actions.
+3. Variables/attributes: `snake_case` - descriptive nouns/noun phrases.
+4. Constants: `UPPER_SNAKE_CASE`.
+5. Private members: Prefix with single underscore `_private_attribute`.
+6. "True" private members: Prefix with double underscore `__truly_private`.
+7. Type variables: `CamelCase` with short, descriptive names (e.g., `T`, `KT`,
+  `VT`).
+8. Boolean variables/functions: Prefix with `is_`, `has_`, `should_`, etc.
+9. Interface classes: Suffix with `Interface` or `Protocol`.
+
+## Linting and type checking
+
+We use [ruff](https://github.com/astral-sh/ruff) to lint Python code
+
+1. All linting rules are enabled except those explicitly disabled in
+  pyproject.toml
+2. The ruff linter is called by the lint session of nox.
+
+We use [mypy](https://mypy.readthedocs.io/) for static type checking of Python
+code.
+
+1. mypy is configured to use the `strict` mode in pyproject.toml
+2. mypy is called by the lint session of nox.
+
+## Documentation
+
+We use docstrings to document the purpose of modules, classes, types, functions,
+its parameters and returns
+
+1. We use Google style docstrings with typed Args and Returns.
+2. We comment complex code and algorithms to explain their purpose and
+  functionality.
+3. We leave references with deep links in code to external documentation,
+  standards, and specifications.
+
+We provide an auto-generated OpenAPI specification and reference documentation.
+
+We generate the final documentation using Sphinx and publish it to readthedocs.
+
+1. Generation of documentation is called by the docs session of nox
+
+## Testing
+
+We use [pytest](https://docs.pytest.org/en/stable/) for testing Python code.
+
+1. Tests are defined in the `tests/` directory
+2. We use pytest fixtures to set up test data and state
+3. We leverage several pytest plugins:
+  1. `pytest-asyncio` for testing async code
+  2. `pytest-cov` for coverage reporting
+  3. `pytest-docker` for integration tests with containers
+  4. `pytest-env` for environment variable management
+  5. `pytest-regressions` for regression testing
+  6. `pytest-xdist` for parallel test execution
+4. Test execution is automated through the nox test session which runs across the
+  Python versions indicated in the `pyproject.toml`.
+
+Our test coverage is measured using `pytest-cov` and reported in the CI
+pipeline.
+
+1. We aim for 100% unit coverage on all code paths, including error handling and
+  edge cases.
+2. We fail the CI if unit test coverage drops below 85%.
+
+Apart from unit tests we provide integration tests and end-to-end tests:
+
+1. We smoke test as part of the CI/CD pipeline.
+2. We facilitate exploratory testing to ensure comprehensive coverage.
+3. We use `pytest-docker` for integration tests with containers.
+
+## Error Handling
+
+We use structured, explicit error handling that enables effective debugging and
+monitoring:
+
+1. Use specific exception classes instead of generic ones.
+2. Include contextual information in exception messages.
+3. Log exceptions with appropriate severity levels and context.
+4. Gracefully degrade functionality when possible rather than failing completely.
+5. Use type hints to catch type errors at compile time rather than runtime.
+6. Design errors to be actionable for both users and developers.
+
+## Logging
+
+We log information to help with debugging and monitoring:
+
+1. Use structured logging with consistent fields across all log entries.
+2. Include correlation IDs for tracking requests across components.
+3. Log at appropriate levels (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+4. Be mindful of PII and sensitive data in logs, using obfuscation where needed.
+5. Consider log volume and performance impact in production environments.
+
+## Performance Considerations
+
+We consider performance from the early design stage, not as an afterthought:
+
+1. Consider algorithmic complexity (Big O notation) for all operations.
+2. Prefer lazy evaluation when dealing with large datasets.
+3. Use appropriate data structures for specific access patterns.
+4. Be mindful of memory usage, especially for long-running processes.
+5. Consider profiling for critical paths and potential bottlenecks.
+6. Document performance characteristics and assumptions.
+7. Write benchmarks for performance-critical code.
+8. Design for horizontal scaling from the beginning.
+9. Use asynchronous operations appropriately for I/O-bound tasks.
+10. Consider caching strategies when appropriate.
+
+## API Design
+
+For both internal and external APIs we follow the principle of least surprise.
+
+1. We maintain backward compatibility whenever possible. If not possible we add a
+  new major version of the API.
+2. Implement proper versioning for breaking changes.
+3. Document error conditions, return values, and side effects.
+4. Design for testability and mockability.
+5. Provide sensible defaults while allowing for configuration.
+6. Follow RESTful principles for HTTP APIs.
+7. Use consistent parameter ordering and naming.
+8. Implement proper validation with helpful error messages.
+9. Consider rate limiting and circuit breaking for external services.
+
+## Security
+
+We prioritize security at every stage of development to prevent vulnerabilities
+and protect our users.
+
+1. Follow the principle of least privilege for all operations and access
+  controls.
+2. Never store secrets (API keys, passwords, tokens) in code repositories.
+  1. Use environment variables or dedicated secret management services.
+  2. Code is checked via `detect-secrets` pre-commit hook to prevent accidental
+    commits of secrets.
+
+We implement proper input validation and sanitization for all external inputs
+via [pydantic](https://pydantic-docs.helpmanual.io/):
+
+1. Validate inputs as early as possible in the data flow.
+
+We handle authentication and authorization correctly:
+
+1. Use industry-standard authentication protocols (OAuth, JWT).
+2. Separate authentication from authorization logic.
+3. Implement proper session management with secure cookies.
+4. Protect against common vulnerabilities:
+  1. SQL Injection: Use parameterized queries or ORM frameworks.
+  2. XSS: Apply proper output encoding.
+  3. CSRF: Implement anti-CSRF tokens for state-changing operations.
+  4. SSRF: Validate and restrict URL destinations.
+  5. Command Injection: Avoid direct system command execution where possible.
+5. Implement proper error handling that doesn't leak sensitive information.
+6. Use secure defaults and fail closed (secure) rather than open (insecure).
+
+We apply the principle of defense in depth:
+
+1. Don't rely on a single security control.
+2. Implement multiple layers of protection.
+3. Document security considerations in code and design documents.
+4. Write security-focused tests:
+  1. Test for security property violations.
+  2. Test error cases and edge conditions.
+  3. Test for resource exhaustion scenarios.
+5. Apply proper rate limiting and throttling to prevent abuse.
+6. For cryptographic operations:
+  1. Use established libraries, not custom implementations.
+  2. Follow current best practices for algorithm selection and key management.
+  3. Be aware of the limitations of cryptographic primitives.
+7. Regularly run security-focused static analysis tools as part of CI/CD:
+  1. CodeQL analysis (via GitHub Actions)
+  2. SonarCloud checks for security vulnerabilities
+
+Our security posture is defined in [SECURITY.md](SECURITY.md).
+
+## Dependency Management
+
+We use modern dependency management practices:
+
+1. [uv](https://github.com/astral-sh/uv) for fast, reliable package installation
+  and environment management
+2. Dependency version locking via uv.lock file
+3. Regular dependency auditing:
+  1. Security auditing via `pip-audit`
+  2. License compliance checks via `pip-licenses`
+  3. SBOM generation via `cyclonedx-py`
+
+Dependency updates are automated via Dependabot and Renovate to ensure we stay
+current with security patches.
+
+## Versioning
+
+We use [semantic versioning](https://semver.org/) for versioning our releases:
+
+1. MAJOR: Breaking changes
+2. MINOR: New features, non-breaking changes
+3. PATCH: Bug fixes, non-breaking changes
+
+Our API versioning follows the same principles, with major versions indicated in
+the URL (e.g., /api/v1/resource) and the full version provided as part of the
+OpenAPI pecification.
+
+## Conventional Commits
+
+Our commit messages follow conventional commits format.
+
+1. We use 'feat','fix','chore','docs','style','refactor','test' prefixes and
+  components in parentheses. E.g.
+  `feat(api): add new endpoint for user registration`.
+
+## Guidance for AI Pair Programming
+
+When generating code with AI assistance:
+
+1. AI-generated code must follow all style guidelines in this document.
+2. Always review AI-generated code for correctness, security implications, and
+  adherence to project patterns.
+3. Use AI to generate tests alongside implementation code.
+4. Request explanations for complex algorithms or patterns in the generated code.
+5. Remember that AI should augment, not replace, human judgment about code
+  quality and design decisions.

{oe_python_template-0.6.25 → oe_python_template-0.6.26}/CONTRIBUTING.md

@@ -55,8 +55,8 @@ examples/                # Example code demonstrating use of the project
 Don't forget to configure your `.env` file with the required environment variables.
 
 Notes:
-* .env.example is provided as a template.
-* .env is excluded from version control, so feel free to add secret values.
+1. .env.example is provided as a template.
+2. .env is excluded from version control, so feel free to add secret values.
 
 ### update dependencies and create virtual environment
 
@@ -117,9 +117,8 @@ uv run nox -s act
 ```
 
 Notes:
-
-- Workflow defined in `.github/workflows/*.yml`
-- test-and-report.yml calls all build steps defined in noxfile.py
+1. Workflow defined in `.github/workflows/*.yml`
+2. test-and-report.yml calls all build steps defined in noxfile.py
 
 ### Docker
 
@@ -147,10 +146,10 @@ uv run nox -s update_from_template
 
 ## Pull Request Guidelines
 
-- Before starting to write code read the [code style guide](CODE_STYLE.md) document for mandatory coding style
-  guidelines.
-- **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.
-- **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.
+1. Before starting to write code read the [code style guide](CODE_STYLE.md) document for mandatory coding style
+   guidelines.
+2. **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.
+3. **Squash Commits:** Before submitting a pull request, please squash your commits into a single commit.
+4. **Branch Naming:** Use descriptive branch names like `feature/your-feature` or `fix/issue-number`.
+5. **Testing:** Ensure new features have appropriate test coverage.
+6. **Documentation:** Update documentation to reflect any changes or new features.

{oe_python_template-0.6.25 → oe_python_template-0.6.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template
-Version: 0.6.25
+Version: 0.6.26
 Summary: 🧠 Copier template to scaffold Python projects compliant with best practices and modern tooling.
 Project-URL: Homepage, https://oe-python-template.readthedocs.io/en/latest/
 Project-URL: Documentation, https://oe-python-template.readthedocs.io/en/latest/
@@ -107,38 +107,40 @@ This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to
 Projects generated from this template can be [easily updated](https://copier.readthedocs.io/en/stable/updating/) to benefit from improvements and new features of the template.
 
 Features:
-- Package management with [uv](https://github.com/astral-sh/uv)
-- Code formatting with [Ruff](https://github.com/astral-sh/ruff)
-- Linting with [Ruff](https://github.com/astral-sh/ruff)
-- Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
-- Complete set of [pre-commit](https://pre-commit.com/) hooks including [detect-secrets](https://github.com/Yelp/detect-secrets) and [pygrep](https://github.com/pre-commit/pygrep-hooks)
-- Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
-- Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
-- Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
-- CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions)
-- CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
-- Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
-- Dependency monitoring with [pip-audit](https://pypi.org/project/pip-audit/), [Renovate](https://github.com/renovatebot/renovate), and [GitHub Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide)
-- Licenses of dependencies extracted with [pip-licenses](https://pypi.org/project/pip-licenses/) and published as release artifacts in CSV and JSON format for compliance checks
-- Software Bill of Materials (SBOM) generated with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) and published as release artifact
-- Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
-- Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
-- Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation and PDF export
-- Documentation published to [Read The Docs](https://readthedocs.org/)
-- Interactive OpenAPI specification with [Swagger](https://swagger.io/)
-- Python package published to [PyPI](https://pypi.org/)
-- Docker images published to [Docker.io](https://hub.docker.com/) and [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) with [artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds)
-- One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
+1. Package management with [uv](https://github.com/astral-sh/uv)
+2. Code formatting with [Ruff](https://github.com/astral-sh/ruff)
+3. Linting with [Ruff](https://github.com/astral-sh/ruff)
+4. Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
+5. Complete set of [pre-commit](https://pre-commit.com/) hooks including [detect-secrets](https://github.com/Yelp/detect-secrets) and [pygrep](https://github.com/pre-commit/pygrep-hooks)
+6. Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
+7. Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
+8. Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
+9. CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions)
+10. CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
+11. Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
+12. Dependency monitoring with [pip-audit](https://pypi.org/project/pip-audit/), [Renovate](https://github.com/renovatebot/renovate), and [GitHub Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide)
+13. Licenses of dependencies extracted with [pip-licenses](https://pypi.org/project/pip-licenses/) and published as release artifacts in CSV and JSON format for compliance checks
+14. Software Bill of Materials (SBOM) generated with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) and published as release artifact
+15. Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
+16. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
+17. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation and PDF export
+18. Documentation published to [Read The Docs](https://readthedocs.org/)
+19. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
+20. Python package published to [PyPI](https://pypi.org/)
+21. Docker images published to [Docker.io](https://hub.docker.com/) and [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) with [artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds)
+22. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
+23. Settings for use with [VSCode](https://code.visualstudio.com/)
+24. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
 
 The generated project includes code, documentation and configuration of a fully functioning demo-application and service, which can be used as a starting point for your own project.
-- Service architecture suitable for use as shared library
-- Validation with [pydantic](https://docs.pydantic.dev/)
-- Command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
-- Versioned Web API with [FastAPI](https://fastapi.tiangolo.com/)
-- [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
-- Simple Web UI with [Streamlit](https://streamlit.io/)
-- Configuration to run the CLI and API in a Docker container including setup for [Docker Compose](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-docker-compose/)
-- Documentation including badges, setup instructions, contribution guide and security policy
+1. Service architecture suitable for use as shared library
+2. Validation with [pydantic](https://docs.pydantic.dev/)
+3. Command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
+4. Versioned Web API with [FastAPI](https://fastapi.tiangolo.com/)
+5. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
+6. Simple Web UI with [Streamlit](https://streamlit.io/)
+7. Configuration to run the CLI and API in a Docker container including setup for [Docker Compose](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-docker-compose/)
+8. Documentation including badges, setup instructions, contribution guide and security policy
 
 Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example) for what's generated out of the box.
 
@@ -187,9 +189,9 @@ external services such as CloudCov, SonarQube Cloud, Read The Docs, Docker.io, a
 ./n bump
 ```
 Notes:
-* You can remove this section post having successfully generated your project.
-* The following sections refer to the dummy application and service provided by this template.
-  Use them as inspiration and adapt them to your own project.
+1. You can remove this section post having successfully generated your project.
+2. The following sections refer to the dummy application and service provided by this template.
+   Use them as inspiration and adapt them to your own project.
 
 ## Overview
 
@@ -215,9 +217,9 @@ uvx oe-python-template serve --port=4711 # serves web API on port 4711
 ```
 
 Notes:
-* The API is versioned, mounted at `/api/v1` resp. `/api/v2`
-* While serving the web API go to [http://127.0.0.1:8000/api/v1/hello-world](http://127.0.0.1:8000/api/v1/hello-world) to see the respons of the `hello-world` operation.
-* Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
+1. The API is versioned, mounted at `/api/v1` resp. `/api/v2`
+2. While serving the web API go to [http://127.0.0.1:8000/api/v1/hello-world](http://127.0.0.1:8000/api/v1/hello-world) to see the respons of the `hello-world` operation.
+3. Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
 
 The CLI provides extensive help:
@@ -235,21 +237,21 @@ uvx oe-python-template serve --help
 
 This project is designed with operational excellence in mind, using modern Python tooling and practices. It includes:
 
-* Various examples demonstrating usage:
-  - [Simple Python script](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/script.py)
-  - [Streamlit web application](https://oe-python-template.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
-  - [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.py) notebook
-* [Complete reference documentation](https://oe-python-template.readthedocs.io/en/latest/reference.html) on Read the Docs
-* [Transparent test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template) including unit and E2E tests (reported on Codecov)
-* Matrix tested with [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
-* Compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
-* Up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate) and [Dependabot](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/security/dependabot))
-* [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template) in security, maintainability, and reliability with low technical debt and codesmell (verified by SonarQube)
-* Additional code security checks using [CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/security/code-scanning)
-* [Security Policy](SECURITY.md)
-* [License](LICENSE) compliant with the Open Source Initiative (OSI)
-* 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/oe-python-template/tags)
-* Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
+1. Various examples demonstrating usage:
+  a. [Simple Python script](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/script.py)
+  b. [Streamlit web application](https://oe-python-template.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
+  c. [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.py) notebook
+2. [Complete reference documentation](https://oe-python-template.readthedocs.io/en/latest/reference.html) on Read the Docs
+3. [Transparent test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template) including unit and E2E tests (reported on Codecov)
+4. Matrix tested with [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
+5. Compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
+6. Up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate) and [Dependabot](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/security/dependabot))
+7. [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template) in security, maintainability, and reliability with low technical debt and codesmell (verified by SonarQube)
+8. Additional code security checks using [CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/security/code-scanning)
+9. [Security Policy](SECURITY.md)
+10. [License](LICENSE) compliant with the Open Source Initiative (OSI)
+11. 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/oe-python-template/tags)
+12. Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
 
 
 ## Usage Examples