opaque_keys package

Subpackages

• opaque_keys.edx package
  • Submodules
  • opaque_keys.edx.keys module
  • opaque_keys.edx.locations module
  • opaque_keys.edx.locator module
  • Module contents

Module contents

Defines the OpaqueKey class, to be used as the base-class for implementing pluggable OpaqueKeys.

These keys are designed to provide a limited, forward-evolveable interface to an application, while concealing the particulars of the serialization formats, and allowing new serialization formats to be installed transparently.

exception opaque_keys.InvalidKeyError(key_class, serialized)

Bases: Exception

Raised to indicated that a serialized key isn’t valid (wasn’t able to be parsed by any available providers).

class opaque_keys.OpaqueKey(*args, **kwargs)

Bases: object

A base-class for implementing pluggable opaque keys. Individual key subclasses identify particular types of resources, without specifying the actual form of the key (or its serialization).

There are two levels of expected subclasses: Key type definitions, and key implementations

OpaqueKey
    |
Key type
    |
Key implementation

The key type base class must define the class property KEY_TYPE, which identifies which entry_point namespace the keys implementations should be registered with.

The KeyImplementation classes must define the following:

CANONICAL_NAMESPACE

Identifies the key namespace for the particular key implementation (when serializing). Key implementations must be registered using the CANONICAL_NAMESPACE as their entry_point name, but can also be registered with other names for backwards compatibility.

KEY_FIELDS

A list of attribute names that will be used to establish object identity. Key implementation instances will compare equal iff all of their KEY_FIELDS match, and will not compare equal to instances of different KeyImplementation classes (even if the KEY_FIELDS match). These fields must be hashable.

_to_string

Serialize the key into a unicode object. This should not include the namespace prefix (CANONICAL_NAMESPACE).

_from_string

Construct an instance of this OpaqueKey from a unicode object. The namespace will already have been parsed.

OpaqueKeys will not have optional constructor parameters (due to the implementation of KEY_FIELDS), by default. However, an implementation class can provide a default, as long as it passes that default to a call to super().__init__. If the KeyImplementation sets the class attribute CHECKED_INIT to False, then the OpaqueKey base class constructor will not validate any of the KEY_FIELDS arguments, and will instead just expect all KEY_FIELDS to be passed as kwargs.

OpaqueKey objects are immutable.

Serialization of an OpaqueKey is performed by using the unicode() builtin. Deserialization is performed by the from_string() method.

CANONICAL_NAMESPACE = None

CHECKED_INIT = True

KEY_FIELDS = []

LOADED_DRIVERS = defaultdict(None, {})

NAMESPACE_SEPARATOR = ':'

deprecated

classmethod from_string(serialized)

Return a OpaqueKey object deserialized from the serialized argument. This object will be an instance of a subclass of the cls argument.

Args:

serialized: A stringified form of a OpaqueKey

classmethod get_namespace_plugin(namespace)

Return the registered OpaqueKey subclass of cls for the supplied namespace

replace(**kwargs)

Return: a new OpaqueKey with KEY_FIELDS specified in kwargs replaced

their corresponding values. Deprecation value is also preserved.

Subclasses should override this if they have required properties that aren’t included in their KEY_FIELDS.

classmethod set_deprecated_fallback(fallback)

Register a deprecated fallback class for this class to revert to.

class opaque_keys.OpaqueKeyMetaclass

Bases: abc.ABCMeta

Metaclass for OpaqueKey. Sets the default value for the values in KEY_FIELDS to None.