Core functionality¶
This page details the core classes and functions that Oscar uses. These aren’t specific to one particular app, but are used throughout Oscar’s codebase.
Dynamic class loading¶
The key to Oscar’s flexibility is dynamically loading classes. This allows projects to provide their own versions of classes that extend and override the core functionality.
-
oscar.core.loading.
get_classes
(module_label, classnames, module_prefix='oscar.apps')[source]¶ Dynamically import a list of classes from the given module.
This works by looping over
INSTALLED_APPS
and looking for a match against the passed module label. If the requested class can’t be found in the matching module, then we attempt to import it from the corresponding core app.This is very similar to
django.db.models.get_model
function for dynamically loading models. This function is more general though as it can load any class from the matching app, not just a model.Parameters: - module_label (str) – Module label comprising the app label and the module name, separated by a dot. For example, ‘catalogue.forms’.
- classname (str) – Name of the class to be imported.
Returns: The requested class object or
None
if it can’t be foundExamples
Load a single class:
>>> get_class('dashboard.catalogue.forms', 'ProductForm') oscar.apps.dashboard.catalogue.forms.ProductForm
Load a list of classes:
>>> get_classes('dashboard.catalogue.forms', ... ['ProductForm', 'StockRecordForm']) [oscar.apps.dashboard.catalogue.forms.ProductForm, oscar.apps.dashboard.catalogue.forms.StockRecordForm]
Raises: AppNotFoundError
– If no app is found inINSTALLED_APPS
that matches the passed module label.ImportError
– If the attempted import of a class raises anImportError
, it is re-raised
-
oscar.core.loading.
get_class
(module_label, classname, module_prefix='oscar.apps')[source]¶ Dynamically import a single class from the given module.
This is a simple wrapper around get_classes for the case of loading a single class.
Parameters: - module_label (str) – Module label comprising the app label and the module name, separated by a dot. For example, ‘catalogue.forms’.
- classname (str) – Name of the class to be imported.
Returns: The requested class object or None if it can’t be found
URL patterns and views¶
Oscar’s app organise their URLs and associated views using a “Application” class instance. This works in a similar way to Django’s admin app, and allows Oscar projects to subclass and customised URLs and views.
-
class
oscar.core.application.
Application
(app_name=None, **kwargs)[source]¶ Base application class.
This is subclassed by each app to provide a customisable container for an app’s views and permissions.
-
default_permissions
= None¶ Default permission for any view not in permissions_map
-
get_permissions
(url)[source]¶ Return a list of permissions for a given URL name
Parameters: url (str) – A URL name (eg basket.basket
)Returns: A list of permission strings. Return type: list
-
get_url_decorator
(pattern)[source]¶ Return the appropriate decorator for the view function with the passed URL name. Mainly used for access-protecting views.
It’s possible to specify:
- no permissions necessary: use None
- a set of permissions: use a list
- two set of permissions (or): use a two-tuple of lists
See permissions_required decorator for details
-
hidable_feature_name
= None¶ A name that allows the functionality within this app to be disabled
-
name
= None¶ Namespace name
-
permissions_map
= {}¶ Maps view names to lists of permissions. We expect tuples of lists as dictionary values. A list is a set of permissions that all needto be fulfilled (AND). Only one set of permissions has to be fulfilled (OR). If there’s only one set of permissions, as a shortcut, you can also just define one list.
-
post_process_urls
(urlpatterns)[source]¶ Customise URL patterns.
This method allows decorators to be wrapped around an apps URL patterns.
By default, this only allows custom decorators to be specified, but you could override this method to do anything you want.
Parameters: urlpatterns (list) – A list of URL patterns
-
Prices¶
Oscar uses a custom price object for easier tax handling.
-
class
oscar.core.prices.
Price
(currency, excl_tax, incl_tax=None, tax=None)[source]¶ Simple price class that encapsulates a price and its tax information
-
incl_tax
¶ Decimal – Price including taxes
-
excl_tax
¶ Decimal – Price excluding taxes
-
tax
¶ Decimal – Tax amount
-
is_tax_known
¶ bool – Whether tax is known
-
currency
¶ str – 3 character currency code
-
Custom model fields¶
Oscar uses a few custom model fields.
-
class
oscar.models.fields.
NullCharField
(*args, **kwargs)[source]¶ CharField that stores ‘’ as None and returns None as ‘’ Useful when using unique=True and forms. Implies null==blank==True.
When a ModelForm with a CharField with null=True gets saved, the field will be set to ‘’: https://code.djangoproject.com/ticket/9590 This breaks usage with unique=True, as ‘’ is considered equal to another field set to ‘’.
-
class
oscar.models.fields.
PhoneNumberField
(*args, **kwargs)[source]¶ An international phone number.
- Validates a wide range of phone number formats
- Displays it nicely formatted
Notes
This field is based on work in django-phonenumber-field https://github.com/maikhoepfel/django-phonenumber-field/
See
oscar/core/phonenumber.py
for the relevant copyright and permission notice.
-
class
oscar.models.fields.
PositiveDecimalField
(verbose_name=None, name=None, max_digits=None, decimal_places=None, **kwargs)[source]¶ A simple subclass of
django.db.models.fields.DecimalField
that restricts values to be non-negative.
-
class
oscar.models.fields.
UppercaseCharField
(*args, **kwargs)[source]¶ A simple subclass of
django.db.models.fields.CharField
that restricts all text to be uppercase.Defined with the with_metaclass helper so that to_python is called https://docs.djangoproject.com/en/1.6/howto/custom-model-fields/#the-subfieldbase-metaclass # NOQA