celerity-sdk 0.2.0__py3-none-any.whl

celerity/__init__.py

@@ -0,0 +1,114 @@
+"""Celerity Python SDK - Build Celerity applications with Python."""
+
+__version__ = "0.1.0"
+
+# Decorators
+# Parameter types
+from celerity.decorators import (
+    Auth,
+    Body,
+    ConnectionId,
+    ConsumerEvent,
+    ConsumerTraceContext,
+    ConsumerVendor,
+    Cookies,
+    EventType,
+    Headers,
+    InvokeContext,
+    MessageBody,
+    MessageId,
+    Messages,
+    Param,
+    Payload,
+    Query,
+    Req,
+    RequestContext,
+    RequestId,
+    ScheduleExpression,
+    ScheduleId,
+    ScheduleInput,
+    Token,
+    action,
+    consumer,
+    controller,
+    delete,
+    get,
+    guard,
+    head,
+    inject,
+    injectable,
+    invoke,
+    message_handler,
+    module,
+    on_connect,
+    on_disconnect,
+    on_message,
+    options,
+    patch,
+    post,
+    protected_by,
+    public,
+    put,
+    schedule_handler,
+    set_handler_metadata,
+    use_layer,
+    use_layers,
+    use_resource,
+    ws_controller,
+)
+
+__all__ = [
+    # Parameter types
+    "Auth",
+    "Body",
+    "ConnectionId",
+    "ConsumerEvent",
+    "ConsumerTraceContext",
+    "ConsumerVendor",
+    "Cookies",
+    "EventType",
+    "Headers",
+    "InvokeContext",
+    "MessageBody",
+    "MessageId",
+    "Messages",
+    "Param",
+    "Payload",
+    "Query",
+    "Req",
+    "RequestContext",
+    "RequestId",
+    "ScheduleExpression",
+    "ScheduleId",
+    "ScheduleInput",
+    "Token",
+    "__version__",
+    # Decorators
+    "action",
+    "consumer",
+    "controller",
+    "delete",
+    "get",
+    "guard",
+    "head",
+    "inject",
+    "injectable",
+    "invoke",
+    "message_handler",
+    "module",
+    "on_connect",
+    "on_disconnect",
+    "on_message",
+    "options",
+    "patch",
+    "post",
+    "protected_by",
+    "public",
+    "put",
+    "schedule_handler",
+    "set_handler_metadata",
+    "use_layer",
+    "use_layers",
+    "use_resource",
+    "ws_controller",
+]

celerity/application.py

@@ -0,0 +1,83 @@
+"""Application classes and factory."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from celerity.bootstrap.bootstrap import bootstrap
+from celerity.layers.dispose import dispose_layers
+from celerity.layers.system import create_default_system_layers
+
+if TYPE_CHECKING:
+    from celerity.bootstrap.module_graph import ModuleGraph
+    from celerity.di.container import Container
+    from celerity.handlers.registry import HandlerRegistry
+
+logger = logging.getLogger("celerity.factory")
+
+
+class CelerityApplication:
+    """Standard application with handler registry and DI container.
+
+    Created via ``CelerityFactory.create()``. Holds the bootstrapped
+    container, handler registry, and layer pipeline configuration.
+    """
+
+    def __init__(
+        self,
+        registry: HandlerRegistry,
+        container: Container,
+        graph: ModuleGraph,
+        system_layers: list[Any] | None = None,
+    ) -> None:
+        self.registry = registry
+        self.container = container
+        self.graph = graph
+        self.system_layers = system_layers or []
+
+    async def close(self) -> None:
+        """Shut down the application, disposing layers and closing resources."""
+        await dispose_layers(self.system_layers)
+        await self.container.close_all()
+
+    def get_container(self) -> Container:
+        """Get the DI container."""
+        return self.container
+
+    def get_registry(self) -> HandlerRegistry:
+        """Get the handler registry."""
+        return self.registry
+
+
+class CelerityFactory:
+    """Factory for creating application instances."""
+
+    @staticmethod
+    async def create(
+        root_module: type,
+        *,
+        layers: list[Any] | None = None,
+    ) -> CelerityApplication:
+        """Create and bootstrap a ``CelerityApplication``.
+
+        Args:
+            root_module: The root ``@module``-decorated class.
+            layers: Optional application-level layers to add after
+                system layers.
+
+        Returns:
+            A bootstrapped application ready to handle requests.
+
+        Example::
+
+            app = await CelerityFactory.create(AppModule)
+            # use app.registry, app.container
+            await app.close()
+        """
+        container, registry, graph = await bootstrap(root_module)
+        system_layers = create_default_system_layers()
+        logger.debug("create: %d system layers", len(system_layers))
+        if layers:
+            system_layers.extend(layers)
+        return CelerityApplication(registry, container, graph, system_layers)

celerity/bootstrap/__init__.py

@@ -0,0 +1,13 @@
+"""Application bootstrap and module graph."""
+
+from celerity.bootstrap.module_graph import (
+    build_module_graph,
+    register_module_graph,
+    walk_module_graph,
+)
+
+__all__ = [
+    "build_module_graph",
+    "register_module_graph",
+    "walk_module_graph",
+]

celerity/bootstrap/bootstrap.py

@@ -0,0 +1,70 @@
+"""Application bootstrap entry point."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import celerity.common.debug as _  # noqa: F401
+from celerity.bootstrap.module_graph import walk_module_graph
+from celerity.di.container import Container
+from celerity.handlers.registry import HandlerRegistry
+from celerity.handlers.scanners.consumer import scan_consumer_handlers
+from celerity.handlers.scanners.custom import scan_custom_handlers
+from celerity.handlers.scanners.http import scan_http_guards, scan_http_handlers
+from celerity.handlers.scanners.schedule import scan_schedule_handlers
+from celerity.handlers.scanners.websocket import scan_websocket_handlers
+
+if TYPE_CHECKING:
+    from celerity.bootstrap.module_graph import ModuleGraph
+
+logger = logging.getLogger("celerity.bootstrap")
+
+
+async def bootstrap(
+    root_module: type,
+) -> tuple[Container, HandlerRegistry, ModuleGraph]:
+    """Bootstrap the DI container and handler registry from a root module.
+
+    Performs the full application bootstrap sequence:
+
+    1. Create ``Container`` and ``HandlerRegistry``
+    2. Walk the module graph (build + register providers)
+    3. Scan HTTP handlers and guards
+    4. Scan WebSocket handlers
+    5. Scan consumer handlers
+    6. Scan schedule handlers
+    7. Scan custom handlers
+
+    Args:
+        root_module: The root ``@module``-decorated class.
+
+    Returns:
+        A tuple of ``(container, registry, graph)``.
+
+    Example::
+
+        @module(controllers=[OrderController], providers=[OrderService])
+        class AppModule:
+            pass
+
+        container, registry, graph = await bootstrap(AppModule)
+    """
+    logger.debug("bootstrap: starting from %s", root_module.__name__)
+    container = Container()
+    registry = HandlerRegistry()
+
+    graph = walk_module_graph(root_module, container)
+    await scan_http_handlers(graph, container, registry)
+    await scan_http_guards(graph, container, registry)
+    await scan_websocket_handlers(graph, container, registry)
+    await scan_consumer_handlers(graph, container, registry)
+    await scan_schedule_handlers(graph, container, registry)
+    await scan_custom_handlers(graph, container, registry)
+
+    logger.debug(
+        "bootstrap: complete — %d handlers, %d guards",
+        len(registry.get_all_handlers()),
+        len(registry.get_all_guards()),
+    )
+    return container, registry, graph

celerity/bootstrap/discovery.py

@@ -0,0 +1,67 @@
+"""Root module discovery for runtime and serverless modes."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import sys
+from pathlib import Path
+
+from celerity.metadata.keys import MODULE, get_metadata
+
+logger = logging.getLogger("celerity.bootstrap")
+
+
+def discover_module(module_path: str | None = None) -> type:
+    """Discover the root ``@module`` class.
+
+    Resolution order:
+
+    1. Explicit ``module_path`` argument
+    2. ``CELERITY_MODULE_PATH`` environment variable
+    3. Raises ``RuntimeError``
+
+    The path is converted to a Python module name, imported, and
+    scanned for a class decorated with ``@module``.
+
+    Args:
+        module_path: Optional explicit path to the module file.
+
+    Returns:
+        The root ``@module``-decorated class.
+
+    Raises:
+        RuntimeError: If no module path is found or no ``@module``
+            class exists in the module.
+    """
+    resolved = module_path or os.environ.get("CELERITY_MODULE_PATH")
+    if not resolved:
+        msg = "No module path provided. Set CELERITY_MODULE_PATH or pass module_path explicitly."
+        raise RuntimeError(msg)
+
+    logger.debug("discover_module: loading %s", resolved)
+
+    path = Path(resolved)
+
+    # Ensure the parent directory is importable.
+    parent = str(path.parent.resolve())
+    if parent not in sys.path:
+        sys.path.insert(0, parent)
+
+    module_name = _path_to_module_name(path)
+    imported = importlib.import_module(module_name)
+
+    for name in dir(imported):
+        obj = getattr(imported, name)
+        if isinstance(obj, type) and get_metadata(obj, MODULE) is not None:
+            logger.debug("discover_module: found %s", obj.__name__)
+            return obj
+
+    msg = f"No @module class found in {resolved}"
+    raise RuntimeError(msg)
+
+
+def _path_to_module_name(path: Path) -> str:
+    """Convert a file path to a Python module name."""
+    return path.with_suffix("").name

celerity/bootstrap/module_graph.py

@@ -0,0 +1,158 @@
+"""Module graph builder and DI registrar."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from celerity.metadata.keys import MODULE, get_metadata
+
+if TYPE_CHECKING:
+    from celerity.di.container import Container
+    from celerity.types.container import Provider
+    from celerity.types.module import (
+        FunctionHandlerDefinition,
+        GuardDefinition,
+        ModuleMetadata,
+    )
+
+logger = logging.getLogger("celerity.bootstrap")
+
+
+@dataclass
+class ModuleNode:
+    """A single node in the module dependency graph."""
+
+    module_class: type
+    own_tokens: set[Any] = field(default_factory=set)
+    exports: set[Any] = field(default_factory=set)
+    imports: list[type] = field(default_factory=list)
+    controllers: list[type] = field(default_factory=list)
+    function_handlers: list[FunctionHandlerDefinition] = field(default_factory=list)
+    guards: list[type | GuardDefinition] = field(default_factory=list)
+    providers: list[type | Provider] = field(default_factory=list)
+    layers: list[Any] = field(default_factory=list)
+
+
+type ModuleGraph = dict[type, ModuleNode]
+
+
+def build_module_graph(root_module: type) -> ModuleGraph:
+    """Walk the module tree depth-first, collecting metadata.
+
+    Args:
+        root_module: The root ``@module``-decorated class.
+
+    Returns:
+        A dict mapping each module class to its ``ModuleNode``.
+
+    Raises:
+        RuntimeError: If a circular module import is detected.
+
+    Example::
+
+        @module(controllers=[OrderController], providers=[OrderService])
+        class AppModule:
+            pass
+
+        graph = build_module_graph(AppModule)
+    """
+    logger.debug("build_module_graph: starting from %s", root_module.__name__)
+    graph: ModuleGraph = {}
+    resolving: set[type] = set()
+
+    def walk(module_class: type, import_chain: list[type]) -> None:
+        if module_class in graph:
+            return
+
+        if module_class in resolving:
+            cycle = " -> ".join(m.__name__ for m in [*import_chain, module_class])
+            raise RuntimeError(f"Circular module import detected: {cycle}")
+
+        resolving.add(module_class)
+        metadata: ModuleMetadata | None = get_metadata(module_class, MODULE)
+
+        if metadata is None:
+            resolving.discard(module_class)
+            graph[module_class] = ModuleNode(module_class=module_class)
+            return
+
+        logger.debug(
+            "walk %s: %d providers, %d controllers, %d guards, %d imports",
+            module_class.__name__,
+            len(metadata.providers or []),
+            len(metadata.controllers or []),
+            len(metadata.guards or []),
+            len(metadata.imports or []),
+        )
+
+        for imported in metadata.imports or []:
+            walk(imported, [*import_chain, module_class])
+
+        own_tokens: set[Any] = set()
+        for provider in metadata.providers or []:
+            own_tokens.add(provider)
+
+        for ctrl in metadata.controllers or []:
+            own_tokens.add(ctrl)
+
+        for g in metadata.guards or []:
+            if isinstance(g, type):
+                own_tokens.add(g)
+
+        resolving.discard(module_class)
+        graph[module_class] = ModuleNode(
+            module_class=module_class,
+            own_tokens=own_tokens,
+            exports=set(metadata.exports or []),
+            imports=metadata.imports or [],
+            controllers=metadata.controllers or [],
+            function_handlers=metadata.function_handlers or [],
+            guards=metadata.guards or [],
+            providers=metadata.providers or [],
+            layers=metadata.layers or [],
+        )
+
+    walk(root_module, [])
+    logger.debug("build_module_graph: complete — %d modules", len(graph))
+    return graph
+
+
+def register_module_graph(graph: ModuleGraph, container: Container) -> None:
+    """Register all providers from the module graph into a DI container.
+
+    Args:
+        graph: The module graph built by ``build_module_graph``.
+        container: The DI container to register providers in.
+    """
+
+    for node in graph.values():
+        for provider in node.providers:
+            if isinstance(provider, type):
+                container.register_class(provider)
+            else:
+                container.register(provider, provider)
+
+        for ctrl in node.controllers:
+            if not container.has(ctrl):
+                container.register_class(ctrl)
+
+        for g in node.guards:
+            if isinstance(g, type) and not container.has(g):
+                container.register_class(g)
+
+
+def walk_module_graph(root_module: type, container: Container) -> ModuleGraph:
+    """Build the module graph and register all providers in one call.
+
+    Args:
+        root_module: The root ``@module``-decorated class.
+        container: The DI container to register providers in.
+
+    Returns:
+        The built module graph.
+    """
+    graph = build_module_graph(root_module)
+    register_module_graph(graph, container)
+    return graph