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)[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 Oscar app (assuming the matched module isn’t in Oscar).

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 found

Examples

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 in INSTALLED_APPS that matches the passed module label.
  • ImportError – If the attempted import of a class raises an ImportError, it is re-raised
oscar.core.loading.get_class(module_label, classname)[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:list – A list of permission strings.
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

get_urls()[source]

Return the url patterns for this app.

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 a tuple or list of permissions

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.PhoneNumberField(*args, **kwargs)[source]

An international phone number.

  • Validates a wide range of phone number formats
  • Displays it nicely formatted
  • Can be given a hint for the country, so that it can accept local numbers, that are not in an international format

Note

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.

attr_class

alias of PhoneNumber

descriptor_class

alias of PhoneNumberDescriptor

get_prep_value(value)[source]

Returns field’s value prepared for saving into a database.

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.