oe-python-template-example 0.0.9__py3-none-any.whl → 0.1.0__py3-none-any.whl

oe_python_template_example/api.py

@@ -1,13 +1,18 @@
-"""FastAPI application with REST API endpoints.
+"""Webservice API of OE Python Template Example.
 
-This module provides a FastAPI application with several endpoints:
+This module provides a webservice API with several endpoints:
+- A health/healthz endpoint that returns the health status of the service
 - A hello-world endpoint that returns a greeting message
 - An echo endpoint that echoes back the provided text
 
 The endpoints use Pydantic models for request and response validation.
 """
 
-from fastapi import FastAPI
+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
@@ -15,7 +20,44 @@ from oe_python_template_example import Service
 HELLO_WORLD_EXAMPLE = "Hello, world!"
 
 
-app = FastAPI(
+def get_service() -> Generator[Service, None, None]:
+    """Get the service instance.
+
+    Yields:
+        Service: The service instance.
+    """
+    service = Service()
+    try:
+        yield service
+    finally:
+        # Cleanup code if needed
+        pass
+
+
+api = FastAPI(
+    root_path="/api",
+    title="OE Python Template Example",
+    contact={
+        "name": "Helmut Hoffer von Ankershoffen",
+        "email": "helmuthva@gmail.com",
+        "url": "https://github.com/helmut-hoffer-von-ankershoffen",
+    },
+    terms_of_service="https://oe-python-template-example.readthedocs.io/en/latest/",
+    openapi_tags=[
+        {
+            "name": "v1",
+            "description": "API version 1, check link on the right",
+            "externalDocs": {"description": "sub-docs", "url": "/api/v1/docs"},
+        },
+        {
+            "name": "v2",
+            "description": "API version 2, check link on the right",
+            "externalDocs": {"description": "sub-docs", "url": "/api/v2/docs"},
+        },
+    ],
+)
+
+api_v1 = FastAPI(
     version="1.0.0",
     title="OE Python Template Example",
     contact={
@@ -26,6 +68,81 @@ app = FastAPI(
     terms_of_service="https://oe-python-template-example.readthedocs.io/en/latest/",
 )
 
+api_v2 = FastAPI(
+    version="2.0.0",
+    title="OE Python Template Example",
+    contact={
+        "name": "Helmut Hoffer von Ankershoffen",
+        "email": "helmuthva@gmail.com",
+        "url": "https://github.com/helmut-hoffer-von-ankershoffen",
+    },
+    terms_of_service="https://oe-python-template-example.readthedocs.io/en/latest/",
+)
+
+
+class _HealthStatus(StrEnum):
+    """Health status enumeration.
+
+    Args:
+        StrEnum (_type_): _description_
+    """
+
+    UP = "UP"
+    DOWN = "DOWN"
+
+
+class Health(BaseModel):
+    """Health status model.
+
+    Args:
+        BaseModel (_type_): _description_
+    """
+
+    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"])
+@api_v2.get("/health", tags=["Observability"])
+async def health(service: Annotated[Service, Depends(get_service)], response: Response) -> Health:
+    """Check the health of the service.
+
+    This endpoint returns the health status of the service.
+    The health status can be either UP or DOWN.
+    If the service is healthy, the status will be UP.
+    If the service is unhealthy, the status will be DOWN and a reason will be provided.
+    The response will have a 200 OK status code if the service is healthy,
+    and a 500 Internal Server Error status code if the service is unhealthy.
+
+    Args:
+        service (Annotated[Service, Depends): _description_
+        response (Response): _description_
+
+    Returns:
+        Health: The health status of the service.
+    """
+    if service.healthy():
+        health_result = Health(status=_HealthStatus.UP)
+    else:
+        health_result = Health(status=_HealthStatus.DOWN, reason="Service is unhealthy")
+
+    if health_result.status == _HealthStatus.DOWN:
+        response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+
+    return health_result
+
 
 class HelloWorldResponse(BaseModel):
     """Response model for hello-world endpoint."""
@@ -37,6 +154,18 @@ class HelloWorldResponse(BaseModel):
     )
 
 
+@api_v1.get("/hello-world", tags=["Basics"])
+@api_v2.get("/hello-world", tags=["Basics"])
+async def hello_world() -> HelloWorldResponse:
+    """
+    Return a hello world message.
+
+    Returns:
+        HelloWorldResponse: A response containing the hello world message.
+    """
+    return HelloWorldResponse(message=Service.get_hello_world())
+
+
 class EchoResponse(BaseModel):
     """Response model for echo endpoint."""
 
@@ -59,18 +188,7 @@ class EchoRequest(BaseModel):
     )
 
 
-@app.get("/hello-world", tags=["Basics"])
-async def hello_world() -> HelloWorldResponse:
-    """
-    Return a hello world message.
-
-    Returns:
-        HelloWorldResponse: A response containing the hello world message.
-    """
-    return HelloWorldResponse(message=Service.get_hello_world())
-
-
-@app.post("/echo", tags=["Basics"])
+@api_v1.post("/echo", tags=["Basics"])
 async def echo(request: EchoRequest) -> EchoResponse:
     """
     Echo back the provided text.
@@ -85,3 +203,35 @@ async def echo(request: EchoRequest) -> EchoResponse:
         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],
+    )
+
+
+@api_v2.post("/echo", tags=["Basics"])
+async def echo_v2(request: Utterance) -> EchoResponse:
+    """
+    Echo back the provided utterance.
+
+    Args:
+        request (EchoRequestV2): The request containing the utterance to echo back.
+
+    Returns:
+        EchoResponse: A response containing the echoed utterance.
+
+    Raises:
+        422 Unprocessable Entity: If utterance is not provided or empty.
+    """
+    return EchoResponse(message=request.utterance)
+
+
+api.mount("/v1", api_v1)
+api.mount("/v2", api_v2)

oe_python_template_example/cli.py

@@ -1,5 +1,6 @@
-"""Command line interface of OE Python Template Example."""
+"""CLI (Command Line Interface) of OE Python Template Example."""
 
+from enum import StrEnum
 from typing import Annotated
 
 import typer
@@ -8,7 +9,7 @@ import yaml
 from rich.console import Console
 
 from oe_python_template_example import Service, __version__
-from oe_python_template_example.api import app as api
+from oe_python_template_example.api import api_v1, api_v2
 
 console = Console()
 
@@ -44,30 +45,71 @@ def hello_world() -> None:
 def serve(
     host: Annotated[str, typer.Option(help="Host to bind the server to")] = "127.0.0.1",
     port: Annotated[int, typer.Option(help="Port to bind the server to")] = 8000,
-    reload: Annotated[bool, typer.Option(help="Enable auto-reload")] = True,
+    watch: Annotated[bool, typer.Option(help="Enable auto-reload")] = True,
 ) -> None:
     """Start the API server."""
     console.print(f"Starting API server at http://{host}:{port}")
     uvicorn.run(
-        "oe_python_template_example.api:app",
+        "oe_python_template_example.api:api",
         host=host,
         port=port,
-        reload=reload,
+        reload=watch,
     )
 
 
+class APIVersion(StrEnum):
+    """
+    Enum representing the API versions.
+
+    This enum defines the supported API verions:
+    - V1: Output doc for v1 API
+    - V2: Output doc for v2 API
+
+    Usage:
+        version = APIVersion.V1
+        print(f"Using {version} version")
+
+    """
+
+    V1 = "v1"
+    V2 = "v2"
+
+
+class OutputFormat(StrEnum):
+    """
+    Enum representing the supported output formats.
+
+    This enum defines the possible formats for output data:
+    - YAML: Output data in YAML format
+    - JSON: Output data in JSON format
+
+    Usage:
+        format = OutputFormat.YAML
+        print(f"Using {format} format")
+    """
+
+    YAML = "yaml"
+    JSON = "json"
+
+
 @cli.command()
 def openapi(
+    api_version: Annotated[APIVersion, typer.Option(help="API Version", case_sensitive=False)] = APIVersion.V1,
     output_format: Annotated[
-        str, typer.Option(help="Output format (yaml or json), defaults to yaml", case_sensitive=False)
-    ] = "yaml",
+        OutputFormat, typer.Option(help="Output format", case_sensitive=False)
+    ] = OutputFormat.YAML,
 ) -> None:
     """Dump the OpenAPI specification to stdout (YAML by default)."""
-    schema = api.openapi()
-    if output_format.lower() == "json":
-        console.print_json(data=schema)
-    else:
-        console.print(yaml.dump(schema, default_flow_style=False), end="")
+    match api_version:
+        case APIVersion.V1:
+            schema = api_v1.openapi()
+        case APIVersion.V2:
+            schema = api_v2.openapi()
+    match output_format:
+        case OutputFormat.JSON:
+            console.print_json(data=schema)
+        case OutputFormat.YAML:
+            console.print(yaml.dump(schema, default_flow_style=False), end="")
 
 
 def _apply_cli_settings(cli: typer.Typer, epilog: str) -> None:

oe_python_template_example/service.py

@@ -13,6 +13,7 @@ class Service:
 
     def __init__(self) -> None:
         """Initialize service."""
+        self.is_healthy = True
 
     @staticmethod
     def get_hello_world() -> str:
@@ -23,3 +24,12 @@ class Service:
             str: Hello world message.
         """
         return f"Hello, world! The value of THE_VAR is {THE_VAR}"
+
+    def healthy(self) -> bool:
+        """
+        Check if the service is healthy.
+
+        Returns:
+            bool: True if the service is healthy, False otherwise.
+        """
+        return self.is_healthy

{oe_python_template_example-0.0.9.dist-info → oe_python_template_example-0.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.0.9
+Version: 0.1.0
 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/
@@ -101,9 +101,9 @@ Use Cases:
 2) Consistent update of already scaffolded projects to benefit from new and improved features.
 3) Dummy CLI application and service demonstrating example usage of the generated directory structure and build pipeline
 
-## Scaffolding Instructions
+## Scaffolding
 
-Step 1: Install uv package manager and copier
+**Step 1**: Install uv package manager and copier
 ```shell
 if [[ "$OSTYPE" == "darwin"* ]]; then                 # Install dependencies for macOS X
   if ! command -v brew &> /dev/null; then             ## Install Homebrew if not present
@@ -119,31 +119,32 @@ fi
 uv tool install copier                                # Install copier as global tool
 ```
 
-Step 2: Now create an empty repo on GitHub and clone it to your local machine in a directory of your choice. Change to that directory.
+**Step 2**: Now create an empty repository on GitHubm, clone to your local machine, and change into it's directory.
 
-Step 3: Scaffold the project
+**Step 3**: Scaffold the project
 ```shell
 copier copy gh:helmut-hoffer-von-ankershoffen/oe-python-template .
 ```
-Step 4: Setup the local environment
+**Step 4**: Setup the local environment
 
 ```shell
 uv run nox -s setup_dev
 ```
 
-Step 5: Perform inital commit and push
+**Step 5**: Perform initial commit and push
 ```shell
 git add .
 git commit -m "feat: Initial commit"
+git push
 ```
 
 Visit your GitHub repository and check the Actions tab. The CI workflow should fail at the SonarQube step,
 as this external service is not yet configured for our new repository.
 
-Step 6: Follow the instructions in SERVICE_CONNECTIONS.md to setup the connections to external services
-such as Cloudcov, SonarQube Cloud, Read The Docs, Docker.io, GHCR.io and Streamlit Community Cloud.
+**Step 6**: Follow the [SERVICE_INSTRUCTIONS.md](instructions) to wire up
+external services such as Cloudcov, SonarQube Cloud, Read The Docs, Docker.io, GHCR.io and Streamlit Community Cloud.
 
-Step 7: Release the first versions
+**Step 7**: Release the first versions
 ```shell
 ./bump
 ```
@@ -166,25 +167,39 @@ If you don't have uv installed follow [these instructions](https://docs.astral.s
 pip install oe-python-template-example        # add dependency to your project
 ```
 
-Executing the command line interface (CLI) 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
+uvx oe-python-template-example hello-world     # prints "Hello, world! [..]"
+uvx oe-python-template-example serve           # serves webservice API
 ```
 
+When serving the 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 result.
+
+The API is versioned and provides interactive documentation at [http://127.0.0.1:8000/api/v1/docs](http://127.0.0.1:8000/api/v1/docs) resp. [http://127.0.0.1:8000/api/v2/docs](http://127.0.0.1:8000/api/v2/docs)
+
+
+```shell
+
+When running the webservice API, goto http://127.0.0.1:8000/api/v1/docs
+
 The CLI provides extensive help:
 
 ```shell
 uvx oe-python-template-example --help                # all CLI commands
 uvx oe-python-template-example hello-world --help    # help for specific command
+uvx oe-python-template-example echo --help
+uvx oe-python-template-example openapi --help
+uvx oe-python-template-example serve --help
 ```
 
 
-## Highlights
+## Operational Excellence
 
-* Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
-* Various Examples:
-  - [Simple Python script]https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/script.py)
+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 documenation](https://oe-python-template-example.readthedocs.io/en/latest/reference.html) on Read the Docs
@@ -199,6 +214,9 @@ uvx oe-python-template-example hello-world --help    # help for specific command
 
 ## Usage Examples
 
+The following examples run from source. Clone this repository first using
+`git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template-example.git`.
+
 ### Minimal Python Script:
 
 ```python
@@ -240,7 +258,7 @@ uv run streamlit run examples/streamlit.py          # Serve on localhost:8501, o
 ... or run within VSCode
 
 ```shell
-uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+uv sync --all-extras                                # Install dependencies required for examples such as Juypyter kernel, see pyproject.toml
 ```
 Install the [Jupyter extension for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)
 
@@ -284,8 +302,12 @@ Execute commands:
 
 ```shell
 uvx oe-python-template-example hello-world
-uvx oe-python-template-example hello-world --json
-uvx oe-python-template-example echo "Lorem Ipsum"
+uvx oe-python-template-example echo --help
+uvx oe-python-template-example echo "Lorem"
+uvx oe-python-template-example echo "Lorem" --json
+uvx oe-python-template-example openapi
+uvx oe-python-template-example openapi --output-format=json
+uvx oe-python-template-example serve
 ```
 
 ### Environment
@@ -306,8 +328,12 @@ You can as well run the CLI within Docker.
 ```shell
 docker run helmuthva/oe-python-template-example --help
 docker run helmuthva/oe-python-template-example hello-world
-docker run helmuthva/oe-python-template-example hello-world --json
+docker run helmuthva/oe-python-template-example echo --help
 docker run helmuthva/oe-python-template-example echo "Lorem"
+docker run helmuthva/oe-python-template-example echo "Lorem" --json
+docker run helmuthva/oe-python-template-example openapi
+docker run helmuthva/oe-python-template-example openapi --output-format=json
+docker run helmuthva/oe-python-template-example serve
 ```
 
 Execute command:
@@ -321,8 +347,18 @@ Or use docker compose
 The .env is passed through from the host to the Docker container.
 
 ```shell
-docker compose up
 docker compose run oe-python-template-example --help
+docker compose run oe-python-template-example hello-world
+docker compose run oe-python-template-example echo --help
+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
+curl http://127.0.0.1:8000/api/v1/hello-world
+curl http://127.0.0.1:8000/api/v1/docs
+curl http://127.0.0.1:8000/api/v2/hello-world
+curl http://127.0.0.1:8000/api/v2/docs
 ```
 
 ## Extra: Lorem Ipsum

oe_python_template_example-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+oe_python_template_example/__init__.py,sha256=-sCwS9lD6CvgWw88f7snBDF947PWIhEupJVebXL_w1M,314
+oe_python_template_example/api.py,sha256=Z5ZBrz7Ayjoi_h2UfD0Y_v3mlaHAkkXZYWonzB9L2hc,6356
+oe_python_template_example/cli.py,sha256=PF4B8XygvY72obDFBu4idxNDntNvFbhSi-5Bl3vs4gU,3383
+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.1.0.dist-info/METADATA,sha256=6tmPpUMuhnNOlQYfR1zHL0sACY0Hdw7EYR_5iyZ6ekw,21925
+oe_python_template_example-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+oe_python_template_example-0.1.0.dist-info/entry_points.txt,sha256=S2eCPB45b1Wgj_GsDRFAN-e4h7dBA5UPxT8od98erDE,82
+oe_python_template_example-0.1.0.dist-info/licenses/LICENSE,sha256=5H409K6xzz9U5eUaoAHQExNkoWJRlU0LEj6wL2QJ34s,1113
+oe_python_template_example-0.1.0.dist-info/RECORD,,

oe_python_template_example-0.0.9.dist-info/RECORD

@@ -1,10 +0,0 @@
-oe_python_template_example/__init__.py,sha256=-sCwS9lD6CvgWw88f7snBDF947PWIhEupJVebXL_w1M,314
-oe_python_template_example/api.py,sha256=3OmZFB_5bVdHS6wcGttfgiOmq86K5R6lXOzvTPXIQ94,2203
-oe_python_template_example/cli.py,sha256=ptgFKScjYQAj364TCBqs23rVZqIpXUxUXEoc_4f1YJE,2399
-oe_python_template_example/constants.py,sha256=6uQHr2CRgzWQWhUQCRRKiPuFhzKB2iblZk3dIRQ5dDc,358
-oe_python_template_example/service.py,sha256=ZpsZFnnJm_3EqoVqGomfAyIjLVmWJFuJ3G9qatWj5yI,516
-oe_python_template_example-0.0.9.dist-info/METADATA,sha256=XKogVxOI9bpkzWJfRstwyDquVsJRPfxZirfBVSq2p0k,20031
-oe_python_template_example-0.0.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-oe_python_template_example-0.0.9.dist-info/entry_points.txt,sha256=S2eCPB45b1Wgj_GsDRFAN-e4h7dBA5UPxT8od98erDE,82
-oe_python_template_example-0.0.9.dist-info/licenses/LICENSE,sha256=5H409K6xzz9U5eUaoAHQExNkoWJRlU0LEj6wL2QJ34s,1113
-oe_python_template_example-0.0.9.dist-info/RECORD,,