oe-python-template-example 0.0.10__py3-none-any.whl → 0.1.1__py3-none-any.whl

oe_python_template_example/api.py

@@ -8,6 +8,7 @@ This module provides a webservice API with several endpoints:
 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
@@ -18,6 +19,8 @@ from pydantic import BaseModel, Field
 from oe_python_template_example import Service
 
 HELLO_WORLD_EXAMPLE = "Hello, world!"
+UVICORN_HOST = os.environ.get("UVICORN_HOST", "127.0.0.1")
+UVICORN_PORT = os.environ.get("UVICORN_PORT", "8000")
 
 
 def get_service() -> Generator[Service, None, None]:
@@ -34,7 +37,36 @@ def get_service() -> Generator[Service, None, None]:
         pass
 
 
-app = FastAPI(
+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": f"http://{UVICORN_HOST}:{UVICORN_PORT}/api/v1/docs",
+            },
+        },
+        {
+            "name": "v2",
+            "description": "API version 2, check link on the right",
+            "externalDocs": {
+                "description": "sub-docs",
+                "url": f"http://{UVICORN_HOST}:{UVICORN_PORT}/api/v2/docs",
+            },
+        },
+    ],
+)
+
+api_v1 = FastAPI(
     version="1.0.0",
     title="OE Python Template Example",
     contact={
@@ -45,6 +77,17 @@ 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.
@@ -78,8 +121,10 @@ class HealthResponse(BaseModel):
     )
 
 
-@app.get("/healthz", tags=["Observability"])
-@app.get("/health", tags=["Observability"])
+@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.
 
@@ -118,7 +163,8 @@ class HelloWorldResponse(BaseModel):
     )
 
 
-@app.get("/hello-world", tags=["Basics"])
+@api_v1.get("/hello-world", tags=["Basics"])
+@api_v2.get("/hello-world", tags=["Basics"])
 async def hello_world() -> HelloWorldResponse:
     """
     Return a hello world message.
@@ -151,7 +197,7 @@ class EchoRequest(BaseModel):
     )
 
 
-@app.post("/echo", tags=["Basics"])
+@api_v1.post("/echo", tags=["Basics"])
 async def echo(request: EchoRequest) -> EchoResponse:
     """
     Echo back the provided text.
@@ -166,3 +212,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 @@
 """CLI (Command Line Interface) of OE Python Template Example."""
 
+import os
 from enum import StrEnum
 from typing import Annotated
 
@@ -9,7 +10,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()
 
@@ -49,14 +50,34 @@ def serve(
 ) -> None:
     """Start the API server."""
     console.print(f"Starting API server at http://{host}:{port}")
+    os.environ["UVICORN_HOST"] = host
+    os.environ["UVICORN_PORT"] = str(port)
     uvicorn.run(
-        "oe_python_template_example.api:app",
+        "oe_python_template_example.api:api",
         host=host,
         port=port,
         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.
@@ -76,12 +97,17 @@ class OutputFormat(StrEnum):
 
 @cli.command()
 def openapi(
+    api_version: Annotated[APIVersion, typer.Option(help="API Version", case_sensitive=False)] = APIVersion.V1,
     output_format: Annotated[
         OutputFormat, typer.Option(help="Output format", case_sensitive=False)
     ] = OutputFormat.YAML,
 ) -> None:
     """Dump the OpenAPI specification to stdout (YAML by default)."""
-    schema = api.openapi()
+    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)

{oe_python_template_example-0.0.10.dist-info → oe_python_template_example-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.0.10
+Version: 0.1.1
 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,24 +167,36 @@ 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
+uvx oe-python-template-example serve --port=4711 # serves webservice API on port 4711
 ```
 
+Notes:
+* 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:
 
 ```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:
+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
@@ -199,6 +212,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 +256,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)
 
@@ -337,7 +353,10 @@ 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
+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.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+oe_python_template_example/__init__.py,sha256=-sCwS9lD6CvgWw88f7snBDF947PWIhEupJVebXL_w1M,314
+oe_python_template_example/api.py,sha256=-K3cLHgmtmnSfCIM3eyZpxL1R5KDkxFd9OvYv6Pdp4M,6647
+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.1.1.dist-info/METADATA,sha256=QM5M_qyG9DY9AH9wUrLQoHa_IoOSjdQSFsCBIxX3Rqo,21949
+oe_python_template_example-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+oe_python_template_example-0.1.1.dist-info/entry_points.txt,sha256=S2eCPB45b1Wgj_GsDRFAN-e4h7dBA5UPxT8od98erDE,82
+oe_python_template_example-0.1.1.dist-info/licenses/LICENSE,sha256=5H409K6xzz9U5eUaoAHQExNkoWJRlU0LEj6wL2QJ34s,1113
+oe_python_template_example-0.1.1.dist-info/RECORD,,

oe_python_template_example-0.0.10.dist-info/RECORD

@@ -1,10 +0,0 @@
-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,,