pythonboot 0.1.0__py3-none-any.whl

pythonboot/beans/lifecycle.py

@@ -0,0 +1,82 @@
+"""Bean initialization callback declarations."""
+
+import inspect
+from typing import Any, Callable, TypeVar
+
+from pythonboot.exceptions import BeanDefinitionError
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def postconstruct(method: F | None = None) -> F | Callable[[F], F]:
+    """Invoke an instance method once after dependency injection completes."""
+    def decorate(target: F) -> F:
+        if not inspect.isfunction(target):
+            raise TypeError("@postconstruct can only decorate instance methods")
+        parameters = tuple(inspect.signature(target).parameters.values())
+        if (
+            len(parameters) != 1 or parameters[0].name != "self"
+            or parameters[0].kind not in (
+                inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ):
+            raise TypeError("@postconstruct methods must accept only self")
+        if inspect.isgeneratorfunction(target) or inspect.isasyncgenfunction(target):
+            raise TypeError("@postconstruct does not support generator methods")
+        target.__pythonboot_postconstruct__ = True
+        return target
+
+    return decorate(method) if method is not None else decorate
+
+
+def ondestroy(method: F | None = None) -> F | Callable[[F], F]:
+    """Invoke an instance method once before a singleton bean is destroyed."""
+    def decorate(target: F) -> F:
+        if not inspect.isfunction(target):
+            raise TypeError("@ondestroy can only decorate instance methods")
+        parameters = tuple(inspect.signature(target).parameters.values())
+        if (
+            len(parameters) != 1 or parameters[0].name != "self"
+            or parameters[0].kind not in (
+                inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ):
+            raise TypeError("@ondestroy methods must accept only self")
+        if inspect.isgeneratorfunction(target) or inspect.isasyncgenfunction(target):
+            raise TypeError("@ondestroy does not support generator methods")
+        target.__pythonboot_ondestroy__ = True
+        return target
+
+    return decorate(method) if method is not None else decorate
+
+
+def get_postconstruct_methods(bean_type: type) -> tuple[str, ...]:
+    """Discover callbacks from base to derived classes, respecting method resolution."""
+    methods: list[str] = []
+    for cls in reversed(bean_type.__mro__):
+        for name, descriptor in vars(cls).items():
+            method = descriptor.__func__ if isinstance(descriptor, (staticmethod, classmethod)) else descriptor
+            if not getattr(method, "__pythonboot_postconstruct__", False):
+                continue
+            if inspect.getattr_static(bean_type, name) is not descriptor:
+                continue
+            if isinstance(descriptor, (staticmethod, classmethod)):
+                raise BeanDefinitionError(f"@postconstruct does not support static or class methods: {bean_type.__name__}.{name}")
+            methods.append(name)
+    return tuple(methods)
+
+
+def get_ondestroy_methods(bean_type: type) -> tuple[str, ...]:
+    """Discover callbacks from derived to base classes, respecting method resolution."""
+    methods: list[str] = []
+    for cls in bean_type.__mro__:
+        for name, descriptor in vars(cls).items():
+            method = descriptor.__func__ if isinstance(descriptor, (staticmethod, classmethod)) else descriptor
+            if not getattr(method, "__pythonboot_ondestroy__", False):
+                continue
+            if inspect.getattr_static(bean_type, name) is not descriptor:
+                continue
+            if isinstance(descriptor, (staticmethod, classmethod)):
+                raise BeanDefinitionError(f"@ondestroy does not support static or class methods: {bean_type.__name__}.{name}")
+            methods.append(name)
+    return tuple(methods)

pythonboot/beans/scanner.py

@@ -0,0 +1,164 @@
+"""Recursive application package scanning with segmented wildcard matching."""
+
+import importlib
+import inspect
+import sys
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+from pathlib import Path
+from types import ModuleType
+from typing import Callable, get_type_hints
+
+from pythonboot.beans.definitions import BeanDefinition, ComponentOptions
+from pythonboot.exceptions import BeanDefinitionError
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    definitions: tuple[BeanDefinition, ...]
+    modules: tuple[ModuleType, ...]
+
+
+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:])
+
+
+def _module_names(package: ModuleType) -> set[str]:
+    """Discover modules in package paths, including namespace directories."""
+    names = {package.__name__}
+    for location in getattr(package, "__path__", ()):
+        root = Path(location)
+        for file in root.rglob("*.py"):
+            relative = file.relative_to(root)
+            parts = (*relative.parts[:-1], file.stem)
+            if any(not part.isidentifier() or part == "__pycache__" for part in parts):
+                continue
+            if parts[-1] == "__init__":
+                parts = parts[:-1]
+            for depth in range(1, len(parts) + 1):
+                names.add(".".join((package.__name__, *parts[:depth])))
+    return names
+
+
+def scan_components(
+    packages: tuple[str, ...], *, exclude_modules: tuple[str, ...] = (),
+    exclude: tuple[type, ...] = (),
+) -> ScanResult:
+    modules: dict[str, ModuleType] = {}
+    candidates: set[str] = set()
+    for pattern in packages:
+        if not isinstance(pattern, str) or not pattern:
+            raise BeanDefinitionError("Scan package names must be non-empty strings")
+        parts = tuple(pattern.split("."))
+        wildcard_index = next((
+            index for index, part in enumerate(parts)
+            if any(character in part for character in "*?[")
+        ), len(parts))
+        if not wildcard_index or any(not part.isidentifier() for part in parts[:wildcard_index]):
+            raise BeanDefinitionError(f"Scan patterns must start with a concrete package name: {pattern}")
+        if any(not part or ("**" in part and part != "**") for part in parts):
+            raise BeanDefinitionError(f"Invalid scan pattern: {pattern}")
+        package = importlib.import_module(".".join(parts[:wildcard_index]))
+        discovered = _module_names(package)
+        if wildcard_index == len(parts):
+            candidates.update(discovered)
+        else:
+            candidates.update(name for name in discovered if _matches(parts, tuple(name.split("."))))
+
+    for name in sorted(candidates, key=lambda item: (item.count("."), item)):
+        if name in exclude_modules:
+            # Reuse the initializing entry module to avoid importing it again under python -m.
+            module = sys.modules.get(name)
+            main = sys.modules.get("__main__")
+            if module is None and getattr(getattr(main, "__spec__", None), "name", None) == name:
+                module = main
+            if module is not None:
+                modules[module.__name__] = module
+            continue
+        module = importlib.import_module(name)
+        modules[module.__name__] = module
+
+    targets = tuple(
+        value for module in modules.values() for value in vars(module).values()
+        if getattr(value, "__module__", None) == module.__name__
+        and not getattr(value, "__pythonboot_auto_configuration__", None)
+    )
+    return ScanResult(collect_definitions(targets, exclude=exclude), tuple(modules.values()))
+
+
+def collect_definitions(
+    targets: tuple[object, ...], *, include_factory: Callable[[object], bool] | None = None,
+    exclude: tuple[type, ...] = (),
+) -> tuple[BeanDefinition, ...]:
+    """Extract declarations from explicit targets without scanning their packages."""
+    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 = set(exclude)
+    definitions: list[BeanDefinition] = []
+    seen: set[int] = set()
+
+    def add_factory(factory: object, owner: type | None = None) -> None:
+        options = getattr(factory, "__pythonboot_bean__", None)
+        if options is None:
+            return
+        if include_factory is not None and not include_factory(factory):
+            return
+        try:
+            bean_type = get_type_hints(factory).get("return")
+        except (NameError, TypeError) as error:
+            raise BeanDefinitionError(f"Cannot resolve type hints for bean factory {factory}") from error
+        if not isinstance(bean_type, type) or bean_type is type(None):
+            raise BeanDefinitionError(f"Bean factory {factory} must declare a concrete return type")
+        if bean_type in excluded_classes:
+            return
+        if inspect.iscoroutinefunction(factory) or inspect.isasyncgenfunction(factory):
+            raise BeanDefinitionError("Bean factories must create objects synchronously; use init_method for async initialization")
+        definitions.append(BeanDefinition(
+            name=options.name or factory.__name__,
+            bean_type=bean_type,
+            factory=factory,
+            owner=owner,
+            init_method=options.init_method,
+            destroy_method=options.destroy_method,
+            lazy=options.lazy,
+            scope=options.scope,
+            primary=options.primary,
+            qualifiers=options.qualifiers,
+            depends_on=options.depends_on,
+        ))
+
+    for value in targets:
+        if id(value) in seen:
+            continue
+        seen.add(id(value))
+        if inspect.isclass(value):
+            if value in excluded_classes:
+                continue
+            options: ComponentOptions | None = vars(value).get("__pythonboot_component__")
+            if options is None:
+                continue
+            definitions.append(BeanDefinition(
+                name=options.name or value.__name__[:1].lower() + value.__name__[1:],
+                bean_type=value,
+                factory=value,
+                init_method=options.init_method,
+                destroy_method=options.destroy_method,
+                lazy=options.lazy,
+                scope=options.scope,
+                primary=options.primary,
+                qualifiers=options.qualifiers,
+                depends_on=options.depends_on,
+            ))
+            for method in vars(value).values():
+                if inspect.isfunction(method):
+                    add_factory(method, owner=value)
+        elif inspect.isfunction(value):
+            add_factory(value)
+
+    return tuple(definitions)

pythonboot/boot/__init__.py

@@ -0,0 +1,5 @@
+"""Application startup and assembly."""
+
+from pythonboot.boot.autoconfiguration import auto_configuration
+
+__all__ = ["auto_configuration"]

pythonboot/boot/autoconfiguration.py

@@ -0,0 +1,120 @@
+"""Discover installed starter entry points and assemble conditional bean definitions."""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from importlib.metadata import entry_points
+import inspect
+from types import ModuleType
+from typing import Any, TypeVar
+
+from pythonboot.beans.conditions import matches_conditions
+from pythonboot.beans.definitions import BeanDefinition, component
+from pythonboot.beans.scanner import collect_definitions
+from pythonboot.exceptions import BeanDefinitionError
+
+T = TypeVar("T", bound=type)
+
+
+@dataclass(frozen=True)
+class AutoConfigurationOptions:
+    order: int = 0
+    imports: tuple[type, ...] = ()
+
+
+def auto_configuration(
+    cls: T | None = None, *, order: int = 0, imports: tuple[type, ...] = (),
+) -> T | Callable[[T], T]:
+    """Declare a starter configuration and its explicitly imported companion beans."""
+    if not isinstance(order, int):
+        raise TypeError("Auto-configuration order must be an integer")
+    if any(not inspect.isclass(target) for target in imports):
+        raise TypeError("Auto-configuration imports must contain classes")
+
+    def decorate(target: T) -> T:
+        if not inspect.isclass(target):
+            raise TypeError("@auto_configuration can only decorate classes")
+        if "__pythonboot_component__" not in vars(target):
+            component(target)
+        target.__pythonboot_auto_configuration__ = AutoConfigurationOptions(order, tuple(imports))
+        return target
+
+    return decorate(cls) if cls is not None else decorate
+
+
+def assemble_auto_configurations(
+    definitions: tuple[BeanDefinition, ...], modules: tuple[ModuleType, ...],
+    configuration: Mapping[str, Any], *, exclude: tuple[str, ...] = (),
+    exclude_classes: tuple[type, ...] = (),
+) -> tuple[BeanDefinition, ...]:
+    """Apply user definitions first, then ordered, explicitly advertised configurations."""
+    if isinstance(exclude, str) or any(not isinstance(name, str) or not name for name in exclude):
+        raise ValueError("Auto-configuration exclusions must be a sequence of non-empty names")
+    candidates: dict[str, type] = {}
+    excluded_classes = set(exclude_classes)
+    excluded_names = {f"{target.__module__}.{target.__qualname__}" for target in excluded_classes}
+
+    def add(target: object) -> None:
+        if isinstance(target, ModuleType):
+            for value in vars(target).values():
+                if inspect.isclass(value) and "__pythonboot_auto_configuration__" in vars(value):
+                    add(value)
+            return
+        if not inspect.isclass(target) or "__pythonboot_auto_configuration__" not in vars(target):
+            raise BeanDefinitionError("Auto-configuration entry points must reference decorated classes or modules")
+        name = f"{target.__module__}.{target.__qualname__}"
+        if name not in exclude and target not in excluded_classes:
+            candidates[name] = target
+
+    from pythonboot.boot.task_configuration import TaskExecutionAutoConfiguration
+
+    add(TaskExecutionAutoConfiguration)
+    for module in modules:
+        add(module)
+    for entry in sorted(entry_points(group="pythonboot.autoconfigure"), key=lambda item: (item.name, item.value)):
+        qualified_name = entry.value.split("[", 1)[0].strip().replace(":", ".")
+        if entry.name in exclude or qualified_name in exclude or qualified_name in excluded_names:
+            continue
+        try:
+            add(entry.load())
+        except Exception as error:
+            raise BeanDefinitionError(f"Cannot load auto-configuration entry point {entry.name}: {entry.value}") from error
+
+    registered = list(definitions)
+    sources = {(id(item.factory), item.owner) for item in definitions}
+    for name, target in sorted(
+        candidates.items(), key=lambda item: (vars(item[1])["__pythonboot_auto_configuration__"].order, item[0]),
+    ):
+        if not matches_conditions(target, tuple(registered), configuration):
+            continue
+        options: AutoConfigurationOptions = vars(target)["__pythonboot_auto_configuration__"]
+        companions = tuple(
+            imported for imported in options.imports
+            if imported not in excluded_classes
+            and matches_conditions(imported, tuple(registered), configuration)
+        )
+        def include_factory(factory: object) -> bool:
+            return all(
+                condition.matches(tuple(registered), configuration)
+                for condition in vars(factory).get("__pythonboot_conditions__", ())
+                if condition.kind in ("module", "property")
+            )
+
+        pending = collect_definitions(
+            (*companions, target), include_factory=include_factory, exclude=exclude_classes,
+        )
+        # Unconditional definitions precede bean-dependent fallback factories.
+        pending = tuple(sorted(pending, key=lambda item: any(
+            condition.kind in ("bean", "missing_bean")
+            for condition in vars(item.factory).get("__pythonboot_conditions__", ())
+        )))
+        for definition in pending:
+            source = (id(definition.factory), definition.owner)
+            if source in sources:
+                continue
+            if definition.factory is not target and not matches_conditions(
+                definition.factory, tuple(registered), configuration,
+            ):
+                continue
+            registered.append(definition)
+            sources.add(source)
+    return tuple(registered)

pythonboot/boot/task_configuration.py

@@ -0,0 +1,38 @@
+"""Conditional application task executor and YAML property binding."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from pythonboot.beans import bean
+from pythonboot.beans.conditions import conditional_on_missing_bean, conditional_on_property
+from pythonboot.boot.autoconfiguration import auto_configuration
+from pythonboot.config import configuration_properties
+from pythonboot.task import RejectionPolicy, TaskExecutor, ThreadPoolTaskExecutor
+
+
+@configuration_properties("pythonboot.task.execution")
+class TaskExecutionProperties(BaseSettings):
+    """Settings for the default executor; environment variables override YAML."""
+
+    model_config = SettingsConfigDict(env_prefix="PYTHONBOOT_TASK_EXECUTION_", extra="ignore")
+
+    core_pool_size: int = Field(default=8, ge=1)
+    max_pool_size: int = Field(default=32, ge=1)
+    queue_capacity: int | None = Field(default=256, ge=0)
+    keep_alive_seconds: float = Field(default=60, gt=0, allow_inf_nan=False)
+    thread_name_prefix: str = Field(default="pythonboot-task-", min_length=1)
+    allow_core_thread_timeout: bool = False
+    rejection_policy: RejectionPolicy = RejectionPolicy.ABORT
+    wait_for_tasks_to_complete_on_shutdown: bool = True
+    await_termination_seconds: float | None = Field(default=None, ge=0, allow_inf_nan=False)
+
+
+@auto_configuration(order=1000, imports=(TaskExecutionProperties,))
+@conditional_on_property("pythonboot.task.execution.enabled", having_value=True, match_if_missing=True)
+class TaskExecutionAutoConfiguration:
+    """Provide a default executor unless an application supplies its own."""
+
+    @bean(name="applicationTaskExecutor", destroy_method="close")
+    @conditional_on_missing_bean(TaskExecutor, "applicationTaskExecutor")
+    def application_task_executor(self, properties: TaskExecutionProperties) -> ThreadPoolTaskExecutor:
+        return ThreadPoolTaskExecutor(**properties.model_dump())

pythonboot/config/__init__.py

@@ -0,0 +1,6 @@
+"""Configuration loading and property binding interfaces."""
+
+from pythonboot.config.logging import configure_logging
+from pythonboot.config.properties import ConfigurationPropertiesOptions, configuration_properties, load_configuration
+
+__all__ = ["ConfigurationPropertiesOptions", "configuration_properties", "configure_logging", "load_configuration"]

pythonboot/config/logging.py

@@ -0,0 +1,90 @@
+"""Application logging configuration."""
+
+from collections.abc import Mapping
+from copy import copy
+import logging
+import logging.config
+import sys
+from typing import Any
+
+from pythonboot.exceptions import ConfigurationError
+
+DEFAULT_LOG_FORMAT = (
+    "%(asctime)s.%(msecs)03d %(levelname)-5s %(process)5d "
+    "[Thread-%(thread)d] %(name)s : %(message)s"
+)
+DEFAULT_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+_LEVEL_COLORS = {
+    logging.DEBUG: "\033[36m",
+    logging.INFO: "\033[32m",
+    logging.WARNING: "\033[33m",
+    logging.ERROR: "\033[31m",
+    logging.CRITICAL: "\033[31m",
+}
+_RESET_COLOR = "\033[0m"
+
+
+class ConsoleFormatter(logging.Formatter):
+    """Render log levels with terminal colors when supported."""
+
+    def __init__(self, *args: Any, colors: bool, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._colors = colors
+
+    def format(self, record: logging.LogRecord) -> str:
+        if not self._colors:
+            return super().format(record)
+        colored_record = copy(record)
+        color = _LEVEL_COLORS.get(record.levelno)
+        if color is not None:
+            colored_record.levelname = f"{color}{record.levelname:<5}{_RESET_COLOR}"
+        return super().format(colored_record)
+
+
+def _log_level(value: Any) -> int:
+    if not isinstance(value, str) or value.upper() not in logging.getLevelNamesMapping():
+        raise ConfigurationError("logging.level must be a valid logging level name")
+    return logging.getLevelNamesMapping()[value.upper()]
+
+
+def _apply_formatter(formatter: logging.Formatter) -> None:
+    for logger_name in ("", "uvicorn", "uvicorn.error", "uvicorn.access"):
+        for handler in logging.getLogger(logger_name).handlers:
+            handler.setFormatter(formatter)
+
+
+def configure_logging(configuration: Mapping[str, Any]) -> None:
+    """Configure logging from the application logging section."""
+    pythonboot = configuration.get("pythonboot", {})
+    if not isinstance(pythonboot, Mapping):
+        raise ConfigurationError("pythonboot configuration must be a mapping")
+    options = pythonboot.get("logging", {})
+    if not isinstance(options, Mapping):
+        raise ConfigurationError("pythonboot.logging configuration must be a mapping")
+    if "version" in options:
+        try:
+            logging.config.dictConfig(dict(options))
+        except (TypeError, ValueError) as error:
+            raise ConfigurationError("Invalid logging dictConfig configuration") from error
+        return
+
+    allowed = {"level", "format", "date_format", "colors", "loggers"}
+    unexpected = set(options).difference(allowed)
+    if unexpected:
+        raise ConfigurationError("Unsupported logging options: " + ", ".join(sorted(unexpected)))
+    level = _log_level(options.get("level", "INFO"))
+    log_format = options.get("format", DEFAULT_LOG_FORMAT)
+    date_format = options.get("date_format", DEFAULT_DATE_FORMAT)
+    colors = options.get("colors", sys.stdout.isatty())
+    if not isinstance(log_format, str) or not isinstance(date_format, str) or not isinstance(colors, bool):
+        raise ConfigurationError("logging.format and logging.date_format must be strings; logging.colors must be a boolean")
+    logging.basicConfig(level=level, format=log_format, datefmt=date_format, stream=sys.stdout)
+    logging.getLogger().setLevel(level)
+    _apply_formatter(ConsoleFormatter(log_format, datefmt=date_format, colors=colors))
+    logger_levels = options.get("loggers", {})
+    if not isinstance(logger_levels, Mapping):
+        raise ConfigurationError("logging.loggers must be a mapping of logger names to levels")
+    for name, logger_level in logger_levels.items():
+        if not isinstance(name, str) or not name:
+            raise ConfigurationError("logging.loggers keys must be non-empty strings")
+        logging.getLogger(name).setLevel(_log_level(logger_level))

pythonboot/config/properties.py

@@ -0,0 +1,148 @@
+"""YAML configuration loading and Pydantic settings property binding."""
+
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+import inspect
+from pathlib import Path
+from typing import Any, Callable, TypeVar
+
+import yaml
+from pydantic_settings import BaseSettings, InitSettingsSource
+
+from pythonboot.beans import component
+from pythonboot.exceptions import ConfigurationError
+
+T = TypeVar("T", bound=type)
+_configuration_values: ContextVar[Mapping[str, Any]] = ContextVar(
+    "pythonboot_configuration_values", default={},
+)
+
+
+@dataclass(frozen=True)
+class ConfigurationPropertiesOptions:
+    """Configuration metadata attached to a settings bean type."""
+
+    prefix: str
+
+
+def _merge(target: dict[str, Any], source: Mapping[str, Any]) -> dict[str, Any]:
+    for key, value in source.items():
+        existing = target.get(key)
+        if isinstance(existing, dict) and isinstance(value, Mapping):
+            _merge(existing, value)
+        else:
+            target[key] = value
+    return target
+
+
+def _load_yaml_file(file: Path) -> Mapping[str, Any]:
+    try:
+        with file.open(encoding="utf-8") as stream:
+            document = yaml.safe_load(stream)
+    except yaml.YAMLError as error:
+        raise ConfigurationError(f"Invalid YAML configuration file: {file}") from error
+    if document is None:
+        return {}
+    if not isinstance(document, Mapping):
+        raise ConfigurationError(f"YAML configuration root must be a mapping: {file}")
+    return document
+
+
+def _active_profiles(values: Mapping[str, Any]) -> tuple[str, ...]:
+    active = values.get("active")
+    if active is None:
+        return ()
+    if not isinstance(active, Mapping):
+        raise ConfigurationError("Configuration property active must be a mapping")
+    profile = active.get("profile")
+    if profile is None:
+        return ()
+    if isinstance(profile, str):
+        profiles = (profile,)
+    elif isinstance(profile, Sequence) and not isinstance(profile, (str, bytes)):
+        profiles = tuple(profile)
+    else:
+        raise ConfigurationError("Configuration property active.profile must be a string or sequence of strings")
+    if any(
+        not isinstance(item, str) or not item or "/" in item or "\\" in item or item in (".", "..")
+        for item in profiles
+    ):
+        raise ConfigurationError("Configuration property active.profile contains an invalid profile name")
+    return profiles
+
+
+def load_configuration(config_dir: str | Path) -> dict[str, Any]:
+    """Load application.yml and the active application-{profile}.yml files."""
+    directory = Path(config_dir)
+    if not directory.is_dir():
+        raise ConfigurationError(f"Configuration directory does not exist or is not a directory: {directory}")
+    values: dict[str, Any] = {}
+    base_file = directory / "application.yml"
+    if base_file.is_file():
+        _merge(values, _load_yaml_file(base_file))
+    for profile in _active_profiles(values):
+        profile_file = directory / f"application-{profile}.yml"
+        if profile_file.is_file():
+            _merge(values, _load_yaml_file(profile_file))
+    return values
+
+
+def _values_for_prefix(prefix: str) -> dict[str, Any]:
+    values: Mapping[str, Any] = _configuration_values.get()
+    for part in prefix.split("."):
+        value = values.get(part)
+        if not isinstance(value, Mapping):
+            return {}
+        values = value
+    return dict(values)
+
+
+@contextmanager
+def use_configuration_values(values: Mapping[str, Any]) -> Iterator[None]:
+    """Bind application configuration while a bean factory executes."""
+    token = _configuration_values.set(values)
+    try:
+        yield
+    finally:
+        _configuration_values.reset(token)
+
+
+def configuration_properties(prefix: str) -> Callable[[T], T]:
+    """Register a Pydantic settings class bound to a YAML configuration prefix."""
+    normalized_prefix = prefix.strip(".") if isinstance(prefix, str) else ""
+    if not normalized_prefix or any(not part for part in normalized_prefix.split(".")):
+        raise ValueError("configuration_properties prefix must be a non-empty dotted path")
+
+    def decorate(target: T) -> T:
+        if not inspect.isclass(target) or not issubclass(target, BaseSettings):
+            raise TypeError("@configuration_properties can only decorate BaseSettings subclasses")
+        if "__pythonboot_configuration_properties__" in vars(target):
+            raise ConfigurationError(f"Configuration properties already declared for {target.__name__}")
+        if "__pythonboot_component__" not in vars(target):
+            component(target)
+        target.__pythonboot_configuration_properties__ = ConfigurationPropertiesOptions(normalized_prefix)
+        original_sources = target.settings_customise_sources
+
+        @classmethod
+        def settings_customise_sources(
+            cls: type[BaseSettings], settings_cls: type[BaseSettings], init_settings: Any, env_settings: Any,
+            dotenv_settings: Any, file_secret_settings: Any,
+        ) -> tuple[Any, ...]:
+            sources = original_sources(
+                settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings,
+            )
+            yaml_settings = InitSettingsSource(
+                settings_cls, init_kwargs=_values_for_prefix(normalized_prefix),
+            )
+            try:
+                index = sources.index(env_settings) + 1
+            except ValueError:
+                index = len(sources)
+            return (*sources[:index], yaml_settings, *sources[index:])
+
+        target.settings_customise_sources = settings_customise_sources
+        return target
+
+    return decorate

pythonboot/context/__init__.py

@@ -0,0 +1,6 @@
+"""IoC container, dependency resolution, scopes, and lifecycle."""
+
+from pythonboot.context.container import ApplicationContext
+from pythonboot.context.injection import autowired
+
+__all__ = ["ApplicationContext", "autowired"]