Framework Decorators

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_core/_decorators/_base.py
• src/flext_core/_root_typing_parts/facades.py
• tests/unit/test_decorators_full_coverage.py
• examples/README.md
• src/flext_core/init.py

Framework Decorators in FLEXT-Core provide a declarative way to augment function behavior with cross-cutting concerns such as dependency injection, error handling, and lifecycle management. These decorators are centralized within the flext_core.decorators module and exposed through the d facade for ease of use across the ecosystem.

The system is built upon a base class, FlextDecoratorsBase, which handles common logic for logger resolution and integration with the framework's core container and context systems. This ensures that decorators behave consistently whether they are used for simple utility functions or complex application handlers.

Sources: src/flext_core/_decorators/_base.py:12-35, src/flext_core/_root_typing_parts/facades.py:23-26, examples/README.md:46-48

Core Decorator Architecture

The decorator system leverages a hierarchical structure where FlextDecoratorsBase provides the foundational utility methods used by concrete implementations. This foundation includes mechanisms for resolving loggers from method arguments or module context and providing access to the shared FlextContainer.

Base Components and Logic

The FlextDecoratorsBase class serves as the root for all framework decorators. It manages the integration with the FlextContainer for dependency resolution and FlextContext for execution scope.

The logic for resolving loggers allows the framework to automatically determine the appropriate logging context by probing the first argument of a function (typically self or cls) for logger attributes, or falling back to the module-level logger.

Sources: src/flext_core/_decorators/_base.py:32-75, src/flext_core/_root_typing_parts/facades.py:23-26

Functional Decorators

FLEXT-Core provides several specialized decorators to handle common development patterns.

Dependency Injection (@inject)

The @inject decorator automates the retrieval of services from the FlextContainer. It maps function parameters to container keys, resolving and injecting the dependencies at runtime if they are not explicitly provided by the caller.

Parameter	Type	Description
**dependencies	str	Keyword arguments where the key is the parameter name and the value is the container lookup key.

Sources: src/flext_core/_decorators/_base.py:100-117, tests/unit/test_decorators_full_coverage.py:33-46

API Evolution (@deprecated)

The @deprecated decorator marks a callable as obsolete. When the decorated function is executed, it emits a DeprecationWarning while preserving the original function's return value and signature.

Sources: src/flext_core/_decorators/_base.py:77-98, tests/unit/test_decorators_full_coverage.py:22-31

Railway-Oriented Programming and Reliability

Advanced decorators facilitate "Railway-Oriented Programming" (ROP) by wrapping standard Python exceptions into Result objects or providing automatic retry logic.

• @railway: Wraps function execution to catch exceptions and return them as failed Result objects, ensuring the caller receives a consistent data structure instead of a raised exception.
• @retry: Provides a mechanism to re-execute a function upon failure, supporting configurable maximum attempts and delays.
• @timeout: Enforces execution time limits, raising a TimeoutError if the function exceeds the specified duration.

Sources: tests/unit/test_decorators_full_coverage.py:73-128, examples/README.md:46-48

Integrated Decorator Patterns

The framework supports combining multiple concerns into a single decorator or using specialized composites like @combined.

The @combined decorator is a high-level utility that can simultaneously handle dependency injection, operation logging, and railway-oriented error wrapping based on its configuration.

Sources: tests/unit/test_decorators_full_coverage.py:145-168, examples/README.md:48

Summary of Available Decorators

The following table summarizes the primary decorators available through the d facade in flext_core.

Decorator	Primary Purpose	Source File
@inject	Dependency Injection from FlextContainer	_base.py
@deprecated	Emit warnings for obsolete APIs	_base.py
@railway	Convert exceptions to Result objects	test_decorators_full_coverage.py
@retry	Retrying flaky operations	test_decorators_full_coverage.py
@timeout	Enforce execution time limits	test_decorators_full_coverage.py
@with_context	Initialize/Propagate FlextContext	examples/README.md
@log_operation	Automatic entry/exit logging	examples/README.md

Sources: src/flext_core/_decorators/_base.py:77-117, tests/unit/test_decorators_full_coverage.py:22-143, examples/README.md:48

Framework Decorators in FLEXT-Core act as the glue between the domain logic and infrastructure services, ensuring that concerns like logging, dependency management, and error handling are handled consistently and declaratively. By centralizing these through the d facade, the framework promotes a clean architecture where business logic remains focused on its primary responsibility.