Metadata-Version: 2.4
Name: flext-core
Version: 0.12.0.dev0
Summary: Enterprise Foundation Framework - Modern Python 3.13 + Clean Architecture
License-Expression: MIT
License-File: LICENSE
Keywords: clean-architecture,ddd,enterprise,flext,modern,solid
Author: FLEXT Team
Author-email: team@flext.sh
Maintainer: FLEXT Team
Maintainer-email: team@flext.sh
Requires-Python: >=3.13,<3.14
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Provides-Extra: dev
Requires-Dist: attrs (>=25.4,<26)
Requires-Dist: autoflake (>=2.3.1) ; extra == "dev"
Requires-Dist: bandit (>=1.8) ; extra == "dev"
Requires-Dist: beartype (>=0.19)
Requires-Dist: beartype (>=0.19) ; extra == "dev"
Requires-Dist: black (>=25.1) ; extra == "dev"
Requires-Dist: cachetools (>=5.3)
Requires-Dist: codespell (>=2.3) ; extra == "dev"
Requires-Dist: dependency-injector (>=4.41)
Requires-Dist: deptry (>=0.23) ; extra == "dev"
Requires-Dist: detect-secrets (>=1.5) ; extra == "dev"
Requires-Dist: django-stubs (>=5.2.2) ; extra == "dev"
Requires-Dist: docker (>=7.1,<8)
Requires-Dist: factory-boy (>=3.3.1) ; extra == "dev"
Requires-Dist: faker (>=37.4) ; extra == "dev"
Requires-Dist: hypothesis (>=6.125) ; extra == "dev"
Requires-Dist: interrogate (>=1.7) ; extra == "dev"
Requires-Dist: isort (>=6.0.1) ; extra == "dev"
Requires-Dist: jinja2 (>=3.1.6)
Requires-Dist: limits (>=3.6)
Requires-Dist: mkdocs (>=1.6) ; extra == "dev"
Requires-Dist: mkdocs-awesome-pages-plugin (>=2.9) ; extra == "dev"
Requires-Dist: mkdocs-encryptcontent-plugin (>=2) ; extra == "dev"
Requires-Dist: mkdocs-exclude (>=1) ; extra == "dev"
Requires-Dist: mkdocs-get-deps (>=0.2) ; extra == "dev"
Requires-Dist: mkdocs-git-revision-date-localized-plugin (>=1.2) ; extra == "dev"
Requires-Dist: mkdocs-literate-nav (>=0.6) ; extra == "dev"
Requires-Dist: mkdocs-macros-plugin (>=1) ; extra == "dev"
Requires-Dist: mkdocs-material (>=9.5) ; extra == "dev"
Requires-Dist: mkdocs-material-extensions (>=1.3.1) ; extra == "dev"
Requires-Dist: mkdocs-mermaid2-plugin (>=1.1) ; extra == "dev"
Requires-Dist: mkdocs-minify-plugin (>=0.7) ; extra == "dev"
Requires-Dist: mkdocs-newsletter (>=0.1) ; extra == "dev"
Requires-Dist: mkdocs-print-site-plugin (>=0.8) ; extra == "dev"
Requires-Dist: mkdocs-redirects (>=1.2) ; extra == "dev"
Requires-Dist: mkdocs-section-index (>=0.3) ; extra == "dev"
Requires-Dist: mkdocs-versioning (>=0.2) ; extra == "dev"
Requires-Dist: mkdocstrings (>=0.24) ; extra == "dev"
Requires-Dist: mkdocstrings-python (>=1.7) ; extra == "dev"
Requires-Dist: mypy (>=1.18.2) ; extra == "dev"
Requires-Dist: orjson (>=3.11.3)
Requires-Dist: pip-audit (>=2.7.3) ; extra == "dev"
Requires-Dist: pre-commit (>=4.0.1) ; extra == "dev"
Requires-Dist: pybreaker (>=0.8)
Requires-Dist: pydantic (>=2.12.3)
Requires-Dist: pydantic-core (>=2.41.4)
Requires-Dist: pydantic-settings (>=2.10.1)
Requires-Dist: pylint (>=3.3) ; extra == "dev"
Requires-Dist: pytest (>=8.4) ; extra == "dev"
Requires-Dist: pytest-benchmark (>=5.1) ; extra == "dev"
Requires-Dist: pytest-clarity (>=1.0.1) ; extra == "dev"
Requires-Dist: pytest-cov (>=6.2) ; extra == "dev"
Requires-Dist: pytest-deadfixtures (>=2.2.1) ; extra == "dev"
Requires-Dist: pytest-env (>=1.1.5) ; extra == "dev"
Requires-Dist: pytest-mock (>=3.14) ; extra == "dev"
Requires-Dist: pytest-randomly (>=3.16) ; extra == "dev"
Requires-Dist: pytest-sugar (>=1) ; extra == "dev"
Requires-Dist: pytest-timeout (>=2.4) ; extra == "dev"
Requires-Dist: pytest-xdist (>=3.8) ; extra == "dev"
Requires-Dist: python-dotenv (>=1)
Requires-Dist: python-on-whales (>=0.79,<0.80)
Requires-Dist: pyupgrade (>=3.19) ; extra == "dev"
Requires-Dist: pyyaml (>=6.0.2)
Requires-Dist: radon (>=6.0.1) ; extra == "dev"
Requires-Dist: returns (>=0.26)
Requires-Dist: ruff (>=0.12.3) ; extra == "dev"
Requires-Dist: structlog (>=25.4)
Requires-Dist: types-cachetools (>=5.3) ; extra == "dev"
Requires-Dist: types-docker (>=7.1) ; extra == "dev"
Requires-Dist: types-ldap3 (>=2.9.13.20250622) ; extra == "dev"
Requires-Dist: types-protobuf (>=6.30.2.20250703) ; extra == "dev"
Requires-Dist: types-psutil (>=7) ; extra == "dev"
Requires-Dist: types-psycopg2 (>=2.9.21.20250718) ; extra == "dev"
Requires-Dist: types-python-dateutil (>=2.9) ; extra == "dev"
Requires-Dist: types-pyyaml (>=6.0.12) ; extra == "dev"
Requires-Dist: types-redis (>=4.6) ; extra == "dev"
Requires-Dist: types-requests (>=2.32.4) ; extra == "dev"
Requires-Dist: types-setuptools (>=80.9) ; extra == "dev"
Requires-Dist: types-toml (>=0.10.8.20240310) ; extra == "dev"
Requires-Dist: uv (>=0.9.6) ; extra == "dev"
Requires-Dist: vulture (>=2.13) ; extra == "dev"
Requires-Dist: wrapt (>=1.17,<2)
Project-URL: Documentation, https://github.com/flext-sh/flext-core/blob/main/README.md
Project-URL: Homepage, https://github.com/flext-sh/flext-core
Project-URL: Repository, https://github.com/flext-sh/flext-core
Description-Content-Type: text/markdown

# FLEXT-Core

<!-- TOC START -->

- [🚀 Key Features](#-key-features)
- [📦 Installation](#-installation)
- [🛠️ Usage](#-usage)
  - [Railway-Oriented Results](#railway-oriented-results)
  - [Dependency Injection](#dependency-injection)
  - [CQRS Dispatching](#cqrs-dispatching)
- [🏗️ Architecture](#-architecture)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

<!-- TOC END -->

**FLEXT-Core** is the foundational library for the FLEXT ecosystem, providing a robust set of architectural primitives, patterns, and utilities for building enterprise-grade Python applications. It enforces Railway-Oriented Programming (ROP), Dependency Injection (DI), and Command Query Responsibility Segregation (CQRS) to ensure type safety, scalability, and maintainability.

**Reviewed**: 2026-02-17 | **Version**: 0.10.0-dev

Part of the [FLEXT](https://github.com/flext-sh/flext) ecosystem.

## 🚀 Key Features

- **Railway-Oriented Programming**: handling errors as values using `FlextResult[T, E]`, eliminating unexpected exceptions in business logic.
- **Dependency Injection**: A lightweight, type-safe DI container (`FlextContainer`) with scoped services and bridge integration.
- **CQRS Dispatcher**: A strictly typed `FlextDispatcher` for routing commands, queries, and events to their respective handlers.
- **Domain-Driven Design**: Base classes (`FlextModels`, `FlextService`) and mixins for rich domain modeling.
- **Protocol-Based Architecture**: Extensive use of Python `Protocol` for loose coupling and improved testability.
- **Infrastructure Helpers**: Built-in support for structured logging, configuration management, and context propagation.

## 📦 Installation

Install `flext-core` using pip:

```bash
pip install flext-core
```

Or with Poetry:

```bash
poetry add flext-core
```

## 🛠️ Usage

### Railway-Oriented Results

Replace exception handling with `FlextResult` for predictable control flow.

```python
from flext_core import FlextResult as r

def divide(a: int, b: int) -> r[float]:
    if b == 0:
        return r[float].fail("Division by zero")
    return r[float].ok(a / b)

result = divide(10, 2)
if result.is_success:
    print(f"Result: {result.unwrap()}")
else:
    print(f"Error: {result.error}")
```

### Dependency Injection

Manage your application's dependencies cleanly using `FlextContainer` and `FlextRuntime`.

```python
from flext_core import FlextContainer, Provide, inject, FlextService

# 1. Register a service
container = FlextContainer.get_global()
container.register_factory("db_client", lambda: DatabaseClient())

# 2. Inject into functions
@inject
def get_user(user_id: str, db=Provide["db_client"]):
    return db.query(user_id)

# 3. Inject into Services
class UserService(FlextService):
    def get_user(self, user_id: str):
        # Access container directly via self.container
        db = self.container.get("db_client").unwrap()
        return db.query(user_id)
```

### CQRS Dispatching

Decouple your business logic using the `FlextDispatcher`.

```python
from dataclasses import dataclass
from flext_core import FlextDispatcher, FlextResult as r

# 1. Define a Command
@dataclass
class CreateUser:
    username: str
    email: str

# 2. Define a Handler
def handle_create_user(cmd: CreateUser) -> r[str]:
    # Business logic here...
    return r[str].ok(f"User {cmd.username} created")

# 3. Register and Dispatch
dispatcher = FlextDispatcher()
dispatcher.register_handler(CreateUser, handle_create_user)

result = dispatcher.dispatch(CreateUser("alice", "alice@example.com"))
```

## 🏗️ Architecture

FLEXT-Core is designed around Clean Architecture and SOLID principles.

- **Protocols First**: Interfaces are defined using `Protocol` to adhere to the Dependency Inversion Principle.
- **Layered Structure**:
  - **Runtime**: Bridges external libraries and provides the DI surface.
  - **Container**: Manages service lifecycles (Singleton, Factory, Scoped).
  - **Handlers/Dispatcher**: Orchestrates application flow.

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](docs/development/contributing.md) to get started.

1. Fork the repository
1. Create your feature branch (`git checkout -b feature/amazing-feature`)
1. Commit your changes (`git commit -m 'Add amazing feature'`)
1. Push to the branch (`git push origin feature/amazing-feature`)
1. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

