From f35379a8387265a3613471830268e724d0788c67 Mon Sep 17 00:00:00 2001 From: Calen Pennington Date: Thu, 15 May 2014 14:31:05 -0400 Subject: [PATCH] Update opaque_keys docs --- .../lib/opaque_keys/opaque_keys/__init__.py | 74 +++++++++++++------ docs/en_us/developers/source/common-lib.rst | 1 + docs/en_us/developers/source/conf.py | 2 +- docs/en_us/developers/source/opaque-keys.rst | 11 +++ 4 files changed, 64 insertions(+), 24 deletions(-) create mode 100644 docs/en_us/developers/source/opaque-keys.rst diff --git a/common/lib/opaque_keys/opaque_keys/__init__.py b/common/lib/opaque_keys/opaque_keys/__init__.py index 3a33add8a1..7a99c15295 100644 --- a/common/lib/opaque_keys/opaque_keys/__init__.py +++ b/common/lib/opaque_keys/opaque_keys/__init__.py @@ -1,6 +1,10 @@ """ -Defines OpaqueKey class, to be used as the base-class for +Defines the :class:`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. """ from abc import ABCMeta, abstractmethod, abstractproperty from copy import deepcopy @@ -21,8 +25,8 @@ class InvalidKeyError(Exception): class OpaqueKeyMetaclass(ABCMeta): """ - Metaclass for OpaqueKeys. Automatically derives the class from a namedtuple - with a fieldset equal to the KEY_FIELDS class attribute, if KEY_FIELDS is set. + Metaclass for :class:`OpaqueKey`. Sets the default value for the values in ``KEY_FIELDS`` to + ``None``. """ def __new__(mcs, name, bases, attrs): if '__slots__' not in attrs: @@ -40,31 +44,48 @@ class OpaqueKey(object): There are two levels of expected subclasses: Key type definitions, and key implementations - OpaqueKey - | - KeyType - | - KeyImplementation + :: - The KeyType base class must define the class property KEY_TYPE, which identifies - which entry_point namespace the keys implementations should be registered with. + OpaqueKey + | + Key type + | + Key implementation - The KeyImplementation classes must define CANONICAL_NAMESPACE and KEY_FIELDS. - CANONICAL_NAMESPACE: Identifies the key namespace for the particular - key_implementation (when serializing). KeyImplementations must be - registered using the CANONICAL_NAMESPACE is 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. KeyImplementation 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. + 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`` is 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 :class:`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, and implementation class can provide a default, - as long as it passes that default to a call to super().__init__. + ``KEY_FIELDS``), by default. However, and implementation class can provide a default, + as long as it passes that default to a call to ``super().__init__``. - OpaqueKeys are immutable. + :class:`OpaqueKey` objects are immutable. + + Serialization of an :class:`OpaqueKey` is performed by using the :func:`unicode` builtin. + Deserialization is performed by the :meth:`from_string` method. """ __metaclass__ = OpaqueKeyMetaclass __slots__ = ('_initialized') @@ -142,6 +163,10 @@ class OpaqueKey(object): self._initialized = True def replace(self, **kwargs): + """ + Return: a new :class:`OpaqueKey` with ``KEY_FIELDS`` specified in ``kwargs`` replaced + their corresponding values. + """ existing_values = {key: getattr(self, key) for key in self.KEY_FIELDS} # pylint: disable=no-member existing_values.update(kwargs) return type(self)(**existing_values) @@ -156,6 +181,9 @@ class OpaqueKey(object): raise AttributeError("Can't delete {!r}. OpaqueKeys are immutable.".format(name)) def __unicode__(self): + """ + Serialize this :class:`OpaqueKey`, in the form ``:``. + """ return self.NAMESPACE_SEPARATOR.join([self.CANONICAL_NAMESPACE, self._to_string()]) # pylint: disable=no-member def __copy__(self): diff --git a/docs/en_us/developers/source/common-lib.rst b/docs/en_us/developers/source/common-lib.rst index 2079ae7a23..f691a83ed2 100644 --- a/docs/en_us/developers/source/common-lib.rst +++ b/docs/en_us/developers/source/common-lib.rst @@ -11,4 +11,5 @@ Contents: sandbox-packages.rst symmath.rst calc.rst + opaque-keys.rst diff --git a/docs/en_us/developers/source/conf.py b/docs/en_us/developers/source/conf.py index 6e590335c4..b836041ec9 100644 --- a/docs/en_us/developers/source/conf.py +++ b/docs/en_us/developers/source/conf.py @@ -65,7 +65,7 @@ else: extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', - 'sphinx.ext.mathjax', 'sphinx.ext.viewcode'] + 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon'] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/en_us/developers/source/opaque-keys.rst b/docs/en_us/developers/source/opaque-keys.rst new file mode 100644 index 0000000000..f845144254 --- /dev/null +++ b/docs/en_us/developers/source/opaque-keys.rst @@ -0,0 +1,11 @@ +******************************************* +OpaqueKeys +******************************************* +.. module:: opaque_keys + +OpaqueKeys +========== + +.. automodule:: opaque_keys + :members: + :show-inheritance: \ No newline at end of file