diff --git a/dependency_injector/providers.py b/dependency_injector/providers.py index 5f0be721..7f94673c 100644 --- a/dependency_injector/providers.py +++ b/dependency_injector/providers.py @@ -131,7 +131,8 @@ class Delegate(Provider): def __init__(self, delegated): """Initializer. - :type delegated: Provider + :provider delegated: Delegated provider + :type delegated: :py:class:`Provider` """ self.delegated = ensure_is_provider(delegated) super(Delegate, self).__init__() @@ -392,10 +393,19 @@ class Singleton(Provider): class ExternalDependency(Provider): - """External dependency provider. + """:py:class:`ExternalDependency` provider describes dependency interface. - Those provider is used when dependency obviously have to be overridden by - the client's code, but it's interface is known. + This provider is used for description of dependency interface. That might + be useful when dependency could be provided in the client's code only, + but it's interface is known. Such situations could happen when required + dependency has non-determenistic list of dependencies itself. + + .. code-block:: python + + database_provider = ExternalDependency(sqlite3.dbapi2.Connection) + database_provider.override(Factory(sqlite3.connect, ':memory:')) + + database = database_provider() """ __slots__ = ('instance_of',) @@ -406,10 +416,25 @@ class ExternalDependency(Provider): raise Error('ExternalDependency provider expects to get class, ' + 'got {0} instead'.format(str(instance_of))) self.instance_of = instance_of + """Class of required dependency. + + :type: type + """ super(ExternalDependency, self).__init__() def __call__(self, *args, **kwargs): - """Return provided instance.""" + """Return provided instance. + + :param args: tuple of context positional arguments + :type args: tuple[object] + + :param kwargs: dictionary of context keyword arguments + :type kwargs: dict[str, object] + + :raise: :py:exc:`dependency_injector.errors.Error` + + :rtype: object + """ if not self.is_overridden: raise Error('Dependency is not defined') @@ -422,7 +447,13 @@ class ExternalDependency(Provider): return instance def provided_by(self, provider): - """Set external dependency provider.""" + """Set external dependency provider. + + :param provider: Provider that provides required dependency + :type provider: :py:class:`Provider` + + :rtype: None + """ return self.override(provider) @@ -438,7 +469,7 @@ class StaticProvider(Provider): def __init__(self, provides): """Initializer. - :param provides: value that have to be provided. + :param provides: Value that have to be provided. :type provides: object """ self.provides = provides @@ -522,7 +553,7 @@ class Callable(Provider): def __init__(self, callback, *args, **kwargs): """Initializer. - :param callback: wrapped callable. + :param callback: Wrapped callable. :type callback: callable :param args: Tuple of injections. diff --git a/docs/images/providers/external_dependency.png b/docs/images/providers/external_dependency.png index 28662c94..a02affbe 100644 Binary files a/docs/images/providers/external_dependency.png and b/docs/images/providers/external_dependency.png differ diff --git a/docs/providers/external_dependency.rst b/docs/providers/external_dependency.rst index e07e2679..71b7f4ad 100644 --- a/docs/providers/external_dependency.rst +++ b/docs/providers/external_dependency.rst @@ -1,7 +1,9 @@ External dependency providers ----------------------------- -``di.ExternalDependency`` provider can be useful for development of +.. module:: dependency_injector.providers + +:py:class:`ExternalDependency` provider can be useful for development of self-sufficient libraries / modules / applications that has required external dependencies. diff --git a/examples/providers/external_dependency.py b/examples/providers/external_dependency.py index 683c265c..1aedd140 100644 --- a/examples/providers/external_dependency.py +++ b/examples/providers/external_dependency.py @@ -1,8 +1,9 @@ -"""`di.ExternalDependency` providers example.""" +"""`ExternalDependency` providers example.""" import sqlite3 import contextlib -import dependency_injector as di + +from dependency_injector import providers class UserService(object): @@ -14,7 +15,8 @@ class UserService(object): def __init__(self, database): """Initializer. - Database dependency need to be injected via init arg. + :param database: Database connection. + :type database: sqlite3.dbapi2.Connection """ self.database = database self.database.row_factory = sqlite3.dbapi2.Row @@ -43,18 +45,18 @@ class UserService(object): # Database and UserService providers: -database = di.ExternalDependency(instance_of=sqlite3.dbapi2.Connection) -users_service_factory = di.Factory(UserService, - database=database) +database = providers.ExternalDependency(instance_of=sqlite3.dbapi2.Connection) +users_service_factory = providers.Factory(UserService, + database=database) # Out of library's scope. # # Setting database provider: -database.provided_by(di.Singleton(sqlite3.dbapi2.Connection, - database=':memory:', - timeout=30, - detect_types=True, - isolation_level='EXCLUSIVE')) +database.provided_by(providers.Singleton(sqlite3.dbapi2.Connection, + database=':memory:', + timeout=30, + detect_types=True, + isolation_level='EXCLUSIVE')) # Creating UserService instance: users_service = users_service_factory()