python-platform 0.1.1__py3-none-any.whl

python_platform/notifications/__init__.py

@@ -0,0 +1,19 @@
+"""独立 typed 通知契约；provider 由 Host 选择。"""
+
+from .catalog import NotificationCatalog
+from .contracts import (
+    NotificationDefinition,
+    NotificationDefinitionError,
+    NotificationPayloadError,
+    NotificationPublishStatus,
+    Notifications,
+)
+
+__all__ = (
+    "NotificationCatalog",
+    "NotificationDefinition",
+    "NotificationDefinitionError",
+    "NotificationPayloadError",
+    "NotificationPublishStatus",
+    "Notifications",
+)

python_platform/notifications/catalog.py

@@ -0,0 +1,46 @@
+"""从已解析 Module 冻结通知声明；不依赖 Redis 或 Settings。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+from ..modularity import ModuleRegistry
+from .contracts import NotificationDefinition, NotificationDefinitionError
+
+
+class NotificationCatalog:
+    __slots__ = ("_definitions",)
+
+    def __init__(self, definitions: tuple[NotificationDefinition[Any], ...]) -> None:
+        indexed: dict[str, NotificationDefinition[Any]] = {}
+        for definition in definitions:
+            if not isinstance(definition, NotificationDefinition) or definition.name in indexed:
+                raise NotificationDefinitionError(
+                    "Notification declarations must have unique valid names"
+                )
+            indexed[definition.name] = definition
+        self._definitions: Mapping[str, NotificationDefinition[Any]] = MappingProxyType(indexed)
+
+    @property
+    def definitions(self) -> tuple[NotificationDefinition[Any], ...]:
+        return tuple(self._definitions.values())
+
+    def require_owned(self, definition: NotificationDefinition[Any]) -> None:
+        if self._definitions.get(definition.name) is not definition:
+            raise NotificationDefinitionError(
+                "Notification definition is not owned by this Application"
+            )
+
+
+def _build_notification_catalog(registry: ModuleRegistry) -> NotificationCatalog:
+    definitions: list[NotificationDefinition[Any]] = []
+    for descriptor in registry.dependency_order:
+        declared = descriptor.module_type.notification_definitions
+        if not isinstance(declared, tuple):
+            raise NotificationDefinitionError(
+                "Module notification_definitions must be an immutable tuple"
+            )
+        definitions.extend(declared)
+    return NotificationCatalog(tuple(definitions))

python_platform/notifications/contracts.py

@@ -0,0 +1,107 @@
+"""Typed Pub/Sub 契约；发布结果不代表送达或组件应用确认。"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from contextlib import AbstractAsyncContextManager
+from enum import Enum
+from typing import Generic, Protocol, TypeVar, cast
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+from ..configuration.immutability import (
+    _serialization_value,
+    freeze_typed_value,
+    validate_immutable_annotation,
+)
+from ..errors import FrameworkError
+
+_T = TypeVar("_T")
+
+
+class NotificationDefinitionError(FrameworkError):
+    """声明重复、类型不合法或引用不属于当前 Application。"""
+
+
+class NotificationPayloadError(FrameworkError):
+    """只暴露安全错误类型，不携带原始消息。"""
+
+
+class NotificationPublishStatus(str, Enum):
+    NOT_CONFIGURED = "not_configured"
+    PUBLISHED = "published"
+    UNAVAILABLE = "unavailable"
+    REJECTED = "rejected"
+
+
+class _NotificationEnvelope(BaseModel, Generic[_T]):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    payload: _T
+    traceparent: str | None = Field(default=None, max_length=512)
+
+
+class NotificationDefinition(Generic[_T]):
+    __slots__ = ("_adapter", "_name", "_value_type")
+
+    def __init__(self, name: str, value_type: type[_T]) -> None:
+        if (
+            not isinstance(name, str)
+            or re.fullmatch(r"[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*", name) is None
+        ):
+            raise NotificationDefinitionError(
+                "Notification name must be a canonical dotted identifier"
+            )
+        try:
+            validate_immutable_annotation(value_type)
+            self._adapter = TypeAdapter(_NotificationEnvelope[value_type])  # type: ignore[valid-type]
+        except (TypeError, ValueError):
+            raise NotificationDefinitionError(
+                "Notification payload type must support immutable JSON values"
+            ) from None
+        self._name = name
+        self._value_type = value_type
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def value_type(self) -> type[_T]:
+        return self._value_type
+
+    def _encode(self, payload: _T, carrier: Mapping[str, str]) -> bytes:
+        try:
+            payload = cast(_T, freeze_typed_value(payload, allow_secrets=True))
+            envelope = self._adapter.validate_python(
+                {"payload": payload, "traceparent": carrier.get("traceparent")}
+            )
+            return self._adapter.dump_json(
+                cast(_NotificationEnvelope[_T], _serialization_value(envelope))
+            )
+        except (TypeError, ValueError):
+            raise NotificationPayloadError("Invalid notification payload") from None
+
+    def _decode(self, encoded: bytes) -> tuple[_T, Mapping[str, str]]:
+        try:
+            envelope = self._adapter.validate_json(encoded)
+            value = cast(_T, freeze_typed_value(envelope.payload, allow_secrets=True))
+            carrier = {} if envelope.traceparent is None else {"traceparent": envelope.traceparent}
+            return value, carrier
+        except (TypeError, ValueError):
+            raise NotificationPayloadError("Invalid notification envelope") from None
+
+
+class Notifications(Protocol):
+    async def publish(
+        self, definition: NotificationDefinition[_T], payload: _T
+    ) -> NotificationPublishStatus: ...
+
+    def subscribe(
+        self,
+        definition: NotificationDefinition[_T],
+        handler: Callable[[_T], Awaitable[None]],
+        *,
+        on_reconnect: Callable[[], None] | None = None,
+    ) -> AbstractAsyncContextManager[None]: ...

python_platform/observability/__init__.py

@@ -0,0 +1,5 @@
+"""Host observability 配置；logging/tracing 集成分别由 optional extras 提供。"""
+
+from .options import LoggingOptions, TracingOptions
+
+__all__ = ("LoggingOptions", "TracingOptions")

python_platform/observability/context.py

@@ -0,0 +1,43 @@
+"""调用追踪边界；基础安装不加载 OpenTelemetry。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Tracer
+
+
+@contextmanager
+def invocation_span(
+    tracer: Tracer | None, name: str, *, carrier: Mapping[str, str] | None = None
+) -> Iterator[None]:
+    if tracer is None:
+        yield
+        return
+    from opentelemetry.trace import StatusCode
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+    context = None if carrier is None else TraceContextTextMapPropagator().extract(carrier)
+    # 异常类型由现有业务/任务边界处理，不复制可能含凭据的 exception.message。
+    with tracer.start_as_current_span(
+        name, context=context, record_exception=False, set_status_on_exception=False
+    ) as span:
+        try:
+            yield
+        except BaseException:
+            span.set_status(StatusCode.ERROR)
+            raise
+
+
+def capture_trace_context(tracer: Tracer | None) -> dict[str, str]:
+    if tracer is None:
+        return {}
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+    carrier: dict[str, str] = {}
+    TraceContextTextMapPropagator().inject(carrier)
+    # envelope 只传播最小父链路；不传播 baggage、tracestate、身份或任意 header。
+    return {key: value for key, value in carrier.items() if key == "traceparent"}

python_platform/observability/export.py

@@ -0,0 +1,73 @@
+"""OTLP 之前的安全数据边界，复用原生 exporter、batching 与 HTTP 传输。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.semconv.trace import SpanAttributes
+from opentelemetry.trace import Link, Status
+
+_LOGGER = logging.getLogger(__name__)
+# 这是导出的公开隐私契约；不按业务字段、模块或调用者维护第二份允许清单。
+_SAFE_ATTRIBUTES = frozenset(
+    {
+        SpanAttributes.HTTP_METHOD,
+        SpanAttributes.HTTP_ROUTE,
+        SpanAttributes.HTTP_STATUS_CODE,
+        "http.request.method",
+        "http.response.status_code",
+        "error.type",
+    }
+)
+
+
+class _SafeSpanExporter(SpanExporter):
+    def __init__(self, exporter: SpanExporter) -> None:
+        self._exporter = exporter
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        try:
+            return self._exporter.export(tuple(_safe_span(span) for span in spans))
+        except Exception as error:
+            _LOGGER.warning("Trace export failed (%s)", type(error).__name__)
+            return SpanExportResult.FAILURE
+
+    def shutdown(self) -> None:
+        self._exporter.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._exporter.force_flush(timeout_millis)
+
+
+def _safe_span(span: ReadableSpan) -> ReadableSpan:
+    # instrumentation 会自动产生 URL、exception event/status description；只转换导出副本，
+    # 不修改 SDK 正在使用的 span，也不让原始请求/任务值越过这个输出边界。
+    return ReadableSpan(
+        name=span.name,
+        context=span.context,
+        parent=span.parent,
+        resource=span.resource,
+        attributes={
+            key: value for key, value in (span.attributes or {}).items() if key in _SAFE_ATTRIBUTES
+        },
+        events=(),
+        links=tuple(Link(link.context) for link in span.links),
+        kind=span.kind,
+        status=Status(span.status.status_code),
+        start_time=span.start_time,
+        end_time=span.end_time,
+        instrumentation_scope=span.instrumentation_scope,
+    )
+
+
+class _ExportDiagnosticFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        # 官方 HTTP exporter 的 reason 来自远端响应/连接异常，不应作为日志正文输出。
+        record.msg = "OTLP exporter diagnostic"
+        record.args = ()
+        record.exc_info = None
+        record.exc_text = None
+        return True

python_platform/observability/formatting.py

@@ -0,0 +1,89 @@
+"""标准库安全输出边界，启动期与 Application 共用；不加载 logging extra。"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import time
+import traceback
+from copy import copy
+from types import TracebackType
+from typing import Any
+
+_DIAGNOSTIC_FIELDS = (
+    "background_worker",
+    "background_exception_type",
+    "audit_exception_type",
+    "audit_contract",
+    "audit_method",
+    "audit_route_template",
+)
+_HTTP_DIAGNOSTIC_LOGGERS = ("httpx", "httpcore", "uvicorn.access")
+
+
+def _safe_exception(info: Any) -> str:
+    # walk_tb 不取源码行或 locals；异常正文、notes 永远不进入输出。
+    if info[1] is None:
+        return "No active exception"
+    lines: list[str] = []
+    seen: set[int] = set()
+
+    def visit(
+        error: BaseException,
+        relation: str,
+        depth: int,
+        trace: TracebackType | None,
+    ) -> None:
+        prefix = "  " * depth + relation
+        if depth >= 32:
+            lines.append(prefix + "<exception depth limit>")
+            return
+        if id(error) in seen:
+            lines.append(prefix + "<exception reference cycle>")
+            return
+        seen.add(id(error))
+        lines.append(prefix + type(error).__qualname__)
+        for frame, lineno in traceback.walk_tb(trace):
+            lines.append(
+                f"{'  ' * (depth + 1)}{frame.f_code.co_filename}:{lineno} in {frame.f_code.co_name}"
+            )
+        if error.__cause__ is not None:
+            visit(error.__cause__, "cause: ", depth + 1, error.__cause__.__traceback__)
+        elif error.__context__ is not None and not error.__suppress_context__:
+            visit(error.__context__, "context: ", depth + 1, error.__context__.__traceback__)
+        if isinstance(error, BaseExceptionGroup):
+            for index, child in enumerate(error.exceptions):
+                visit(child, f"group[{index}]: ", depth + 1, child.__traceback__)
+
+    visit(info[1], "", 0, info[2])
+    return "\n".join(lines)
+
+
+class _SafeTextFormatter(logging.Formatter):
+    converter = staticmethod(time.gmtime)
+    _append_diagnostics = True
+
+    def formatException(self, ei: Any) -> str:
+        return _safe_exception(ei)
+
+    def format(self, record: logging.LogRecord) -> str:
+        safe_record = copy(record)
+        # handler 共享 record；清空其他 handler 的缓存及原生含源码的 stack_info。
+        safe_record.exc_text = None
+        safe_record.stack_info = None
+        if any(
+            record.name == name or record.name.startswith(name + ".")
+            for name in _HTTP_DIAGNOSTIC_LOGGERS
+        ):
+            safe_record.msg, safe_record.args = "HTTP transport diagnostic", ()
+        elif record.name == "uvicorn" or record.name.startswith("uvicorn."):
+            # Uvicorn 的 factory/lifespan 错误可能已把异常插入 message，不能格式化原正文。
+            safe_record.msg, safe_record.args = "ASGI server diagnostic", ()
+            if safe_record.exc_info is None and sys.exc_info()[0] is not None:
+                safe_record.exc_info = sys.exc_info()
+        rendered = super().format(safe_record)
+        if not self._append_diagnostics:
+            return rendered
+        return rendered + "".join(
+            f" {key}={record.__dict__[key]}" for key in _DIAGNOSTIC_FIELDS if key in record.__dict__
+        )

python_platform/observability/logging.py

@@ -0,0 +1,118 @@
+"""Host 配置标准 logging；业务使用 logging.getLogger，不需要新的日志 API。"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pythonjsonlogger.json import JsonFormatter
+
+from python_platform import ConfigureContext
+
+from ..application_services.invocation import _InvocationRuntime
+from ..lifecycle import PreInitializeContext, ShutdownContext
+from ..modularity import AppModule
+from .formatting import _DIAGNOSTIC_FIELDS, _SafeTextFormatter
+from .options import LoggingOptions
+
+_LOG_FIELDS = (
+    "asctime",
+    "levelname",
+    "name",
+    "application",
+    "environment",
+    "correlation_id",
+    "trace_id",
+    "span_id",
+    "message",
+)
+
+
+class ApplicationLogFilter(logging.Filter):
+    _application_logging = True
+
+    def __init__(self, runtime: _InvocationRuntime, options: LoggingOptions) -> None:
+        super().__init__()
+        self._runtime = runtime
+        self._options = options
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.application = self._options.application
+        record.environment = self._options.environment
+        record.correlation_id = self._runtime.diagnostic_correlation_id()
+        record.trace_id = None
+        record.span_id = None
+        if self._runtime.tracer is not None:
+            from opentelemetry.trace import get_current_span
+
+            context = get_current_span().get_span_context()
+            if context.is_valid:
+                record.trace_id = format(context.trace_id, "032x")
+                record.span_id = format(context.span_id, "016x")
+        return True
+
+
+class _SafeJsonFormatter(_SafeTextFormatter, JsonFormatter):
+    _append_diagnostics = False
+
+    def process_log_record(self, log_data: dict[str, Any]) -> dict[str, Any]:
+        # 默认不把任意 extra 字典（可能含 request/job payload）自动写入 JSON。
+        return {
+            key: value
+            for key, value in log_data.items()
+            if key in (*_LOG_FIELDS, *_DIAGNOSTIC_FIELDS, "exc_info")
+        }
+
+
+class StructuredLoggingModule(AppModule):
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(LoggingOptions, section="logging")
+
+    def __init__(self) -> None:
+        self._handler: logging.StreamHandler[Any] | None = None
+        self._previous_level: int | None = None
+        self._category_levels: dict[str, int] = {}
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        root = logging.getLogger()
+        if any(
+            isinstance(log_filter, ApplicationLogFilter)
+            for handler in root.handlers
+            for log_filter in handler.filters
+        ):
+            raise RuntimeError("one Host must own the process logging configuration")
+        options = context.options.get(LoggingOptions)
+        runtime = await context.container.get(_InvocationRuntime)
+        handler: logging.StreamHandler[Any] = logging.StreamHandler()
+        handler.addFilter(ApplicationLogFilter(runtime, options))
+        fields = " ".join(f"%({field})s" for field in _LOG_FIELDS)
+        formatter = (
+            _SafeJsonFormatter(fields) if options.format == "json" else _SafeTextFormatter(fields)
+        )
+        handler.setFormatter(formatter)
+        handler.setLevel(
+            min(
+                logging.getLevelName(level)
+                for level in (options.level, *options.logger_levels.values())
+            )
+        )
+        for name, level in options.logger_levels.items():
+            logger = logging.getLogger(name)
+            self._category_levels[name] = logger.level
+            logger.setLevel(level)
+        self._previous_level = root.level
+        root.setLevel(options.level)
+        root.addHandler(handler)
+        self._handler = handler
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        if self._handler is not None:
+            root = logging.getLogger()
+            root.removeHandler(self._handler)
+            self._handler.close()
+            self._handler = None
+            if self._previous_level is not None:
+                root.setLevel(self._previous_level)
+            for name, level in self._category_levels.items():
+                logging.getLogger(name).setLevel(level)
+            self._category_levels.clear()

python_platform/observability/options.py

@@ -0,0 +1,45 @@
+"""Host 显式选择日志输出及追踪导出；不从业务代码修改运行配置。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal
+from urllib.parse import urlsplit
+
+from pydantic import Field, model_validator
+
+from ..options import BaseOptions
+
+
+class LoggingOptions(BaseOptions):
+    application: str = Field(min_length=1)
+    environment: str = Field(min_length=1)
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+    format: Literal["text", "json"] = "text"
+    logger_levels: Mapping[str, Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]] = Field(
+        default_factory=dict
+    )
+
+    @model_validator(mode="after")
+    def _validate_logger_names(self) -> LoggingOptions:
+        if any(not name or name.strip() != name or name == "root" for name in self.logger_levels):
+            raise ValueError("logger_levels requires nonempty category names; root uses level")
+        return self
+
+
+class TracingOptions(BaseOptions):
+    service_name: str = Field(min_length=1)
+    export_enabled: bool = False
+    endpoint: str = "http://localhost:4318/v1/traces"
+    queue_size: int = Field(default=2048, ge=1)
+    batch_size: int = Field(default=512, ge=1)
+    export_timeout_seconds: float = Field(default=5, gt=0, le=30)
+
+    @model_validator(mode="after")
+    def _validate_export(self) -> TracingOptions:
+        target = urlsplit(self.endpoint)
+        if target.scheme not in ("http", "https") or not target.hostname or target.username:
+            raise ValueError("OTLP endpoint must be an HTTP URL without credentials")
+        if self.batch_size > self.queue_size:
+            raise ValueError("trace batch size cannot exceed queue size")
+        return self

python_platform/observability/tracing.py

@@ -0,0 +1,80 @@
+"""Application-owned OpenTelemetry SDK，Host 按需启用有界 OTLP 导出。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from dishka import Provider, Scope
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from ..application_services.invocation import _InvocationRuntime
+from ..lifecycle import ConfigureContext, PreInitializeContext, ShutdownContext
+from ..modularity import AppModule
+from ..options import Options
+from .export import _ExportDiagnosticFilter, _SafeSpanExporter
+from .options import TracingOptions
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class TracingModule(AppModule):
+    def __init__(self) -> None:
+        self._provider: TracerProvider | None = None
+        self._export_filter: _ExportDiagnosticFilter | None = None
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(TracingOptions, section="tracing")
+        provider = Provider()
+        provider.provide(self._prepare, provides=TracerProvider, scope=Scope.APP)
+        context.services.contribute(provider, reason="Application-owned OpenTelemetry provider")
+
+    def _prepare(self, options: Options[TracingOptions]) -> TracerProvider:
+        if self._provider is None:
+            # Web 安装可先取得 provider；此时没有 exporter/thread/I/O。导出只在 runtime 启动。
+            self._provider = TracerProvider(
+                resource=Resource({"service.name": options.value.service_name}),
+                shutdown_on_exit=False,
+            )
+        return self._provider
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        options = context.options.get(TracingOptions)
+        provider = await context.container.get(TracerProvider)
+        runtime = await context.container.get(_InvocationRuntime)
+        runtime.tracer = provider.get_tracer(__package__)
+        if options.export_enabled:
+            self._export_filter = _ExportDiagnosticFilter()
+            logging.getLogger(OTLPSpanExporter.__module__).addFilter(self._export_filter)
+            provider.add_span_processor(
+                BatchSpanProcessor(
+                    _SafeSpanExporter(
+                        OTLPSpanExporter(
+                            endpoint=options.endpoint, timeout=options.export_timeout_seconds
+                        )
+                    ),
+                    max_queue_size=options.queue_size,
+                    max_export_batch_size=options.batch_size,
+                    export_timeout_millis=options.export_timeout_seconds * 1000,
+                )
+            )
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        if self._provider is None:
+            return
+        runtime = await context.container.get(_InvocationRuntime)
+        runtime.tracer = None
+        try:
+            # SDK BatchSpanProcessor 自身限制关闭等待；等待原生关闭结束再撤销输出过滤，
+            # 不取消 to_thread 留下仍在导出、却已失去生命周期 owner 的后台工作。
+            await asyncio.to_thread(self._provider.shutdown)
+        except Exception as error:
+            _LOGGER.warning("Trace shutdown failed (%s)", type(error).__name__)
+        finally:
+            if self._export_filter is not None:
+                logging.getLogger(OTLPSpanExporter.__module__).removeFilter(self._export_filter)
+                self._export_filter = None
+            self._provider = None

python_platform/options/__init__.py

@@ -0,0 +1,19 @@
+"""Typed Options public contracts and Application-internal binding owner."""
+
+from .models import (
+    BaseOptions,
+    Options,
+    OptionsContribution,
+    OptionsSnapshot,
+    OptionsValidationIssue,
+    PreOptionsSnapshot,
+)
+
+__all__ = (
+    "BaseOptions",
+    "Options",
+    "OptionsContribution",
+    "OptionsSnapshot",
+    "OptionsValidationIssue",
+    "PreOptionsSnapshot",
+)