Added docs about propagation.

Signed-off-by: Pavel Kirilin <win10@list.ru>

Author: s3rius

README.md

@@ -125,3 +125,54 @@ with graph.sync_ctx() as ctx:
 ```
 
 The ParamInfo has the information about name and parameters signature. It's useful if you want to create a dependency that changes based on parameter name, or signature.
+
+
+## Exception propagation
+
+By default if error happens within the context, we send this error to the dependency,
+so you can close it properly. You can disable this functionality by setting `exception_propagation` parameter to `False`.
+
+Let's imagine that you want to get a database session from pool and commit after the function is done.
+
+
+```python
+async def get_session():
+    session = sessionmaker()
+
+    yield session
+
+    await session.commit()
+
+```
+
+But what if the error happened when the dependant function was called? In this case you want to rollback, instead of commit.
+To solve this problem, you can just wrap the `yield` statement in `try except` to handle the error.
+
+```python
+async def get_session():
+    session = sessionmaker()
+
+    try:
+        yield session
+    except Exception:
+        await session.rollback()
+        return
+
+    await session.commit()
+
+```
+
+**Also, as a library developer, you can disable exception propagation**. If you do so, then no exception will ever be propagated to dependencies and no such `try except` expression will ever work.
+
+
+Example of disabled propogation.
+
+```python
+
+graph = DependencyGraph(target_func)
+
+with graph.sync_ctx(exception_propagation=False) as ctx:
+    print(ctx.resolve_kwargs())
+
+
+```

taskiq_dependencies/ctx.py

@@ -20,13 +20,13 @@ def __init__(
         self,
         graph: "DependencyGraph",
         initial_cache: Optional[Dict[Any, Any]] = None,
-        exception_propogation: bool = True,
+        exception_propagation: bool = True,
     ) -> None:
         self.graph = graph
         self.opened_dependencies: List[Any] = []
         self.sub_contexts: "List[Any]" = []
         self.initial_cache = initial_cache or {}
-        self.propogate_excs = exception_propogation
+        self.propagate_excs = exception_propagation
 
     def traverse_deps(  # noqa: C901, WPS210
         self,
@@ -133,7 +133,7 @@ def close(self, *args: Any) -> None:  # noqa: C901
         :param args: exception info if any.
         """
         exception_found = False
-        if args[1] is not None and self.propogate_excs:
+        if args[1] is not None and self.propagate_excs:
             exception_found = True
         for ctx in self.sub_contexts:
             ctx.close(*args)
@@ -234,7 +234,7 @@ async def close(self, *args: Any) -> None:  # noqa: C901
         :param args: exception info if any.
         """
         exception_found = False
-        if args[1] is not None and self.propogate_excs:
+        if args[1] is not None and self.propagate_excs:
             exception_found = True
         for ctx in self.sub_contexts:
             await ctx.close(*args)  # type: ignore

taskiq_dependencies/graph.py

@@ -41,43 +41,43 @@ def is_empty(self) -> bool:
     def async_ctx(
         self,
         initial_cache: Optional[Dict[Any, Any]] = None,
-        exception_propogation: bool = True,
+        exception_propagation: bool = True,
     ) -> AsyncResolveContext:
         """
         Create dependency resolver context.
 
         This context is used to actually resolve dependencies.
 
         :param initial_cache: initial cache dict.
-        :param exception_propogation: If true, all found errors within
-            context will be propogated to dependencies.
+        :param exception_propagation: If true, all found errors within
+            context will be propagated to dependencies.
         :return: new resolver context.
         """
         return AsyncResolveContext(
             self,
             initial_cache,
-            exception_propogation,
+            exception_propagation,
         )
 
     def sync_ctx(
         self,
         initial_cache: Optional[Dict[Any, Any]] = None,
-        exception_propogation: bool = True,
+        exception_propagation: bool = True,
     ) -> SyncResolveContext:
         """
         Create dependency resolver context.
 
         This context is used to actually resolve dependencies.
 
         :param initial_cache: initial cache dict.
-        :param exception_propogation: If true, all found errors within
-            context will be propogated to dependencies.
+        :param exception_propagation: If true, all found errors within
+            context will be propagated to dependencies.
         :return: new resolver context.
         """
         return SyncResolveContext(
             self,
             initial_cache,
-            exception_propogation,
+            exception_propagation,
         )
 
     def _build_graph(self) -> None:  # noqa: C901, WPS210

tests/test_graph.py

@@ -403,7 +403,7 @@ def target(_: int = Depends(my_generator)) -> None:
 
 
 @pytest.mark.anyio
-async def test_async_propogation_disabled() -> None:
+async def test_async_propagation_disabled() -> None:
 
     errors_found = 0
 
@@ -420,14 +420,14 @@ def target(_: int = Depends(my_generator)) -> None:
 
     with pytest.raises(ValueError):
         async with DependencyGraph(target=target).async_ctx(
-            exception_propogation=False,
+            exception_propagation=False,
         ) as g:
             target(**(await g.resolve_kwargs()))
 
     assert errors_found == 0
 
 
-def test_sync_propogation_disabled() -> None:
+def test_sync_propagation_disabled() -> None:
 
     errors_found = 0
 
@@ -443,7 +443,7 @@ def target(_: int = Depends(my_generator)) -> None:
         raise ValueError()
 
     with pytest.raises(ValueError):
-        with DependencyGraph(target=target).sync_ctx(exception_propogation=False) as g:
+        with DependencyGraph(target=target).sync_ctx(exception_propagation=False) as g:
             target(**(g.resolve_kwargs()))
 
     assert errors_found == 0