module-dependency 1.1.4__tar.gz → 1.1.6__tar.gz

{module_dependency-1.1.4 → module_dependency-1.1.6}/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v1.1.5] - 2026-03-
+
+### Added
+
+- Extensive unit tests for core modules, including resolution strategy, injection, and product management
+- Updated documentation with examples and usage guidelines for new features and changes
+
 ## [v1.1.4] - 2026-03-19
 
 ### Added

{module_dependency-1.1.4 → module_dependency-1.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: module_dependency
-Version: 1.1.4
+Version: 1.1.6
 Summary: A dependency management tool for Python projects.
 Project-URL: Homepage, https://github.com/fabaindaiz/module-injection
 Project-URL: Documentation, https://github.com/fabaindaiz/module-dependency/tree/main/docs
@@ -15,14 +15,14 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Requires-Dist: dependency-injector
 Requires-Dist: jinja2
 Requires-Dist: pydantic
 Requires-Dist: pydantic-settings
 Description-Content-Type: text/markdown
 
-# module-dependency
+# Module Dependency
 
 A Dependency Injection Framework for Modular Embedded Python Applications.
 
@@ -42,6 +42,8 @@ This project is available on PyPI on [module_dependency](https://pypi.org/projec
 pip install module-dependency
 ```
 
+Documentation are available on [GitHub Pages](https://fabaindaiz.github.io/module-dependency/).
+
 ## Core Components
 
 The project is built around three components that implement different aspects of dependency management:
@@ -210,7 +212,7 @@ from ...plugin.....other_product import OtherProduct
 @product(
     module=SomeModule,              # Declares the module or plugin this component belongs to
     imports=[SomeService, ...],     # List of dependencies (components) that this product needs
-    provider=providers.Singleton,   # Provider type (Singleton, Factory, Resource)
+    provider=providers.Factory,   # Provider type (Singleton, Factory, Resource)
 )
 class SomeProduct(Interface, Product):
     """This is the product class. This class will check for its dependencies.
@@ -238,32 +240,28 @@ class SomeProduct(Interface, Product):
 
 ## Important Notes
 
-- Declare all the dependencies (components) on Instances and Products to avoid injection issues.
+- Remember to declare all the dependencies you need in the `imports` parameter of the `@instance` or `@product` decorator.
 - Read the documentation carefully and refer to the examples to understand the framework's behavior.
 
 ## 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.
 
-This example requires the `module-injection` package to be installed and the `library` folder to be present in the project root.
-
 ## Future Work
 
 This project is a work in progress, and there are several improvements and enhancements planned for the future.
 
 Some planned features are:
+- Add pre-defined components for common patterns and use cases
+- Dependency CLI support for easier interaction with the framework
+- Pytest testing framework integration for better test management
+
+Some new improvements that has been recently added:
 - Enhance documentation and examples for better understanding
 - Implement framework API and extension points for customization
 - Improve injection resolution and initialization process
-- Testing framework integration for better test coverage
 - Visualization tools for dependency graphs and relationships
 
-Some of the areas that will be explored in the future include:
-- Add some basic components and plugins for common use cases
-- Dependency CLI support for easier interaction with the framework
-- Explore more advanced dependency injection patterns and use cases
-- Improve testing and validation for projects using this framework
-
 Pending issues that eventually will be addressed:
 - Migration guide from previous versions (some breaking changes were introduced)
 

module_dependency-1.1.6/README.md

@@ -0,0 +1,251 @@
+# Module Dependency
+
+A Dependency Injection Framework for Modular Embedded Python Applications.
+
+## Overview
+
+The goal of this project is to provide a comprehensive framework for managing structure for complex Python applications. The framework is designed to be modular, allowing developers to define components, interfaces, and instances that can be easily managed and injected throughout the application.
+
+Declare components with interfaces, provide multiple implementations of them, and manage which implementation to use at runtime. Multiple components can be organized and composed together to form complex behaviors using modular design principles.
+
+This repository includes a working example of a simple application that demonstrates these concepts in action. Based on a real-world use case, the example showcases how to effectively manage dependencies and implement modular design patterns in an embedded Python environment.
+
+## Install
+
+This project is available on PyPI on [module_dependency](https://pypi.org/project/module_dependency/). It can be installed using pip:
+
+```bash
+pip install module-dependency
+```
+
+Documentation are available on [GitHub Pages](https://fabaindaiz.github.io/module-dependency/).
+
+## 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
+from ...plugin.........module import ParentModule
+
+@module(
+    module=ParentModule,  # Declares the parent module (leave empty for plugins)
+)
+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
+
+@component(
+    module=SomeModule,     # Declares the module or plugin this component belongs to
+)
+class SomeService(ABC, Component):
+    """This is the component class. A instance will be injected here.
+       Components are only started when provided or bootstrapped.
+       Components also defines the interface for all instances.
+    """
+    @abstractmethod
+    def method(self, ...) -> ...:
+        pass
+```
+
+### 3. Instance
+- Delivers concrete implementations of Components
+- Manages the lifecycle and injection of dependency objects
+
+```python
+from dependency_injector.wiring import inject
+from dependency.core import instance, providers
+from dependency.core.injection import LazyProvide
+from ...plugin.........component import SomeService
+from ...plugin...other_component import OtherService
+from ...plugin...........product import SomeProduct
+
+@instance(
+    imports=[OtherService, ...],    # List of dependencies (components) that this product needs
+    provider=providers.Singleton,   # Provider type from di (Singleton, Factory, Resource)
+    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.
+       Instances must inherit from the component class and implement all its methods.
+    """
+    def __init__(self) -> None:
+        """Init method will be called when the instance is started.
+           This will happen once for singleton and every time for factories.
+        """
+        # Once declared, i can use the dependencies for the class
+        self.dependency: OtherService = OtherService.provide()
+
+    @inject
+    def method(self,
+        # Dependencies also can be provided using @inject decorator with LazyProvide
+        # With @inject always use LazyProvide, to avoid deferred evaluation issues.
+        dependency: OtherService = LazyProvide(OtherService.reference),
+    ...) -> ...:
+        """Methods declared in the interface must be implemented.
+        """
+        # Once declared, i can safely create any product
+        # Products are just normal classes (see next section)
+        product = SomeProduct()
+
+        # You can do anything here
+        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 entrypoint 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:
+        # Declare all the plugins that will be used in the application
+        # Its recommended to declare the plugins list them in a separate file
+        # You can also include in the same file all the instances imports
+        PLUGINS = [
+            SomePlugin,
+            ...
+        ]
+
+        # This is the main container, it will hold all the containers and providers
+        # Requires to have a valid configuration that will be used to initialize plugins
+        container = Container.from_dict(config={...}, required=True)
+        super().__init__(container, PLUGINS)
+
+        # Import all the instances that will be used on the application
+        # You can apply some logic to determine which instances to import
+        # This will automatically generate the internal provider structure
+        import ...plugin.........instance
+
+        # Once all the plugins and instances are imported, we can initialize the application
+        super().initialize()
+```
+
+### 2. Plugin
+- Represents a special module that can be included in the application
+- Provides additional functionality and 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 information about the plugin (only affects logging)
+    meta = PluginMeta(name="SomePlugin", version="0.0.1")
+
+    # Type hint for the plugin configuration
+    # On startup, config will be instantiated using the container config
+    config: SomePluginConfig
+```
+
+### 3. Product
+- Represents a class that requires dependencies injected from the framework
+- Allows to provide standalone classes without the need to define new providers
+
+```python
+from dependency.core import Product, product, providers
+from dependency.core.injection import LazyProvide, inject
+from ...plugin.........component import SomeService
+from ...plugin.....other_product import OtherProduct
+
+@product(
+    module=SomeModule,              # Declares the module or plugin this component belongs to
+    imports=[SomeService, ...],     # List of dependencies (components) that this product needs
+    provider=providers.Factory,   # Provider type (Singleton, Factory, Resource)
+)
+class SomeProduct(Interface, Product):
+    """This is the product class. This class will check for its dependencies.
+       Products must be declared in some instance and can be instantiated as normal classes.
+    """
+    def __init__(self, ...) -> None:
+        # Dependencies can be used in the same way as before
+        self.dependency: SomeService = SomeService.provide()
+
+    @inject
+    def method(self,
+        # Dependencies also can be provided using @inject decorator with LazyProvide
+        # With @inject always use LazyProvide, to avoid deferred evaluation issues.
+        dependency: SomeService = LazyProvide(SomeService.reference),
+    ...) -> ...:
+        """Product interface can be defined using normal inheritance.
+        """
+        # Once declared, i can safely create any sub-product
+        # Products are just normal classes (see next section)
+        product = OtherProduct()
+
+        # You can do anything here
+        do_something()
+```
+
+## Important Notes
+
+- Remember to declare all the dependencies you need in the `imports` parameter of the `@instance` or `@product` decorator.
+- Read the documentation carefully and refer to the examples to understand the framework's behavior.
+
+## 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 planned features are:
+- Add pre-defined components for common patterns and use cases
+- Dependency CLI support for easier interaction with the framework
+- Pytest testing framework integration for better test management
+
+Some new improvements that has been recently added:
+- Enhance documentation and examples for better understanding
+- Implement framework API and extension points for customization
+- Improve injection resolution and initialization process
+- Visualization tools for dependency graphs and relationships
+
+Pending issues that eventually will be addressed:
+- Migration guide from previous versions (some breaking changes were introduced)
+
+## Aknowledgements
+
+This project depends on:
+- [dependency-injector](https://python-dependency-injector.ets-labs.org/introduction/di_in_python.html) a robust and flexible framework for dependency injection in Python.
+- [pydantic](https://docs.pydantic.dev/latest/) a data validation and settings management library using Python type annotations.
+- [jinja2](https://jinja.palletsprojects.com/) a modern and designer-friendly templating engine for Python.
+
+Thanks to [Reite](https://reite.cl/) for providing inspiration and guidance throughout the development of this project.

{module_dependency-1.1.4 → module_dependency-1.1.6/docs}/README.md

@@ -1,4 +1,4 @@
-# module-dependency
+# Module Dependency
 
 A Dependency Injection Framework for Modular Embedded Python Applications.
 
@@ -18,6 +18,8 @@ This project is available on PyPI on [module_dependency](https://pypi.org/projec
 pip install module-dependency
 ```
 
+Documentation are available on [GitHub Pages](https://fabaindaiz.github.io/module-dependency/).
+
 ## Core Components
 
 The project is built around three components that implement different aspects of dependency management:

{module_dependency-1.1.4 → module_dependency-1.1.6}/mkdocs.yaml

@@ -40,5 +40,5 @@ nav:
   - Architecture: ARCHITECTURE.md
   - API Reference:
     - Core: reference/core.md
-    #- CLI: reference/cli.md
+    # - CLI: reference/cli.md
     - Bibliography: REFERENCES.md

{module_dependency-1.1.4 → module_dependency-1.1.6}/pyproject.toml

@@ -17,10 +17,12 @@ packages = [
 template = "default"
 skip-install = false
 dependencies = [
+  "graphviz",
   "mypy",
   "pytest-asyncio",
   "pytest-cov",
   "pytest-xdist",
+  "uvloop",
 ]
 
 [tool.hatch.envs.build.env-vars]
@@ -28,6 +30,7 @@ PYTHONPATH = "src"
 
 [tool.hatch.envs.build.scripts]
 coverage = "pytest --cov src/dependency --cov-report html -n auto --dist=loadfile"
+graph = "python src/graph.py"
 example = "python src/main.py"
 stubs = "stubgen src/dependency -o stubs --include-docstrings"
 tests = "pytest -n auto --dist=loadfile"
@@ -37,9 +40,9 @@ typecheck = "mypy --strict src/dependency"
 template = "default"
 skip-install = false
 dependencies = [
-    "mkdocs",
-    "mkdocs-material",
-    "mkdocstrings[python]",
+  "mkdocs",
+  "mkdocs-material",
+  "mkdocstrings[python]",
 ]
 
 [tool.hatch.envs.docs.env-vars]
@@ -66,14 +69,14 @@ testpaths = ["tests"]
 
 [project]
 name = "module_dependency"
-version = "1.1.4"
+version = "1.1.6"
 dependencies = [
   "dependency_injector",
   "jinja2",
   "pydantic",
   "pydantic-settings",
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 authors = [
   { name="Fabian D", email="github.clapping767@passmail.net" },
 ]

{module_dependency-1.1.4 → module_dependency-1.1.6}/src/dependency/core/agrupation/entrypoint.py

@@ -8,6 +8,7 @@ from dependency.core.resolution.container import Container
 from dependency.core.agrupation.fallback import initialize_fallback
 from dependency.core.resolution.resolver import InjectionResolver
 from dependency.core.resolution.strategy import ResolutionStrategy
+from dependency.library.threading import handle_exit
 _logger = logging.getLogger("dependency.loader")
 
 class Entrypoint:
@@ -69,6 +70,10 @@ class Entrypoint:
         )
         _logger.info(f"Application initialized in {time.time() - self.init_time} seconds")
 
+    @handle_exit
     def main_loop(self) -> None:
-        """Main loop for the application. Waits indefinitely."""
+        """Main loop for the application. Waits indefinitely.
+
+        This method is intended to be called after the application has been initialized.
+        """
         Event().wait() # pragma: no cover

{module_dependency-1.1.4 → module_dependency-1.1.6}/src/dependency/core/injection/injectable.py

@@ -1,4 +1,5 @@
 import logging
+
 from typing import Any, Callable, Iterable, Optional
 _logger = logging.getLogger("dependency.loader")
 
@@ -22,12 +23,27 @@ class Injectable:
         # Dependency tracking
         self.imports: set['Injectable'] = set()
         self.dependent: set['Injectable'] = set()
+        self._weight: Optional[int] = None
 
         # Validation flags
         self.partial_resolution: bool = False
         self.strict_resolution: bool = True
         self.is_resolved: bool = False
 
+    def weight(self) -> int:
+        """Calculate the weight of this injectable for graph visualization.
+
+        The weight is defined as the number of imports plus twice the number of
+        dependents. This heuristic emphasizes providers that are more central in
+        the dependency graph, as they have more dependents relying on them.
+
+        Returns:
+            int: The calculated weight of this injectable.
+        """
+        if self._weight is None:
+            self._weight = len(self.imports) + sum(d.weight() for d in self.imports)
+        return self._weight
+
     def has_implementation(self) -> bool:
         """Check if the implementation of this injectable is valid.
 

{module_dependency-1.1.4 → module_dependency-1.1.6}/src/dependency/core/utils/cycle.py

@@ -70,7 +70,7 @@ def find_cycles(
         visited.add(node)
         path.append(node)
         for dep in function(node):
-            visit(dep, path, visited)
+            visit(dep, path, visited.copy())
         path.pop()
 
     for element in elements:

module_dependency-1.1.6/src/dependency/library/graph/__init__.py

@@ -0,0 +1,5 @@
+from dependency.library.graph.generate import generate_graph
+
+__all__ = [
+    "generate_graph",
+]

module_dependency-1.1.6/src/dependency/library/graph/generate.py

@@ -0,0 +1,56 @@
+from dependency.core import Registry
+from dependency.core.injection import ContainerInjection, ProviderInjection
+from dependency.library.graph.models import Graph, Cluster, Node, Edge
+
+def generate_graph(
+    output: str = "build/output",
+    ignore_modules: set[str] = {"BasePlugin"},
+) -> None:
+    """Generate a graph visualization of the registered containers and providers.
+
+    This method allows you to visualize the structure of your dependency graph, including the
+    containers (modules) and providers (components/products) and their relationships. The generated
+    graph can be used for debugging, documentation, or simply to understand the structure of your
+    dependency graph. The output will be saved as an SVG file at the specified location.
+
+    Args:
+        output: The output path for the generated graph.
+        ignore_modules: A set of module names to ignore during graph generation.
+    """
+    graph: Graph = Graph(name="Dependency Graph")
+    for container in Registry.containers:
+        if container.is_root:
+            graph.drawable.append(process_container(graph, container, ignore_modules))
+
+    digraph = graph.draw()
+    digraph.render(filename=output, format="svg") # type: ignore
+
+def process_container(
+    graph: Graph,
+    container: ContainerInjection,
+    ignore_modules: set[str] = {"BasePlugin"},
+) -> Cluster:
+    cluster = Cluster(name=container.name)
+    for child in container.childs:
+        if isinstance(child, ContainerInjection):
+            cluster.childs.append(process_container(graph, child, ignore_modules))
+        elif isinstance(child, ProviderInjection):
+            cluster.childs.append(process_provider(graph, child, ignore_modules))
+    return cluster
+
+def process_provider(
+    graph: Graph,
+    provider: ProviderInjection,
+    ignore_modules: set[str] = {"BasePlugin"},
+) -> Node:
+    if provider.parent is not None and str(provider.parent) in ignore_modules:
+        return Node(name=provider.name)
+
+    for dependent in provider.injectable.dependent:
+        source: str = provider.injectable.interface_cls.__name__
+        target: str = dependent.interface_cls.__name__
+        edge: Edge = Edge(source=source, target=target)
+        graph.edges.append(edge)
+
+    in_degree: int = provider.injectable.weight()
+    return Node(name=provider.name, in_degree=in_degree)

module_dependency-1.1.6/src/dependency/library/graph/models.py

@@ -0,0 +1,79 @@
+from abc import ABC, abstractmethod
+from itertools import groupby, pairwise
+from graphviz import Digraph
+from pydantic import BaseModel
+
+GROUP_SIZE: int = 2
+
+class Graph(BaseModel):
+    name: str = "Dependency Graph"
+    drawable: list[Drawable] = []
+    edges: list[Edge] = []
+
+    def draw(self) -> Digraph:
+        graph: Digraph = Digraph(comment=self.name, engine="dot")
+        graph.attr(rankdir="TB", newrank="true", ordering="in", overlap="false", splines="true", nodesep="1.0", ranksep="1.0")
+        graph.attr("node", fontname="Helvetica", fontsize="12", margin="0.2", style="invis")
+
+        for drawable in self.drawable:
+            drawable.draw(graph)
+        for edge in self.edges:
+            edge.draw(graph)
+        return graph
+
+class Drawable(BaseModel, ABC):
+    name: str
+    in_degree: int = 0
+
+    @abstractmethod
+    def draw(self, parent: Digraph) -> None:
+        pass
+
+class Cluster(Drawable):
+    childs: list[Drawable] = []
+    style: dict[str, str] = {
+        "style": "rounded,filled",
+        "fillcolor": "lightyellow",
+        "color": "gray",
+        "penwidth": "2",
+    }
+
+    def draw(self, parent: Digraph) -> None:
+        with parent.subgraph(name=f"cluster_{self.name}") as c:
+            c.attr(label=self.name, **self.style)
+
+            # Agrupar por profundidad y ordenar por in_degree dentro de cada grupo
+            def bucket(x: Drawable): return x.in_degree // GROUP_SIZE
+            childs: list[Drawable] = sorted(self.childs, key=lambda c: c.in_degree)
+            groups = [list(g) for _, g in groupby(childs, key=bucket)]
+
+            for group in groups:
+                for child in group:
+                    child.draw(c)
+
+                # Arista invisible entre nodos del mismo grupo para mantenerlos juntos
+                for i, (n1, n2) in enumerate(pairwise(group)):
+                    if isinstance(n2, Node) and i % min(2,  max(1, len(group) // GROUP_SIZE)) != 0:
+                        c.edge(n1.name, n2.name, style="invis", weight="1")
+
+            # Arista invisible solo entre representantes de grupos consecutivos
+            for (g1, g2) in pairwise(groups):
+                c.edge(g1[0].name, g2[0].name, style="invis", weight="1")
+
+class Node(Drawable):
+    style: dict[str, str] = {
+        "shape": "box",
+        "style": "filled",
+        "fillcolor": "white",
+    }
+
+    def draw(self, parent: Digraph) -> None:
+        parent.node(self.name, **self.style)
+
+class Edge(BaseModel):
+    source: str
+    target: str
+
+    def draw(self, parent: Digraph) -> None:
+        kwargs: dict[str, str] = {}
+        parent.edge(self.source, self.target, weight="5", minlen="1", **kwargs)