Metadata-Version: 1.2
Name: django-hexdi
Version: 0.2.1
Summary: Highly extensible Dependency injection framework for humans. Django integration
Home-page: https://github.com/zibertscrem/django-hexdi
Author: Dmitriy Selischev
Author-email: zibertscrem@gmail.com
License: MIT
Description: django-hexdi
        ============
        
        This is the project that integrates **hexdi** framework into Django.
        
        Visit `github page <https://github.com/zibertscrem/hexdi>`__ of
        **hexdi** project for use-cases and instructions.
        
        Created for using with django-based applications.
        
        Installation
        ============
        
        .. code:: bash
        
            pip install django-hexdi
        
        Keep in mind that we really recommend to use the same version of hexdi
        that django-hexdi has
        
        Usage
        =====
        
        First step is to add ``djhexdi`` to your ``INSTALLED_APPS`` setting.
        
        Imagine next project tree:
        
        ::
        
            app_folder
            |-->__init__.py
            |-->services.py
            |-->concrete_services.py
            .....
            |-->urls.py
            |-->forms.py
            |-->views.py
        
        File services.py contains service class declarations and "interfaces".
        
        File concrete\_services.py contains implementations of services stored
        in services.py and binded using **hexdi** calls.
        
        forms.py, views.py, and so on use services.py interfaces and inject
        these interfaces implementations using **hexdi** injections.
        
        So, there are several ways to set up **hexdi** on Django for static or
        automatic implementations loading:
        
        Dummy strategy
        --------------
        
        This is the **default strategy** that does nothing on application
        startup. You really should use something other!
        
        .. code:: python
        
            HEXDI_STRATEGY = 'djhexdi.strategy.Dummy'
        
        Static strategy
        ---------------
        
        This is the simplest and static strategy of implementations discovery
        using modules list that contain bindings.
        
        Use next setting to set up this strategy:
        
        .. code:: python
        
            HEXDI_STRATEGY = 'djhexdi.strategy.Static'
        
        Use the special setting to provide dotted path of modules where bindings
        are presented:
        
        .. code:: python
        
            HEXDI_MODULES_LIST = [
                'path.to.first.module',
                'path.to.second.module',
            ]
        
        You can specify a module that contains this list:
        
        .. code:: python
        
            HEXDI_MODULE = '__hexdi__'
        
        Use this discovery when you are sure that there is no other place with
        bindings and your dependency modules don't use hexdi, so on.
        
        Fully automatic strategy
        ------------------------
        
        This is the dynamic strategy of modules finding which works on
        application startup.
        
        Use next setting to set up this strategy:
        
        .. code:: python
        
            HEXDI_STRATEGY = 'djhexdi.strategy.Auto'
        
        By default, **hexdi** will search in packages that presented in
        ``INSTALLED_APPS``. But, you can also specify your special packages for
        searching using following setting:
        
        .. code:: python
        
            HEXDI_FINDER_PACKAGES = [
                'path.to.first.package',
                'path.to.second.package',
            ]
        
        You can also specify a static modules to load it additionally if it is
        needed:
        
        .. code:: python
        
            HEXDI_MODULES_LIST = [
                'path.to.first.module',
                'path.to.second.module',
            ]
        
        And you can specify a number of modules that should be excluded from
        loading:
        
        .. code:: python
        
            HEXDI_EXCLUDE_MODULES = [
                'path.to.first.excluded.module',
                'path.to.second.excluded.module',
            ]
        
        Use this strategy if you can **rely on module-finder** or your
        dependencies are using **hexdi**, or something.
        
        But keep in mind that **this strategy may slowdown your application
        startup** if you have a huge number of modules/dependencies.
        
        Pre-build automatic discovery with static loading
        -------------------------------------------------
        
        This is the best configuration for application that has a build process
        or same thing.
        
        Workflow explanation
        ~~~~~~~~~~~~~~~~~~~~
        
        Build process:
        
        1. requirements installation
        2. other build activities (migrations, caching, template building, etc.)
        3. modules automatic discovery and storing results in py-file artifact
        
        Run application:
        
        1. application start
        2. pre-searched artifact loading with modules list on application
           startup process
        
        Setup Django project
        ~~~~~~~~~~~~~~~~~~~~
        
        Define setting for using static strategy:
        
        .. code:: python
        
            HEXDI_STRATEGY = 'djhexdi.strategy.Static'
        
        Define a file where discovered modules will be stored:
        
        .. code:: python
        
            HEXDI_MODULE = '__hexdi__'
        
        The best way is to use ``__hexdi__`` as HEXDI\_MODULE value.
        
        By default, **hexdi** will search in packages that presented in
        ``INSTALLED_APPS``. But, you can also specify your special packages for
        searching using following setting:
        
        .. code:: python
        
            HEXDI_FINDER_PACKAGES = [
                'path.to.first.package',
                'path.to.second.package',
            ]
        
        You can also define modules that should be loaded additionally
        
        .. code:: python
        
            HEXDI_MODULES_LIST = [
                'path.to.first.module',
                'path.to.second.module',
            ]
        
        Set up build step
        ~~~~~~~~~~~~~~~~~
        
        Use the special manage.py command for modules automatic discovery
        
        If you have configured your Django project with ``HEXDI_MODULE`` setting
        then you can just apply following command:
        
        .. code:: bash
        
            python manage.py di_find --auto
        
        If you want to specify some other module, just use -m option:
        
        .. code:: bash
        
            python manage.py di_find -m other.module.path --auto
        
        **--auto** option is used for automatic creation of packages tree if not
        exists.
        
        Use this strategy when you have too much dependencies to store all
        modules manually and if you have build process with controllable build
        steps. That configuration allows you to have **fully automatic
        discovery** once while build process and then **quick application
        startup** with cached module paths.
        
        All supported settings
        ======================
        
        List of built-in settings and it's description
        
        -  ``HEXDI_STRATEGY`` - Strategy for DI container bindings discovery
           used on application startup. Should be inherited from
           ``djhexdi.strategy.AbstractStrategy`` class. Default value
           ``djhexdi.strategy.Dummy``;
        -  ``HEXDI_FINDER_PACKAGES`` - A list of packages(dotted paths). By
           default uses ``INSTALLED_APPS`` modules list. Used by
           ``Automatic strategy`` and ``di_find`` management command;
        -  ``HEXDI_MODULES_LIST`` - A list of modules(dotted paths) that should
           be loaded on application startup. Used by ``Static strategy`` and
           ``Automatic strategy``;
        -  ``HEXDI_EXCLUDE_MODULES`` - A list of modules that should be excluded
           from module-loading. Used by ``Static loading`` and
           ``Automatic loading``;
        -  ``HEXDI_MODULE_LIST_NAME`` - A name of variable with modules list
           that should be presented in module(HEXDI\_MODULE setting). Used by
           ``Static strategy`` and ``di_find`` management command;
        -  ``HEXDI_MODULE`` - A module path(dotted path) that contains a
           variable(name stores in HEXDI\_MODULES\_LIST\_NAME) with list of
           module paths(dotted paths). Used by ``Static strategy``,
           ``Automatic strategy``, and ``di_find`` management command.
        -  ``HEXDI_LOADER`` - A string contained dotted path to a class that
           will be used as **module loader**. Default value
           ``hexdi.loader.BasicLoader``
        -  ``HEXDI_FINDER`` - A string contained dotted path to a class that
           will be used as **module finder**. Default value
           ``hexdi.finder.RecursiveRegexFinder``
        
        Custom strategy
        ===============
        
        If you have some other vision of startup loading strategy, then you are
        able to implement it.
        
        Check module ``djhexdi.strategy`` for useful abstract classes and
        functions:
        
        -  function ``load_modules`` loads found or specified modules. Accepts
           modules list(dotted paths) as a first argument and modules to
           exclude(dotted paths) as a second argument. Uses loader specified in
           ``HEXDI_LOADER`` setting;
        -  function ``find_modules`` discover modules. Accepts packages
           list(dotted paths) to find as a single argument. Uses finder
           specified in ``HEXDI_FINDER`` setting;
        -  class ``AbstractStrategy`` is a very base abstract class that
           provides method ``go`` without arguments for doing some module-load
           staff on application startup. All other strategies should be
           inherited from that class.
        -  class ``AbstractLoadModulesStrategy`` is an abstract strategy
           inherited from ``AbstractStrategy`` and provides implemented method
           ``go`` and 2 other methods: discover\_modules - abstract method that
           should return a modules list, get\_excluded\_modules - already
           implemented method that returns a list presented in
           ``HEXDI_EXCLUDE_MODULES`` setting.
        -  class ``Static`` is a ready-to-go strategy inherited from
           ``AbstractLoadModulesStrategy`` with implemented behaviour of static
           modules list(HEXDI\_MODULES\_LIST) loading and module
           loading(HEXDI\_MODULE). You can inherit from that class and extend
           static loading with some other staff.
        -  class ``Auto`` is a ready-to-go strategy inherited from ``Static``
           strategy and extended it with automatic discovery of modules to load.
        
        Check module
        `hexdi.utils <https://github.com/zibertscrem/hexdi/blob/master/hexdi/utils.py>`__
        for useful functions
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.5,<4
