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

module_dependency-1.1.4/.github/workflows/docs.yaml

@@ -0,0 +1,37 @@
+name: Deploy Documentation
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install Hatch
+        run: pipx install hatch
+      - name: Build documentation
+        run: hatch run docs:build
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+      - id: deployment
+        name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

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

@@ -5,17 +5,28 @@ 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.3] - 2026-02-
+## [v1.1.4] - 2026-03-19
 
 ### Added
 
--
+- MkDocs configuration for documentation site deployment to GitHub Pages
+
+### Changed
+
+- Updated documentation and docstrings to reflect recent changes and improvements
+
+## [v1.1.3] - 2026-03-16
+
+### Added
+
+- Support for provider classes in LazyWiring, allowing for more flexible and intuitive dependency injection configurations
+- Fallback plugin will be used as parent for all orphans injectables, allowing for better handling of unregistered dependencies
 
 ### Changed
 
 - LazyWiring now accepts provider classes directly, allowing for more intuitive usage
 
-## [v1.1.2] - 2026-02-
+## [v1.1.2] - 2026-03-16
 
 ### Added
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: module_dependency
-Version: 1.1.2
+Version: 1.1.4
 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

module_dependency-1.1.4/docs/ARCHITECTURE.md

@@ -0,0 +1,352 @@
+# Architecture — module-dependency
+
+## Overview
+
+`module-dependency` is a dependency injection framework for modular Python applications,
+built on top of [`dependency-injector`](https://python-dependency-injector.ets-labs.org/).
+It adds a structured layer of abstraction that enforces modular design through a hierarchy
+of organizational and providable units, with a resolution process that validates and wires
+the full dependency graph before the application starts.
+
+The framework is designed with embedded and long-running applications in mind: all
+dependencies are declared statically, resolved eagerly at startup, and injected
+transparently at runtime.
+
+---
+
+## Mental Model
+
+The framework organizes an application around two orthogonal concepts:
+
+- **Structure**: how code is organized and grouped (Plugin, Module)
+- **Providers**: how dependencies are declared and injected (Component, Instance, Product)
+
+Every class in the framework is either a structural container or a providable unit,
+and the two hierarchies mirror each other at runtime through the injection tree.
+
+---
+
+## Core Concepts
+
+### Plugin
+
+A `Plugin` is the top-level structural unit. It represents a self-contained, reusable
+feature of the application. Plugins are the entry points into the dependency graph — only
+classes registered under a plugin (directly or through child modules) will be resolved
+at startup.
+
+Plugins can declare a typed `config` attribute (a Pydantic `BaseModel`), which is
+automatically populated from the application `Container` during resolution.
+
+```python
+@module()
+class HardwarePlugin(Plugin):
+    meta = PluginMeta(name="HardwarePlugin", version="0.1.0")
+    config: HardwarePluginConfig  # populated from Container on resolution
+```
+
+Plugins have no parent module — they are roots of the injection tree.
+
+### Module
+
+A `Module` groups related components under a plugin. Modules can be nested to represent
+sub-features or layers within a plugin. They carry no logic themselves; their only role
+is structural — to define scope and namespace within the injection tree.
+
+```python
+@module(module=HardwarePlugin)
+class HardwareFactoryModule(Module):
+    pass
+```
+
+### Component
+
+A `Component` declares an interface (or contract) for a dependency. It is the unit that
+consumers depend on — other classes declare `Component` types in their `imports`, and
+the framework ensures a concrete implementation is available before they run.
+
+A component without a declared `provider` is purely an interface declaration: it can
+be depended upon, but cannot be provided directly until an `Instance` implements it.
+
+```python
+@component(module=HardwarePlugin)
+class HardwareFactory(ABC, Component):
+    @abstractmethod
+    def createHardware(self, product: str) -> Hardware: ...
+```
+
+### Instance
+
+An `Instance` is the concrete implementation of a `Component`. It inherits from the
+component class and registers itself as the provider for that interface. Multiple
+instances can be declared for the same component — the last one registered wins
+(with a warning log).
+
+```python
+@instance(
+    imports=[HardwareObserver, HardwareA, HardwareB],
+    provider=providers.Singleton,
+)
+class HardwareFactoryCreatorA(HardwareFactory):
+    def __init__(self):
+        self.__factory = HardwareFactory.provide()
+```
+
+### Product
+
+A `Product` is functionally identical to a `Component` with `provider=providers.Factory`.
+The distinction is semantic: Products represent objects that are instantiated on demand
+(not managed as singletons), typically by a factory or service that creates them as
+part of its operation.
+
+```python
+@product(
+    imports=[NumberService],
+    provider=providers.Factory,
+)
+class HardwareA(Hardware, Product):
+    @inject
+    def doStuff(self, operation: str, number: NumberService = LazyProvide[NumberService.reference]):
+        ...
+```
+
+Products are declared as dependencies of the instances or other products that create
+them — not consumed directly by end users of the framework.
+
+---
+
+## Injection Hierarchy
+
+The structural and injection trees are parallel. At the structural level:
+
+```
+Entrypoint
+└── Plugin (root container)
+    └── Module (child container)
+        ├── Component / Instance (provider)
+        └── Product (provider)
+```
+
+At the injection level, this maps to a tree of `ContainerInjection` and
+`ProviderInjection` objects:
+
+```
+ContainerInjection (Plugin)
+└── ContainerInjection (Module)
+    ├── ProviderInjection (Component)
+    └── ProviderInjection (Product)
+```
+
+Each node in this tree knows its parent, and the full dot-separated path from root to
+node is used as the `reference` string for `dependency-injector`'s wiring system
+(e.g. `HardwarePlugin.HardwareFactory`).
+
+---
+
+## Resolution Process
+
+Resolution happens in five sequential phases, triggered by `Entrypoint.initialize()`:
+
+### Phase 1 — Module Resolution (`resolve_modules`)
+
+Each plugin's `ContainerInjection` tree is attached to the application `Container`.
+Plugin configuration is validated and populated from the container config at this point.
+This phase sets up the structural scaffolding before any providers are touched.
+
+### Phase 2 — Injectable Collection (`resolve_injectables`)
+
+Each plugin walks its injection tree and yields the `Injectable` objects for all
+providers that have a valid implementation. Providers without implementation are silently
+skipped (or warned, depending on `strict_resolution`).
+
+### Phase 3 — Graph Expansion (`expand`)
+
+Starting from the collected injectables, the resolver follows each provider's `imports`
+recursively to discover the full transitive dependency graph. Providers marked with
+`partial_resolution=True` are included in the set but their imports are not followed —
+this is the escape hatch for providers that depend on external or optional components.
+
+### Phase 4 — Topological Resolution (`injection`)
+
+Dependencies are resolved in layers. In each iteration, all providers whose imports are
+already resolved are marked as resolved. If an iteration produces no new resolved
+providers, resolution has deadlocked — the error handler checks for circular dependencies
+first, then reports missing implementations.
+
+```
+Layer 1: providers with no imports → resolved
+Layer 2: providers whose imports are all in Layer 1 → resolved
+...
+```
+
+### Phase 5 — Wiring and Initialization
+
+After all providers are resolved, their modules are wired into the `Container` using
+`dependency-injector`'s wiring mechanism. Then, providers with `bootstrap=True` have
+their implementation instantiated eagerly, triggering any `__init__` logic. If `__init__`
+raises `CancelInitialization`, the bootstrap is skipped with a warning rather than
+crashing the application.
+
+---
+
+## The Registry
+
+The `Registry` is a global class-level store of all `ContainerInjection` and
+`ProviderInjection` objects ever created. It is populated at decoration time (when
+`@module`, `@component`, etc. are applied), before any resolution happens.
+
+Its current role is diagnostic: `Registry.validation()` runs before resolution and
+warns about any containers or providers that have no parent module (i.e., were declared
+without being registered under any plugin or module). These are called "orphan"
+providers, and the `FallbackPlugin` handles them at initialization time.
+
+---
+
+## Dependency Injection at Runtime
+
+Once resolved, dependencies can be accessed in two ways:
+
+**Direct provision** — call `.provide()` on the component class. This returns the
+underlying `dependency-injector` provider result (a singleton instance, a new factory
+instance, etc.):
+
+```python
+factory: HardwareFactory = HardwareFactory.provide()
+```
+
+**`@inject` with `LazyProvide`** — for method-level injection, use the `@inject`
+decorator from `dependency-injector` combined with `LazyProvide`. The `Lazy` prefix
+is required to defer the reference resolution to runtime rather than import time:
+
+```python
+@inject
+def doStuff(self,
+    operation: str,
+    number: NumberService = LazyProvide[NumberService.reference],
+) -> None:
+    ...
+```
+
+`LazyProvide`, `LazyProvider`, and `LazyClosing` mirror the standard `Provide`,
+`Provider`, and `Closing` markers from `dependency-injector`, but accept either a
+callable returning a reference string, or a `ProviderMixin` class directly (which
+internally calls `.reference` on it).
+
+---
+
+## Provider Types
+
+The framework supports the three provider types from `dependency-injector`:
+
+| Type | Behavior | Typical use |
+|---|---|---|
+| `providers.Singleton` | One instance for the lifetime of the container | Services, observers, factories |
+| `providers.Factory` | New instance on every `.provide()` call | Products, short-lived objects |
+| `providers.Resource` | Singleton with context manager lifecycle (`__enter__`/`__exit__`) | Resources that need explicit cleanup |
+
+---
+
+## Entrypoint
+
+The `Entrypoint` class orchestrates the full startup sequence. The expected pattern is:
+
+```python
+class MyApplication(Entrypoint):
+    def __init__(self) -> None:
+        container = Container.from_dict(config={...})
+        super().__init__(container, PLUGINS)
+
+        # Import all instance modules here — this triggers @instance decoration,
+        # which registers implementations into the injection tree.
+        import my_app.imports
+
+        # Run the five-phase resolution process.
+        super().initialize()
+```
+
+The separation between `__init__` and `initialize()` is intentional: instance imports
+must happen after the structural tree is set up (after `super().__init__`), but before
+resolution starts (before `super().initialize()`).
+
+---
+
+## Imports File Convention
+
+Because `@instance` and `@product` decorators register themselves at import time,
+implementations must be imported before `initialize()` is called. The convention is
+to collect all these imports in a dedicated `imports.py` file per plugin:
+
+```python
+# example/plugin/hardware/imports.py
+import example.plugin.hardware.bridge.bridgeA
+import example.plugin.hardware.factory.providers.creatorA
+import example.plugin.hardware.observer.publisherA
+```
+
+And then import all plugin imports files from the application's root `imports.py`:
+
+```python
+# app/main/imports.py
+import example.plugin.base.imports
+import example.plugin.hardware.imports
+import example.plugin.reporter.imports
+```
+
+This pattern makes the set of active implementations explicit and easy to swap — for
+example, to run in a test environment with fake implementations, you would create an
+alternative imports file that imports the fakes instead.
+
+---
+
+## Fallback Plugin
+
+Providers that are declared without a parent module (orphan providers) would fail
+resolution because they have no `ContainerInjection` to attach to, and therefore no
+`reference` string for wiring. The `FallbackPlugin` is an internal plugin created
+at initialization time that adopts all such orphan providers, attaches them to its
+container, and marks them with `strict_resolution=False` so they do not block
+resolution if they lack an implementation.
+
+This is a safety mechanism, not a recommended pattern. Orphan providers are warned
+about in `Registry.validation()` and should be assigned to a proper module.
+
+---
+
+## Error Handling
+
+| Exception | When raised |
+|---|---|
+| `DeclarationError` | A provider is accessed (`.provide()`, `.reference`) before being resolved, or has no implementation |
+| `ResolutionError` | The topological resolution deadlocks (circular dependency or unresolved import) |
+| `ProvisionError` | Plugin config validation fails, or a provider without a parent tries to build a reference |
+| `InitializationError` | A bootstrapped provider's `__init__` raises an unexpected exception |
+| `CancelInitialization` | Raised intentionally inside `__init__` to skip bootstrap without crashing |
+
+---
+
+## Internal Class Map
+
+```
+dependency.core
+├── agrupation
+│   ├── Entrypoint          — application startup orchestrator
+│   ├── Plugin              — root structural unit, carries config
+│   ├── Module              — intermediate structural grouping
+│   └── FallbackPlugin      — internal, adopts orphan providers
+├── declaration
+│   ├── Component           — interface declaration + ProviderMixin base
+│   ├── Instance            — concrete implementation of a Component
+│   └── Product             — Component alias, Factory default, legacy support
+├── injection
+│   ├── Injectable          — tracks implementation, imports, resolution state
+│   ├── ContainerInjection  — injection node for structural units (Module/Plugin)
+│   ├── ProviderInjection   — injection node for providable units (Component/Product)
+│   ├── ContainerMixin      — class-level methods for structural units
+│   ├── ProviderMixin       — class-level methods for providable units
+│   └── LazyProvide/Provider/Closing — deferred wiring markers
+└── resolution
+    ├── Container           — DynamicContainer with config helpers
+    ├── Registry            — global store of all injection nodes
+    ├── InjectionResolver   — orchestrates the five resolution phases
+    └── ResolutionStrategy  — implements expand, injection, wiring, initialize
+```

module_dependency-1.1.4/docs/reference/cli.md

@@ -0,0 +1,6 @@
+# CLI Reference
+
+::: dependency.cli.generation.plugin
+::: dependency.cli.generation.module
+::: dependency.cli.generation.component
+::: dependency.cli.generation.instance

module_dependency-1.1.4/docs/reference/core.md

@@ -0,0 +1,32 @@
+# Core Reference
+
+## Agrupation
+
+::: dependency.core.agrupation.entrypoint
+::: dependency.core.agrupation.plugin
+::: dependency.core.agrupation.module
+
+## Declaration
+
+::: dependency.core.declaration.component
+::: dependency.core.declaration.instance
+::: dependency.core.declaration.product
+
+## Injection
+
+::: dependency.core.injection.mixin
+::: dependency.core.injection.injectable
+::: dependency.core.injection.injection
+::: dependency.core.injection.wiring
+
+## Resolution
+
+::: dependency.core.resolution.resolver
+::: dependency.core.resolution.strategy
+::: dependency.core.resolution.registry
+::: dependency.core.resolution.container
+::: dependency.core.resolution.errors
+
+## Exceptions
+
+::: dependency.core.exceptions

module_dependency-1.1.4/mkdocs.yaml

@@ -0,0 +1,44 @@
+site_name: module-dependency
+site_description: A Dependency Injection Framework for Modular Embedded Python Applications
+site_url: https://fabaindaiz.github.io/module-dependency/
+repo_name: module-dependency
+repo_url: https://github.com/tu-usuario/module-dependency
+docs_dir: docs
+strict: true
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.indexes
+    - navigation.top
+    - toc.integrate
+    - content.code.copy
+    - content.code.annotate
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: google
+            show_source: false
+            show_root_heading: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            members_order: source
+            merge_init_into_class: true
+            filters:
+              - "!^_"
+              - "^__init__"
+              - "^__repr__"
+
+nav:
+  - Overview: README.md
+  - Architecture: ARCHITECTURE.md
+  - API Reference:
+    - Core: reference/core.md
+    #- CLI: reference/cli.md
+    - Bibliography: REFERENCES.md

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

@@ -33,6 +33,22 @@ stubs = "stubgen src/dependency -o stubs --include-docstrings"
 tests = "pytest -n auto --dist=loadfile"
 typecheck = "mypy --strict src/dependency"
 
+[tool.hatch.envs.docs]
+template = "default"
+skip-install = false
+dependencies = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
+
+[tool.hatch.envs.docs.env-vars]
+PYTHONPATH = "src"
+
+[tool.hatch.envs.docs.scripts]
+build = "mkdocs build"
+serve = "mkdocs serve"
+
 [tool.mypy]
 plugins = [
   "pydantic.mypy",
@@ -50,7 +66,7 @@ testpaths = ["tests"]
 
 [project]
 name = "module_dependency"
-version = "1.1.2"
+version = "1.1.4"
 dependencies = [
   "dependency_injector",
   "jinja2",

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

@@ -5,6 +5,7 @@ from typing import Iterable
 from dependency.core.agrupation.plugin import Plugin
 from dependency.core.injection.injectable import Injectable
 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
 _logger = logging.getLogger("dependency.loader")
@@ -20,6 +21,19 @@ class Entrypoint:
         plugins: Iterable[type[Plugin]],
         strategy: ResolutionStrategy = ResolutionStrategy(),
     ) -> None:
+        """Set up the application entrypoint.
+
+        Stores the plugin list and initializes the InjectionResolver with the
+        given container. Resolves the structural dependency tree so that the
+        injection hierarchy is ready before instance imports loaded.
+        Full resolution is deferred to initialize().
+
+        Args:
+            container (Container): The application container holding configuration.
+            plugins (Iterable[type[Plugin]]): List of root Plugin classes to load.
+            strategy (ResolutionStrategy): Resolution strategy to use. Defaults to
+                a standard ResolutionStrategy with default config.
+        """
         self.init_time: float = time.time()
         self.modules: list[type[Plugin]] = list(plugins)
         self.strategy: ResolutionStrategy = strategy
@@ -41,6 +55,10 @@ class Entrypoint:
         injectables: Iterable[Injectable] = (),
     ) -> None:
         """Initialize the application."""
+        if self.strategy.config.init_fallback:
+            initialize_fallback(parent=self.resolver.container)
+            _logger.info("Fallback plugin initialized")
+
         providers: set[Injectable] = self.resolver.resolve_injectables(
             modules=self.modules,
         )

module_dependency-1.1.4/src/dependency/core/agrupation/fallback.py

@@ -0,0 +1,48 @@
+import logging
+from dependency_injector import containers
+from dependency.core.agrupation.module import module
+from dependency.core.agrupation.plugin import Plugin, PluginMeta
+from dependency.core.resolution.registry import Registry
+_logger = logging.getLogger("dependency.loader")
+
+def initialize_fallback(parent: containers.Container) -> type[Plugin]:
+    """Create and initialize the internal FallbackPlugin.
+
+    The FallbackPlugin adopts all orphan providers — providers that were declared
+    without a parent module and therefore have no ContainerInjection node in the
+    tree. Without adoption, these providers would fail resolution because they
+    cannot build a reference string for wiring.
+
+    Orphan providers are attached to the FallbackPlugin's container, marked with
+    strict_resolution=False so they do not block resolution if they lack an
+    implementation, and their providers are resolved against the parent container.
+
+    This function is called once during Entrypoint.initialize() before the main
+    resolution phases run. It is an internal safety mechanism — orphan providers
+    should ideally be assigned to a proper module.
+
+    Args:
+        parent (containers.Container): The root application container.
+
+    Returns:
+        type[Plugin]: The dynamically created FallbackInternal plugin class.
+    """
+    @module()
+    class FallbackInternal(Plugin):
+        meta = PluginMeta(name="FallbackPlugin", version="1.0.0")
+
+        @classmethod
+        def initialize_fallback(cls, parent: containers.Container) -> None:
+            #for container in Registry.containers:
+            #    if container.parent is None and not container.is_root:
+            #        _logger.debug(f"Container {container} has been registered to fallback module")
+            #        container.change_parent(cls.injection)
+            for provider in Registry.providers:
+                if provider.parent is None and not provider.is_root:
+                    _logger.debug(f"Provider {provider} has been registered to fallback module")
+                    provider.injectable.strict_resolution = False
+                    provider.change_parent(cls.injection)
+            cls.resolve_providers(container=parent)
+
+    FallbackInternal.initialize_fallback(parent=parent)
+    return FallbackInternal

module_dependency-1.1.4/src/dependency/core/agrupation/module.py

@@ -0,0 +1,52 @@
+from typing import Callable, Optional, TypeVar
+from dependency.core.injection.mixin import ContainerMixin
+
+MODULE = TypeVar('MODULE', bound='Module')
+
+class Module(ContainerMixin):
+    """Base class for all structural grouping units in the framework.
+
+    A Module organizes related Components and Products under a common namespace
+    within the injection tree. It carries no logic of its own — its only role is
+    structural: to define scope and hierarchy for the providers registered under it.
+
+    Modules must be decorated with @module to be registered in the injection tree.
+    """
+
+def module(
+    module: Optional[type[Module]] = None
+) -> Callable[[type[MODULE]], type[MODULE]]:
+    """Register a Module class into the injection tree.
+
+    Initializes a ContainerInjection node for the decorated class and attaches
+    it to the parent module's injection node if one is provided. The decorated
+    class must be a subclass of Module.
+
+    Args:
+        module (type[Module], optional): Parent module or plugin this module
+            belongs to. If None, the module is registered without a parent —
+            it will be treated as an orphan unless it is itself a Plugin root.
+            Defaults to None.
+
+    Raises:
+        TypeError: If the decorated class is not a subclass of Module.
+
+    Returns:
+        Callable[[type[MODULE]], type[MODULE]]: Decorator that registers the
+            module class and returns it unchanged.
+    """
+    def wrap(cls: type[MODULE]) -> type[MODULE]:
+        """Register the module class into the injection tree.
+
+        Initializes the ContainerInjection for the class and attaches it to the
+        parent module's injection node if one was provided.
+        """
+        if not issubclass(cls, Module):
+            raise TypeError(f"Class {cls} has decorator @module but is not a subclass of Module") # pragma: no cover
+
+        cls.init_injection(
+            parent=module.injection if module else None
+        )
+
+        return cls
+    return wrap