oe-python-template-example 0.0.9__tar.gz → 0.0.10__tar.gz

oe_python_template_example-0.0.9/.act-env → oe_python_template_example-0.0.10/.act-env-public

@@ -1,2 +1 @@
 GITHUB_WORKFLOW_RUNTIME=ACT
-ACTIONS_RUNTIME_TOKEN=TOKEN

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/.copier-answers.yml

@@ -1,4 +1,4 @@
-_commit: v0.3.6
+_commit: v0.3.9
 _src_path: gh:helmut-hoffer-von-ankershoffen/oe-python-template
 author_email: helmuthva@gmail.com
 author_github_username: helmut-hoffer-von-ankershoffen

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/.gitignore

@@ -8,6 +8,15 @@ ENV/
 env/
 .envrc
 
+## secrets
+.secret
+.secrets
+.secrets.toml
+.secrets.yaml
+.secrets.yml
+.secrets.json
+.act-env-secret
+
 # Python virtual environment
 venv/
 .venv/

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/Dockerfile

@@ -35,5 +35,8 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 
 ENV OE_PYTHON_TEMPLATE_EXAMPLE_RUNNING_IN_CONTAINER=1
 
+# API will run on port 8000 by default
+EXPOSE 8000/tcp
+
 # But feel free to add arguments and options as needed when doing a docker run
 ENTRYPOINT ["uv", "run", "--no-dev", "oe-python-template-example"]

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/PKG-INFO

@@ -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.9 → oe_python_template_example-0.0.10}/README.md

@@ -123,7 +123,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
@@ -223,8 +223,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
@@ -245,8 +249,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:
@@ -260,8 +268,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/VERSION

@@ -0,0 +1 @@
+0.0.10

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/_readme_main.md

@@ -88,7 +88,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
@@ -188,8 +188,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
@@ -210,8 +214,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:
@@ -225,8 +233,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/compose.yaml

@@ -0,0 +1,35 @@
+services:
+  oe-python-template-example:
+    build: .
+    env_file:
+      - path: .env
+        required: true
+    develop:
+      watch:
+        - path: src
+          action: rebuild
+    restart: no
+    profiles:
+      - manual
+    tty: true
+    stdin_open: true
+  oe-python-template-example-api:
+    build: .
+    env_file:
+      - path: .env
+        required: true
+    develop:
+      watch:
+        - path: src
+          action: rebuild
+    command: serve --host=0.0.0.0 --port=8000 --no-reload
+    restart: always
+    ports:
+      - "8000:8000"
+    healthcheck:
+      test: [ "CMD", "curl", "-f", "http://127.0.0.1:8000/healthz" ]
+      interval: 5s
+      timeout: 2s
+      retries: 3
+      start_period: 5s
+      start_interval: 1s

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/docs/source/_static/openapi.json

@@ -11,6 +11,50 @@
     "version": "1.0.0"
   },
   "paths": {
+    "/health": {
+      "get": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "Health",
+        "description": "Check the health of the service.\n\nThis endpoint returns the health status of the service.\nThe health status can be either UP or DOWN.\nIf the service is healthy, the status will be UP.\nIf the service is unhealthy, the status will be DOWN and a reason will be provided.\nThe response will have a 200 OK status code if the service is healthy,\nand a 500 Internal Server Error status code if the service is unhealthy.\n\nArgs:\n    service (Annotated[Service, Depends): _description_\n    response (Response): _description_\n\nReturns:\n    Health: The health status of the service.",
+        "operationId": "health_health_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Health"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/healthz": {
+      "get": {
+        "tags": [
+          "Observability"
+        ],
+        "summary": "Health",
+        "description": "Check the health of the service.\n\nThis endpoint returns the health status of the service.\nThe health status can be either UP or DOWN.\nIf the service is healthy, the status will be UP.\nIf the service is unhealthy, the status will be DOWN and a reason will be provided.\nThe response will have a 200 OK status code if the service is healthy,\nand a 500 Internal Server Error status code if the service is unhealthy.\n\nArgs:\n    service (Annotated[Service, Depends): _description_\n    response (Response): _description_\n\nReturns:\n    Health: The health status of the service.",
+        "operationId": "health_healthz_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Health"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/hello-world": {
       "get": {
         "tags": [
@@ -129,6 +173,30 @@
         "type": "object",
         "title": "HTTPValidationError"
       },
+      "Health": {
+        "properties": {
+          "status": {
+            "$ref": "#/components/schemas/_HealthStatus"
+          },
+          "reason": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Reason"
+          }
+        },
+        "type": "object",
+        "required": [
+          "status"
+        ],
+        "title": "Health",
+        "description": "Health status model.\n\nArgs:\n    BaseModel (_type_): _description_"
+      },
       "HelloWorldResponse": {
         "properties": {
           "message": {
@@ -179,6 +247,15 @@
           "type"
         ],
         "title": "ValidationError"
+      },
+      "_HealthStatus": {
+        "type": "string",
+        "enum": [
+          "UP",
+          "DOWN"
+        ],
+        "title": "_HealthStatus",
+        "description": "Health status enumeration.\n\nArgs:\n    StrEnum (_type_): _description_"
       }
     }
   }

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/docs/source/_static/openapi.yaml

@@ -37,6 +37,21 @@ components:
           type: array
       title: HTTPValidationError
       type: object
+    Health:
+      description: "Health status model.\n\nArgs:\n    BaseModel (_type_): 
+_description_"
+      properties:
+        reason:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Reason
+        status:
+          $ref: '#/components/schemas/_HealthStatus'
+      required:
+      - status
+      title: Health
+      type: object
     HelloWorldResponse:
       description: Response model for hello-world endpoint.
       properties:
@@ -71,6 +86,14 @@ components:
       - type
       title: ValidationError
       type: object
+    _HealthStatus:
+      description: "Health status enumeration.\n\nArgs:\n    StrEnum (_type_): 
+_description_"
+      enum:
+      - UP
+      - DOWN
+      title: _HealthStatus
+      type: string
 info:
   contact:
     email: helmuthva@gmail.com
@@ -113,6 +136,62 @@ Unprocessable\
       summary: Echo
       tags:
       - Basics
+  /health:
+    get:
+      description: "Check the health of the service.\n\nThis endpoint returns 
+the\
+        \ health status of the service.\nThe health status can be either UP or 
+DOWN.\n\
+        If the service is healthy, the status will be UP.\nIf the service is 
+unhealthy,\
+        \ the status will be DOWN and a reason will be provided.\nThe response 
+will\
+        \ have a 200 OK status code if the service is healthy,\nand a 500 
+Internal\
+        \ Server Error status code if the service is unhealthy.\n\nArgs:\n    
+service\
+        \ (Annotated[Service, Depends): _description_\n    response (Response): 
+_description_\n\
+        \nReturns:\n    Health: The health status of the service."
+      operationId: health_health_get
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Health'
+          description: Successful Response
+      summary: Health
+      tags:
+      - Observability
+  /healthz:
+    get:
+      description: "Check the health of the service.\n\nThis endpoint returns 
+the\
+        \ health status of the service.\nThe health status can be either UP or 
+DOWN.\n\
+        If the service is healthy, the status will be UP.\nIf the service is 
+unhealthy,\
+        \ the status will be DOWN and a reason will be provided.\nThe response 
+will\
+        \ have a 200 OK status code if the service is healthy,\nand a 500 
+Internal\
+        \ Server Error status code if the service is unhealthy.\n\nArgs:\n    
+service\
+        \ (Annotated[Service, Depends): _description_\n    response (Response): 
+_description_\n\
+        \nReturns:\n    Health: The health status of the service."
+      operationId: health_healthz_get
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Health'
+          description: Successful Response
+      summary: Health
+      tags:
+      - Observability
   /hello-world:
     get:
       description: "Return a hello world message.\n\nReturns:\n    

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/docs/source/conf.py

@@ -26,7 +26,7 @@ extensions = [
 project = "oe-python-template-example"
 author = "Helmut Hoffer von Ankershoffen"
 copyright = f" (c) 2025-{datetime.now(UTC).year}, {author}"  # noqa: A001
-version = "0.0.9"
+version = "0.0.10"
 release = version
 github_username = "helmut-hoffer-von-ankershoffen"
 github_repository = "oe-python-template-example"

oe_python_template_example-0.0.10/github-action-run

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# Locally run job test of CI workflow in .github/workflows/test-and-report.yml. Helpful for debugging.
+act -j test --env-file .act-env-public --secret-file .act-env-secret --container-architecture linux/amd64 -P
+ubuntu-latest=catthehacker/ubuntu:act-latest --action-offline-mode --container-daemon-socket -

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/noxfile.py

@@ -117,7 +117,8 @@ def setup_dev(session: nox.Session) -> None:
     session.run("ruff", "format", ".", external=True)
     git_dir = Path(".git")
     if git_dir.is_dir():
-        session.run("echo", "found .git directory, running pre-commit install and hooks", external=True)
+        session.run("echo", "found .git directory", external=True)
+        session.run("touch", ".act-env-secret", external=True)
         session.run("pre-commit", "install", external=True)
         with Path(".secrets.baseline").open("w", encoding="utf-8") as out:
             session.run("detect-secrets", "scan", stdout=out, external=True)

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oe-python-template-example"
-version = "0.0.9"
+version = "0.0.10"
 description = "🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template)."
 readme = "README.md"
 authors = [
@@ -244,7 +244,7 @@ source = ["src/"]
 
 
 [tool.bumpversion]
-current_version = "0.0.9"
+current_version = "0.0.10"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{oe_python_template_example-0.0.9 → oe_python_template_example-0.0.10}/sonar-project.properties

@@ -1,6 +1,6 @@
 sonar.projectKey=helmut-hoffer-von-ankershoffen_oe-python-template-example
 sonar.organization=helmut-hoffer-von-ankershoffen
-sonar.projectVersion=0.0.9
+sonar.projectVersion=0.0.10
 sonar.projectDescription=🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
 sonar.links.homepage=https://oe-python-template-example.readthedocs.io/en/latest/
 sonar.links.scm=https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example

oe_python_template_example-0.0.10/src/oe_python_template_example/api.py

@@ -0,0 +1,168 @@
+"""Webservice API of OE Python Template Example.
+
+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 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
+
+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",
+    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],
+    )
+
+
+@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."""
+
+    message: str = Field(
+        ...,
+        description="The hello world message",
+        examples=[HELLO_WORLD_EXAMPLE],
+    )
+
+
+@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."""
+
+    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],
+    )
+
+
+@app.post("/echo", tags=["Basics"])
+async def echo(request: EchoRequest) -> EchoResponse:
+    """
+    Echo back the provided text.
+
+    Args:
+        request (EchoRequest): The request containing the text to echo back.
+
+    Returns:
+        EchoResponse: A response containing the echoed text.
+
+    Raises:
+        422 Unprocessable Entity: If text is not provided or empty.
+    """
+    return EchoResponse(message=request.text)