diff --git a/docs/pages/annotations.md b/docs/pages/annotations.md index 6b159a2..79c0441 100644 --- a/docs/pages/annotations.md +++ b/docs/pages/annotations.md @@ -47,11 +47,8 @@ def target( ### Explicit injection annotation Even though annotating services is optional, you CAN still annotate them to be explicit about what will -be injected. This also has the benefit of making the container throw when such as service -does not exist instead of silently skipping this parameter. - -This has limited application when using annotated types as the runtime will raise regardless, but when using -default values as annotations it can be quite useful. +be injected. This also has the benefit of making the container throw when the service does not exist instead +of silently skipping this parameter. ```python @container.autowire diff --git a/docs/pages/getting_started.md b/docs/pages/getting_started.md index 38e09b5..d5fec85 100644 --- a/docs/pages/getting_started.md +++ b/docs/pages/getting_started.md @@ -161,7 +161,7 @@ Next, we add a weather service that will perform requests against a remote serve ``` 1. * Injection is supported for regular classes as well as dataclasses. - * When using dataclasses it is important that the `@dataclass` decorator is applied before `@service`. + * With dataclasses it is important that the `@dataclass` decorator is applied before `@service`. 2. * Use type hints to indicate which dependency to inject. * Dependencies are automatically discovered and injected. diff --git a/docs/pages/interfaces.md b/docs/pages/interfaces.md index f662438..0fceb06 100644 --- a/docs/pages/interfaces.md +++ b/docs/pages/interfaces.md @@ -1,6 +1,5 @@ -When autowiring dependencies, you might want to inject an interface rather than -the concrete implementation directly. Since Python doesn't have built-in interfaces, you can use classes -that are marked as abstract within the container. +Sometimes you might want to inject an interface rather than the concrete implementation directly. +Since Python doesn't have built-in interfaces, you can use any class marked as abstract. This method makes testing easier as you can create dummy implementations of these services in your tests in order to control their behavior. @@ -10,7 +9,7 @@ in order to control their behavior. The following code registers `Engine` as an interface. This implies that `Engine` can't be directly injected. Instead, a dependency that implements the interface must also be registered in the container. -To autowire interfaces, register a dependency that **directly inherits** the interface +To use interfaces, register a dependency that **directly inherits** the interface with the container. When injecting, ask for the interface itself, not the implementations. ```python @@ -19,12 +18,14 @@ from wireup import abstract, container, service @abstract class Engine(abc.ABC): + @abc.abstractmethod def get_type(self) -> EngineType: raise NotImplementedError -@service +@Service class CombustionEngine(Engine): + @override def get_type(self) -> EngineType: return EngineType.COMBUSTION @@ -37,7 +38,8 @@ def target(engine: Engine): ## Multiple implementations -When dealing with multiple implementations of an interface, associate them with a qualifier. +If an interface has multiple implementations, associate each of them with a qualifier. +This is essentially a tag used to differentiate between implementations. ```python @service(qualifier="electric") @@ -71,10 +73,10 @@ def target( ## Default implementation -When there are many implementations associated with a given interface, you may want to associate one of them as the +If there are many implementations associated with a given interface, you may want to associate one of them as the "default" implementation. -To achieve that, omit the qualifier when registering the implementation that should be injected by default. +To accomplish that, omit the qualifier when registering the implementation. ```python @service # <-- Qualifier being absent will make this the default impl.