Merge pull request #5 from whiteducksoftware:feature/decorator

feat: Enhance DI Container with Service Decorators and Robustness Improvements

This PR introduces a powerful service decorator pattern to the `wd-di` dependency injection container, modernizes core components, and significantly improves robustness, error handling, and backward compatibility.

**Key Enhancements:**

1.  **Service Decorator Support:**
    *   **`ServiceDescriptor` Rework:** The `ServiceDescriptor` is now an immutable `dataclass` and includes a `decorators` attribute to hold a list of decorator factories. This enables services to be wrapped or augmented after creation but before use.
    *   **`ServiceCollection.decorate()`:** A new `decorate(service_type, decorator_factory)` method allows users to register decorator factories against specific service types. Decorators are applied in reverse order of registration (last registered is outermost).
    *   **Decorator Application:** The `ServiceProvider` now applies these decorators sequentially when a service instance is created.
    *   **Use Cases:** This feature is ideal for cross-cutting concerns like caching, logging, transaction management, retries, etc., without modifying the core service logic.

2.  **Core DI Component Modernization & Robustness:**
    *   **`ServiceCollection` Improvements:**
        *   Retained full backward compatibility for all existing registration methods (`add_transient`, `add_singleton`, `add_instance`, `add_*_factory`, `configure`, and Python-level class decorators like `@services.singleton`).
        *   Introduced a build-time lock to prevent modifications after `build_service_provider()` is called, enhancing stability (`InvalidOperationError`).
        *   Internal logic refined for consistent handling of `ServiceDescriptor` creation.
    *   **`ServiceProvider` & `Scope` Overhaul:**
        *   Unified `ServiceProvider` and `Scope` into a single class, simplifying the internal model while maintaining backward compatibility for `from wd.di.container import Scope` via an alias.
        *   The constructor now flexibly accepts both the legacy dictionary-based and new list-based `ServiceDescriptor` collections from `ServiceCollection`.
        *   **Circular Dependency Detection:** Implemented robust cycle detection for both constructor injection and the new service decorator application using a `ContextVar`-based resolution stack. Raises `RuntimeError` for DI cycles and `CircularDecoratorError` for decorator cycles.
        *   **Thread-Safe Singletons:** Singleton creation is now thread-safe using `threading.RLock()`.
        *   **Improved Constructor Injection:**
            *   Uses `inspect.signature` and `typing.get_type_hints` for accurate parameter and type resolution, including handling of string forward references.
            *   Gracefully manages classes without explicit `__init__` methods by ignoring unannotated `*args`/`**kwargs`.
        *   **Scoped Service Resolution:** Restored the behavior of raising an `InvalidOperationError` if a scoped service is requested directly from the root provider.
        *   **Typed `get_service`:** Ensured `get_service(ServiceType)` returns `ServiceType` (not `Any`) for better static type checking, using `@overload`.

3.  **Exception Handling:**
    *   Leveraged existing custom exceptions (`InvalidOperationError`, `CircularDecoratorError`) for more specific and actionable error reporting.
    *   Improved error messages to include resolution stacks where relevant.

4.  **Testing & Examples:**
    *   **New Tests:** Added `tests/test_service_decorators.py` with comprehensive tests for the new decorator functionality, including basic application, multiple decorators, error cases, and circular decorator detection.
    *   **Existing Test Fixes:** Addressed and fixed failures in `test_decorators.py`, `test_scoped.py`, and `test_circular_dependency.py` to align with the updated container behavior and ensure backward compatibility.
    *   **New Example (`examples/caching_with_decorators`):** Added a practical example demonstrating how to implement a caching layer using service decorators.
    *   **READMEs for Examples:** Generated detailed `README.md` files for `examples/complex_ingest` and `examples/order_processor` based on their existing structure and functionality.

5.  **Documentation:**
    *   Created a new documentation page (`docs/advanced/decorators.md`) explaining the service decorator feature, its use cases, how to register decorators, ordering, handling parameters, and circular detection.

This set of changes significantly enhances the capabilities and reliability of the `wd-di` library, providing users with a more powerful and flexible tool for managing dependencies and implementing cross-cutting concerns.

Author: AndreRatzenberger

docs/advanced/decorators.md

@@ -0,0 +1,143 @@
+# Service Decorators
+
+The dependency injection container supports a powerful decorator pattern that allows you to wrap, intercept, or modify service instances *after* they are created but *before* they are returned to the caller or cached by their lifetime manager. This is an implementation of the [Decorator design pattern](https://en.wikipedia.org/wiki/Decorator_pattern) applied to services managed by the DI container.
+
+Decorators are registered against a specific service type and are applied in the reverse order of their registration (the last decorator registered is the outermost).
+
+## Use Cases
+
+Service decorators are useful for a variety of cross-cutting concerns, such as:
+
+*   **Caching:** Wrap a service with a caching layer.
+*   **Logging/Auditing:** Log method calls to a service or audit actions.
+*   **Transaction Management:** Start and commit/rollback transactions around service method calls.
+*   **Retries/Circuit Breakers:** Add resilience to service operations.
+*   **Data Validation/Transformation:** Validate input or transform output of service methods.
+*   **Feature Toggling:** Conditionally alter behavior by applying different decorators.
+
+## Registering Decorators
+
+You register decorators using the `decorate` method on the `ServiceCollection`:
+
+```python
+from wd.di import ServiceCollection, ServiceProvider
+
+# 1. Define your service interface and implementation
+class IDataService:
+    def get_data(self, item_id: str) -> str:
+        raise NotImplementedError
+
+class RealDataService(IDataService):
+    def get_data(self, item_id: str) -> str:
+        print(f"RealDataService: Fetching data for {item_id}")
+        return f"Data for {item_id}"
+
+# 2. Define your decorator(s)
+class LoggingDecorator(IDataService):
+    def __init__(self, inner: IDataService, provider: ServiceProvider):
+        self._inner = inner
+        self._provider = provider # Example: if decorator needs other services
+        print("LoggingDecorator: Initialized")
+
+    def get_data(self, item_id: str) -> str:
+        print(f"LoggingDecorator: Before calling get_data for {item_id}")
+        result = self._inner.get_data(item_id)
+        print(f"LoggingDecorator: After calling get_data for {item_id}, result: {result}")
+        return result
+
+# 3. Define a decorator factory
+# A decorator factory is a callable that takes two arguments:
+# - The current ServiceProvider instance.
+# - The "inner" service instance that is being decorated.
+# It must return the decorated instance.
+def logging_decorator_factory(provider: ServiceProvider, inner_service: IDataService) -> IDataService:
+    return LoggingDecorator(inner_service, provider)
+
+# 4. Configure services
+services = ServiceCollection()
+services.add_transient(IDataService, RealDataService)
+
+# 5. Apply the decorator
+services.decorate(IDataService, logging_decorator_factory)
+
+# 6. Build and use
+provider = services.build_service_provider()
+data_service = provider.get_service(IDataService)
+data_service.get_data("item123")
+
+# Output would be:
+# LoggingDecorator: Initialized
+# LoggingDecorator: Before calling get_data for item123
+# RealDataService: Fetching data for item123
+# LoggingDecorator: After calling get_data for item123, result: Data for item123
+```
+
+### Decorator Factories
+
+A **decorator factory** is a callable with the signature:
+
+```python
+Callable[[ServiceProvider, InnerServiceType], OuterServiceType]
+```
+
+*   `ServiceProvider`: The current service provider, which can be used by the decorator to resolve other dependencies if needed.
+*   `InnerServiceType`: The instance of the service being wrapped.
+*   `OuterServiceType`: The (potentially) wrapped instance that will be returned. Often, this is the same type as `InnerServiceType`, but it can be different if the decorator changes the interface (though this should be done with care).
+
+### Order of Application
+
+If multiple decorators are registered for the same service type, they are applied sequentially. The `ServiceDescriptor` stores them in a list. When an instance is created:
+1.  The base instance (from `implementation_type` or `factory`) is created.
+2.  The decorators are applied in **reverse order of registration**. This means the decorator registered *last* becomes the *outermost* wrapper, and the decorator registered *first* becomes the *innermost* wrapper (closest to the original service instance).
+
+```python
+services.decorate(IMyService, inner_decorator_factory) # Applied first (becomes inner)
+services.decorate(IMyService, outer_decorator_factory) # Applied second (becomes outer)
+
+# Execution flow: outer_decorator -> inner_decorator -> actual_service
+```
+
+## Advanced: Decorators with Parameters
+
+Sometimes, your decorator itself might need configuration. You can achieve this by creating a decorator factory *function* that takes parameters and *returns* the actual decorator factory callable:
+
+```python
+class RetryingDataServiceDecorator(IDataService):
+    def __init__(self, inner: IDataService, max_retries: int):
+        self._inner = inner
+        self._max_retries = max_retries
+
+    def get_data(self, item_id: str) -> str:
+        attempts = 0
+        while True:
+            try:
+                return self._inner.get_data(item_id)
+            except Exception as e:
+                attempts += 1
+                if attempts >= self._max_retries:
+                    print(f"RetryingDecorator: Max retries ({self._max_retries}) reached. Failing.")
+                    raise
+                print(f"RetryingDecorator: Attempt {attempts} failed. Retrying...")
+                # In a real scenario, you might add a delay here
+
+# Factory that creates the decorator factory
+def create_retrying_decorator_factory(max_retries: int):
+    def actual_decorator_factory(provider: ServiceProvider, inner: IDataService) -> IDataService:
+        return RetryingDataServiceDecorator(inner, max_retries)
+    return actual_decorator_factory
+
+# Usage:
+services.add_transient(IDataService, RealDataService)
+retry_factory_with_config = create_retrying_decorator_factory(max_retries=3)
+services.decorate(IDataService, retry_factory_with_config)
+
+provider = services.build_service_provider()
+service = provider.get_service(IDataService)
+# service.get_data("test") will now have retry logic
+```
+
+## Circular Decorator Detection
+
+The container includes a mechanism to detect circular decorator applications at runtime. If a decorator, during its application to a service, causes itself to be re-applied to the *same service instance resolution*, a `CircularDecoratorError` will be raised. This helps prevent infinite loops during service construction.
+
+For example, if `DecoratorA` for `IServiceX` internally tries to resolve `IServiceX` again in a way that re-triggers the application of `DecoratorA` to the same `IServiceX` instance being formed, a cycle is detected. 

examples/caching_with_decorators/README.md

@@ -0,0 +1,43 @@
+# Caching with Service Decorators Example
+
+This example demonstrates how to use the service decorator functionality of the `wd-di` library to add a caching layer to a service.
+
+## Scenario
+
+We have an `IExternalWeatherService` that simulates fetching weather data from an external source. The concrete implementation, `SlowExternalWeatherService`, is intentionally slow to mimic network latency or computationally expensive operations. 
+
+To improve performance and reduce calls to the slow service, we introduce a `CachingWeatherServiceDecorator`. This decorator wraps the `IExternalWeatherService` and caches its results for a configured duration.
+
+## Files
+
+*   `services.py`: Defines the `IExternalWeatherService` interface and the `SlowExternalWeatherService` implementation.
+*   `decorators.py`: Defines the `CachingWeatherServiceDecorator` and `create_caching_weather_decorator_factory` which creates the actual decorator factory callable used for registration.
+*   `main.py`: Sets up the `ServiceCollection`, registers the services, applies the caching decorator, and then demonstrates the caching behavior by calling the weather service multiple times for different cities and observing cache hits, misses, and expirations.
+
+## How it Works
+
+1.  **Service Registration**: In `main.py`, `SlowExternalWeatherService` is registered as a singleton for the `IExternalWeatherService` interface.
+2.  **Decorator Factory Creation**: `create_caching_weather_decorator_factory(cache_duration_seconds=5)` is called. This function returns another function (the actual decorator factory) that is configured with a 5-second cache duration. This demonstrates how decorators can be parameterized.
+3.  **Decorator Application**: `services.decorate(IExternalWeatherService, caching_factory)` tells the service collection that whenever `IExternalWeatherService` is resolved, it should be passed through the `caching_factory`.
+4.  **Instance Creation & Decoration**: When `provider.get_service(IExternalWeatherService)` is first called:
+    *   The `ServiceProvider` creates an instance of `SlowExternalWeatherService`.
+    *   It then calls the `caching_factory`, passing the `ServiceProvider` and the `SlowExternalWeatherService` instance.
+    *   The `caching_factory` returns an instance of `CachingWeatherServiceDecorator` which wraps the `SlowExternalWeatherService` instance.
+    *   This decorated instance is returned to the caller.
+5.  **Caching Logic**: 
+    *   The `CachingWeatherServiceDecorator` maintains an in-memory cache (`self._cache`).
+    *   When `get_current_temperature` is called, it first checks the cache for the given city.
+    *   If a valid (non-expired) entry is found (Cache HIT), it returns the cached temperature.
+    *   If the entry is missing or expired (Cache MISS/STALE), it calls the `get_current_temperature` method of the *inner* (`SlowExternalWeatherService`) instance, stores the result in the cache with a new timestamp, and then returns it.
+
+## Running the Example
+
+Navigate to the `examples/caching_with_decorators` directory and run:
+
+```bash
+python main.py
+```
+
+You will see output indicating cache hits, misses, and the calls made to the `SlowExternalWeatherService`. The simulated delays will make the effect of caching apparent.
+
+This example showcases how decorators can add significant cross-cutting concerns like caching in a clean, modular, and maintainable way without modifying the original service implementation. 

examples/caching_with_decorators/decorators.py

@@ -0,0 +1,44 @@
+# examples/caching_with_decorators/decorators.py
+import time
+from typing import Dict, Tuple
+from wd.di import ServiceProvider # Assuming ServiceProvider is available for type hinting
+from .services import IExternalWeatherService
+
+class CachingWeatherServiceDecorator(IExternalWeatherService):
+    def __init__(self, inner: IExternalWeatherService, cache_duration_seconds: int = 60):
+        self._inner = inner
+        self._cache: Dict[str, Tuple[float, float]] = {} # Key: city, Value: (timestamp, temperature)
+        self._cache_duration = cache_duration_seconds
+        print(f"[CachingWeatherServiceDecorator] Initialized with cache duration: {self._cache_duration}s")
+
+    def get_current_temperature(self, city: str) -> float:
+        city_key = city.lower()
+        current_time = time.time()
+
+        if city_key in self._cache:
+            timestamp, temperature = self._cache[city_key]
+            if current_time - timestamp < self._cache_duration:
+                print(f"[CachingWeatherServiceDecorator] Cache HIT for {city}. Temp: {temperature}°C")
+                return temperature
+            else:
+                print(f"[CachingWeatherServiceDecorator] Cache STALE for {city}. Re-fetching...")
+        else:
+            print(f"[CachingWeatherServiceDecorator] Cache MISS for {city}. Fetching from real service...")
+
+        # Cache miss or stale, fetch from inner service
+        temperature = self._inner.get_current_temperature(city)
+        self._cache[city_key] = (current_time, temperature)
+        print(f"[CachingWeatherServiceDecorator] Cached new temperature for {city}: {temperature}°C")
+        return temperature
+
+    def clear_cache(self):
+        self._cache.clear()
+        print("[CachingWeatherServiceDecorator] Cache cleared.")
+
+# Decorator Factory that creates the CachingWeatherServiceDecorator
+def create_caching_weather_decorator_factory(cache_duration_seconds: int = 60):
+    print(f"[Factory] Creating caching decorator factory with duration: {cache_duration_seconds}s")
+    def actual_factory(provider: ServiceProvider, inner: IExternalWeatherService) -> IExternalWeatherService:
+        # `provider` is available if the decorator itself needed other services, not used in this simple cache.
+        return CachingWeatherServiceDecorator(inner, cache_duration_seconds)
+    return actual_factory 

examples/caching_with_decorators/main.py

@@ -0,0 +1,57 @@
+# examples/caching_with_decorators/main.py
+import time
+from wd.di import ServiceCollection
+from .services import IExternalWeatherService, SlowExternalWeatherService
+from .decorators import create_caching_weather_decorator_factory
+
+def main():
+    print("--- Caching Decorator Example ---")
+
+    services = ServiceCollection()
+
+    # Register the slow weather service
+    services.add_singleton(IExternalWeatherService, SlowExternalWeatherService)
+
+    # Create a caching decorator factory with a short cache duration for demo purposes
+    caching_factory = create_caching_weather_decorator_factory(cache_duration_seconds=5)
+    
+    # Decorate the weather service with the caching layer
+    services.decorate(IExternalWeatherService, caching_factory)
+
+    provider = services.build_service_provider()
+
+    weather_service = provider.get_service(IExternalWeatherService)
+    slow_weather_service_instance = provider.get_service(SlowExternalWeatherService) # Get direct instance for call count
+
+    print("\n--- First call for London (should be slow and cache miss) ---")
+    temp_london1 = weather_service.get_current_temperature("London")
+    print(f"Reported temperature for London: {temp_london1}°C")
+    print(f"API call count: {slow_weather_service_instance.get_api_call_count()}") # type: ignore
+
+    print("\n--- Second call for London (should be fast from cache) ---")
+    temp_london2 = weather_service.get_current_temperature("London")
+    print(f"Reported temperature for London: {temp_london2}°C")
+    print(f"API call count: {slow_weather_service_instance.get_api_call_count()}") # type: ignore
+
+    print("\n--- First call for New York (should be slow and cache miss) ---")
+    temp_ny1 = weather_service.get_current_temperature("New York")
+    print(f"Reported temperature for New York: {temp_ny1}°C")
+    print(f"API call count: {slow_weather_service_instance.get_api_call_count()}") # type: ignore
+
+    print(f"\n--- Waiting for {7} seconds to ensure London cache expires... ---")
+    time.sleep(7)
+
+    print("\n--- Third call for London (should be slow again due to cache expiry) ---")
+    temp_london3 = weather_service.get_current_temperature("London")
+    print(f"Reported temperature for London: {temp_london3}°C")
+    print(f"API call count: {slow_weather_service_instance.get_api_call_count()}") # type: ignore
+
+    print("\n--- Second call for New York (should still be fast from cache) ---")
+    temp_ny2 = weather_service.get_current_temperature("New York") # NY cache (5s) might be stale or not depending on timing
+    print(f"Reported temperature for New York: {temp_ny2}°C")
+    print(f"API call count: {slow_weather_service_instance.get_api_call_count()}") # type: ignore
+
+    print("\n--- Example Complete ---")
+
+if __name__ == "__main__":
+    main() 

examples/caching_with_decorators/services.py

@@ -0,0 +1,34 @@
+# examples/caching_with_decorators/services.py
+import time
+from abc import ABC, abstractmethod
+
+class IExternalWeatherService(ABC):
+    @abstractmethod
+    def get_current_temperature(self, city: str) -> float:
+        """Simulates fetching current temperature for a city."""
+        pass
+
+class SlowExternalWeatherService(IExternalWeatherService):
+    """A simulated weather service that is intentionally slow."""
+    def __init__(self):
+        self._call_count = 0
+
+    def get_current_temperature(self, city: str) -> float:
+        self._call_count += 1
+        print(f"[SlowExternalWeatherService] Fetching temperature for {city}... (Call #{self._call_count})")
+        time.sleep(2) # Simulate network latency or expensive computation
+        if city.lower() == "london":
+            temp = 15.0 + self._call_count # Make it change slightly to show cache effect
+            print(f"[SlowExternalWeatherService] Temperature for London: {temp}°C")
+            return temp
+        elif city.lower() == "new york":
+            temp = 22.0 + self._call_count
+            print(f"[SlowExternalWeatherService] Temperature for New York: {temp}°C")
+            return temp
+        else:
+            temp = 10.0 + self._call_count
+            print(f"[SlowExternalWeatherService] Temperature for {city}: {temp}°C")
+            return temp
+
+    def get_api_call_count(self) -> int:
+        return self._call_count