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

{oe_python_template_example-0.2.5 → oe_python_template_example-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.2.5
+Version: 0.2.7
 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,130 @@ 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).
 
-Use Cases:
+### Scaffolding
+
+This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to quickly generate (scaffold) a Python package with fully functioning build and test automation:
+
+1. 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.
+2. During project generation, you can flexibly configure naming of the Python distribution, import package, main author, GitHub repository, organization, and many other aspects to match your specific requirements (see [copier.yml](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/copier.yml) for all available options).
+
+### Development Infrastructure
+
+Projects generated with this template come with a comprehensive development toolchain and quality assurance framework that supports the entire software development lifecycle - from coding and testing to documentation, release management, and compliance auditing. This infrastructure automates routine tasks, enforces code quality standards, and streamlines the path to production:
+
+1. Linting with [Ruff](https://github.com/astral-sh/ruff)
+2. Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
+3. 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)
+4. Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
+5. Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
+6. Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
+7. CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions)
+8. CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
+9. Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
+10. 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)
+11. 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
+12. Software Bill of Materials (SBOM) generated with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) and published as release artifact
+13. Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
+14. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
+15. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation and PDF export
+16. Documentation published to [Read The Docs](https://readthedocs.org/)
+17. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
+18. Python package published to [PyPI](https://pypi.org/)
+19. 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)
+20. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
+21. Settings for use with [VSCode](https://code.visualstudio.com/)
+22. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
+
+### Application Features
+
+Beyond development tooling, projects generated with this template include the code, documentation, and configuration of a fully functioning demo application and service. This reference implementation serves as a starting point for your own business logic with modern patterns and practices already in place:
+
+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
+
+To generate, build and release a fully functioning project in a few minutes, follow these 5 steps:
+
+**Step 1**: Execute the following command to install or update tooling.
+```shell
+# Install Homebrew, uv package manager, copier and further dev tools
+curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh
+```
+
+**Step 2**: [Create a 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**: Execute the following command to generate a new project based on this template.
+```shell
+# Ensure to stand in your freshly created git repository before executing this command
+copier copy --trust gh:helmut-hoffer-von-ankershoffen/oe-python-template .
+```
+
+**Step 4**: Execute the following commands to push your initial commit to GitHub.
+```shell
+git add .
+git commit -m "chore: Initial commit"
+git push
+```
+
+Check the [Actions tab](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/actions) of your GitHub repository: The CI/CD workflow of your project is already running!
+
+The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository. We will configure SonarQube and other services in the next step!
+
+Notes:
+1. Check out [this manual](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) on how to set up signed commits
+
+**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.
+
+**Step 6**: Release the first version of your project
+```shell
+make bump
+```
+Notes:
+1. You can remove the above sections - from "Scaffolding" to this notes - post having successfully generated your project.
+2. The following sections refer to the dummy application and service generated into the `tests` and `src` folder by this template.
+   Use the documentation and code as inspiration, adapt to your business logic, or remove and start documenting and coding from scratch.
 
-1. Dummy CLI application and service demonstrating example usage of the
-   directory structure and build pipeline generated by oe-python-template
 
 ## 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 +239,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:
@@ -346,11 +411,30 @@ docker compose run oe-python-template-example echo "Lorem"
 docker compose run oe-python-template-example echo "Lorem" --json
 docker compose run oe-python-template-example openapi
 docker compose run oe-python-template-example openapi --output-format=json
-docker compose up
+echo "Running OE Python Template Example's API container as a daemon ..."
+docker compose up -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
 ```
 
 ## Extra: Lorem Ipsum

{oe_python_template_example-0.2.5 → oe_python_template_example-0.2.7}/README.md

@@ -43,48 +43,130 @@
 ---
 
 
-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).
+
+### Scaffolding
+
+This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to quickly generate (scaffold) a Python package with fully functioning build and test automation:
+
+1. 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.
+2. During project generation, you can flexibly configure naming of the Python distribution, import package, main author, GitHub repository, organization, and many other aspects to match your specific requirements (see [copier.yml](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/copier.yml) for all available options).
+
+### Development Infrastructure
+
+Projects generated with this template come with a comprehensive development toolchain and quality assurance framework that supports the entire software development lifecycle - from coding and testing to documentation, release management, and compliance auditing. This infrastructure automates routine tasks, enforces code quality standards, and streamlines the path to production:
+
+1. Linting with [Ruff](https://github.com/astral-sh/ruff)
+2. Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
+3. 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)
+4. Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
+5. Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
+6. Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
+7. CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions)
+8. CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
+9. Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
+10. 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)
+11. 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
+12. Software Bill of Materials (SBOM) generated with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) and published as release artifact
+13. Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
+14. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
+15. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation and PDF export
+16. Documentation published to [Read The Docs](https://readthedocs.org/)
+17. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
+18. Python package published to [PyPI](https://pypi.org/)
+19. 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)
+20. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
+21. Settings for use with [VSCode](https://code.visualstudio.com/)
+22. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
+
+### Application Features
+
+Beyond development tooling, projects generated with this template include the code, documentation, and configuration of a fully functioning demo application and service. This reference implementation serves as a starting point for your own business logic with modern patterns and practices already in place:
+
+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
+
+To generate, build and release a fully functioning project in a few minutes, follow these 5 steps:
+
+**Step 1**: Execute the following command to install or update tooling.
+```shell
+# Install Homebrew, uv package manager, copier and further dev tools
+curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh
+```
+
+**Step 2**: [Create a 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**: Execute the following command to generate a new project based on this template.
+```shell
+# Ensure to stand in your freshly created git repository before executing this command
+copier copy --trust gh:helmut-hoffer-von-ankershoffen/oe-python-template .
+```
+
+**Step 4**: Execute the following commands to push your initial commit to GitHub.
+```shell
+git add .
+git commit -m "chore: Initial commit"
+git push
+```
+
+Check the [Actions tab](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/actions) of your GitHub repository: The CI/CD workflow of your project is already running!
 
-Use Cases:
+The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository. We will configure SonarQube and other services in the next step!
+
+Notes:
+1. Check out [this manual](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) on how to set up signed commits
+
+**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.
+
+**Step 6**: Release the first version of your project
+```shell
+make bump
+```
+Notes:
+1. You can remove the above sections - from "Scaffolding" to this notes - post having successfully generated your project.
+2. The following sections refer to the dummy application and service generated into the `tests` and `src` folder by this template.
+   Use the documentation and code as inspiration, adapt to your business logic, or remove and start documenting and coding from scratch.
 
-1. Dummy CLI application and service demonstrating example usage of the
-   directory structure and build pipeline generated by oe-python-template
 
 ## 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:
 
@@ -96,48 +178,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:
@@ -285,11 +350,30 @@ docker compose run oe-python-template-example echo "Lorem"
 docker compose run oe-python-template-example echo "Lorem" --json
 docker compose run oe-python-template-example openapi
 docker compose run oe-python-template-example openapi --output-format=json
-docker compose up
+echo "Running OE Python Template Example's API container as a daemon ..."
+docker compose up -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
 ```
 
 ## Extra: Lorem Ipsum

{oe_python_template_example-0.2.5 → oe_python_template_example-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oe-python-template-example"
-version = "0.2.5"
+version = "0.2.7"
 description = "🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template)."
 readme = "README.md"
 authors = [
@@ -79,9 +79,15 @@ Changelog = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-templat
 Issues = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/issues"
 
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling==1.27.0"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build]
+include = ["src/*"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oe_python_template_example"]
+
 [project.optional-dependencies]
 examples = [
     "streamlit>=1.43.2",
@@ -119,7 +125,6 @@ dev = [
     "sphinx-copybutton>=0.5.2",
     "sphinx-inline-tabs>=2023.4.21",
     "sphinx-mdinclude>=0.6.2",
-    "sphinx-pydantic>=0.1.1",
     "sphinx-rtd-theme>=3.0.2",
     "sphinx_selective_exclude>=1.0.3",
     "sphinx-toolbox>=3.9.0",
@@ -130,6 +135,12 @@ dev = [
     "watchdog>=6.0.0",
 ]
 
+[tool.uv]
+override-dependencies = [ # https://github.com/astral-sh/uv/issues/4422
+    "rfc3987; sys_platform == 'never'",                 # GPLv3
+]
+
+
 [tool.ruff]
 target-version = "py311"
 preview = true
@@ -242,7 +253,7 @@ source = ["src/"]
 
 
 [tool.bumpversion]
-current_version = "0.2.5"
+current_version = "0.2.7"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{oe_python_template_example-0.2.5 → oe_python_template_example-0.2.7}/src/oe_python_template_example/__init__.py

@@ -5,10 +5,15 @@ from .constants import (
     __project_path__,
     __version__,
 )
+from .models import Echo, Health, HealthStatus, Utterance
 from .service import Service
 
 __all__ = [
+    "Echo",
+    "Health",
+    "HealthStatus",
     "Service",
+    "Utterance",
     "__project_name__",
     "__project_path__",
     "__version__",