Metadata-Version: 2.4
Name: module_dependency
Version: 0.4.0
Summary: A dependency management tool for Python projects.
Project-URL: Homepage, https://github.com/fabaindaiz/module-injection
Project-URL: Issues, https://github.com/fabaindaiz/module-injection/issues
Author-email: Fabian D <github.clapping767@passmail.net>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: dependency-injection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: dependency-injector
Requires-Dist: jinja2
Requires-Dist: pydantic
Description-Content-Type: text/markdown

# module-dependency

This repository contains experiments and examples for managing dependencies using dependency injection with class decorators in Python projects. The structures and patterns demonstrated here are flexible and can be adapted to suit various project needs.

## Overview

The goal of this project is to showcase different approaches to dependency management, focusing on modularity, flexibility, and ease of use. While the provided examples are specific, the underlying concepts can be applied to a wide range of scenarios.

## Core Components

The project is built around three components that implement different aspects of dependency management:

### 1. Module
- Acts as a container for organizing and grouping related dependencies
- Facilitates modular design and hierarchical structuring of application components

```python
from dependency.core import Module, module

@module()
class SomeModule(Module):
    """This is a module class. Use this to group related components.
    """
    pass
```

### 2. Component
- Defines abstract interfaces or contracts for dependencies
- Promotes loose coupling and enables easier testing and maintenance

```python
from abc import ABC, abstractmethod
from dependency.core import Component, component
from ...plugin.........module import SomeModule

class SomeService(ABC):
    """This is the interface for a new component.
    """
    @abstractmethod
    def method(self, ...) -> ...:
        pass

@component(
    module=SomeModule,     # Declares the module or plugin this component belongs to
    interface=SomeService, # Declares the interface used by the component
)
class SomeServiceComponent(Component):
    """This is the component class. A instance will be injected here.
       Components are only started when provided or bootstrapped.
    """
    pass
```

### 3. Instance
- Delivers concrete implementations of Components
- Manages the lifecycle and injection of dependency objects

```python
from dependency.core import instance, providers
from ...plugin.........component import SomeService, SomeServiceComponent
from ...plugin...other_component import OtherService, OtherServiceComponent

@instance(
    component=SomeServiceComponent, # Declares the component to be provided
    imports=[OtherService, ...],    # List of dependencies (components) that are needed
    provider=providers.Singleton,   # Provider type (Singleton, Factory)
    bootstrap=False,                # Whether to bootstrap on application start
)
class ImplementedSomeService(SomeService):
    """This is a instance class. Here the component is implemented.
       Instances are injected into the respective components when provided.
    """
    def __init__(self) -> None:
        """Init method will be called when the instance is stared.
           This will happen once for singleton and every time for factories.
        """
        # Once declared, i can use the dependencies for the class.
        self.dependency: OtherService = OtherServiceComponent.provide()
    
    def method(self, ...) -> ...:
        """Methods declared in the interface must be implemented.
        """
        do_something()
```

These components work together to create a powerful and flexible dependency injection system, allowing for more maintainable and testable Python applications.

## Extra Components

The project has additional components that enhance its functionality and organization. These components include:

### 1. Entrypoint
- Represents a entry point for the application
- Responsible for initializing and starting the application

```python
from dependency.core import Entrypoint, Container
from ...plugin...... import SomePlugin

class SomeApplication(Entrypoint):
    """This is an application entry point.
       Plugins included here will be loaded and initialized.
    """
    def __init__(self) -> None:
        # Import the instances that will be used on the application
        # This will generate the internal provider structure
        import ...plugin.........component

        # This is the main container, it will hold all the providers
        container = Container.from_dict(config={...}, required=True)
        super().__init__(
            container,
            plugins=[
                SomePlugin,
                ...
            ])

    def main_loop(self) -> None:
        """Main application loop.
        """
        pass
```

### 2. Plugin
- Represents a special module that can be included in the application
- Provides additional functionality or features to the application

```python
from pydantic import BaseModel
from dependency.core import Plugin, PluginMeta, module

class SomePluginConfig(BaseModel):
    """Include configuration options for the plugin.
    """
    pass

@module()
class SomePlugin(Plugin):
    """This is a plugin class. Plugins can be included in the application.
       Plugins are modules that provide additional functionality.
    """
    meta = PluginMeta(name="SomePlugin", version="0.0.1")

    @property
    def config(self) -> SomePluginConfig:
        """Plugins can have their own configuration options.
           Instantiates the model using the container config.
        """
        return SomePluginConfig(**self.container.config())
```

### 3. Dependent
- Represents a class produced by a Provider that requires dependencies
- Allows to provide standalone classes without the need to define new providers

```python
from dependency.core import Dependent, dependent

@dependent(
    imports=[SomeComponent, ...], # List of dependencies (components) that are needed
)
class SomeDependent(Interface, Dependent):
    """This is the dependent class. This class will check for its dependencies.
       Dependents must be declared in some provider and can be instantiated as normal classes.
    """
    def method(self, ...) -> ...:
        pass
```

## Usage Examples

This repository includes a practical example demonstrating how to use the framework. You can find this example in the `example` directory. It showcases the implementation of the core components and how they interact to manage dependencies effectively in a sample application.

## Future Work

This project is a work in progress, and there are several improvements and enhancements planned for the future. Some of the areas that will be explored include:
- Improve component registration and resolution mechanisms
- Improve ways to handle module definitions and configurations
- Explore more advanced dependency injection patterns and use cases
- Enhance validation and error handling mechanisms of the framework

## Aknowledgements

This project depends on [dependency-injector](https://python-dependency-injector.ets-labs.org/introduction/di_in_python.html). This library provides a robust and flexible framework for managing dependencies in Python projects.