oe-python-template-example 0.2.6__py3-none-any.whl → 0.2.7__py3-none-any.whl

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__",

oe_python_template_example/api.py

@@ -10,13 +10,12 @@ The endpoints use Pydantic models for request and response validation.
 
 import os
 from collections.abc import Generator
-from enum import StrEnum
 from typing import Annotated
 
 from fastapi import Depends, FastAPI, Response, status
 from pydantic import BaseModel, Field
 
-from oe_python_template_example import Service
+from oe_python_template_example import Echo, Health, HealthStatus, Service, Utterance
 
 TITLE = "OE Python Template Example"
 HELLO_WORLD_EXAMPLE = "Hello, world!"
@@ -94,30 +93,6 @@ api_v2 = FastAPI(
 )
 
 
-class _HealthStatus(StrEnum):
-    """Health status enumeration."""
-
-    UP = "UP"
-    DOWN = "DOWN"
-
-
-class Health(BaseModel):
-    """Health status model."""
-
-    status: _HealthStatus
-    reason: str | None = None
-
-
-class HealthResponse(BaseModel):
-    """Response model for health endpoint."""
-
-    health: str = Field(
-        ...,
-        description="The hello world message",
-        examples=[HELLO_WORLD_EXAMPLE],
-    )
-
-
 @api_v1.get("/healthz", tags=["Observability"])
 @api_v1.get("/health", tags=["Observability"])
 @api_v2.get("/healthz", tags=["Observability"])
@@ -136,17 +111,17 @@ async def health(service: Annotated[Service, Depends(get_service)], response: Re
         Health: The health status of the service.
     """
     if service.healthy():
-        health_result = Health(status=_HealthStatus.UP)
+        health_result = Health(status=HealthStatus.UP)
     else:
-        health_result = Health(status=_HealthStatus.DOWN, reason="Service is unhealthy")
+        health_result = Health(status=HealthStatus.DOWN, reason="Service is unhealthy")
 
-    if health_result.status == _HealthStatus.DOWN:
+    if health_result.status == HealthStatus.DOWN:
         response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
 
     return health_result
 
 
-class HelloWorldResponse(BaseModel):
+class _HelloWorldResponse(BaseModel):
     """Response model for hello-world endpoint."""
 
     message: str = Field(
@@ -158,81 +133,48 @@ class HelloWorldResponse(BaseModel):
 
 @api_v1.get("/hello-world", tags=["Basics"])
 @api_v2.get("/hello-world", tags=["Basics"])
-async def hello_world() -> HelloWorldResponse:
+async def hello_world() -> _HelloWorldResponse:
     """
     Return a hello world message.
 
     Returns:
-        HelloWorldResponse: A response containing the hello world message.
+        _HelloWorldResponse: A response containing the hello world message.
     """
-    return HelloWorldResponse(message=Service.get_hello_world())
-
-
-class EchoResponse(BaseModel):
-    """Response model for echo endpoint."""
-
-    message: str = Field(
-        ...,
-        min_length=1,
-        description="The message content",
-        examples=[HELLO_WORLD_EXAMPLE],
-    )
-
-
-class EchoRequest(BaseModel):
-    """Request model for echo endpoint."""
-
-    text: str = Field(
-        ...,
-        min_length=1,
-        description="The text to echo back",
-        examples=[HELLO_WORLD_EXAMPLE],
-    )
+    return _HelloWorldResponse(message=Service.get_hello_world())
 
 
-@api_v1.post("/echo", tags=["Basics"])
-async def echo(request: EchoRequest) -> EchoResponse:
+@api_v1.get("/echo/{text}", tags=["Basics"])
+async def echo(text: str) -> Echo:
     """
     Echo back the provided text.
 
     Args:
-        request (EchoRequest): The request containing the text to echo back.
+        text (str): The text to echo.
 
     Returns:
-        EchoResponse: A response containing the echoed text.
+        Echo: The echo.
 
     Raises:
         422 Unprocessable Entity: If text is not provided or empty.
     """
-    return EchoResponse(message=request.text)
-
-
-class Utterance(BaseModel):
-    """Request model for echo endpoint."""
-
-    utterance: str = Field(
-        ...,
-        min_length=1,
-        description="The utterance to echo back",
-        examples=[HELLO_WORLD_EXAMPLE],
-    )
+    return Service.echo(Utterance(text=text))
 
 
 @api_v2.post("/echo", tags=["Basics"])
-async def echo_v2(request: Utterance) -> EchoResponse:
+async def echo_v2(request: Utterance) -> Echo:
     """
     Echo back the provided utterance.
 
     Args:
-        request (Utterance): The request containing the utterance to echo back.
+        request (Utterance): The utterance to echo back.
 
     Returns:
-        EchoResponse: A response containing the echoed utterance.
+        Echo: The echo.
 
     Raises:
         422 Unprocessable Entity: If utterance is not provided or empty.
     """
-    return EchoResponse(message=request.utterance)
+    return Service.echo(request)
 
 
 api.mount("/v1", api_v1)

oe_python_template_example/cli.py

@@ -9,7 +9,7 @@ import uvicorn
 import yaml
 from rich.console import Console
 
-from oe_python_template_example import Service, __version__
+from oe_python_template_example import Service, Utterance, __version__
 from oe_python_template_example.api import api_v1, api_v2
 
 console = Console()
@@ -30,10 +30,11 @@ def echo(
     ] = False,
 ) -> None:
     """Echo the text."""
+    echo = Service.echo(Utterance(text=text))
     if json:
-        console.print_json(data={"text": text})
+        console.print_json(data={"text": echo.text})
     else:
-        console.print(text)
+        console.print(echo.text)
 
 
 @cli.command()

oe_python_template_example/models.py

@@ -0,0 +1,44 @@
+"""Models used throughout OE Python Template Example's codebase ."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+UTTERANCE_EXAMPLE = "Hello, world!"
+ECHO_EXAMPLE = "HELLO, WORLD!"
+
+
+class Utterance(BaseModel):
+    """Model representing a text utterance."""
+
+    text: str = Field(
+        ...,
+        min_length=1,
+        description="The utterance to echo back",
+        examples=[UTTERANCE_EXAMPLE],
+    )
+
+
+class Echo(BaseModel):
+    """Response model for echo endpoint."""
+
+    text: str = Field(
+        ...,
+        min_length=1,
+        description="The echo",
+        examples=[ECHO_EXAMPLE],
+    )
+
+
+class HealthStatus(StrEnum):
+    """Health status enumeration."""
+
+    UP = "UP"
+    DOWN = "DOWN"
+
+
+class Health(BaseModel):
+    """Health status model."""
+
+    status: HealthStatus
+    reason: str | None = None

oe_python_template_example/service.py

@@ -1,9 +1,11 @@
-"""Service of OE Python Template Example."""
+"""Service of OE Python Template Example's."""
 
 import os
 
 from dotenv import load_dotenv
 
+from oe_python_template_example.models import Echo, Utterance
+
 load_dotenv()
 THE_VAR = os.getenv("THE_VAR", "not defined")
 
@@ -33,3 +35,19 @@ class Service:
             bool: True if the service is healthy, False otherwise.
         """
         return self.is_healthy
+
+    @staticmethod
+    def echo(utterance: Utterance) -> Echo:
+        """
+        Loudly echo utterance.
+
+        Args:
+            utterance (Utterance): The utterance to echo.
+
+        Returns:
+            Echo: The loudly echoed utterance.
+
+        Raises:
+            ValueError: If the utterance is empty or contains only whitespace.
+        """
+        return Echo(text=utterance.text.upper())

{oe_python_template_example-0.2.6.dist-info → oe_python_template_example-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.2.6
+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/
@@ -106,36 +106,44 @@ Description-Content-Type: text/markdown
 
 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.
+### 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/)
@@ -149,52 +157,48 @@ Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-templ
 
 ## 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:
+To generate, build and release a fully functioning project in a few minutes, follow these 5 steps:
 
-**Step 1**: Install uv package manager and copier. Copy the following code into your terminal and execute it.
+**Step 1**: Execute the following command to install or update tooling.
 ```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
+# 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 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 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**: Generate the project. Copy
+**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**: Perform initial commit and push. Copy the following code into your terminal and execute it.
+**Step 4**: Execute the following commands to push your initial commit to GitHub.
 ```shell
 git add .
-git commit -m "feat: Initial commit"
+git commit -m "chore: 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.
+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 versions
+**Step 6**: Release the first version of your project
 ```shell
-./n bump
+make 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.
+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.
+
 
 ## Overview
 
@@ -407,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.7.dist-info/RECORD

@@ -0,0 +1,11 @@
+oe_python_template_example/__init__.py,sha256=Ks3KjkBuzEO1gaezabSfal_WVOsJbuweHwRCs58oRv4,435
+oe_python_template_example/api.py,sha256=Al2SrT0O8NFdb93OFi-5vFtMJ3TKps-pooMZynDU9B8,5010
+oe_python_template_example/cli.py,sha256=a2NXRpybbrCGzlpPDk-YKwxD1TFV0xPdwWgYqGgv0vs,3541
+oe_python_template_example/constants.py,sha256=6uQHr2CRgzWQWhUQCRRKiPuFhzKB2iblZk3dIRQ5dDc,358
+oe_python_template_example/models.py,sha256=IbegPBFJq0OCAWS70V-ozl6coMd0dC2OsHZY-nIumGs,846
+oe_python_template_example/service.py,sha256=Hm3uytzdik2v66agUAX9IsH_tynSuCu4NZK9BySEMUM,1226
+oe_python_template_example-0.2.7.dist-info/METADATA,sha256=WHhQv5kl4DAOgOx7_mDAWhYNbWKQdPbwyLuJBhRvbCM,28966
+oe_python_template_example-0.2.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+oe_python_template_example-0.2.7.dist-info/entry_points.txt,sha256=S2eCPB45b1Wgj_GsDRFAN-e4h7dBA5UPxT8od98erDE,82
+oe_python_template_example-0.2.7.dist-info/licenses/LICENSE,sha256=5H409K6xzz9U5eUaoAHQExNkoWJRlU0LEj6wL2QJ34s,1113
+oe_python_template_example-0.2.7.dist-info/RECORD,,

oe_python_template_example-0.2.6.dist-info/RECORD

@@ -1,10 +0,0 @@
-oe_python_template_example/__init__.py,sha256=-sCwS9lD6CvgWw88f7snBDF947PWIhEupJVebXL_w1M,314
-oe_python_template_example/api.py,sha256=tYX07MjjmDJWMvxciwFbtuaB5CyptItqR5NyMNOmmqU,6291
-oe_python_template_example/cli.py,sha256=BHuDCrzYkvJYDdvk06KwkK_sKQx7h7hhRiO0peQMM1s,3474
-oe_python_template_example/constants.py,sha256=6uQHr2CRgzWQWhUQCRRKiPuFhzKB2iblZk3dIRQ5dDc,358
-oe_python_template_example/service.py,sha256=XlCrklSRy8_YaYvlVYiDFPUubHHm-J8BPx2f7_niGG4,760
-oe_python_template_example-0.2.6.dist-info/METADATA,sha256=nOJWUtLAPPnB53d2urwkOWGdDoN38v6DWTGpbEZL7_Q,27715
-oe_python_template_example-0.2.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-oe_python_template_example-0.2.6.dist-info/entry_points.txt,sha256=S2eCPB45b1Wgj_GsDRFAN-e4h7dBA5UPxT8od98erDE,82
-oe_python_template_example-0.2.6.dist-info/licenses/LICENSE,sha256=5H409K6xzz9U5eUaoAHQExNkoWJRlU0LEj6wL2QJ34s,1113
-oe_python_template_example-0.2.6.dist-info/RECORD,,