Dynamic class loading explained¶
Dynamic class loading is the foundation for making Oscar extensively customisable. It is hence worth understanding how it works, because most customisation depends on it.
It is achieved by oscar.core.loading.get_classes()
and its
single-class cousin get_class()
. Wherever feasible,
Oscar uses get_classes
instead of a regular import statement:
from oscar.apps.shipping.repository import Repository
is replaced by:
from oscar.core.loading import get_class
Repository = get_class('shipping.repository', 'Repository')
Note
This is done for almost all classes: views, models, etc. Every class
imported by get_class
can be overridden.
Why?¶
This structure enables a project to create a local shipping.repository
module, and optionally subclass the class from
oscar.apps.shipping.repository
. When Oscar tries to load the
Repository
class, it will load the one from your local project.
This way, most classes can be overridden with minimal duplication, as only the to-be-changed classes have to be altered. They can optionally inherit from Oscar’s implementation, which often amounts to little more than a few lines of custom code for changes to core behaviour.
Seen on a bigger scale, this structures enables Oscar to ship with classes with minimal assumptions about the domain, and make it easy to modify behaviour as needed.
How it works¶
The get_class
function looks through your INSTALLED_APPS
for a matching
app and will attempt to load the custom class from the specified module. If the
app isn’t overridden or the custom module doesn’t define the class, it will
fall back to the default Oscar class.
In practice¶
For get_class
to pick up the customised class, the Oscar apps need to be
forked. The process is detailed and illustrated with examples in
Customising Oscar. It is usually enough to call oscar_fork_app
and replace the app in INSTALLED_APPS
.
Using get_class
in your own code¶
Generally, there is no need for get_class
in your own code as the location
of the module for the class is known. Some Oscar developers nonetheless
use get_class
when importing classes from Oscar. This means that if someday
the class is overridden, it will not require code changes. Care should be taken
when doing this, as this is a tricky trade-off between maintainability and
added complexity.
Please note that we cannot recommend ever using get_model
in your own code.
Model initialisation is a tricky process and it’s
easy to run into circular import issues.
Overriding dynamic class loading behaviour¶
In some cases it may be necessary to customise the logic used by Oscar to
dynamically load classes. You can do this by supplying your own class loader
function to the OSCAR_DYNAMIC_CLASS_LOADER
setting:
OSCAR_DYNAMIC_CLASS_LOADER = 'myproject.custom_class_loader'
Supply a dotted Python path to a callable that takes
the same arguments as default_class_loader()
.
Testing¶
You can test whether your overriding worked by trying to get a class from your module:
>>> from oscar.core.loading import get_class
>>> get_class('shipping.repository', 'Repository')
yourproject.shipping.repository.Repository # it worked!