Metadata-Version: 2.4
Name: turbolightdi
Version: 0.1.0
Summary: TurboLightDI: TurboLightDI is a lightweight, high-performance Inversion of Control (IoC) container.
Project-URL: Homepage, https://github.com/turborg/turbolightdi
Project-URL: Repository, https://github.com/turborg/turbolightdi
Project-URL: Bug Tracker, https://github.com/turborg/turbolightdi/issues
Author-email: stefanzc <stefanzc@turborg.com>
License: MIT
License-File: LICENSE
Keywords: dependency-injection,fast,high-performance,inversion-of-control,micro-di,minimalist,turborg
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
<a href="https://turborg.com/TurboLightDI" target="_blank">
<img src="https://i.postimg.cc/4dwfgzNr/TurboLightDItransparent.png" alt="TurboLightDI Logo" width="400px">
</a>
</p>

<div align="center">

![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?style=flat-square)
![Development Status](https://img.shields.io/badge/status-Alpha-orange?style=flat-square)

</div>

<p align="center">
TurboLightDI is a lightweight, high-performance Inversion of Control container for Python.
</p>


## About TurboLightDI

TurboLightDI aims to provide elegant dependency injection using decorators and type hints, allowing you to build decoupled, testable, and maintainable applications.

Core features:

* Zero Configuration: Use standard Python decorators.
* Constructor Injection: Automatic wiring based on Python type hints.
* Lifecycle Management: Efficiently manages object lifecycles (singleton, prototype...)
* Third-Party Support: Use `@borg` to inject objects from libraries like Redis, SQLAlchemy or any other third party lib.
* Circular Dependency Detection: Built-in protection against recursive injections (for example, A → B, B → A).

---
## Development
```bash
uv venv --python 3.12
uv pip install .[dev]
pre-commit install
```

## Usage
**TurboLightDI** uses a special hierarchy to manage your application's lifecycle. Components are divided into **External Components** and **Internal Logic**.

### Quick Example
```python
from TurboLightDI import cy, borg, service, repository

@cy
class DatabaseConfig:
    @borg
    def session_factory(self) -> Session:
        return create_session_factory()

@repository
class UserRepository(TurboquentRepository):
    pass

@service
class UserService:
    def __init__(self, user_repository: UserRepository):
        self.user_repository = user_repository
```

### External Integration
Use these decorators to integrate third-party libraries (like Redis, SQLAlchemy etc..) into your application.
* **`@cy` (Configuration Yield)**: A class-level decorator for modules that house the configurations required to yield the objects your application needs.
* **`@borg` (Bound Object Resource Graph)**: A method-level decorator used within a `@cy` class. It holds and registers third-party libraries as assimilated components in the DI graph.

### Internal Logic (Components)
For classes created within your own codebase, use the following decorators to enable auto DI:

* **`@Component`**: The base decorator for any general-purpose class managed by the TurboLightDIContainer.

#### Specialized Components
To maintain clean architectural separation, use these specific aliases:

| Decorator         | Role | Description                                                                                                                                                          |
|:------------------| :--- |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **`@controller`** | **REST APIs** | Entry points that orchestrate RESTful communication and handle incoming requests                                                                                     |
| **`@service`**    | **Business Logic** | Encapsulates business logic.                                                                                                                                         |
| **`@repository`** | **Data Access** | Communicates with data holders. Usually implements `TurboquentRepository`, providing a powerful abstraction layer for common DB operations with minimal boilerplate. |



---
*Part of the [**Turborg**](https://turborg.com) AI-First Open Source Suite Ecosystem*
