docs: Imporve dependencies docs (#2263)

Author: sobolevn

docs/docs/en/getting-started/dependencies/index.md

@@ -84,7 +84,7 @@ To implement dependencies in **FastStream**, a special class called **Depends**
 **The first step**: You need to declare a dependency, which can be any `Callable` object.
 
 ??? note "Callable"
-    A "Callable" is an object that can be "called". It can be a function, a class, or a class method.
+    A ["Callable"](https://docs.python.org/3/glossary.html#term-callable){.external-link target="_blank"} is an object that can be "called". It can be a function, a class, or a class method.
 
     In other words, if you can write code like `my_object()` - `my_object` is `Callable`
 
@@ -140,13 +140,7 @@ To implement dependencies in **FastStream**, a special class called **Depends**
     {!> docs_src/getting_started/dependencies/basic/redis/depends.py [ln:11-12] !}
     ```
 
-**The last step**: Just use the result of executing your dependency!
-
-It's easy, isn't it?
-
-!!! tip "Auto `#!python @apply_types`"
-    In the code above, we didn't use this decorator for our dependencies. However, it still applies
-    to all functions used as dependencies. Please keep this in your mind.
+**The last step**: Use the result of executing your dependency!
 
 ## Top-level Dependencies
 
@@ -210,6 +204,10 @@ Dependencies can also contain other dependencies. This works in a very predictab
 
     1. A nested dependency is called here
 
+!!! tip "Auto `#!python @apply_types`"
+    In the code above, we didn't use this decorator on our `simple_dependency`.
+    However, it still automatically applies to all functions used as dependencies.
+
 !!! Tip "Caching"
     In the example above, the `another_dependency` function will be called at **ONCE**!
     **FastDepends** caches all dependency execution results within **ONE** `#!python @apply_types` call stack.
@@ -247,13 +245,17 @@ these types have the same annotation. Just keep it in mind. Or not... Anyway, I'
 from faststream import Depends, apply_types
 
 def simple_dependency(a: int, b: int = 3) -> str:
+    # NOTE: This will make type-checkers unhappy,
+    # it is better to avoid this pattern in production code!
     return a + b  # 'return' is cast to `str` for the first time
 
 @apply_types
 def method(a: int, d: int = Depends(simple_dependency)):
     # 'd' is cast to `int` for the second time
     return a + d
 
+# NOTE: This will make type-checkers unhappy,
+# it is better to avoid this pattern in production code!
 assert method("1") == 5
 ```
 

docs/docs_src/getting_started/dependencies/basic/async_.py

@@ -2,10 +2,10 @@
 import pytest
 from faststream import Depends, apply_types
 
-async def simple_dependency(a: int, b: int = 3):
+async def simple_dependency(a: int, b: int = 3) -> int:
     return a + b
 
-def another_dependency(a: int):
+def another_dependency(a: int) -> int:
     return a
 
 @apply_types
@@ -17,5 +17,5 @@ async def method(
     return a + b + c
 
 @pytest.mark.asyncio
-async def test_async_dependency():
-    assert 6 == await method("1")
+async def test_async_dependency() -> None:
+    assert 6 == await method(1)

docs/docs_src/getting_started/dependencies/basic/confluent/depends.py

@@ -4,7 +4,7 @@
 broker = KafkaBroker("localhost:9092")
 app = FastStream(broker)
 
-def simple_dependency():
+def simple_dependency() -> int:
     return 1
 
 @broker.subscriber("test")

docs/docs_src/getting_started/dependencies/basic/confluent/nested_depends.py

@@ -4,15 +4,16 @@
 broker = KafkaBroker("localhost:9092")
 app = FastStream(broker)
 
-def another_dependency():
+def another_dependency() -> int:
     return 1
 
-def simple_dependency(b: int = Depends(another_dependency)): # (1)
+def simple_dependency(b: int = Depends(another_dependency)) -> int: # (1)
     return b * 2
 
 @broker.subscriber("test")
 async def handler(
     body: dict,
     a: int = Depends(another_dependency),
-    b: int = Depends(simple_dependency)):
-    assert (a + b) == 3
+    b: int = Depends(simple_dependency),
+):
+    assert a + b == 3

docs/docs_src/getting_started/dependencies/basic/kafka/depends.py

@@ -4,7 +4,7 @@
 broker = KafkaBroker("localhost:9092")
 app = FastStream(broker)
 
-def simple_dependency():
+def simple_dependency() -> int:
     return 1
 
 @broker.subscriber("test")

docs/docs_src/getting_started/dependencies/basic/kafka/nested_depends.py

@@ -4,15 +4,16 @@
 broker = KafkaBroker("localhost:9092")
 app = FastStream(broker)
 
-def another_dependency():
+def another_dependency() -> int:
     return 1
 
-def simple_dependency(b: int = Depends(another_dependency)): # (1)
+def simple_dependency(b: int = Depends(another_dependency)) -> int: # (1)
     return b * 2
 
 @broker.subscriber("test")
 async def handler(
     body: dict,
     a: int = Depends(another_dependency),
-    b: int = Depends(simple_dependency)):
-    assert (a + b) == 3
+    b: int = Depends(simple_dependency),
+):
+    assert a + b == 3

docs/docs_src/getting_started/dependencies/basic/nats/depends.py

@@ -4,7 +4,7 @@
 broker = NatsBroker("nats://localhost:4222")
 app = FastStream(broker)
 
-def simple_dependency():
+def simple_dependency() -> int:
     return 1
 
 @broker.subscriber("test")

docs/docs_src/getting_started/dependencies/basic/nats/nested_depends.py

@@ -4,15 +4,16 @@
 broker = NatsBroker("nats://localhost:4222")
 app = FastStream(broker)
 
-def another_dependency():
+def another_dependency() -> int:
     return 1
 
-def simple_dependency(b: int = Depends(another_dependency)): # (1)
+def simple_dependency(b: int = Depends(another_dependency)) -> int: # (1)
     return b * 2
 
 @broker.subscriber("test")
 async def handler(
     body: dict,
     a: int = Depends(another_dependency),
-    b: int = Depends(simple_dependency)):
-    assert (a + b) == 3
+    b: int = Depends(simple_dependency),
+):
+    assert a + b == 3

docs/docs_src/getting_started/dependencies/basic/rabbit/depends.py

@@ -4,7 +4,7 @@
 broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
 app = FastStream(broker)
 
-def simple_dependency():
+def simple_dependency() -> int:
     return 1
 
 @broker.subscriber("test")

docs/docs_src/getting_started/dependencies/basic/rabbit/nested_depends.py

@@ -4,15 +4,16 @@
 broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
 app = FastStream(broker)
 
-def another_dependency():
+def another_dependency() -> int:
     return 1
 
-def simple_dependency(b: int = Depends(another_dependency)): # (1)
+def simple_dependency(b: int = Depends(another_dependency)) -> int: # (1)
     return b * 2
 
 @broker.subscriber("test")
 async def handler(
     body: dict,
     a: int = Depends(another_dependency),
-    b: int = Depends(simple_dependency)):
-    assert (a + b) == 3
+    b: int = Depends(simple_dependency),
+):
+    assert a + b == 3