Update external dependency provider docs, including API, and examples

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
+    This provider is used for description of dependency interface. That might
-    the client's code, but it's interface is known.
+    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.

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.
 

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,14 +45,14 @@ class UserService(object):
 
 
 # Database and UserService providers:
-database = di.ExternalDependency(instance_of=sqlite3.dbapi2.Connection)
+database = providers.ExternalDependency(instance_of=sqlite3.dbapi2.Connection)
-users_service_factory = di.Factory(UserService,
+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.provided_by(providers.Singleton(sqlite3.dbapi2.Connection,
                                          database=':memory:',
                                          timeout=30,
                                          detect_types=True,