pythonboot 0.1.0__py3-none-any.whl

pythonboot/__init__.py

@@ -0,0 +1,41 @@
+"""PythonBoot public interfaces."""
+
+from pythonboot.aop import (
+    JoinPoint, MethodAnnotation, MethodInfo, Pointcut, ProceedingJoinPoint, annotation,
+    after, after_returning, after_throwing, around, aspect, before, pointcut,
+)
+from pythonboot.beans import Scope, bean, component, configuration, ondestroy, postconstruct, service
+from pythonboot.boot import auto_configuration
+from pythonboot.beans.conditions import (
+    conditional_on_bean, conditional_on_missing_bean,
+    conditional_on_module, conditional_on_property,
+)
+from pythonboot.context import ApplicationContext, autowired
+from pythonboot.config import ConfigurationPropertiesOptions, configuration_properties
+from pythonboot.util import ContextUtil
+from pythonboot.task import RejectionPolicy, TaskExecutor, TaskRejectedError, ThreadPoolTaskExecutor
+from pythonboot.transaction import (
+    AsyncPlatformTransactionManager, AsyncSavepointManager, Isolation,
+    PlatformTransactionManager, Propagation, SavepointManager,
+    TransactionAttribute, TransactionDefinition, TransactionInterceptor, TransactionStatus,
+    get_transaction_attribute, transactional,
+)
+
+__all__ = [
+    "auto_configuration", "conditional_on_bean", "conditional_on_missing_bean",
+    "conditional_on_module", "conditional_on_property",
+    "ApplicationContext", "bean", "component", "configuration", "service",
+    "aspect", "pointcut", "before", "after", "after_returning", "after_throwing", "around",
+    "JoinPoint", "ProceedingJoinPoint", "MethodInfo", "Pointcut",
+    "annotation", "MethodAnnotation",
+    "autowired",
+    "Scope",
+    "ContextUtil",
+    "TaskExecutor", "ThreadPoolTaskExecutor", "TaskRejectedError", "RejectionPolicy",
+    "postconstruct", "ondestroy",
+    "configuration_properties", "ConfigurationPropertiesOptions",
+    "Propagation", "Isolation", "TransactionDefinition", "TransactionAttribute",
+    "TransactionStatus", "PlatformTransactionManager", "AsyncPlatformTransactionManager",
+    "SavepointManager", "AsyncSavepointManager", "transactional", "get_transaction_attribute",
+    "TransactionInterceptor",
+]

pythonboot/aop/__init__.py

@@ -0,0 +1,11 @@
+"""Public AOP declarations and invocation contexts."""
+
+from pythonboot.aop.decorators import after, after_returning, after_throwing, around, aspect, before
+from pythonboot.aop.joinpoint import JoinPoint, ProceedingJoinPoint
+from pythonboot.aop.pointcut import MethodAnnotation, MethodInfo, Pointcut, annotation, pointcut
+
+__all__ = [
+    "aspect", "pointcut", "before", "after", "after_returning", "after_throwing", "around",
+    "JoinPoint", "ProceedingJoinPoint", "MethodInfo", "Pointcut",
+    "annotation", "MethodAnnotation",
+]

pythonboot/aop/decorators.py

@@ -0,0 +1,75 @@
+"""Aspect and advice declarations without decoration-time instantiation."""
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, TypeVar
+
+from pythonboot.aop.pointcut import MethodAnnotation, MethodInfo, Pointcut
+from pythonboot.beans import Scope, component
+
+T = TypeVar("T", bound=type)
+F = TypeVar("F", bound=Callable[..., Any])
+AdviceKind = Literal["before", "after", "after_returning", "after_throwing", "around"]
+Cut = str | Pointcut | MethodAnnotation | Callable[[MethodInfo], bool]
+
+
+@dataclass(frozen=True)
+class AdviceDefinition:
+    kind: AdviceKind
+    pointcut: Pointcut
+    order: int
+
+
+def aspect(
+    cls: T | None = None, *, order: int = 0, 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 aspect; lower order values enter the advice chain first."""
+    def decorate(target: T) -> T:
+        if not inspect.isclass(target):
+            raise TypeError("@aspect 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_aspect__ = order
+        return target
+
+    return decorate(cls) if cls is not None else decorate
+
+
+def _advice(kind: AdviceKind, cut: Cut, order: int) -> Callable[[F], F]:
+    matcher = cut if isinstance(cut, Pointcut) else Pointcut(cut)
+
+    def decorate(method: F) -> F:
+        if not inspect.isfunction(method):
+            raise TypeError("Advice must be declared as an aspect instance method")
+        definitions = list(getattr(method, "__pythonboot_advices__", ()))
+        definitions.append(AdviceDefinition(kind, matcher, order))
+        method.__pythonboot_advices__ = tuple(definitions)
+        return method
+
+    return decorate
+
+
+def before(cut: Cut, *, order: int = 0) -> Callable[[F], F]:
+    return _advice("before", cut, order)
+
+
+def after(cut: Cut, *, order: int = 0) -> Callable[[F], F]:
+    return _advice("after", cut, order)
+
+
+def after_returning(cut: Cut, *, order: int = 0) -> Callable[[F], F]:
+    return _advice("after_returning", cut, order)
+
+
+def after_throwing(cut: Cut, *, order: int = 0) -> Callable[[F], F]:
+    return _advice("after_throwing", cut, order)
+
+
+def around(cut: Cut, *, order: int = 0) -> Callable[[F], F]:
+    return _advice("around", cut, order)

pythonboot/aop/joinpoint.py

@@ -0,0 +1,33 @@
+"""Context for a method invocation."""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class JoinPoint:
+    bean_name: str
+    target: Any
+    method: Callable[..., Any]
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
+
+    @property
+    def method_name(self) -> str:
+        return self.method.__name__
+
+    @property
+    def qualified_name(self) -> str:
+        cls = type(self.target)
+        return f"{cls.__module__}.{cls.__qualname__}.{self.method_name}"
+
+
+@dataclass
+class ProceedingJoinPoint(JoinPoint):
+    _proceed: Callable[..., Any] = field(repr=False)
+
+    def proceed(self, *args: Any, **kwargs: Any) -> Any:
+        """Proceed with current arguments, or replace all arguments when supplied."""
+        if not args and not kwargs:
+            return self._proceed(*self.args, **self.kwargs)
+        return self._proceed(*args, **kwargs)

pythonboot/aop/pointcut.py

@@ -0,0 +1,81 @@
+"""Pointcuts based on qualified method names, annotations, or predicates."""
+
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+import inspect
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(frozen=True)
+class MethodInfo:
+    bean_name: str
+    target_type: type
+    method_name: str
+    method: Callable[..., Any]
+
+    @property
+    def qualified_name(self) -> str:
+        return f"{self.target_type.__module__}.{self.target_type.__qualname__}.{self.method_name}"
+
+
+@dataclass(frozen=True)
+class MethodAnnotation:
+    name: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise ValueError("Aspect annotation names must be non-empty strings")
+
+    def __call__(self, method: F) -> F:
+        """Mark a business method without changing its signature or coroutine type."""
+        if not inspect.isfunction(method):
+            raise TypeError("Aspect annotations can only decorate instance methods")
+        names = frozenset(getattr(method, "__pythonboot_annotations__", ()))
+        method.__pythonboot_annotations__ = names | {self.name}
+        return method
+
+    def matches(self, method: MethodInfo) -> bool:
+        return self.name in getattr(method.method, "__pythonboot_annotations__", ())
+
+
+def annotation(name: str) -> MethodAnnotation:
+    """Create an aspect annotation usable as @logged and @around(logged)."""
+    return MethodAnnotation(name)
+
+
+def _matches(pattern: tuple[str, ...], name: tuple[str, ...]) -> bool:
+    if not pattern:
+        return not name
+    if pattern[0] == "**":
+        return _matches(pattern[1:], name) or (
+            bool(name) and _matches(pattern, name[1:])
+        )
+    return bool(name) and fnmatchcase(name[0], pattern[0]) and _matches(pattern[1:], name[1:])
+
+
+@dataclass(frozen=True)
+class Pointcut:
+    expression: str | MethodAnnotation | Callable[[MethodInfo], bool]
+
+    def __post_init__(self) -> None:
+        if isinstance(self.expression, str):
+            if not self.expression or any(
+                not part or ("**" in part and part != "**")
+                for part in self.expression.split(".")
+            ):
+                raise ValueError("Pointcut expressions must not be empty; ** must occupy an entire segment")
+        elif not callable(self.expression):
+            raise TypeError("Pointcuts must be method path expressions, annotations, or matching functions")
+
+    def matches(self, method: MethodInfo) -> bool:
+        if isinstance(self.expression, MethodAnnotation):
+            return self.expression.matches(method)
+        if callable(self.expression):
+            return bool(self.expression(method))
+        return _matches(tuple(self.expression.split(".")), tuple(method.qualified_name.split(".")))
+
+
+def pointcut(expression: str | MethodAnnotation | Callable[[MethodInfo], bool]) -> Pointcut:
+    return Pointcut(expression)

pythonboot/aop/proxy.py

@@ -0,0 +1,196 @@
+"""Application-scoped bean proxies and synchronous or asynchronous advice chains."""
+
+import inspect
+from dataclasses import dataclass
+from functools import wraps
+import sys
+from typing import Any, Callable
+
+import wrapt
+
+from pythonboot.aop.decorators import AdviceDefinition
+from pythonboot.aop.joinpoint import JoinPoint, ProceedingJoinPoint
+from pythonboot.aop.pointcut import MethodInfo
+from pythonboot.exceptions import AopError
+from pythonboot.transaction.interceptor import TransactionInterceptor
+
+
+@dataclass(frozen=True)
+class Advisor:
+    bean_name: str
+    aspect_type: type
+    method_name: str
+    method: Callable[..., Any]
+    definition: AdviceDefinition
+    aspect_order: int
+
+
+class BeanProxy(wrapt.ObjectProxy):
+    def __init__(self, target: Any, methods: dict[str, Callable[..., Any]]) -> None:
+        super().__init__(target)
+        self._self_methods = methods
+
+    def __getattr__(self, name: str) -> Any:
+        if name in self._self_methods:
+            return self._self_methods[name]
+        return getattr(self.__wrapped__, name)
+
+
+class AopEngine:
+    def __init__(
+        self, beans: tuple[tuple[str, type], ...],
+        resolver: Callable[[type, str | None], Any],
+        *, async_resolver: Callable[[type, str | None], Any] | None = None,
+    ) -> None:
+        self._resolver = resolver
+        self._transaction_interceptor = TransactionInterceptor(resolver, async_resolver)
+        transaction_advice = TransactionInterceptor.invoke.__pythonboot_advices__[0]
+        advisors: list[Advisor] = [Advisor(
+            "pythonboot.transactionInterceptor", TransactionInterceptor, "invoke",
+            TransactionInterceptor.invoke, transaction_advice, -sys.maxsize - 1,
+        )]
+        for bean_name, cls in beans:
+            if not hasattr(cls, "__pythonboot_aspect__"):
+                continue
+            for method_name, method in inspect.getmembers(cls, inspect.isfunction):
+                definitions = getattr(method, "__pythonboot_advices__", ())
+                if not definitions:
+                    continue
+                descriptor = inspect.getattr_static(cls, method_name)
+                if isinstance(descriptor, (staticmethod, classmethod)):
+                    raise AopError("Aspect advice must use instance methods")
+                if inspect.isgeneratorfunction(method) or inspect.isasyncgenfunction(method):
+                    raise AopError("Aspect advice does not support generators")
+                for definition in definitions:
+                    parameter_count = 2 if definition.kind in ("after_returning", "after_throwing") else 1
+                    try:
+                        inspect.signature(method).bind(object(), *[object() for _ in range(parameter_count)])
+                    except TypeError as error:
+                        raise AopError(f"Invalid advice signature: {cls.__name__}.{method_name}") from error
+                    advisors.append(Advisor(
+                        bean_name, cls, method_name, method, definition,
+                        cls.__pythonboot_aspect__,
+                    ))
+        self._advisors = tuple(sorted(advisors, key=lambda item: (
+            item.aspect_order, item.definition.order, item.bean_name, item.method_name,
+        )))
+
+    def create_proxy(
+        self, target: Any, bean_name: str, *, excluded_methods: tuple[str, ...] = (),
+    ) -> Any:
+        if not self._advisors or hasattr(type(target), "__pythonboot_aspect__"):
+            return target
+        methods: dict[str, Callable[..., Any]] = {}
+        for method_name, method in inspect.getmembers(type(target), inspect.isfunction):
+            if method_name.startswith("_") or method_name in excluded_methods:
+                continue
+            descriptor = inspect.getattr_static(type(target), method_name)
+            if isinstance(descriptor, (staticmethod, classmethod)):
+                continue
+            info = MethodInfo(bean_name, type(target), method_name, method)
+            advisors = tuple(item for item in self._advisors if item.definition.pointcut.matches(info))
+            if not advisors:
+                continue
+            if inspect.isgeneratorfunction(method) or inspect.isasyncgenfunction(method):
+                raise AopError(f"AOP does not support generator methods: {info.qualified_name}")
+            is_async = inspect.iscoroutinefunction(method)
+            if not is_async and any(inspect.iscoroutinefunction(item.method) for item in advisors):
+                raise AopError(f"Synchronous methods cannot match asynchronous advice: {info.qualified_name}")
+            methods[method_name] = self._wrap(getattr(target, method_name), target, bean_name, advisors, is_async)
+        return BeanProxy(target, methods) if methods else target
+
+    def _advice(self, advisor: Advisor) -> Callable[..., Any]:
+        if advisor.aspect_type is TransactionInterceptor:
+            return self._transaction_interceptor.invoke
+        aspect = self._resolver(advisor.aspect_type, advisor.bean_name)
+        return getattr(aspect, advisor.method_name)
+
+    @staticmethod
+    def _sync_result(result: Any) -> Any:
+        if inspect.isawaitable(result):
+            if inspect.iscoroutine(result):
+                result.close()
+            raise AopError("Synchronous advice returned an awaitable; use synchronous advice or declare the target method as async")
+        return result
+
+    @staticmethod
+    async def _async_result(result: Any) -> Any:
+        return await result if inspect.isawaitable(result) else result
+
+    def _wrap(
+        self, method: Callable[..., Any], target: Any, bean_name: str,
+        advisors: tuple[Advisor, ...], is_async: bool,
+    ) -> Callable[..., Any]:
+        def invoke(index: int, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            if index == len(advisors):
+                return self._sync_result(method(*args, **kwargs))
+            advisor = advisors[index]
+            advice = self._advice(advisor)
+            kind = advisor.definition.kind
+            jp = JoinPoint(bean_name, target, method, args, dict(kwargs))
+
+            def proceed(*next_args: Any, **next_kwargs: Any) -> Any:
+                return invoke(index + 1, next_args, next_kwargs)
+
+            if kind == "around":
+                pjp = ProceedingJoinPoint(bean_name, target, method, args, dict(kwargs), proceed)
+                return self._sync_result(advice(pjp))
+            if kind == "before":
+                self._sync_result(advice(jp))
+                return proceed(*jp.args, **jp.kwargs)
+            if kind == "after":
+                try:
+                    return proceed(*jp.args, **jp.kwargs)
+                finally:
+                    self._sync_result(advice(jp))
+            if kind == "after_throwing":
+                try:
+                    return proceed(*jp.args, **jp.kwargs)
+                except BaseException as error:
+                    self._sync_result(advice(jp, error))
+                    raise
+            result = proceed(*jp.args, **jp.kwargs)
+            self._sync_result(advice(jp, result))
+            return result
+
+        async def invoke_async(index: int, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            if index == len(advisors):
+                return await self._async_result(method(*args, **kwargs))
+            advisor = advisors[index]
+            advice = self._advice(advisor)
+            kind = advisor.definition.kind
+            jp = JoinPoint(bean_name, target, method, args, dict(kwargs))
+
+            async def proceed(*next_args: Any, **next_kwargs: Any) -> Any:
+                return await invoke_async(index + 1, next_args, next_kwargs)
+
+            if kind == "around":
+                pjp = ProceedingJoinPoint(bean_name, target, method, args, dict(kwargs), proceed)
+                return await self._async_result(advice(pjp))
+            if kind == "before":
+                await self._async_result(advice(jp))
+                return await proceed(*jp.args, **jp.kwargs)
+            if kind == "after":
+                try:
+                    return await proceed(*jp.args, **jp.kwargs)
+                finally:
+                    await self._async_result(advice(jp))
+            if kind == "after_throwing":
+                try:
+                    return await proceed(*jp.args, **jp.kwargs)
+                except BaseException as error:
+                    await self._async_result(advice(jp, error))
+                    raise
+            result = await proceed(*jp.args, **jp.kwargs)
+            await self._async_result(advice(jp, result))
+            return result
+
+        if is_async:
+            @wraps(method)
+            async def endpoint(*args: Any, **kwargs: Any) -> Any:
+                return await invoke_async(0, args, kwargs)
+        else:
+            @wraps(method)
+            def endpoint(*args: Any, **kwargs: Any) -> Any:
+                return invoke(0, args, kwargs)
+        return endpoint

pythonboot/beans/__init__.py

@@ -0,0 +1,7 @@
+"""Bean declarations, metadata, and component scanning."""
+
+from pythonboot.beans.definitions import BeanDefinition, Scope, bean, component, configuration, service
+from pythonboot.beans.scanner import ScanResult, scan_components
+from pythonboot.beans.lifecycle import ondestroy, postconstruct
+
+__all__ = ["BeanDefinition", "Scope", "ScanResult", "bean", "component", "configuration", "service", "scan_components", "postconstruct", "ondestroy"]

pythonboot/beans/conditions.py

@@ -0,0 +1,108 @@
+"""Declarative conditions evaluated while assembling auto-configurations."""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from importlib.util import find_spec
+from typing import Any, TypeVar
+
+from pythonboot.beans.definitions import BeanDefinition
+
+T = TypeVar("T")
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class Condition:
+    kind: str
+    values: tuple[type | str, ...] = ()
+    having_value: Any = _MISSING
+    match_if_missing: bool = False
+
+    def matches(
+        self, definitions: tuple[BeanDefinition, ...], configuration: Mapping[str, Any],
+    ) -> bool:
+        if self.kind == "module":
+            for module in self.values:
+                try:
+                    if find_spec(module) is None:
+                        return False
+                except ModuleNotFoundError as error:
+                    if error.name == module or module.startswith(f"{error.name}."):
+                        return False
+                    raise
+            return True
+        if self.kind == "property":
+            value: Any = configuration
+            for part in self.values[0].split("."):
+                if not isinstance(value, Mapping) or part not in value:
+                    return self.match_if_missing
+                value = value[part]
+            if self.having_value is _MISSING:
+                return value is not None and str(value).lower() != "false"
+            return str(value).lower() == str(self.having_value).lower()
+        matches = tuple(
+            any(
+                definition.name == value if isinstance(value, str)
+                else issubclass(definition.bean_type, value)
+                for definition in definitions
+            )
+            for value in self.values
+        )
+        return not any(matches) if self.kind == "missing_bean" else all(matches)
+
+
+def _declare(condition: Condition) -> Callable[[T], T]:
+    def decorate(target: T) -> T:
+        if not isinstance(target, type) and not callable(target):
+            raise TypeError("Conditions can only decorate configuration classes or bean factories")
+        conditions = vars(target).get("__pythonboot_conditions__", ())
+        target.__pythonboot_conditions__ = (*conditions, condition)
+        return target
+    return decorate
+
+
+def conditional_on_module(*modules: str) -> Callable[[T], T]:
+    """Enable an auto-configuration or factory when all modules are available."""
+    if not modules or any(
+        not isinstance(module, str) or not all(part.isidentifier() for part in module.split("."))
+        for module in modules
+    ):
+        raise ValueError("Module conditions require non-empty dotted module names")
+    return _declare(Condition("module", modules))
+
+
+def conditional_on_property(
+    name: str, *, having_value: Any = _MISSING, match_if_missing: bool = False,
+) -> Callable[[T], T]:
+    """Match a dotted application YAML property without creating any beans."""
+    if not isinstance(name, str) or any(not part.strip() for part in name.split(".")):
+        raise ValueError("Property conditions require a non-empty dotted name")
+    return _declare(Condition("property", (name,), having_value, match_if_missing))
+
+
+def _bean_condition(kind: str, beans: tuple[type | str, ...]) -> Callable[[T], T]:
+    if not beans or any(
+        not isinstance(bean, (type, str)) or isinstance(bean, str) and not bean.strip()
+        for bean in beans
+    ):
+        raise ValueError("Bean conditions require bean types or non-empty bean names")
+    return _declare(Condition(kind, beans))
+
+
+def conditional_on_bean(*beans: type | str) -> Callable[[T], T]:
+    """Match when all specified bean types or names have been registered."""
+    return _bean_condition("bean", beans)
+
+
+def conditional_on_missing_bean(*beans: type | str) -> Callable[[T], T]:
+    """Back off when any specified bean type or name is already registered."""
+    return _bean_condition("missing_bean", beans)
+
+
+def matches_conditions(
+    target: object, definitions: tuple[BeanDefinition, ...], configuration: Mapping[str, Any],
+) -> bool:
+    return all(
+        condition.matches(definitions, configuration)
+        for condition in vars(target).get("__pythonboot_conditions__", ())
+    )

pythonboot/beans/definitions.py

@@ -0,0 +1,108 @@
+"""Component declarations and scanning metadata."""
+
+from dataclasses import dataclass
+import inspect
+from typing import Any, Callable, Literal, TypeVar
+
+T = TypeVar("T", bound=type)
+F = TypeVar("F", bound=Callable[..., Any])
+Scope = Literal["singleton", "prototype"]
+
+
+@dataclass(frozen=True)
+class ComponentOptions:
+    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, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.scope not in ("singleton", "prototype"):
+            raise ValueError("scope must be singleton or prototype")
+        for label, value in (("name", self.name), ("init_method", self.init_method), ("destroy_method", self.destroy_method)):
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise ValueError(f"{label} must be a non-empty string")
+        for label in ("qualifiers", "depends_on"):
+            values = getattr(self, label)
+            if isinstance(values, str) or any(not isinstance(value, str) or not value.strip() for value in values):
+                raise ValueError(f"{label} must be a sequence of non-empty strings")
+            object.__setattr__(self, label, tuple(dict.fromkeys(values)))
+
+
+@dataclass(frozen=True)
+class BeanDefinition:
+    name: str
+    bean_type: type
+    factory: Callable[..., Any]
+    owner: type | 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, ...] = ()
+
+    def __post_init__(self) -> None:
+        options = ComponentOptions(
+            self.name, self.init_method, self.destroy_method, self.lazy,
+            self.scope, self.primary, self.qualifiers, self.depends_on,
+        )
+        object.__setattr__(self, "qualifiers", options.qualifiers)
+        object.__setattr__(self, "depends_on", options.depends_on)
+
+
+def component(
+    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 component, singleton by default, without instantiating it."""
+    def decorate(target: T) -> T:
+        if not inspect.isclass(target):
+            raise TypeError("Component decorators can only decorate classes")
+        target.__pythonboot_component__ = ComponentOptions(
+            name, init_method, destroy_method, lazy, scope, primary, qualifiers, depends_on
+        )
+        return target
+
+    return decorate(cls) if cls is not None else decorate
+
+
+service = component
+configuration = component
+
+
+def bean(
+    factory: F | 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, ...] = (),
+) -> F | Callable[[F], F]:
+    """Declare a module-level factory or a configuration bean factory method."""
+    def decorate(target: F) -> F:
+        if not inspect.isfunction(target):
+            raise TypeError("@bean decorates factory methods; use @component for classes")
+        target.__pythonboot_bean__ = ComponentOptions(
+            name, init_method, destroy_method, lazy, scope, primary, qualifiers, depends_on
+        )
+        return target
+
+    return decorate(factory) if factory is not None else decorate