Merge pull request #2 from tylersuehr7/feature/providers

feat: Injection Factories

Author: tylersuehr7

CHANGELOG.md

@@ -5,7 +5,25 @@ 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).
 
-## [0.1.0] — Unreleased
+## [0.3.0] — Unreleased
+
+### Added
+
+- `@provides` decorator for conditional/factory-based bindings. Use when the
+  concrete implementation of an interface must be chosen at runtime (feature
+  flags, environment, etc.). Factories support dependency injection via
+  annotated parameters and respect `Scope.SINGLETON`, `TRANSIENT`, and
+  `THREAD` for invocation frequency. Factories are evaluated eagerly at
+  `container.initialize()`; failures raise the new `ProviderResolutionError`.
+- `ProviderResolutionError` exception type for `@provides` factory failures.
+- All three example apps (Django, FastAPI, Flask) now demo `@provides` via a
+  `GREETER_FORMATTER_STYLE` env var that swaps the name formatter at boot.
+
+### Changed
+
+- Lowered minimum Python version to 3.12 (was 3.13).
+
+## [0.2.0]
 
 ### Fixed
 
@@ -21,11 +39,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   injector approach did not affect transitive dependencies of parent-owned
   singletons, so overrides silently had no effect on deeper graphs.
 
+## [0.1.0]
+
 ### Added
 
-- `examples/django_demo/` — minimal Django project demonstrating ports/adapters,
-  `@injectable`, `AutowiredAppConfig`, `container.get()` in views, and the
-  three testing patterns (pure unit, full wiring, override).
+- `examples/django_demo/`, `examples/fastapi_demo/`, `examples/flask_demo/` —
+  minimal projects demonstrating ports/adapters, `@injectable`, framework
+  integration, and the three testing patterns (pure unit, full wiring, override).
 - `django_autowired.inspect` module with `BindingReport`, `report()`, and
   renderers for `table`, `tree`, `json`, and `mermaid` output.
 - `python -m django_autowired inspect` CLI that scans packages and prints
@@ -53,4 +73,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `ContainerAlreadyInitializedError`, `DuplicateBindingError`,
   `BackendNotInstalledError`, `UnresolvableTypeError`.
 
+[0.3.0]: https://github.com/tylersuehr7/django-autowired/releases/tag/v0.3.0
+[0.2.0]: https://github.com/tylersuehr7/django-autowired/releases/tag/v0.2.0
 [0.1.0]: https://github.com/tylersuehr7/django-autowired/releases/tag/v0.1.0

docs/guide/injectable.md

@@ -1,8 +1,12 @@
 # `@injectable`
 
-The `@injectable` decorator is the only user-facing touchpoint for registering
+The `@injectable` decorator is the primary user-facing touchpoint for registering
 a class with the container.
 
+!!! tip "Need conditional binding?"
+    If the concrete implementation must be chosen at runtime — for example,
+    based on a feature flag — see [`@provides`](provides.md) instead.
+
 ## Signature
 
 ```python

docs/guide/provides.md

@@ -0,0 +1,137 @@
+# `@provides`
+
+`@injectable` covers 99% of dependency wiring. Use `@provides` when the concrete
+implementation of an interface must be chosen **at runtime** — typically based
+on a feature flag, environment, or config rule.
+
+## When to reach for `@provides`
+
+- A composite/strategy binding where the selected implementation depends on
+  runtime state (feature flag, region, tenant, environment).
+- A third-party SDK client that needs non-trivial construction and can't be
+  expressed as a single `@injectable` class.
+
+If you just need to register a class, use `@injectable`. If you need a manual
+binding for a value that never changes (e.g. a constant config object), prefer
+`extra_modules`.
+
+## Basic usage
+
+```python
+from abc import ABC, abstractmethod
+from django_autowired import injectable, provides
+
+
+class IPaymentGateway(ABC):
+    @abstractmethod
+    def charge(self, amount: int) -> str: ...
+
+
+class StripeV1Gateway(IPaymentGateway):
+    def charge(self, amount: int) -> str:
+        return f"stripe-v1:{amount}"
+
+
+class StripeV2Gateway(IPaymentGateway):
+    def charge(self, amount: int) -> str:
+        return f"stripe-v2:{amount}"
+
+
+@provides(bind_to=IPaymentGateway)
+def payment_gateway(flags: FeatureFlags) -> IPaymentGateway:
+    if flags.is_enabled("use_stripe_v2"):
+        return StripeV2Gateway()
+    return StripeV1Gateway()
+```
+
+`FeatureFlags` is resolved from the container just like any `@injectable`
+dependency — provider functions support full dependency injection.
+
+## Signature
+
+```python
+@provides(bind_to: type, scope: Scope = Scope.SINGLETON)
+```
+
+- `bind_to` — **required**. The interface/type the factory's return value binds
+  to. A provider without `bind_to` is rejected at decoration time.
+- `scope` — Lifecycle scope the container applies to factory invocation.
+
+## Scope semantics
+
+`@provides` is a factory — the framework owns the scope around it:
+
+| Scope | Factory invoked |
+| --- | --- |
+| `SINGLETON` (default) | Once per container lifetime. Result cached. |
+| `TRANSIENT` | On every `container.get()` call. |
+| `THREAD` | Once per thread. Result cached per-thread. |
+
+This matches Spring `@Bean` / Dagger `@Provides` semantics. Your factory does
+not manage caching — the framework does.
+
+## Factory injection
+
+Factory parameters are resolved from the container. All parameters **must be
+type-annotated**:
+
+```python
+@provides(bind_to=IPaymentGateway)
+def payment_gateway(
+    flags: FeatureFlags,
+    cfg: StripeConfig,
+    logger: ILogger,
+) -> IPaymentGateway:
+    if flags.is_enabled("use_stripe_v2"):
+        return StripeV2Gateway(cfg, logger)
+    return StripeV1Gateway(cfg, logger)
+```
+
+A factory parameter without an annotation raises `TypeError` at build time.
+
+## One binding per target
+
+Whether you use `@injectable` or `@provides`, each interface can be bound
+**exactly once**. Any combination of:
+
+- two `@injectable` classes with the same `bind_to`
+- two `@provides` functions with the same `bind_to`
+- one `@injectable` + one `@provides` with the same `bind_to`
+
+…raises `DuplicateBindingError`. This is a feature: predictable, deterministic
+resolution is a core guarantee of `django-autowired`.
+
+If you need multiple candidates selected at runtime, express the conditional
+logic **inside a single** `@provides` function that returns the correct
+instance.
+
+## Eager evaluation
+
+Every `@provides` factory runs once during `container.initialize()` to catch
+errors at boot:
+
+- Factory raises → `ProviderResolutionError` wraps the exception.
+- Factory has unresolvable dependencies → `ProviderResolutionError`.
+
+For `SINGLETON` scope this eager invocation produces the cached instance. For
+`TRANSIENT` and `THREAD` scope the instance is discarded — the eager run is
+pure verification. This matches the library's "fail loudly at boot" principle.
+
+## What `@provides` cannot do
+
+- **Cannot decorate a class.** `@provides` only decorates functions.
+- **Cannot be called without `bind_to`.** Raises `TypeError` immediately.
+- **Cannot chain/fallback.** Multiple providers for the same target are an
+  error, not an ordered list.
+
+## FAQ
+
+**Q: Should my factory return a class or an instance?**
+An instance. `@provides` is a factory. The framework handles scope/caching.
+
+**Q: What if the factory needs to construct something complex with many deps?**
+Declare those deps as factory parameters — they are resolved from the container
+just like `@injectable` constructor parameters.
+
+**Q: Can a `@provides` factory depend on another `@provides` factory?**
+Yes. Dependency resolution across factories is handled by the backend.

docs/index.md

@@ -93,6 +93,7 @@ That's the whole integration. No `binder.bind()`. No `Module` subclasses.
 ## Next steps
 
 - **[`@injectable`](guide/injectable.md)** — the decorator in depth
+- **[`@provides`](guide/provides.md)** — conditional/factory-based bindings
 - **[Scopes](guide/scopes.md)** — singleton, transient, thread
 - **[Scanning](guide/scanning.md)** — how packages get discovered
 - **[Django integration](integrations/django.md)** — the full tour

examples/django_demo/greetings/adapters/out_/config/__init__.py

@@ -0,0 +1,23 @@
+"""Runtime configuration for the name-formatter selection.
+
+Reads ``GREETER_FORMATTER_STYLE`` from the environment so the demo can
+switch implementations without code changes:
+
+    GREETER_FORMATTER_STYLE=upper python main.py
+"""
+
+import os
+
+from django_autowired import injectable
+
+
+@injectable()
+class FormatterConfig:
+    """Holds the runtime-selected formatter style.
+
+    The value of ``style`` is consulted by the ``@provides`` factory in
+    ``services.name_formatter_provider`` to pick the concrete formatter.
+    """
+
+    def __init__(self) -> None:
+        self.style: str = os.getenv("GREETER_FORMATTER_STYLE", "title").lower()

examples/django_demo/greetings/adapters/out_/config/formatter_config.py

@@ -1,7 +1,6 @@
 """Greeter service — the port implementation you actually call into."""
 
 from django_autowired import injectable
-
 from greetings.domain.ports.services.greeter import IGreeter
 from greetings.domain.ports.services.name_formatter import INameFormatter
 

examples/django_demo/greetings/adapters/out_/services/friendly_greeter.py

@@ -0,0 +1,32 @@
+"""``@provides`` factory that picks the name formatter at runtime.
+
+Demonstrates two things:
+
+1. **Conditional binding** — the concrete ``INameFormatter`` implementation
+   is chosen from a runtime config value rather than hard-wired at boot.
+2. **Factory injection** — the factory itself receives ``FormatterConfig``
+   from the container, just like an ``@injectable`` constructor would.
+
+Try it::
+
+    GREETER_FORMATTER_STYLE=upper python main.py
+    GREETER_FORMATTER_STYLE=title python main.py    # default
+"""
+
+from django_autowired import provides
+from greetings.adapters.out_.config.formatter_config import FormatterConfig
+from greetings.adapters.out_.services.title_case_name_formatter import (
+    TitleCaseNameFormatter,
+)
+from greetings.adapters.out_.services.upper_case_name_formatter import (
+    UpperCaseNameFormatter,
+)
+from greetings.domain.ports.services.name_formatter import INameFormatter
+
+
+@provides(bind_to=INameFormatter)
+def name_formatter(config: FormatterConfig) -> INameFormatter:
+    """Pick the formatter based on ``FormatterConfig.style``."""
+    if config.style == "upper":
+        return UpperCaseNameFormatter()
+    return TitleCaseNameFormatter()

examples/django_demo/greetings/adapters/out_/services/name_formatter_provider.py

@@ -1,11 +1,13 @@
-"""Title-case name formatter — outbound adapter for ``INameFormatter``."""
+"""Title-case name formatter — default implementation of ``INameFormatter``.
 
-from django_autowired import injectable
+This class is intentionally **not** decorated with ``@injectable``. It is
+selected by the ``@provides`` factory in ``name_formatter_provider`` based
+on the runtime value of ``FormatterConfig.style``.
+"""
 
 from greetings.domain.ports.services.name_formatter import INameFormatter
 
 
-@injectable(bind_to=INameFormatter)
 class TitleCaseNameFormatter(INameFormatter):
     """Capitalizes the first letter of each word."""
 

examples/django_demo/greetings/adapters/out_/services/title_case_name_formatter.py

@@ -0,0 +1,15 @@
+"""Upper-case name formatter — alternative implementation of ``INameFormatter``.
+
+This class is intentionally **not** decorated with ``@injectable``. It is
+selected by the ``@provides`` factory in ``name_formatter_provider`` based
+on the runtime value of ``FormatterConfig.style``.
+"""
+
+from greetings.domain.ports.services.name_formatter import INameFormatter
+
+
+class UpperCaseNameFormatter(INameFormatter):
+    """Upper-cases the entire name."""
+
+    def format(self, name: str) -> str:
+        return name.strip().upper()