oe-python-template-example 0.0.9__py3-none-any.whl → 0.0.10__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,6 +20,20 @@ from oe_python_template_example import Service
 HELLO_WORLD_EXAMPLE = "Hello, world!"
 
 
+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
+
+
 app = FastAPI(
     version="1.0.0",
     title="OE Python Template Example",
@@ -27,6 +46,68 @@ app = FastAPI(
 )
 
 
+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],
+    )
+
+
+@app.get("/healthz", tags=["Observability"])
+@app.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 +118,17 @@ class HelloWorldResponse(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())
+
+
 class EchoResponse(BaseModel):
     """Response model for echo endpoint."""
 
@@ -59,17 +151,6 @@ 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"])
 async def echo(request: EchoRequest) -> EchoResponse:
     """

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
@@ -44,7 +45,7 @@ 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}")
@@ -52,22 +53,40 @@ def serve(
         "oe_python_template_example.api:app",
         host=host,
         port=port,
-        reload=reload,
+        reload=watch,
     )
 
 
+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(
     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 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.0.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.0.9
+Version: 0.0.10
 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/
@@ -184,7 +184,7 @@ uvx oe-python-template-example hello-world --help    # help for specific command
 
 * 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)
+  - [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
@@ -284,8 +284,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 +310,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 +329,15 @@ 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
 ```
 
 ## Extra: Lorem Ipsum

oe_python_template_example-0.0.10.dist-info/RECORD

@@ -0,0 +1,10 @@
+oe_python_template_example/__init__.py,sha256=-sCwS9lD6CvgWw88f7snBDF947PWIhEupJVebXL_w1M,314
+oe_python_template_example/api.py,sha256=HMcssyqFSXXVxAxhXz8Mb-5TtVGxR09R-uS8-1c7mVw,4346
+oe_python_template_example/cli.py,sha256=WL5Mn4U0jnORqjphfSxDlhFiPIAlz0RiSWPOLlB46jw,2824
+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.0.10.dist-info/METADATA,sha256=bYxQ6xq0kI3Qq3cUZ32esYtBhlTrDv9rWaSP1jBXXWg,20852
+oe_python_template_example-0.0.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+oe_python_template_example-0.0.10.dist-info/entry_points.txt,sha256=S2eCPB45b1Wgj_GsDRFAN-e4h7dBA5UPxT8od98erDE,82
+oe_python_template_example-0.0.10.dist-info/licenses/LICENSE,sha256=5H409K6xzz9U5eUaoAHQExNkoWJRlU0LEj6wL2QJ34s,1113
+oe_python_template_example-0.0.10.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,,