diff --git a/docs/providers.rst b/docs/providers.rst index 164ae7c4..d987bf96 100644 --- a/docs/providers.rst +++ b/docs/providers.rst @@ -199,24 +199,81 @@ Example: External dependency providers ----------------------------- -``ExternalDependency`` provider can be useful for development of self-sufficient -libraries / modules / applications, that has required external dependencies. +``ExternalDependency`` provider can be useful for development of +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 -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 -external dependencies (like *SQLAlchemy*) to the top level and make them to be -injected on your software component's initialization. It will make third party -developers feel themselves more 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. +that has dependency on *database connection*. + +Second step you want to do is to make this 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 external dependencies (like +*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 ---------------- diff --git a/examples/readme2/external_dependency_providers.py b/examples/readme2/external_dependency_providers.py index 30ee4640..ad2c5533 100644 --- a/examples/readme2/external_dependency_providers.py +++ b/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): - """Initializer.""" - self.db = db + 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] -class ObjectB(object): - - """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""" +# Database and `ObjectA` providers. +database = ExternalDependency(instance_of=sqlite3.Connection) +object_a = NewInstance(ObjectA, + KwArg('database', database)) # Satisfaction of external dependency. -Catalog.database.override(Singleton(sqlite3.Connection, - KwArg('database', ':memory:'), - Attribute('row_factory', sqlite3.Row))) +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. -a1, a2 = Catalog.object_a(), Catalog.object_a() -b1, b2 = Catalog.object_b(), Catalog.object_b() +# Creating several `ObjectA` instances. +object_a_1 = object_a() +object_a_2 = object_a() -# Some asserts. -assert a1 is not a2 -assert b1 is not b2 -assert a1.db is a2.db is b1.db is b2.db is Catalog.database() +# Making some asserts. +assert object_a_1 is not object_a_2 +assert object_a_1.database is object_a_2.database is database()