uvicorn 0.52.1: Config, Server

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:pypi/uvicorn@0.52.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/uvicorn@0.52.1
Demonstrate these symbols/APIs:
  - uvicorn.Config
  - uvicorn.Server

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:96f1a56f7721585a017c9765c3b25fd23c320909965ffc5166844457f6c1e629","contract":["assert uvicorn.__version__ == '0.52.1'","uvicorn.Config initializes with specified host, port, log_level, and lifespan configuration and resolves ASGI application","uvicorn.Config configures HTTP protocol handler and SSL status","uvicorn.Server initializes with Config instance and manages server lifecycle state","uvicorn.Server starts HTTP server on ephemeral port, handles ASGI request, and terminates upon should_exit"],"goal":"verify pkg:pypi/uvicorn@0.52.1","kind":"HOW","packages":["pkg:pypi/uvicorn@0.52.1"],"schemaVersion":1,"symbols":["uvicorn.Config","uvicorn.Server"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","runtimeVersion":"3.12","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/uvicorn@0.52.1"],"schemaVersion":1,"subject":"pkg:pypi/uvicorn@0.52.1","symbols":["uvicorn.Config","uvicorn.Server"],"verifierAdapter":"python@1"}

[project]
name = "sample-uvicorn"
version = "0.1.0"
description = "Clean-room verification sample for pkg:pypi/uvicorn@0.52.1"
readme = "PROMPT.md"
requires-python = ">=3.12"
dependencies = [
    "uvicorn==0.52.1",
    "click==8.5.0",
    "h11==0.16.0",
]

click==8.5.0
h11==0.16.0
uvicorn==0.52.1

uvicorn==0.52.1
click==8.5.0
h11==0.16.0

{
  "schemaVersion": 1,
  "goal": "verify pkg:pypi/uvicorn@0.52.1",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/uvicorn@0.52.1"
  ],
  "symbols": [
    "uvicorn.Config",
    "uvicorn.Server"
  ]
}

"""ASGI application and server helpers using uvicorn."""

from src.server_app import create_app, create_server_config, create_server

__all__ = ["create_app", "create_server_config", "create_server"]

"""ASGI application and server helpers using uvicorn."""

import typing
import uvicorn


def create_app(message: str = "ok") -> typing.Callable:
    """Create a minimal ASGI application that serves a static text message."""
    encoded_body = message.encode("utf-8")

    async def app(scope: dict, receive: typing.Callable, send: typing.Callable) -> None:
        if scope.get("type") == "http":
            await send({
                "type": "http.response.start",
                "status": 200,
                "headers": [
                    (b"content-type", b"text/plain; charset=utf-8"),
                    (b"content-length", str(len(encoded_body)).encode("ascii")),
                ],
            })
            await send({
                "type": "http.response.body",
                "body": encoded_body,
            })

    return app


def create_server_config(
    app: typing.Any = None,
    host: str = "127.0.0.1",
    port: int = 8000,
    log_level: str = "warning",
    lifespan: str = "off",
) -> uvicorn.Config:
    """Create a uvicorn Config instance with specified parameters."""
    if app is None:
        app = create_app()
    return uvicorn.Config(
        app=app,
        host=host,
        port=port,
        log_level=log_level,
        lifespan=lifespan,
    )


def create_server(config: uvicorn.Config) -> uvicorn.Server:
    """Create a uvicorn Server instance from a Config."""
    return uvicorn.Server(config=config)

"""Contract tests package."""

"""Contract verification tests for uvicorn 0.52.1."""

import asyncio
import os
import sys
import unittest
import uvicorn

# Ensure source package can be imported
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from src.server_app import create_app, create_server_config, create_server


class TestUvicornContract(unittest.TestCase):
    def test_version(self):
        """assert uvicorn.__version__ == '0.52.1'"""
        self.assertEqual(uvicorn.__version__, "0.52.1")

    def test_config_initialization(self):
        """uvicorn.Config initializes with specified host, port, log_level, and lifespan configuration and resolves ASGI application"""
        app = create_app("hello from uvicorn")
        config = create_server_config(app=app, host="127.0.0.1", port=8000, log_level="warning")
        self.assertEqual(config.host, "127.0.0.1")
        self.assertEqual(config.port, 8000)
        self.assertEqual(config.log_level, "warning")
        self.assertEqual(config.lifespan, "off")
        self.assertFalse(config.loaded)
        config.load()
        self.assertTrue(config.loaded)
        self.assertEqual(config.app, app)

    def test_config_protocol_and_ssl(self):
        """uvicorn.Config configures HTTP protocol handler and SSL status"""
        app = create_app()
        config = create_server_config(app=app)
        config.load()
        self.assertFalse(config.is_ssl)
        self.assertEqual(config.http, "auto")
        self.assertIsNotNone(config.http_protocol_class)
        self.assertIsNone(config.ws_protocol_class)

    def test_server_initialization(self):
        """uvicorn.Server initializes with Config instance and manages server lifecycle state"""
        app = create_app()
        config = create_server_config(app=app)
        server = create_server(config)
        self.assertIs(server.config, config)
        self.assertFalse(server.started)
        self.assertFalse(server.should_exit)

    def test_server_serve_and_graceful_shutdown(self):
        """uvicorn.Server starts HTTP server on ephemeral port, handles ASGI request, and terminates upon should_exit"""
        async def run_server_test():
            message = "uvicorn contract verified"
            app = create_app(message)
            config = create_server_config(app=app, host="127.0.0.1", port=0)
            server = create_server(config)

            task = asyncio.create_task(server.serve())
            while not server.started:
                await asyncio.sleep(0.01)

            server_socket = server.servers[0].sockets[0]
            port = server_socket.getsockname()[1]

            reader, writer = await asyncio.open_connection("127.0.0.1", port)
            writer.write(b"GET / HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n")
            await writer.drain()

            raw_response = await reader.read()
            writer.close()
            await writer.wait_closed()

            self.assertIn(b"200 OK", raw_response)
            self.assertIn(message.encode("utf-8"), raw_response)

            server.should_exit = True
            await task
            self.assertTrue(server.started)

        asyncio.run(run_server_test())


if __name__ == "__main__":
    unittest.main()

version = 1
revision = 3
requires-python = ">=3.12"

[[package]]
name = "click"
version = "8.5.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/c7/0e/7fa0ef50764b67090eca4114772a2abf8b6148198475e54c660b97caeee6/click-8.5.0.tar.gz", hash = "sha256:ba0d2089de75ea0310e2dde03160e6ca10009947fb95a182f9b54021bb272e34", size = 382235, upload-time = "2026-08-26T13:33:14.56Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/58/50/6c0d534c5f134586a8e1ba4e330569e32f057e33372ae556463212fb4cd3/click-8.5.0-py3-none-any.whl", hash = "sha256:255bc9599cf7748b4b1a446ccc735421bd08a2ae529a8b88597d3de5664ee360", size = 125251, upload-time = "2026-08-26T13:33:12.928Z" },
]

[[package]]
name = "h11"
version = "0.16.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
]

[[package]]
name = "sample-uvicorn"
version = "0.1.0"
source = { virtual = "." }
dependencies = [
    { name = "click" },
    { name = "h11" },
    { name = "uvicorn" },
]

[package.metadata]
requires-dist = [
    { name = "click", specifier = "==8.5.0" },
    { name = "h11", specifier = "==0.16.0" },
    { name = "uvicorn", specifier = "==0.52.1" },
]

[[package]]
name = "uvicorn"
version = "0.52.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "click" },
    { name = "h11" },
]
sdist = { url = "https://files.pythonhosted.org/packages/03/18/ccce41535dee1be77735592bd19965f3972c82e07ee703d324709496b716/uvicorn-0.52.1.tar.gz", hash = "sha256:112ec661814189acbccd3f7b86460147cc065fc92c0821afa78918780e4354dd", size = 100571, upload-time = "2026-08-01T18:19:30.732Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/c7/d5/68e6e9bca63c0badf67002890a46d3784c958de45b65e1275ec583ca1f06/uvicorn-0.52.1-py3-none-any.whl", hash = "sha256:e4403f9d93188cf9d1088e9f40e3acd12630e2df8675316704379a7fc20fff6a", size = 79859, upload-time = "2026-08-01T18:19:29.294Z" },
]