nti.externalization.interfaces
: Interfaces and constants¶
Externalization Interfaces
-
class
ExternalizationPolicy
(use_iso8601_for_unix_timestamp=False)[source]¶ Bases:
object
Adjustment knobs for making tweaks across an entire externalization.
These knobs will tweak low-level details of the externalization format, details that are often in a hot code path where overhead should be kept to a minimum.
Instances of this class are used by registering them as named components in the global site manager. Certain low-level functions accept an optional policy argument that must be an instance of this class; higher level functions accept a policy_name argument that is used to find the registered component. If either argument is not given, then
DEFAULT_EXTERNALIZATION_POLICY
is used instead.Instances are immutable.
This class must not be subclassed; as such, there is no interface for it, merely the class itself.
-
use_iso8601_for_unix_timestamp
¶ Should unix timestamp fields be output as their numeric value, or be converted into an ISO 8601 timestamp string? By default, the numeric value is output. This is known to specifically apply to “Created Time” and “Last Modified.”
-
-
class
LocatedExternalDict
(*args, **kwargs)[source]¶ Bases:
dict
A dictionary that implements
ILocatedExternalMapping
. Returned byto_standard_external_dictionary()
.This class is not
IContentTypeAware
, and it indicates so explicitly by declaring amime_type
value of None.
-
interface
IInternalObjectExternalizer
[source]¶ Implemented by, or adapted from, an object that can be externalized.
-
__external_can_create__
¶ This must be set to true, generally at the class level, for objects that can be created by specifying their Class name.
-
__external_class_name__
¶ If present, the value is a string that is used for the ‘Class’ key in the external dictionary. If not present, the local name of the object’s class is used instead.
-
toExternalObject
(**kwargs)¶ Optional, see this
to_external_object()
.
-
-
interface
INonExternalizableReplacement
[source]¶ This interface may be applied to objects that serve as a replacement for a non-externalized object.
-
interface
INonExternalizableReplacementFactory
[source]¶ An factory object called to make a replacement when some object cannot be externalized.
-
__call__
(obj)¶ Returns: An externalized object to replace the given object. Possibly the given object itself if some higher level will handle it. The returned object may have the INonExternalizableReplacement
interface.
-
-
interface
IExternalObjectDecorator
[source]¶ Used as a subscription adapter (of the object or the object and request) to provide additional information to the externalization of an object after it has been externalized by the primary implementation of
IInternalObjectExternalizer
. Allows for a separation of concerns. These are called in no specific order, and so must operate by mutating the external object.These are called after
IExternalStandardDictionaryDecorator
.-
decorateExternalObject
(origial, external)¶ Decorate the externalized object (which is almost certainly a mapping, though this is not guaranteed).
Parameters: - original – The object that is being externalized. Passed to facilitate using non-classes as decorators.
- external – The externalization of that object, produced
by an implementation of
IInternalObjectExternalizer
or default rules.
Returns: Undefined.
-
-
interface
IExternalStandardDictionaryDecorator
[source]¶ Used as a subscription adapter (of the object or the object and request) to provide additional information to the externalization of an object after it has been externalized by the primary implementation of
IInternalObjectExternalizer
(which in turn must have invokedto_standard_external_dictionary()
).Allows for a separation of concerns. These are called in no specific order, and so must operate by mutating the external object.
These are called before
IExternalObjectDecorator
.Changed in version 2.3.0: Previously this was called
IExternalMappingDecorator
; that name remains as a backward compatibility alias.-
decorateExternalMapping
(original, external)¶ Decorate the externalized object mapping.
Parameters: - original – The object that is being externalized. Passed to facilitate using non-classes as decorators.
- external – The externalization of that object, an
ILocatedExternalMapping
, produced by an implementation ofIInternalObjectExternalizer
or default rules.
Returns: Undefined.
-
-
interface
IExternalizedObject
[source]¶ An object that has already been externalized and needs no further transformation.
-
interface
ILocatedExternalMapping
[source]¶ Extends:
nti.externalization.interfaces.IExternalizedObject
,zope.location.interfaces.ILocation
,zope.interface.common.collections.IMapping
The externalization of an object as a dictionary, maintaining its location information.
-
interface
ILocatedExternalSequence
[source]¶ Extends:
nti.externalization.interfaces.IExternalizedObject
,zope.location.interfaces.ILocation
,zope.interface.common.collections.ISequence
The externalization of an object as a sequence, maintaining its location information.
-
class
LocatedExternalList
[source]¶ Bases:
list
A list that implements
ILocatedExternalSequence
. Returned byto_external_object()
.This class is not
IContentTypeAware
, and it indicates so explicitly by declaring amimeType
value of None.
-
interface
IExternalObjectRepresenter
[source]¶ Something that can represent an external object as a sequence of bytes.
These will be registered as named utilities and may each have slightly different representation characteristics.
-
dump
(obj, fp=None)¶ Write the given object. If
fp
is None, then the string representation will be returned, otherwise, fp specifies a writeable object to which the representation will be written.
-
-
interface
IExternalRepresentationReader
[source]¶ Something that can read an external string, as produced by
IExternalObjectRepresenter
and return an equivalent external value.`-
load
(stream)¶ Load from the stream an external value. String values should be read as unicode.
All objects must support the stream being a sequence of bytes, some may support an open file object.
-
-
interface
IExternalObjectIO
[source]¶ Extends:
nti.externalization.interfaces.IExternalObjectRepresenter
,nti.externalization.interfaces.IExternalRepresentationReader
Something that can read and write external values.
-
EXT_REPR_JSON
= u'json'¶ Constant requesting JSON format data
-
EXT_REPR_YAML
= u'yaml'¶ Constant requesting YAML format data
-
interface
IMimeObjectFactory
[source]¶ Extends:
zope.component.interfaces.IFactory
A factory named for the external mime-type of objects it works with.
-
interface
IClassObjectFactory
[source]¶ Extends:
zope.component.interfaces.IFactory
A factory named for the external class name of objects it works with.
-
interface
IAnonymousObjectFactory
[source]¶ Extends:
zope.component.interfaces.IFactory
A factory for external data that doesn’t identify its object type.
This data is not produced by this library but comes from external sources.
When these are registered as factories (utilities) care must be taken to avoid name clashes (since there are no “natural” unique names).
See the ZCML directive
IAnonymousObjectFactoryDirective
for a simple way to do this.New in version 1.0a3.
-
interface
IExternalizedObjectFactoryFinder
[source]¶ An adapter from an externalized object to something that can find factories.
-
find_factory
(externalized_object)¶ Given an externalized object, return a
zope.component.interfaces.IFactory
to create the proper internal types.Returns: An zope.component.interfaces.IFactory
, orNone
.
-
-
interface
IExternalReferenceResolver
[source]¶ Used as a multi-adapter from an internal object and an external reference to something that can resolve the reference.
-
resolve
(reference)¶ Resolve the external reference and return it.
-
-
interface
INamedExternalizedObjectFactoryFinder
[source]¶ An object that can find factories for particular named external objects.
This is registered as an adapter for particular internal objects, so that internal object, and any schema it implements, can be used to choose the factory for nested objects being updated into it.
-
find_factory_for_named_value
(name, value)¶ Find a factory for the external object value when it is the value with the name name.
This function has three key pieces of information to work with.
First, it is an adapter from an internal object, so it knows the ultimate destination object (the context) where the results of the factory will be set.
Second, it knows the incoming name of the external value.
Third, it knows the actual incoming external value.
For example, if the external data looked like
{'key': 'value'}
a call toupdate_from_external_object(internal_object, data)
would conceptually result in a call that looked like this:adapter = INamedExternalizedObjectFactoryFinder(internal_object) factory = adapter.find_factory_for_named_value('key', 'value')
When the value for the external data is a mutable sequence, this function will be called once for each item in the sequence. So external data of
{'key': [1, 2, 3]}
would result in calls('key', 1)
,('key', 2)
and('key', 3)
.This function can return actual factories that produce fresh objects, or it can return the current object assigned to the ultimate attribute in the context to update that exact object in place. This can be beneficial for persistent objects.
-
-
interface
IInternalObjectUpdater
[source]¶ An adapter that can be used to update an internal object from its externalized representation.
-
__external_resolvers__
¶ For objects who need to perform arbitrary resolution from external forms to internal forms, this attribute is a map from key path to a function of three arguments, the dataserver, the parsed object, and the value to resolve. It should return the new value. Note that the function here is at most a class or static method, not an instance method.
-
__external_oids__
¶ For objects whose external form includes object references (OIDs), this attribute is a list of key paths that should be resolved. The values for the key paths may be singleton items or mutable sequences. Resolution may involve placing a None value for a key.
-
updateFromExternalObject
(externalObject, context, **kwargs)¶ Update the object this is adapting from the external object.
Alternately, the signature can be
updateFromExternalObject(externalObject)
or simplyupdateFromExternalObject(externalObject, **kwargs)
. In this last case,context
will be passed as a value in**kwargs
.Returns: If not None
, a value that can be interpreted as a boolean, indicating whether or not the internal object actually underwent updates. IfNone
, the caller should assume that the object was updated (to allow older code that doesn’t return at all.)
-
-
interface
IInternalObjectIO
[source]¶ Extends:
nti.externalization.interfaces.IInternalObjectExternalizer
,nti.externalization.interfaces.IInternalObjectUpdater
A single object responsible for both reading and writing internal objects in external forms. This is convenient for keeping code organized.
-
interface
IInternalObjectIOFinder
[source]¶ Extends:
nti.externalization.interfaces.INamedExternalizedObjectFactoryFinder
,nti.externalization.interfaces.IInternalObjectIO
Like
IInternalObjectIO
, but this object also gets the chance to find factories for objects.The class
InterfaceObjectIO
implements this interface.
-
interface
IObjectWillUpdateFromExternalEvent
[source]¶ Extends:
zope.interface.interfaces.IObjectEvent
An object will be updated from an external value.
-
root
¶ The object initially passed to update_from_external_object. For nested objects, this will be some ancestor of the object this event is for. For updaters that manually update sub-objects, this isn’t guaranteed to be the actual true root object being updated.
-
external_value
¶ The external value. This is not necessarily a pristine object as decoded from, e.g., JSON. It will be mutated as sub-objects get updated and parsed. For example, strings may get replaced with datetimes, and so on. The consequences of modifying this object in an event subscriber are undefined.
-
-
interface
IObjectModifiedFromExternalEvent
[source]¶ Extends:
zope.lifecycleevent.interfaces.IObjectModifiedEvent
An object has been updated from an external value.
-
external_value
¶ The external value
-
kwargs
¶ The keyword arguments
-
-
class
ObjectModifiedFromExternalEvent
(obj, *descriptions, **kwargs)[source]¶ Bases:
zope.lifecycleevent.ObjectModifiedEvent
Default implementation of
IObjectModifiedFromExternalEvent
.
-
class
StandardExternalFields
[source]¶ Bases:
object
Namespace object defining constants whose values are the keys used in external mappings.
These are text (unicode).
Not all external objects will have all possible keys.
Two special values are collections of metadata, not strings:
ALL
andEXTERNAL_KEYS
.-
ID
¶ An id
-
OID
¶ An identifier specific to this exact object instance
-
HREF
¶ A hyperlink to reach this object
-
INTID
¶ An integer uniquely identifying the object in some scope
-
NTIID
¶ A structured identifier similar to a hyperlink
-
CREATOR
¶ The name of the creator of the object
-
CONTAINER_ID
¶ The name of the container holding the object
-
CREATED_TIME
¶ The floating point value giving the Unix epoch time of the object’s creation
-
LAST_MODIFIED
¶ The floating point value giving the Unix epoch time of the last modification of the object
-
CLASS
¶ ‘Class’: The class of the object. If the object provides
__external_class_name__
it will be used to populate this.
-
LINKS
¶ A dictionary mapping “rel” to more hrefs.
-
MIMETYPE
¶ The MIME type of this object
-
ITEMS
¶ A list or dictionary of external objects contained within this object
-
TOTAL
¶ A counter
-
ITEM_COUNT
¶ The total number of items contained in this object
-
ALL
¶ A collection of all names of all the attributes of this class.
That is, the contents of this collection are the attribute names that give standard external fields. You can iterate this and use
getattr()
to get the corresponding values.
-
EXTERNAL_KEYS
¶ A collection of all values of all attributes of this class.
That is, the contents of this collection are the keys that a standard external object would be expected to have.
-
-
class
StandardInternalFields
[source]¶ Bases:
object
Namespace object defining constants whose values are the property/attribute names looked for on internal objects.
These must be native strings.
-
CONTAINER_ID
¶ ‘containerId’: The ID of the container of this object. Fills
StandardExternalFields.CONTAINER_ID
.
-
CREATED_TIME
¶ ‘createdTime’: The Unix timestamp of the creation of this object. If no value can be found, we will attempt to adapt to
zope.dublincore.interfaces.IDCTimes
and use its ‘created’ attribute. FillsStandardExternalFields.CREATED_TIME
-
CREATOR
¶ ‘creator’: An object that created this object. This will be converted to a text string to fill in
StandardExternalFields.CREATOR
.
-
ID
¶ ‘id’: An object ID
-
LAST_MODIFIED
¶ ‘lastModified’: The Unix timestamp of the last modification of this object. If no value can be found, we will attempt to adapt to zope.dublincore.interfaces.IDCTimes` and use its ‘modified’ attribute. Fills
StandardExternalFields.LAST_MODIFIED
-
NTIID
¶ ‘ntiid’: An object’s structured ID.
-
-
DEFAULT_EXTERNALIZATION_POLICY
= ExternalizationPolicy(use_iso8601_for_unix_timestamp=False)¶ The default externalization policy.
Deprecated Names¶
-
IList
= <InterfaceClass zope.interface.common.builtins.IList>[source]¶ Marker interface for lists.
Deprecated since version 2.1.0: Use
zope.interface.common.builtins.IList
directly. This is just an alias.
-
IIterable
= <ABCInterfaceClass zope.interface.common.collections.IIterable>[source]¶ Base interface for iterable types.
Deprecated since version 2.1.0: Use
zope.interface.common.collections.IIterable
directly. This is just an alias.
-
IExternalObject
= <InterfaceClass nti.externalization.interfaces.IInternalObjectExternalizer>¶ Backwards compatibility alias.
Deprecated since version 2.0.0: Use
IInternalObjectExternalizer
directly.
-
INonExternalizableReplacer
= <InterfaceClass nti.externalization.interfaces.INonExternalizableReplacementFactory>¶ Backwards compatibility alias.
Deprecated since version 2.0.0: Use
INonExternalizableReplacement
directly.
-
IExternalMappingDecorator
= <InterfaceClass nti.externalization.interfaces.IExternalStandardDictionaryDecorator>¶ Backwards compatibility alias.
Deprecated since version 2.3.0: Use
IExternalStandardDictionaryDecorator
directly.