django-hexdi
This is the project that integrates hexdi framework into Django.
Visit github page of hexdi project for use-cases and instructions.
Created for using with django-based applications.
Installation
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!
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:
HEXDI_STRATEGY = 'djhexdi.strategy.Static'
Use the special setting to provide dotted path of modules where bindings are presented:
HEXDI_MODULES_LIST = [
'path.to.first.module',
'path.to.second.module',
]
You can specify a module that contains this list:
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:
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:
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:
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:
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:
- requirements installation
- other build activities (migrations, caching, template building, etc.)
- modules automatic discovery and storing results in py-file artifact
Run application:
- application start
- pre-searched artifact loading with modules list on application startup process
Setup Django project
Define setting for using static strategy:
HEXDI_STRATEGY = 'djhexdi.strategy.Static'
Define a file where discovered modules will be stored:
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:
HEXDI_FINDER_PACKAGES = [
'path.to.first.package',
'path.to.second.package',
]
You can also define modules that should be loaded additionally
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:
python manage.py di_find --auto
If you want to specify some other module, just use -m option:
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 fromdjhexdi.strategy.AbstractStrategy
class. Default valuedjhexdi.strategy.Dummy
; -
HEXDI_FINDER_PACKAGES
- A list of packages(dotted paths). By default usesINSTALLED_APPS
modules list. Used byAutomatic strategy
anddi_find
management command; -
HEXDI_MODULES_LIST
- A list of modules(dotted paths) that should be loaded on application startup. Used byStatic strategy
andAutomatic strategy
; -
HEXDI_EXCLUDE_MODULES
- A list of modules that should be excluded from module-loading. Used byStatic loading
andAutomatic loading
; -
HEXDI_MODULE_LIST_NAME
- A name of variable with modules list that should be presented in module(HEXDI_MODULE setting). Used byStatic strategy
anddi_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 byStatic strategy
,Automatic strategy
, anddi_find
management command. -
HEXDI_LOADER
- A string contained dotted path to a class that will be used as module loader. Default valuehexdi.loader.BasicLoader
-
HEXDI_FINDER
- A string contained dotted path to a class that will be used as module finder. Default valuehexdi.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 inHEXDI_LOADER
setting; - function
find_modules
discover modules. Accepts packages list(dotted paths) to find as a single argument. Uses finder specified inHEXDI_FINDER
setting; - class
AbstractStrategy
is a very base abstract class that provides methodgo
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 fromAbstractStrategy
and provides implemented methodgo
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 inHEXDI_EXCLUDE_MODULES
setting. - class
Static
is a ready-to-go strategy inherited fromAbstractLoadModulesStrategy
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 fromStatic
strategy and extended it with automatic discovery of modules to load.
Check module hexdi.utils for useful functions