Metadata-Version: 1.1
Name: Objects
Version: 0.4.2
Summary: Python catalogs of objects providers
Home-page: https://github.com/rmk135/objects
Author: Roman Mogilatov
Author-email: rmogilatov@gmail.com
License: BSD New
Description: Objects
        =======
        
        Python catalogs of objects providers.
        
        
        Example of objects catalog definition and usage:
        
        ```python
        """
        Concept example of objects catalogs.
        """
        
        from objects import AbstractCatalog
        from objects.providers import Singleton, NewInstance
        from objects.injections import InitArg, Attribute
        
        import sqlite3
        
        
        # Some example classes.
        class ObjectA(object):
            def __init__(self, db):
                self.db = db
        
        
        class ObjectB(object):
            def __init__(self, a, db):
                self.a = a
                self.db = db
        
        
        # Catalog of objects providers.
        class Catalog(AbstractCatalog):
            """
            Objects catalog.
            """
        
            database = Singleton(sqlite3.Connection,
                                 InitArg('database', ':memory:'),
                                 Attribute('row_factory', sqlite3.Row))
            """ :type: (objects.Provider) -> sqlite3.Connection """
        
            object_a = NewInstance(ObjectA,
                                   InitArg('db', database))
            """ :type: (objects.Provider) -> ObjectA """
        
            object_b = NewInstance(ObjectB,
                                   InitArg('a', object_a),
                                   InitArg('db', database))
            """ :type: (objects.Provider) -> ObjectB """
        
        
        # Catalog static provides.
        a1, a2 = Catalog.object_a(), Catalog.object_a()
        b1, b2 = Catalog.object_b(), Catalog.object_b()
        
        # 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()
        
        
        # Dependencies injection (The Python Way) into class.
        class Consumer(object):
        
            dependencies = Catalog(Catalog.object_a,
                                   Catalog.object_b)
        
            def test(self):
                a1 = self.dependencies.object_a()
                a2 = self.dependencies.object_a()
        
                b1 = self.dependencies.object_b()
                b2 = self.dependencies.object_b()
        
                # Some asserts.
                assert a1 is not a2
                assert b1 is not b2
                assert a1.db is a2.db is b1.db is b2.db
        
                try:
                    self.dependencies.database()
                except AttributeError:
                    pass
                else:
                    raise Exception('Database is not listed as a dependency')
        
        Consumer().test()
        
        
        # Dependencies injection (The Python Way) into a callback.
        def consumer_callback(dependencies=Catalog(Catalog.object_a,
                                                   Catalog.object_b)):
            a1 = dependencies.object_a()
            a2 = dependencies.object_a()
        
            b1 = dependencies.object_b()
            b2 = dependencies.object_b()
        
            # Some asserts.
            assert a1 is not a2
            assert b1 is not b2
            assert a1.db is a2.db is b1.db is b2.db
        
            try:
                dependencies.database()
            except AttributeError:
                pass
            else:
                raise Exception('Database is not listed as a dependency')
        ```
        
        Example of overriding object providers:
        
        ```python
        """
        Concept example of objects overrides.
        """
        
        
        from objects import AbstractCatalog, overrides
        from objects.providers import Singleton, NewInstance
        from objects.injections import InitArg, Attribute
        
        import sqlite3
        
        
        # Some example class.
        class ObjectA(object):
            def __init__(self, db):
                self.db = db
        
        
        # Mock of example class.
        class ObjectAMock(ObjectA):
            pass
        
        
        # Catalog of objects providers.
        class Catalog(AbstractCatalog):
            """
            Objects catalog.
            """
        
            database = Singleton(sqlite3.Connection,
                                 InitArg('database', ':memory:'),
                                 Attribute('row_factory', sqlite3.Row))
            """ :type: (objects.Provider) -> sqlite3.Connection """
        
            object_a = NewInstance(ObjectA,
                                   InitArg('db', database))
            """ :type: (objects.Provider) -> ObjectA """
        
        
        # Overriding Catalog by SandboxCatalog with some mocks.
        @overrides(Catalog)
        class SandboxCatalog(Catalog):
            """
            Sandbox objects catalog with some mocks.
            """
        
            object_a = NewInstance(ObjectAMock,
                                   InitArg('db', Catalog.database))
            """ :type: (objects.Provider) -> ObjectA """
        
        
        # Catalog static provides.
        a1 = Catalog.object_a()
        a2 = Catalog.object_a()
        
        # Some asserts.
        assert isinstance(a1, ObjectAMock)
        assert isinstance(a2, ObjectAMock)
        assert a1 is not a2
        assert a1.db is a2.db is Catalog.database()
        ```
        
        Example of objects catalog external dependency:
        
        ```python
        """
        Concept example of objects catalogs.
        """
        
        from objects import AbstractCatalog
        from objects.providers import Singleton, NewInstance, ExternalDependency
        from objects.injections import InitArg, Attribute
        
        import sqlite3
        
        
        # Some example classes.
        class ObjectA(object):
            def __init__(self, db):
                self.db = db
        
        
        class ObjectB(object):
            def __init__(self, a, db):
                self.a = a
                self.db = db
        
        
        # Catalog of objects providers.
        class Catalog(AbstractCatalog):
            """
            Objects catalog.
            """
        
            database = ExternalDependency(instance_of=sqlite3.Connection)
            """ :type: (objects.Provider) -> sqlite3.Connection """
        
            object_a = NewInstance(ObjectA,
                                   InitArg('db', database))
            """ :type: (objects.Provider) -> ObjectA """
        
            object_b = NewInstance(ObjectB,
                                   InitArg('a', object_a),
                                   InitArg('db', database))
            """ :type: (objects.Provider) -> ObjectB """
        
        
        # Satisfaction of external dependency.
        Catalog.database.satisfy(Singleton(sqlite3.Connection,
                                           InitArg('database', ':memory:'),
                                           Attribute('row_factory', sqlite3.Row)))
        
        # Catalog static provides.
        a1, a2 = Catalog.object_a(), Catalog.object_a()
        b1, b2 = Catalog.object_b(), Catalog.object_b()
        
        # 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()
        ```
        
        Example of objects catalog with scoped provider:
        
        ```python
        """
        Scoped provider examples.
        """
        
        from objects import AbstractCatalog
        from objects.providers import Singleton, Scoped
        from objects.injections import InitArg, Attribute
        
        import sqlite3
        
        
        class ObjectA(object):
            def __init__(self, db):
                self.db = db
        
        
        # Catalog of objects providers.
        class Catalog(AbstractCatalog):
            """
            Objects catalog.
            """
        
            database = Singleton(sqlite3.Connection,
                                 InitArg('database', ':memory:'),
                                 Attribute('row_factory', sqlite3.Row))
            """ :type: (objects.Provider) -> sqlite3.Connection """
        
            object_a = Scoped(ObjectA,
                              InitArg('db', database))
            """ :type: (objects.Provider) -> ObjectA """
        
        
        # Making scope using `with` statement.
        with Catalog.object_a as object_a_provider:
            object_a1 = object_a_provider()
            object_a2 = object_a_provider()
        
            assert object_a1 is object_a2
            assert object_a1.db is object_a2.db
        
        # Making another one scope using `with` statement.
        with Catalog.object_a as object_a_provider:
            object_a3 = object_a_provider()
            object_a4 = object_a_provider()
        
            assert object_a3 is object_a4
            assert object_a3.db is object_a4.db
        
            assert (object_a1 is not object_a3) and \
                   (object_a1 is not object_a4)
            assert (object_a2 is not object_a3) and \
                   (object_a2 is not object_a4)
        
        
        # Making one more scope using provider methods.
        Catalog.object_a.in_scope()
        
        object_a5 = Catalog.object_a()
        object_a6 = Catalog.object_a()
        
        Catalog.object_a.out_of_scope()
        
        assert object_a5 is object_a6
        assert object_a5.db is object_a6.db
        
        assert (object_a1 is not object_a3) and \
               (object_a1 is not object_a4) and \
               (object_a1 is not object_a5) and \
               (object_a1 is not object_a6)
        assert (object_a2 is not object_a3) and \
               (object_a2 is not object_a4) and \
               (object_a2 is not object_a5) and \
               (object_a2 is not object_a6)
        ```
        
        Example of objects catalog with callable provider:
        
        ```python
        """
        Callable provider examples.
        """
        
        from objects import AbstractCatalog
        from objects.providers import Singleton, Callable
        from objects.injections import Injection, InitArg, Attribute
        
        import sqlite3
        
        
        # Some example function.
        def consuming_function(arg, db):
            return arg, db
        
        
        # Catalog of objects providers.
        class Catalog(AbstractCatalog):
            """
            Objects catalog.
            """
        
            database = Singleton(sqlite3.Connection,
                                 InitArg('database', ':memory:'),
                                 Attribute('row_factory', sqlite3.Row))
            """ :type: (objects.Provider) -> sqlite3.Connection """
        
            consuming_function = Callable(consuming_function,
                                          Injection('db', database))
            """ :type: (objects.Provider) -> consuming_function """
        
        
        # Some calls.
        arg1, db1 = Catalog.consuming_function(1)
        arg2, db2 = Catalog.consuming_function(2)
        arg3, db3 = Catalog.consuming_function(3)
        
        # Some asserts.
        assert db1 is db2 is db3
        assert arg1 == 1
        assert arg2 == 2
        assert arg3 == 3
        ```
        
        Example of objects catalog with config provider:
        
        ```python
        """
        Config provider examples.
        """
        
        from objects import AbstractCatalog
        from objects.providers import Config, NewInstance
        from objects.injections import InitArg
        
        
        # Some example class.
        class ObjectA(object):
            def __init__(self, setting_one, setting_two, setting_three):
                self.setting_one = setting_one
                self.setting_two = setting_two
                self.setting_three = setting_three
        
        
        # Catalog of objects providers.
        class Catalog(AbstractCatalog):
            """
            Objects catalog.
            """
        
            config = Config()
            """ :type: (objects.Config) """
        
            object_a = NewInstance(ObjectA,
                                   InitArg('setting_one', config.SETTING_ONE),
                                   InitArg('setting_two', config.SETTING_TWO),
                                   InitArg('setting_three', config.GLOBAL.SETTING_THREE))
            """ :type: (objects.Provider) -> ObjectA """
        
        
        # Setting config value and making some tests.
        Catalog.config.update_from({
            'SETTING_ONE': 1,
            'SETTING_TWO': 2,
            'GLOBAL': {
                'SETTING_THREE': 3
            }
        })
        
        object_a1 = Catalog.object_a()
        
        assert object_a1.setting_one == 1
        assert object_a1.setting_two == 2
        assert object_a1.setting_three == 3
        
        # Changing config value one more time and making some tests.
        Catalog.config.update_from({
            'SETTING_ONE': 11,
            'SETTING_TWO': 22,
            'GLOBAL': {
                'SETTING_THREE': 33
            }
        })
        
        object_a2 = Catalog.object_a()
        
        assert object_a2.setting_one == 11
        assert object_a2.setting_two == 22
        assert object_a2.setting_three == 33
        
        assert object_a1.setting_one == 1
        assert object_a1.setting_two == 2
        assert object_a1.setting_three == 3
        ```
        
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
