pythonboot-web 0.1.0__tar.gz

pythonboot_web-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Tools
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Node.js and VitePress generated files
+node_modules/
+viteDocs/docs/.vitepress/cache/
+viteDocs/docs/.vitepress/dist/
+
+# IDE and OS
+.idea/
+.vscode/
+.DS_Store

pythonboot_web-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: pythonboot-web
+Version: 0.1.0
+Summary: FastAPI integration and Web application startup for PythonBoot
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: pythonboot<0.2,>=0.1.0
+Requires-Dist: uvicorn[standard]<1,>=0.34
+Description-Content-Type: text/markdown
+
+# pythonboot-web
+
+PythonBoot 的独立 Web 实现包，包含 Controller、路由、异常处理、请求与响应上下文、
+日期格式化、API 文档、ASGI 生命周期和 Web 启动类。
+
+依赖 `pythonboot`、FastAPI 和 Uvicorn，用户推荐安装 `pythonboot-starter-web`。
+核心接口从 `pythonboot` 导入，Web 接口从 `pythonboot_web` 导入。
+原来的 `pythonboot.web` 和核心包顶层 Web 导出已移除。
+YAML 的 `pythonboot.web` 配置键保持不变。
+
+```python
+from pythonboot import autowired, service
+from pythonboot_web import PythonBootApplication, controller, get, pythonboot_application
+
+@service
+class GreetingService:
+    def greeting(self) -> str:
+        return "Hello"
+
+@controller(prefix="/greeting")
+class GreetingController:
+    service: GreetingService = autowired()
+
+    @get("")
+    def greeting(self) -> str:
+        return self.service.greeting()
+
+@pythonboot_application(scan_packages=("myapp",))
+class Application(PythonBootApplication):
+    pass
+```
+
+
+完整分层应用见 [全量 Starter 示例](../../example/README.md)，包含全部 Starter、PostgreSQL／Redis 和同步／异步 HTTP 用法。
+See the [complete Starter application](../../example/README.md) for all Starters and sync/async HTTP examples.

pythonboot_web-0.1.0/README.md

@@ -0,0 +1,35 @@
+# pythonboot-web
+
+PythonBoot 的独立 Web 实现包，包含 Controller、路由、异常处理、请求与响应上下文、
+日期格式化、API 文档、ASGI 生命周期和 Web 启动类。
+
+依赖 `pythonboot`、FastAPI 和 Uvicorn，用户推荐安装 `pythonboot-starter-web`。
+核心接口从 `pythonboot` 导入，Web 接口从 `pythonboot_web` 导入。
+原来的 `pythonboot.web` 和核心包顶层 Web 导出已移除。
+YAML 的 `pythonboot.web` 配置键保持不变。
+
+```python
+from pythonboot import autowired, service
+from pythonboot_web import PythonBootApplication, controller, get, pythonboot_application
+
+@service
+class GreetingService:
+    def greeting(self) -> str:
+        return "Hello"
+
+@controller(prefix="/greeting")
+class GreetingController:
+    service: GreetingService = autowired()
+
+    @get("")
+    def greeting(self) -> str:
+        return self.service.greeting()
+
+@pythonboot_application(scan_packages=("myapp",))
+class Application(PythonBootApplication):
+    pass
+```
+
+
+完整分层应用见 [全量 Starter 示例](../../example/README.md)，包含全部 Starter、PostgreSQL／Redis 和同步／异步 HTTP 用法。
+See the [complete Starter application](../../example/README.md) for all Starters and sync/async HTTP examples.

pythonboot_web-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pythonboot-web"
+version = "0.1.0"
+description = "FastAPI integration and Web application startup for PythonBoot"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pythonboot>=0.1.0,<0.2",
+    "fastapi>=0.115,<1",
+    "uvicorn[standard]>=0.34,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pythonboot_web"]

pythonboot_web-0.1.0/src/pythonboot_web/__init__.py

@@ -0,0 +1,24 @@
+"""FastAPI routing, dependency injection, and exception handling integration."""
+
+from pythonboot_web.integration import inject, register_exception_handlers, register_routers
+from pythonboot_web.docs import register_api_docs, resolve_docs_options
+from pythonboot_web.datetime import DateTimeFormatMiddleware, date_time, resolve_datetime_format
+from pythonboot_web.context_middleware import ApplicationContextMiddleware
+from pythonboot_web.request_context import RequestContextHolder
+from pythonboot_web.decorators import (
+    controller, controller_advise, delete, exception_handler, get, patch, post, put, route,
+)
+
+__all__ = [
+    "controller", "controller_advise", "exception_handler", "route", "get", "post", "put", "patch", "delete",
+    "inject", "register_routers", "register_exception_handlers", "resolve_datetime_format",
+    "DateTimeFormatMiddleware", "date_time",
+    "resolve_docs_options", "register_api_docs",
+    "ApplicationContextMiddleware",
+    "RequestContextHolder",
+]
+
+from pythonboot_web.application import PythonBootApplication, create_app
+from pythonboot_web.bootstrap import pythonboot_application
+
+__all__ += ["PythonBootApplication", "create_app", "pythonboot_application"]

pythonboot_web-0.1.0/src/pythonboot_web/application.py

@@ -0,0 +1,151 @@
+"""PythonBoot application creation and startup entry points."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+import uvicorn
+from fastapi import FastAPI
+
+from pythonboot.beans import scan_components
+from pythonboot.boot.autoconfiguration import assemble_auto_configurations
+from pythonboot.context import ApplicationContext
+from pythonboot.config import configure_logging, load_configuration
+from pythonboot.util import ContextUtil
+from pythonboot_web import (
+    ApplicationContextMiddleware, DateTimeFormatMiddleware, register_api_docs, register_exception_handlers,
+    register_routers, resolve_datetime_format, resolve_docs_options,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(
+    *, title: str = "PythonBoot", version: str = "0.1.0",
+    scan_packages: tuple[str, ...] = (),
+    exclude_modules: tuple[str, ...] = (), config_dir: str | Path | None = None,
+    auto_configure: bool = True, exclude_auto_configurations: tuple[str, ...] = (),
+    exclude: tuple[type, ...] = (),
+    **options: Any,
+) -> FastAPI:
+    """Create an independent application instance."""
+    if isinstance(scan_packages, str):
+        raise ValueError("scan_packages must be a sequence of package names, not a string")
+    if isinstance(exclude, (str, type)) or any(not isinstance(target, type) for target in exclude):
+        raise TypeError("exclude must be a sequence of classes")
+    excluded_classes = tuple(exclude)
+    result = scan_components(
+        tuple(scan_packages), exclude_modules=exclude_modules, exclude=excluded_classes,
+    )
+    logger.info("Scanned %d component definitions from %d modules.", len(result.definitions), len(result.modules))
+    configuration = load_configuration(config_dir) if config_dir is not None else {}
+    configure_logging(configuration)
+    docs_options = resolve_docs_options(configuration)
+    date_time_format = resolve_datetime_format(configuration)
+    definitions = result.definitions
+    if auto_configure:
+        definitions = assemble_auto_configurations(
+            definitions, result.modules, configuration, exclude=exclude_auto_configurations,
+            exclude_classes=excluded_classes,
+        )
+        logger.info("Auto-configuration assembled %d bean definitions.", len(definitions))
+    else:
+        logger.info("Auto-configuration is disabled.")
+    context = ApplicationContext(definitions, configuration=configuration)
+    fastapi_options = {
+        **options,
+        "docs_url": None,
+        "redoc_url": None,
+        "openapi_url": docs_options.openapi_path if docs_options.enabled else None,
+    }
+    app = FastAPI(title=title, version=version, **fastapi_options)
+    app.state.context = context
+    native_lifespan = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(application: FastAPI) -> AsyncIterator[Any]:
+        with ContextUtil.use(context):
+            logger.info("Starting application context.")
+            await context.start()
+            try:
+                async with native_lifespan(application) as state:
+                    yield state
+            finally:
+                logger.info("Closing application context.")
+                await context.close()
+
+    app.router.lifespan_context = lifespan
+    app.add_middleware(ApplicationContextMiddleware, context=context)
+    app.add_middleware(DateTimeFormatMiddleware, date_time_format=date_time_format)
+    register_api_docs(app, docs_options)
+    register_routers(
+        app, result.modules, exclude=excluded_classes, date_time_format=date_time_format,
+    )
+    register_exception_handlers(app, result.modules, exclude=excluded_classes)
+    logger.info("Created FastAPI application '%s' version %s.", title, version)
+    return app
+
+
+class PythonBootApplication:
+    """Extensible startup class with an independent FastAPI application per instance."""
+
+    def __init__(
+        self,
+        *,
+        title: str = "PythonBoot",
+        version: str = "0.1.0",
+        scan_packages: tuple[str, ...] | None = None,
+        config_dir: str | Path | None = None,
+        auto_configure: bool = True,
+        exclude_auto_configurations: tuple[str, ...] | None = None,
+        exclude: tuple[type, ...] | None = None,
+        **options: Any,
+    ) -> None:
+        packages = (
+            scan_packages if scan_packages is not None
+            else getattr(type(self), "__pythonboot_scan_packages__", None)
+        )
+        module_name = type(self).__module__
+        module = sys.modules.get(module_name)
+        if module_name == "__main__":
+            module_name = getattr(getattr(module, "__spec__", None), "name", module_name)
+        if packages is None:
+            if type(self) is PythonBootApplication:
+                packages = ()
+            else:
+                package_name = getattr(module, "__package__", None) or module_name.rpartition(".")[0]
+                if not package_name:
+                    raise ValueError("The application class has no importable parent package; set scan_packages explicitly")
+                packages = (package_name,)
+        self.app: FastAPI = create_app(
+            title=title, version=version, scan_packages=packages,
+            exclude_modules=(module_name,), config_dir=config_dir,
+            auto_configure=auto_configure,
+            exclude_auto_configurations=(
+                exclude_auto_configurations if exclude_auto_configurations is not None
+                else getattr(type(self), "__pythonboot_exclude_auto_configurations__", ())
+            ),
+            exclude=(
+                exclude if exclude is not None else getattr(type(self), "__pythonboot_exclude__", ())
+            ),
+            **options,
+        )
+        self.context: ApplicationContext = self.app.state.context
+        self.configure(self.app)
+
+    def configure(self, app: FastAPI) -> None:
+        """Allow subclasses to register routes, middleware, and exception handlers."""
+
+    def run(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        log_level: str = "info",
+    ) -> None:
+        """Start the application; use a Uvicorn module entry for reload or multiple workers."""
+        logger.info("Starting Uvicorn server on %s:%d.", host, port)
+        uvicorn.run(self.app, host=host, port=port, log_level=log_level)

pythonboot_web-0.1.0/src/pythonboot_web/bootstrap.py

@@ -0,0 +1,38 @@
+"""Composite application startup declarations."""
+
+from typing import Callable, TypeVar
+
+T = TypeVar("T", bound=type)
+
+
+def pythonboot_application(
+    cls: T | None = None, *, scan_packages: tuple[str, ...] | None = None,
+    exclude_auto_configurations: tuple[str, ...] = (),
+    exclude: tuple[type, ...] = (),
+) -> T | Callable[[T], T]:
+    """Scan the application package by default, or use explicit package patterns."""
+    if isinstance(scan_packages, str):
+        raise ValueError("scan_packages must be a sequence of package names, not a string")
+    packages = tuple(scan_packages) if scan_packages is not None else None
+    if packages is not None and any(not isinstance(package, str) or not package for package in packages):
+        raise ValueError("Scan package names must be non-empty strings")
+    if isinstance(exclude_auto_configurations, str) or any(
+        not isinstance(name, str) or not name for name in exclude_auto_configurations
+    ):
+        raise ValueError("Auto-configuration exclusions must be a sequence of non-empty names")
+    exclusions = tuple(exclude_auto_configurations)
+    if isinstance(exclude, (str, type)) or any(not isinstance(target, type) for target in exclude):
+        raise TypeError("exclude must be a sequence of classes")
+    excluded_classes = tuple(exclude)
+
+    def decorate(cls: T) -> T:
+        from pythonboot_web.application import PythonBootApplication
+
+        if not issubclass(cls, PythonBootApplication):
+            raise TypeError("Application classes must inherit PythonBootApplication")
+        cls.__pythonboot_scan_packages__ = packages
+        cls.__pythonboot_exclude_auto_configurations__ = exclusions
+        cls.__pythonboot_exclude__ = excluded_classes
+        return cls
+
+    return decorate(cls) if cls is not None else decorate

pythonboot_web-0.1.0/src/pythonboot_web/context_middleware.py

@@ -0,0 +1,42 @@
+"""Bind the application container for HTTP, WebSocket, and background callbacks."""
+
+from fastapi import Request
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from pythonboot.context import ApplicationContext
+from pythonboot.util import ContextUtil
+from pythonboot_web.request_context import RequestContextHolder, ResponseContext
+
+
+class ApplicationContextMiddleware:
+    def __init__(self, app: ASGIApp, context: ApplicationContext) -> None:
+        self.app = app
+        self.context = context
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        with ContextUtil.use(self.context):
+            if scope["type"] != "http":
+                await self.app(scope, receive, send)
+                return
+            body_parts: list[bytes] = []
+
+            async def request_receive() -> Message:
+                message = await receive()
+                if message["type"] == "http.request":
+                    body_parts.append(message.get("body", b""))
+                    if not message.get("more_body", False):
+                        request._body = b"".join(body_parts)
+                        body_parts.clear()
+                return message
+
+            request = Request(scope, receive=request_receive)
+            response = ResponseContext()
+
+            async def response_send(message: Message) -> None:
+                if message["type"] == "http.response.start":
+                    await send(response.apply(message))
+                    return
+                await send(message)
+
+            with RequestContextHolder.use(request, response):
+                await self.app(scope, request_receive, response_send)

pythonboot_web-0.1.0/src/pythonboot_web/datetime.py

@@ -0,0 +1,208 @@
+"""Date-time request parameter configuration and parsing."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+import json
+from types import UnionType
+from typing import Annotated, Any, Union, get_args, get_origin
+
+from pydantic import BaseModel, BeforeValidator
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from pythonboot.exceptions import ConfigurationError
+
+DEFAULT_DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+@dataclass(frozen=True)
+class DateTimeFormat:
+    """Per-parameter date-time format metadata."""
+
+    value: str
+
+
+def date_time(format: str) -> DateTimeFormat:
+    """Set a controller parameter or body field date-time format."""
+    if not isinstance(format, str) or not format:
+        raise ValueError("date_time format must be a non-empty string")
+    return DateTimeFormat(format)
+
+
+class DateTimeFormatMiddleware:
+    """Format serialized JSON date-time values using the application setting."""
+
+    def __init__(self, app: ASGIApp, date_time_format: str) -> None:
+        self.app = app
+        self.date_time_format = date_time_format
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        start: Message | None = None
+        body_parts: list[bytes] = []
+        json_response = False
+
+        async def capture(message: Message) -> None:
+            nonlocal start, json_response
+            if message["type"] == "http.response.start":
+                start = message
+                json_response = _is_json_response(message)
+                if not json_response:
+                    await send(message)
+                return
+            if message["type"] != "http.response.body":
+                await send(message)
+                return
+            if not json_response:
+                await send(message)
+                return
+            body_parts.append(message.get("body", b""))
+            if message.get("more_body", False):
+                return
+            if start is None:
+                await send(message)
+                return
+            body = b"".join(body_parts)
+            body = _format_json_date_times(body, self.date_time_format)
+            await send(_response_start_with_length(start, len(body)))
+            await send({"type": "http.response.body", "body": body, "more_body": False})
+
+        await self.app(scope, receive, capture)
+
+
+def resolve_datetime_format(configuration: Mapping[str, Any]) -> str:
+    """Read the PythonBoot web date-time format setting."""
+    pythonboot = configuration.get("pythonboot", {})
+    if not isinstance(pythonboot, Mapping):
+        raise ConfigurationError("pythonboot configuration must be a mapping")
+    web = pythonboot.get("web", {})
+    if not isinstance(web, Mapping):
+        raise ConfigurationError("pythonboot.web configuration must be a mapping")
+    value = web.get("datetime_format", DEFAULT_DATETIME_FORMAT)
+    if not isinstance(value, str) or not value:
+        raise ConfigurationError("pythonboot.web.datetime_format must be a non-empty string")
+    return value
+
+
+def date_time_annotation(annotation: Any, date_time_format: str) -> Any:
+    """Add configured date-time parsing to controller parameters and body models."""
+    arguments = get_args(annotation)
+    if get_origin(annotation) is Annotated:
+        target, *metadata = arguments
+    else:
+        target, metadata = annotation, []
+    format_value = _metadata_format(metadata) or date_time_format
+    parser = _date_time_parser(format_value)
+
+    if target is datetime:
+        return Annotated[datetime, *metadata, BeforeValidator(parser)]
+    if isinstance(target, type) and issubclass(target, BaseModel):
+        def normalize_body(value: Any) -> Any:
+            return _normalize_model_values(value, target, parser)
+
+        return Annotated[target, *metadata, BeforeValidator(normalize_body)]
+    return annotation
+
+
+def _date_time_parser(format_value: str) -> Any:
+    def parse(value: Any) -> Any:
+        if not isinstance(value, str):
+            return value
+        try:
+            return datetime.strptime(value, format_value)
+        except ValueError as error:
+            raise ValueError(
+                f"Date-time value must match the configured format: {format_value}"
+            ) from error
+    return parse
+
+
+def _normalize_model_values(value: Any, model_type: type[BaseModel], parser: Any) -> Any:
+    """Normalize only declared date-time fields before Pydantic validates a body model."""
+    if not isinstance(value, Mapping):
+        return value
+    return {
+        name: _normalize_value(item, _field_annotation(model_type.model_fields[name]), parser)
+        if name in model_type.model_fields else item
+        for name, item in value.items()
+    }
+
+
+def _normalize_value(value: Any, annotation: Any, parser: Any) -> Any:
+    """Recursively normalize date-time fields in nested body values."""
+    if annotation is datetime:
+        parsed = parser(value)
+        return parsed.isoformat() if isinstance(parsed, datetime) else parsed
+    origin = get_origin(annotation)
+    arguments = get_args(annotation)
+    if origin is Annotated:
+        return _normalize_value(
+            value, arguments[0], _date_time_parser(_metadata_format(arguments[1:]))
+            if _metadata_format(arguments[1:]) else parser,
+        )
+    if origin in (Union, UnionType):
+        date_time_types = [item for item in arguments if item is datetime]
+        if date_time_types:
+            return _normalize_value(value, date_time_types[0], parser)
+        for item in arguments:
+            if item is not type(None):
+                return _normalize_value(value, item, parser)
+        return value
+    if origin in (list, set, tuple) and isinstance(value, list) and arguments:
+        return [_normalize_value(item, arguments[0], parser) for item in value]
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return _normalize_model_values(value, annotation, parser)
+    return value
+
+
+def _metadata_format(metadata: list[Any] | tuple[Any, ...]) -> str | None:
+    for item in metadata:
+        if isinstance(item, DateTimeFormat):
+            return item.value
+    return None
+
+
+def _field_annotation(field: Any) -> Any:
+    return Annotated[field.annotation, *field.metadata] if field.metadata else field.annotation
+
+
+def _is_json_response(message: Message) -> bool:
+    return any(
+        name.lower() == b"content-type" and b"application/json" in value.lower()
+        for name, value in message.get("headers", [])
+    )
+
+
+def _format_json_date_times(body: bytes, date_time_format: str) -> bytes:
+    try:
+        value = json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return body
+    return json.dumps(
+        _format_value(value, date_time_format), ensure_ascii=False, separators=(",", ":"),
+    ).encode()
+
+
+def _format_value(value: Any, date_time_format: str) -> Any:
+    if isinstance(value, list):
+        return [_format_value(item, date_time_format) for item in value]
+    if isinstance(value, dict):
+        return {name: _format_value(item, date_time_format) for name, item in value.items()}
+    if not isinstance(value, str) or "T" not in value:
+        return value
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return value
+    return parsed.strftime(date_time_format)
+
+
+def _response_start_with_length(message: Message, length: int) -> Message:
+    headers = [
+        (name, value) for name, value in message.get("headers", [])
+        if name.lower() != b"content-length"
+    ]
+    headers.append((b"content-length", str(length).encode()))
+    return {**message, "headers": headers}

pythonboot_web-0.1.0/src/pythonboot_web/decorators.py

@@ -0,0 +1,129 @@
+"""Class-based controllers and method route declarations."""
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, TypeVar
+
+from pythonboot.beans import Scope, component
+
+T = TypeVar("T", bound=type)
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(frozen=True)
+class RouteDefinition:
+    path: str
+    methods: tuple[str, ...]
+    options: dict[str, Any]
+
+
+def controller(
+    cls: T | None = None,
+    *,
+    prefix: str = "",
+    tags: list[str] | None = None,
+    name: str | None = None,
+    init_method: str | None = None,
+    destroy_method: str | None = None,
+    lazy: bool = False,
+    scope: Scope = "singleton",
+    primary: bool = False,
+    qualifiers: tuple[str, ...] = (),
+    depends_on: tuple[str, ...] = (),
+    **router_options: Any,
+) -> T | Callable[[T], T]:
+    """Declare a controller, singleton by default, with container-injected dependencies."""
+    def decorate(target: T) -> T:
+        if not inspect.isclass(target):
+            raise TypeError("@controller can only decorate classes")
+        component(
+            target, name=name, init_method=init_method, destroy_method=destroy_method,
+            lazy=lazy, scope=scope, primary=primary, qualifiers=qualifiers, depends_on=depends_on,
+        )
+        target.__pythonboot_controller__ = {
+            **router_options, "prefix": prefix, "tags": list(tags or []),
+        }
+        return target
+
+    return decorate(cls) if cls is not None else decorate
+
+
+def controller_advise(
+    cls: T | None = None,
+    *,
+    name: str | None = None,
+    init_method: str | None = None,
+    destroy_method: str | None = None,
+    lazy: bool = False,
+    scope: Scope = "singleton",
+    primary: bool = False,
+    qualifiers: tuple[str, ...] = (),
+    depends_on: tuple[str, ...] = (),
+) -> T | Callable[[T], T]:
+    """Declare a managed global exception handler component."""
+    def decorate(target: T) -> T:
+        if not inspect.isclass(target):
+            raise TypeError("@controller_advise can only decorate classes")
+        component(
+            target, name=name, init_method=init_method, destroy_method=destroy_method,
+            lazy=lazy, scope=scope, primary=primary, qualifiers=qualifiers, depends_on=depends_on,
+        )
+        target.__pythonboot_controller_advise__ = True
+        return target
+
+    return decorate(cls) if cls is not None else decorate
+
+
+def exception_handler(
+    exception_type: int | type[Exception],
+) -> Callable[[F], F]:
+    """Map a controller advice instance method to an exception or status code."""
+    if not isinstance(exception_type, int) and (
+        not inspect.isclass(exception_type) or not issubclass(exception_type, Exception)
+    ):
+        raise TypeError("exception_handler target must be an exception type or status code")
+
+    def decorate(method: F) -> F:
+        if not inspect.isfunction(method):
+            raise TypeError("@exception_handler can only decorate instance methods")
+        handlers = list(getattr(method, "__pythonboot_exception_handlers__", ()))
+        handlers.append(exception_type)
+        method.__pythonboot_exception_handlers__ = tuple(handlers)
+        return method
+
+    return decorate
+
+
+def route(
+    path: str, *, methods: tuple[str, ...] = ("GET",), **options: Any
+) -> Callable[[F], F]:
+    """Declare a controller instance route using FastAPI add_api_route options."""
+    def decorate(method: F) -> F:
+        if not inspect.isfunction(method):
+            raise TypeError("Route decorators can only decorate controller instance methods")
+        definitions = list(getattr(method, "__pythonboot_routes__", ()))
+        definitions.append(RouteDefinition(path, tuple(methods), dict(options)))
+        method.__pythonboot_routes__ = tuple(definitions)
+        return method
+
+    return decorate
+
+
+def get(path: str, **options: Any) -> Callable[[F], F]:
+    return route(path, methods=("GET",), **options)
+
+
+def post(path: str, **options: Any) -> Callable[[F], F]:
+    return route(path, methods=("POST",), **options)
+
+
+def put(path: str, **options: Any) -> Callable[[F], F]:
+    return route(path, methods=("PUT",), **options)
+
+
+def patch(path: str, **options: Any) -> Callable[[F], F]:
+    return route(path, methods=("PATCH",), **options)
+
+
+def delete(path: str, **options: Any) -> Callable[[F], F]:
+    return route(path, methods=("DELETE",), **options)

pythonboot_web-0.1.0/src/pythonboot_web/docs.py

@@ -0,0 +1,70 @@
+"""OpenAPI documentation UI registration."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from html import escape
+from typing import Any, Literal
+
+from fastapi import FastAPI, Request
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.responses import HTMLResponse
+
+from pythonboot.exceptions import ConfigurationError
+
+DocsProvider = Literal["scalar", "swagger", "redoc"]
+
+
+@dataclass(frozen=True)
+class DocsOptions:
+    enabled: bool
+    provider: DocsProvider
+    path: str
+    openapi_path: str
+
+
+def resolve_docs_options(configuration: Mapping[str, Any]) -> DocsOptions:
+    """Read documentation UI settings from the application configuration."""
+    pythonboot = configuration.get("pythonboot", {})
+    if not isinstance(pythonboot, Mapping):
+        raise ConfigurationError("pythonboot configuration must be a mapping")
+    values = pythonboot.get("docs", {})
+    if not isinstance(values, Mapping):
+        raise ConfigurationError("pythonboot.docs configuration must be a mapping")
+    enabled = values.get("enabled", True)
+    provider = values.get("provider", "scalar")
+    path = values.get("path", "/docs")
+    openapi_path = values.get("openapi_path", "/openapi.json")
+    if not isinstance(enabled, bool):
+        raise ConfigurationError("pythonboot.docs.enabled must be a boolean")
+    if provider not in ("scalar", "swagger", "redoc"):
+        raise ConfigurationError("pythonboot.docs.provider must be scalar, swagger, or redoc")
+    for name, value in (("pythonboot.docs.path", path), ("pythonboot.docs.openapi_path", openapi_path)):
+        if not isinstance(value, str) or not value.startswith("/") or value == "/":
+            raise ConfigurationError(f"{name} must be an absolute non-root path")
+    if path == openapi_path:
+        raise ConfigurationError("pythonboot.docs.path and pythonboot.docs.openapi_path must be different")
+    return DocsOptions(enabled, provider, path, openapi_path)
+
+
+def register_api_docs(app: FastAPI, options: DocsOptions) -> None:
+    """Register the selected documentation UI for an application."""
+    if not options.enabled:
+        return
+    async def endpoint(request: Request) -> HTMLResponse:
+        openapi_url = f"{request.scope.get('root_path', '')}{app.openapi_url}"
+        title = f"{app.title} API Reference"
+        if options.provider == "swagger":
+            return get_swagger_ui_html(openapi_url=openapi_url, title=title)
+        if options.provider == "redoc":
+            return get_redoc_html(openapi_url=openapi_url, title=title)
+        return HTMLResponse(
+            "<!doctype html>"
+            "<html><head>"
+            f"<title>{escape(title)}</title>"
+            "</head><body>"
+            f'<script id="api-reference" data-url="{escape(openapi_url, quote=True)}"></script>'
+            '<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>'
+            "</body></html>"
+        )
+
+    app.add_api_route(options.path, endpoint, methods=["GET"], include_in_schema=False)

pythonboot_web-0.1.0/src/pythonboot_web/integration.py

@@ -0,0 +1,154 @@
+"""Container integration preserving native FastAPI routing and dependencies."""
+
+import inspect
+from functools import wraps
+from types import ModuleType
+from typing import Any, Callable, TypeVar, get_type_hints
+
+from fastapi import APIRouter, FastAPI, Request
+
+from pythonboot.exceptions import BeanDefinitionError
+from pythonboot_web.datetime import date_time_annotation
+
+T = TypeVar("T")
+
+
+def inject(
+    bean_type: type[T], *, name: str | None = None, qualifier: str | None = None,
+) -> Callable[[Request], T]:
+    """Use Depends(inject(Service)) to resolve a bean according to its scope."""
+    def dependency(request: Request) -> T:
+        return request.app.state.context.get_bean(bean_type, name=name, qualifier=qualifier)
+
+    return dependency
+
+
+def _controller_endpoint(
+    cls: type, method: Callable[..., Any], *, date_time_format: str,
+) -> Callable[..., Any]:
+    """Hide self and resolve the current application's controller for each request."""
+    signature = inspect.signature(method)
+    parameters = list(signature.parameters.values())
+    if not parameters or parameters[0].name != "self":
+        raise BeanDefinitionError(f"Controller route {cls.__name__}.{method.__name__} must be an instance method")
+    parameters = parameters[1:]
+    if any(parameter.kind in (
+        parameter.POSITIONAL_ONLY, parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD,
+    ) for parameter in parameters):
+        raise BeanDefinitionError("Controller routes do not support positional-only parameters, *args, or **kwargs")
+    try:
+        hints = get_type_hints(method, include_extras=True)
+    except (NameError, TypeError) as error:
+        raise BeanDefinitionError(f"Cannot resolve type hints for controller route {cls.__name__}.{method.__name__}") from error
+    parameters = [
+        parameter.replace(annotation=date_time_annotation(
+            hints.get(parameter.name, parameter.annotation), date_time_format,
+        ))
+        for parameter in parameters
+    ]
+    request_name = "_pythonboot_request"
+    while request_name in signature.parameters:
+        request_name += "_"
+    parameters.append(inspect.Parameter(
+        request_name, kind=inspect.Parameter.KEYWORD_ONLY, annotation=Request,
+    ))
+    component_options = vars(cls)["__pythonboot_component__"]
+    bean_name = component_options.name or cls.__name__[:1].lower() + cls.__name__[1:]
+
+    def bound_method(kwargs: dict[str, Any]) -> Callable[..., Any]:
+        request: Request = kwargs.pop(request_name)
+        instance = request.app.state.context.get_bean(cls, name=bean_name)
+        return getattr(instance, method.__name__)
+
+    if inspect.iscoroutinefunction(method):
+        @wraps(method)
+        async def endpoint(*args: Any, **kwargs: Any) -> Any:
+            target = bound_method(kwargs)
+            return await target(*args, **kwargs)
+    else:
+        @wraps(method)
+        def endpoint(*args: Any, **kwargs: Any) -> Any:
+            target = bound_method(kwargs)
+            return target(*args, **kwargs)
+
+    endpoint.__name__ = f"{cls.__name__}_{method.__name__}"
+    endpoint.__signature__ = signature.replace(
+        parameters=parameters,
+        return_annotation=hints.get("return", signature.return_annotation),
+    )
+    return endpoint
+
+
+def register_routers(
+    app: FastAPI, modules: tuple[ModuleType, ...], *, exclude: tuple[type, ...] = (),
+    date_time_format: str,
+) -> None:
+    """Automatically register class-based controllers and native APIRouter objects."""
+    seen: set[int] = set()
+    for module in modules:
+        for value in vars(module).values():
+            if isinstance(value, APIRouter) and id(value) not in seen:
+                seen.add(id(value))
+                app.include_router(value)
+            elif (
+                inspect.isclass(value)
+                and value not in exclude
+                and value.__module__ == module.__name__
+                and "__pythonboot_controller__" in vars(value)
+                and id(value) not in seen
+            ):
+                seen.add(id(value))
+                router = APIRouter(**vars(value)["__pythonboot_controller__"])
+                for _, method in inspect.getmembers(value, inspect.isfunction):
+                    definitions = getattr(method, "__pythonboot_routes__", ())
+                    if not definitions:
+                        continue
+                    endpoint = _controller_endpoint(value, method, date_time_format=date_time_format)
+                    for definition in definitions:
+                        router.add_api_route(
+                            definition.path, endpoint,
+                            methods=list(definition.methods), **definition.options,
+                        )
+                app.include_router(router)
+
+
+def register_exception_handlers(
+    app: FastAPI, modules: tuple[ModuleType, ...], *, exclude: tuple[type, ...] = (),
+) -> None:
+    """Register managed controller advice methods as FastAPI exception handlers."""
+    excluded_classes = set(exclude)
+    for module in modules:
+        for advice_type in vars(module).values():
+            if (
+                not inspect.isclass(advice_type)
+                or advice_type in excluded_classes
+                or advice_type.__module__ != module.__name__
+                or not vars(advice_type).get("__pythonboot_controller_advise__")
+            ):
+                continue
+            component_options = vars(advice_type)["__pythonboot_component__"]
+            bean_name = component_options.name or advice_type.__name__[:1].lower() + advice_type.__name__[1:]
+            for method_name, method in vars(advice_type).items():
+                targets = getattr(method, "__pythonboot_exception_handlers__", ())
+                if not targets:
+                    continue
+                signature = inspect.signature(method)
+                parameters = list(signature.parameters.values())
+                if not parameters or parameters[0].name != "self":
+                    raise BeanDefinitionError(
+                        f"Exception handler {advice_type.__name__}.{method_name} must be an instance method"
+                    )
+
+                async def handler(
+                    request: Request, error: Exception, *,
+                    _method_name: str = method_name, _advice_type: type = advice_type,
+                    _bean_name: str = bean_name,
+                ) -> Any:
+                    instance = request.app.state.context.get_bean(_advice_type, name=_bean_name)
+                    result = getattr(instance, _method_name)(request, error)
+                    if inspect.isawaitable(result):
+                        return await result
+                    return result
+
+                for target in targets:
+                    app.add_exception_handler(target, handler)

pythonboot_web-0.1.0/src/pythonboot_web/request_context.py

@@ -0,0 +1,150 @@
+"""Access the HTTP request bound to the current execution context."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from http.cookies import SimpleCookie
+from threading import RLock
+from typing import Any
+
+from fastapi import Request
+from starlette.types import Message
+
+_current_request: ContextVar[Request | None] = ContextVar(
+    "pythonboot_current_request", default=None,
+)
+
+
+@dataclass
+class _RequestData:
+    values: dict[str, Any] = field(default_factory=dict)
+    lock: Any = field(default_factory=RLock)
+
+
+_current_data: ContextVar[_RequestData | None] = ContextVar(
+    "pythonboot_request_data", default=None,
+)
+_current_response: ContextVar["ResponseContext | None"] = ContextVar(
+    "pythonboot_current_response", default=None,
+)
+
+
+class ResponseContext:
+    """Mutable response settings applied before the ASGI response starts."""
+
+    def __init__(self) -> None:
+        self._status_code: int | None = None
+        self._headers: dict[bytes, bytes] = {}
+        self._cookies: list[bytes] = []
+        self._committed = False
+        self._lock = RLock()
+
+    @property
+    def status_code(self) -> int | None:
+        return self._status_code
+
+    @status_code.setter
+    def status_code(self, value: int) -> None:
+        if not isinstance(value, int) or not 100 <= value <= 599:
+            raise ValueError("status_code must be an integer between 100 and 599")
+        with self._lock:
+            self._ensure_mutable()
+            self._status_code = value
+
+    def set_header(self, name: str, value: str) -> None:
+        """Set a response header."""
+        if not isinstance(name, str) or not isinstance(value, str):
+            raise TypeError("response header name and value must be strings")
+        with self._lock:
+            self._ensure_mutable()
+            self._headers[name.encode("latin-1").lower()] = value.encode("latin-1")
+
+    def set_cookie(self, key: str, value: str, **options: Any) -> None:
+        """Add a Set-Cookie header."""
+        cookie = SimpleCookie()
+        cookie[key] = value
+        for name, option_value in options.items():
+            cookie[key][name.replace("_", "-")] = option_value
+        with self._lock:
+            self._ensure_mutable()
+            self._cookies.append(cookie.output(header="").strip().encode("latin-1"))
+
+    def redirect(self, url: str, status_code: int = 307) -> None:
+        """Set a redirect location and status code."""
+        self.status_code = status_code
+        self.set_header("Location", url)
+
+    def apply(self, message: Message) -> Message:
+        """Apply pending settings to an ASGI response-start message."""
+        with self._lock:
+            self._committed = True
+            headers = [
+                (name, value) for name, value in message.get("headers", [])
+                if name.lower() not in self._headers
+            ]
+            headers.extend(self._headers.items())
+            headers.extend((b"set-cookie", cookie) for cookie in self._cookies)
+            return {
+                **message,
+                "status": self._status_code if self._status_code is not None else message["status"],
+                "headers": headers,
+            }
+
+    def _ensure_mutable(self) -> None:
+        if self._committed:
+            raise RuntimeError("The HTTP response has already started")
+
+
+class RequestContextHolder:
+    """Expose the current request to controllers, services, and advice."""
+
+    @staticmethod
+    def get_request() -> Request:
+        request = _current_request.get()
+        if request is None:
+            raise RuntimeError("No HTTP request is bound to the current execution context")
+        return request
+
+    @staticmethod
+    def get_response() -> ResponseContext:
+        """Return the mutable response context for the current request."""
+        response = _current_response.get()
+        if response is None:
+            raise RuntimeError("No HTTP request is bound to the current execution context")
+        return response
+
+    @staticmethod
+    def putData(key: str, value: Any) -> None:
+        """Store a custom value in the current request's thread-safe map."""
+        data = RequestContextHolder._data()
+        with data.lock:
+            data.values[key] = value
+
+    @staticmethod
+    def getData(key: str, default: Any = None) -> Any:
+        """Read a custom value from the current request's thread-safe map."""
+        data = RequestContextHolder._data()
+        with data.lock:
+            return data.values.get(key, default)
+
+    @staticmethod
+    def _data() -> _RequestData:
+        data = _current_data.get()
+        if data is None:
+            raise RuntimeError("No HTTP request is bound to the current execution context")
+        return data
+
+    @staticmethod
+    @contextmanager
+    def use(request: Request, response: ResponseContext) -> Iterator[Request]:
+        """Bind a request temporarily and restore the previous binding on exit."""
+        token = _current_request.set(request)
+        data_token = _current_data.set(_RequestData())
+        response_token = _current_response.set(response)
+        try:
+            yield request
+        finally:
+            _current_response.reset(response_token)
+            _current_data.reset(data_token)
+            _current_request.reset(token)