#98 Increase granularity of context.

docs/index.md

@@ -34,10 +34,20 @@
     testing/fixture
     testing/provider-overriding
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Migration
+
+    migration/v2
+
+
 .. toctree::
     :maxdepth: 1
     :caption: For developers
 
     dev/main-decisions
     dev/contributing
+
+
+
 ```

docs/migration/v2.md

@@ -0,0 +1,150 @@
+# Migrating from 1.* to 2.*
+
+## How to Read This Guide
+
+This guide is intended to help you migrate existing functionality from `that-depends` version `1.*` to `2.*`.  
+The goal is to enable you to migrate as quickly as possible while making only the minimal necessary changes to your codebase.
+
+If you want to learn more about the new features introduced in `2.*`, please refer to the [documentation](https://that-depends.readthedocs.io/) and the [release notes](https://github.com/modern-python/that-depends/releases).
+
+---
+
+## Deprecated Features
+
+1. **`BaseContainer.init_async_resources()` removed**  
+   The method `BaseContainer.init_async_resources()` has been removed. Use `BaseContainer.init_resources()` instead.
+
+   **Example:**  
+   If you are using containers, your setup might look like this:
+
+   ```python
+   from that_depends import BaseContainer
+
+   class MyContainer(BaseContainer):
+       # Define your providers here
+       ...
+   ```
+   Replace all instances of:
+   ```python
+   await MyContainer.init_async_resources()
+   ```
+   With:
+   ```python
+   await MyContainer.init_resources()
+   ```
+
+2. **`that_depends.providers.AsyncResource` removed**  
+   The `AsyncResource` class has been removed. Use `providers.Resource` instead.
+
+   **Example:**  
+   Replace all instances of:
+   ```python
+   from that_depends.providers import AsyncResource
+   my_provider = providers.AsyncResource(some_async_function)
+   ```
+   With:
+   ```python
+   from that_depends.providers import Resource
+   my_provider = providers.Resource(some_async_function)
+   ```
+
+---
+
+## Changes in the API
+
+1. **`container_context()` now requires a keyword argument for initial Context**  
+   Previously, a global context could be initialized by passing a dictionary to the `container_context()` context manager:
+
+   ```python
+   my_global_context = {"some_key": "some_value"}
+   async with container_context(my_global_context):
+       assert fetch_context_item("some_key") == "some_value"
+   ```
+
+   In `2.*`, use the `global_context` keyword argument instead:
+
+   ```python
+   my_global_context = {"some_key": "some_value"}
+   async with container_context(global_context=my_global_context):
+       assert fetch_context_item("some_key") == "some_value"
+   ```
+
+2. **Context reset behavior changed in `container_context()`**  
+   Previously, calling `container_context(my_global_context)` would:
+   - Set the global context to `my_global_context`, allowing values to be resolved using `fetch_context_item()`. This behavior remains the same.
+   - Reset the context for all `providers.ContextResource` instances globally. This behavior has changed.
+
+   In `2.*`, if you want to reset the context for all resources in addition to setting a global context, you need to use the `reset_all_containers=True` argument:
+
+   ```python
+   async with container_context(global_context=my_global_context, reset_all_containers=True):
+       assert fetch_context_item("some_key") == "some_value"
+   ```
+
+   > **Note:** `reset_all_containers=True` only reinitializes the context for `ContextResource` instances defined within containers (i.e., classes inheriting from `BaseContainer`). If you also need to reset contexts for resources defined outside containers, you must handle these explicitly. See the [ContextResource documentation](../providers/context-resources.md) for more details.
+
+---
+
+## Potential Issues with `container_context()`
+
+If you have migrated the functionality as described above but still experience issues managing context resources, it might be due to improperly initializing resources when entering `container_context()`.
+
+Here’s an example of an incompatibility with `1.*`:
+
+```python
+from that_depends import container_context
+
+async def some_async_function():
+    # Enter a new context but import `MyContainer` later
+    async with container_context():
+        from some_other_module import MyContainer
+        # Attempt to resolve a `ContextResource` resource
+        my_resource = await MyContainer.my_context_resource.async_resolve()  # ❌ Error!
+```
+
+To resolve such issues in `2.*`, consider the following suggestions:
+
+1. **Pass explicit arguments to `DIContextMiddleware`**  
+   If you are using `DIContextMiddleware` with your ASGI application, you can now pass additional arguments.
+
+   **Example with `FastAPI`:**
+
+   ```python
+   import fastapi
+   from that_depends.providers import DIContextMiddleware, ContextResource
+   from that_depends import BaseContainer
+
+   MyContainer: BaseContainer
+   my_context_resource_provider: ContextResource
+   my_app: fastapi.FastAPI
+
+   my_app.add_middleware(DIContextMiddleware, MyContainer, my_context_resource_provider)
+   ```
+
+   This middleware will automatically initialize the context for the provided resources when an endpoint is called.
+
+2. **Avoid entering `container_context()` without arguments**  
+   Pass all resources supporting context initialization (e.g., `providers.ContextResource` instances and `BaseContainer` subclasses) explicitly.
+
+   **Example:**
+
+   ```python
+   from that_depends import container_context
+
+   MyContainer: BaseContainer
+   my_context_resource_provider: ContextResource
+
+   async with container_context(MyContainer, my_context_resource_provider):
+       # Resolve resources
+       my_container_instance = MyContainer.my_context_resource.sync_resolve()
+       my_provider_instance = my_context_resource_provider.sync_resolve()
+   ```
+
+   Explicit initialization of container context is recommended to prevent unexpected behavior and improve performance.
+
+---
+
+## Further Help
+
+If you continue to experience issues during migration, consider creating a [discussion](https://github.com/modern-python/that-depends/discussions) or opening an [issue](https://github.com/modern-python/that-depends/issues).
+```