Finilizing of external dependecy provider documentation

docs/providers.rst

@@ -199,24 +199,81 @@ Example:
 External dependency providers
 -----------------------------
 
-``ExternalDependency`` provider can be useful for development of self-sufficient
+``ExternalDependency`` provider can be useful for development of
-libraries / modules / applications, that has required external dependencies.
+self-sufficient libraries / modules / applications, that has required external
+dependencies.
 
 For example, you have created self-sufficient library / module / application,
-that has dependency on *SQLAlchemy*. Second step you want to do is to make this
+that has dependency on *database connection*.
-software component to be easy reusable by wide amount of developers and to be
+
-easily integrated into many applications. It may be good idea, to move all
+Second step you want to do is to make this software component to be easy
-external dependencies (like *SQLAlchemy*) to the top level and make them to be
+reusable by wide amount of developers and to be easily integrated into many
-injected on your software component's initialization. It will make third party
+applications.
-developers feel themselves more free about integration of yours component in
+
-their applications because of they would be able to find right place / right
+It may be good idea, to move all external dependencies (like
-way for doing this in their application's architectures.
+*dabase connection*)  to the top level and make them to be injected on your
+software component's initialization. It will make third party developers feel
+themselves free about integration of yours component in their applications,
+because of they would be able to find right place / right way for doing this
+in their application's architectures.
+
+On the other side,
+you can be sure, that your external dependency will be satisfied by appropriate
+instance.
 
 Example:
 
 .. code-block:: python
 
-    import this
+    """External dependency providers example."""
+
+    import sqlite3
+
+    from objects.providers import Singleton
+    from objects.providers import NewInstance
+    from objects.providers import ExternalDependency
+
+    from objects.injections import KwArg
+    from objects.injections import Attribute
+
+
+    class ObjectA(object):
+
+        """ObjectA has dependency on database."""
+
+        def __init__(self, database):
+            """Initializer.
+
+            Database dependency need to be injected via init arg."""
+            self.database = database
+
+        def get_one(self):
+            """Select one from database and return it."""
+            return self.database.execute('SELECT 1').fetchone()[0]
+
+
+    # Database and `ObjectA` providers.
+    database = ExternalDependency(instance_of=sqlite3.Connection)
+
+    object_a = NewInstance(ObjectA,
+                           KwArg('database', database))
+
+    # Satisfaction of external dependency.
+    database.override(Singleton(sqlite3.Connection,
+                                KwArg('database', ':memory:'),
+                                KwArg('timeout', 30),
+                                KwArg('detect_types', True),
+                                KwArg('isolation_level', 'EXCLUSIVE'),
+                                Attribute('row_factory', sqlite3.Row)))
+
+    # Creating several `ObjectA` instances.
+    object_a_1 = object_a()
+    object_a_2 = object_a()
+
+    # Making some asserts.
+    assert object_a_1 is not object_a_2
+    assert object_a_1.database is object_a_2.database is database()
+
 
 Config providers
 ----------------

examples/readme2/external_dependency_providers.py

@@ -1,6 +1,6 @@
 """External dependency providers example."""
 
-from objects.catalog import AbstractCatalog
+import sqlite3
 
 from objects.providers import Singleton
 from objects.providers import NewInstance
@@ -9,55 +9,40 @@ from objects.providers import ExternalDependency
 from objects.injections import KwArg
 from objects.injections import Attribute
 
-import sqlite3
-
 
 class ObjectA(object):
 
-    """Example class ObjectA, that has dependency on database."""
+    """ObjectA has dependency on database."""
 
-    def __init__(self, db):
+    def __init__(self, database):
-        """Initializer."""
+        """Initializer.
-        self.db = db
+
+        Database dependency need to be injected via init arg."""
+        self.database = database
+
+    def get_one(self):
+        """Select one from database and return it."""
+        return self.database.execute('SELECT 1').fetchone()[0]
 
 
-class ObjectB(object):
+# Database and `ObjectA` providers.
-
+database = ExternalDependency(instance_of=sqlite3.Connection)
-    """Example class ObjectB, that has dependencies on ObjectA and database."""
-
-    def __init__(self, a, db):
-        """Initializer."""
-        self.a = a
-        self.db = db
-
-
-class Catalog(AbstractCatalog):
-
-    """Catalog of objects providers."""
-
-    database = ExternalDependency(instance_of=sqlite3.Connection)
-    """:type: (objects.Provider) -> sqlite3.Connection"""
-
-    object_a = NewInstance(ObjectA,
-                           KwArg('db', database))
-    """:type: (objects.Provider) -> ObjectA"""
-
-    object_b = NewInstance(ObjectB,
-                           KwArg('a', object_a),
-                           KwArg('db', database))
-    """:type: (objects.Provider) -> ObjectB"""
 
+object_a = NewInstance(ObjectA,
+                       KwArg('database', database))
 
 # Satisfaction of external dependency.
-Catalog.database.override(Singleton(sqlite3.Connection,
+database.override(Singleton(sqlite3.Connection,
                             KwArg('database', ':memory:'),
+                            KwArg('timeout', 30),
+                            KwArg('detect_types', True),
+                            KwArg('isolation_level', 'EXCLUSIVE'),
                             Attribute('row_factory', sqlite3.Row)))
 
-# Catalog static provides.
+# Creating several `ObjectA` instances.
-a1, a2 = Catalog.object_a(), Catalog.object_a()
+object_a_1 = object_a()
-b1, b2 = Catalog.object_b(), Catalog.object_b()
+object_a_2 = object_a()
 
-# Some asserts.
+# Making some asserts.
-assert a1 is not a2
+assert object_a_1 is not object_a_2
-assert b1 is not b2
+assert object_a_1.database is object_a_2.database is database()
-assert a1.db is a2.db is b1.db is b2.db is Catalog.database()