update providers docs

docs/index.md

@@ -16,13 +16,12 @@
     :maxdepth: 1
     :caption: Providers
 
-    providers/resource
-    providers/async-resource
+    providers/resources
+    providers/context-resources
     providers/singleton
-    providers/factory
+    providers/factories
     providers/async-factory
-    providers/list
-    providers/dict
+    providers/collections
     providers/selector
 
 .. toctree::

docs/providers/collections.md

@@ -0,0 +1,38 @@
+# Collections
+There are several collection providers: `List` and `Dict`
+
+## List
+- List provider contains other providers.
+- Resolves into list of dependencies.
+
+```python
+import random
+from that_depends import BaseContainer, providers
+
+
+class DIContainer(BaseContainer):
+    random_number = providers.Factory(random.random)
+    numbers_sequence = providers.List(random_number, random_number)
+
+
+DIContainer.numbers_sequence.sync_resolve()
+# [0.3035656170071561, 0.8280498192037787]
+```
+
+## Dict
+- Dict provider is a collection of named providers.
+- Resolves into dict of dependencies.
+
+```python
+import random
+from that_depends import BaseContainer, providers
+
+
+class DIContainer(BaseContainer):
+    random_number = providers.Factory(random.random)
+    numbers_map = providers.Dict(key1=random_number, key2=random_number)
+
+
+DIContainer.numbers_map.sync_resolve()
+# {'key1': 0.6851384528299208, 'key2': 0.41044920948045294}
+```

docs/providers/context-resources.md

@@ -0,0 +1,57 @@
+# Context resources
+Context resources are resources with scoped lifecycle.
+There are `ContextResource` and `AsyncContextResource`
+
+## ContextResource
+- Generator function is required.
+```python
+import typing
+
+import pytest
+
+from that_depends import BaseContainer, providers, container_context
+
+
+def create_sync_resource() -> typing.Iterator[str]:
+    # resource initialization
+    try:
+        yield "sync resource"
+    finally:
+        pass  # resource teardown
+
+class DIContainer(BaseContainer):
+    context_resource = providers.ContextResource(create_sync_resource)
+
+
+async def main() -> None:
+    async with container_context():
+        # context resource can be resolved only inside of context
+        DIContainer.context_resource.sync_resolve()
+
+    # outside the context resolving will fail
+    with pytest.raises(RuntimeError, match="Context is not set. Use container_context"):
+        DIContainer.context_resource.sync_resolve()
+```
+
+## AsyncContextResource
+- Async generator function is required.
+```python
+import typing
+
+from that_depends import BaseContainer, providers
+
+
+async def create_async_resource() -> typing.AsyncIterator[str]:
+    # resource initialization
+    try:
+        yield "async resource"
+    finally:
+        pass  # resource teardown
+
+
+class DIContainer(BaseContainer):
+    async_resource = providers.AsyncContextResource(create_async_resource)
+
+
+# resolving is the same as for ContextResource
+```

docs/providers/factories.md

@@ -0,0 +1,36 @@
+# Factories
+Factories are initialized on every call.
+
+## Factory
+- Class or simple function is allowed.
+```python
+import dataclasses
+
+from that_depends import BaseContainer, providers
+
+
+@dataclasses.dataclass(kw_only=True, slots=True)
+class IndependentFactory:
+    dep1: str
+    dep2: int
+
+
+class DIContainer(BaseContainer):
+    independent_factory = providers.Factory(IndependentFactory, dep1="text", dep2=123)
+```
+
+## AsyncFactory
+- Async function is required.
+```python
+import datetime
+
+from that_depends import BaseContainer, providers
+
+
+async def async_factory() -> datetime.datetime:
+    return datetime.datetime.now(tz=datetime.timezone.utc)
+
+
+class DIContainer(BaseContainer):
+    async_factory = providers.Factory(async_factory)
+```

docs/providers/resources.md

@@ -0,0 +1,42 @@
+# Resources
+Resources are initialized only once and have teardown logic.
+There are `Resource` and `AsyncResource`
+
+## Resource
+- Generator function is required.
+```python
+import typing
+
+from that_depends import BaseContainer, providers
+
+
+def create_sync_resource() -> typing.Iterator[str]:
+    # resource initialization
+    try:
+        yield "sync resource"
+    finally:
+        pass  # resource teardown
+
+class DIContainer(BaseContainer):
+    sync_resource = providers.Resource(create_sync_resource)
+```
+
+## AsyncResource
+- Async generator function is required.
+```python
+import typing
+
+from that_depends import BaseContainer, providers
+
+
+async def create_async_resource() -> typing.AsyncIterator[str]:
+    # resource initialization
+    try:
+        yield "async resource"
+    finally:
+        pass  # resource teardown
+
+
+class DIContainer(BaseContainer):
+    async_resource = providers.AsyncResource(create_async_resource)
+```