oe-python-template-example 0.2.5__tar.gz → 0.2.6__tar.gz

{oe_python_template_example-0.2.5 → oe_python_template_example-0.2.6}/.copier-answers.yml

@@ -1,4 +1,4 @@
-_commit: v0.6.21
+_commit: v0.6.26
 _src_path: gh:helmut-hoffer-von-ankershoffen/oe-python-template
 author_email: helmuthva@gmail.com
 author_github_username: helmut-hoffer-von-ankershoffen

{oe_python_template_example-0.2.5 → oe_python_template_example-0.2.6}/.github/workflows/codeql.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      # Add any setup steps before running the `github/codeql-action/init` action.
+        # Add any setup steps before running the `github/codeql-action/init` action.
       # This includes steps like installing compilers or runtimes (`actions/setup-node`
       # or others). This is typically only required for manual builds.
       # - name: Setup runtime (example)

oe_python_template_example-0.2.6/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_example-0.2.5 → oe_python_template_example-0.2.6}/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_example-0.2.5 → oe_python_template_example-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.2.5
+Version: 0.2.6
 Summary: 🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
 Project-URL: Homepage, https://oe-python-template-example.readthedocs.io/en/latest/
 Project-URL: Documentation, https://oe-python-template-example.readthedocs.io/en/latest/
@@ -104,48 +104,126 @@ Description-Content-Type: text/markdown
 ---
 
 
-Example project scaffolded and kept up to date with OE Python Template
-(oe-python-template).
+Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
+
+This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to quickly generate a Python package with fully functioning build and test automation.
+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:
+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.
+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.
+
+## Generate a new project
+
+This template is designed to be used with the [copier](https://copier.readthedocs.io/en/stable/) project generator. It allows you to create a new project based on this template and customize it according to your needs.
+To generate a new project, follow these steps:
+
+**Step 1**: Install uv package manager and copier. Copy the following code into your terminal and execute it.
+```shell
+if [[ "$OSTYPE" == "darwin"* ]]; then                 # Install dependencies for macOS X
+  if ! command -v brew &> /dev/null; then             ## Install Homebrew if not present
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  fi
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then            # Install dependencies for Linux
+  sudo apt-get update -y && sudo apt-get install curl -y # Install curl
+fi
+if ! command -v uvx &> /dev/null; then                # Install uv package manager if not present
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  source $HOME/.local/bin/env
+fi
+uv tool install copier                                # Install copier as global tool
+```
+
+**Step 2**: [Create an empty repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository), clone to your local machine, and change into it's directory.
+
+**Step 3**: Generate the project. Copy
+```shell
+copier copy --trust gh:helmut-hoffer-von-ankershoffen/oe-python-template .
+```
+
+**Step 4**: Perform initial commit and push. Copy the following code into your terminal and execute it.
+```shell
+git add .
+git commit -m "feat: Initial commit"
+git push
+```
+
+Visit your GitHub repository and check the Actions tab. The CI workflow should already be running! The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository.
 
-Use Cases:
+**Step 5**: Follow the [instructions](SERVICE_CONNECTIONS.md) to wire up
+external services such as CloudCov, SonarQube Cloud, Read The Docs, Docker.io, and Streamlit Community Cloud.
 
-1. Dummy CLI application and service demonstrating example usage of the
-   directory structure and build pipeline generated by oe-python-template
+**Step 6**: Release the first versions
+```shell
+./n bump
+```
+Notes:
+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
 
-Adding OE Python Template Example to your project as a dependency is easy.
+Adding OE Python Template Example to your project as a dependency is easy. See below for usage examples.
 
 ```shell
 uv add oe-python-template-example             # add dependency to your project
 ```
 
-If you don't have uv installed follow
-[these instructions](https://docs.astral.sh/uv/getting-started/installation/).
-If you still prefer pip over the modern and fast package manager
-[uv](https://github.com/astral-sh/uv), you can install the library like this:
+If you don't have uv installed follow [these instructions](https://docs.astral.sh/uv/getting-started/installation/). If you still prefer pip over the modern and fast package manager [uv](https://github.com/astral-sh/uv), you can install the library like this:
+
 
 ```shell
 pip install oe-python-template-example        # add dependency to your project
 ```
 
-Executing the command line interface (CLI) in an isolated Python environment is
-just as easy:
+Executing the command line interface (CLI) in an isolated Python environment is just as easy:
 
 ```shell
-uvx oe-python-template-example hello-world     # prints "Hello, world! [..]"
-uvx oe-python-template-example serve           # serves webservice API
-uvx oe-python-template-example serve --port=4711 # serves webservice API on port 4711
+uvx oe-python-template-example hello-world       # prints "Hello, world! [..]"
+uvx oe-python-template-example serve             # serves web API
+uvx oe-python-template-example serve --port=4711 # serves web API on port 4711
 ```
 
 Notes:
+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 API is versioned, mounted at `/api/v1` resp. `/api/v2`
-- While serving the webservice 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)
 
 The CLI provides extensive help:
 
@@ -157,48 +235,31 @@ uvx oe-python-template-example openapi --help
 uvx oe-python-template-example serve --help
 ```
 
+
 ## Operational Excellence
 
-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-example/blob/main/examples/script.py)
-  - [Streamlit web application](https://oe-python-template-example.streamlit.app/)
-    deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
-  - [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/notebook.ipynb)
-    and
-    [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/notebook.py)
-    notebook
-- [Complete reference documentation](https://oe-python-template-example.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-example)
-  including unit and E2E tests (reported on Codecov)
-- Matrix tested with
-  [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/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
-  [GitHub Dependabot](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/security/dependabot))
-- [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template-example)
-  in security, maintainability, and reliability with low technical debt and
-  codesmell (verified by SonarQube)
-- Additional code security checks using
-  [GitHub CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/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-example/tags)
-- Setup for developing inside a
-  [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers)
-  included (supports VSCode and GitHub Codespaces)
+This project is designed with operational excellence in mind, using modern Python tooling and practices. It includes:
+
+1. Various examples demonstrating usage:
+  a. [Simple Python script](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/script.py)
+  b. [Streamlit web application](https://oe-python-template-example.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
+  c. [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/notebook.py) notebook
+2. [Complete reference documentation](https://oe-python-template-example.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-example) 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-example/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-example/security/dependabot))
+7. [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template-example) 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-example/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-example/tags)
+12. Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
+
 
 ## Usage Examples
 
-The following examples run from source. Clone this repository first using
+The following examples run from source - clone this repository using
 `git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template-example.git`.
 
 ### Minimal Python Script: