nti.externalization.interfaces: Interfaces and constants

Externalization Interfaces

EXT_REPR_JSON = 'json'

Constant requesting JSON format data

EXT_REPR_YAML = 'yaml'

Constant requesting YAML format data

class ExternalizationPolicy(use_iso8601_for_unix_timestamp=False)

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.”

interface IAnonymousObjectFactory

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.

Added in version 1.0a3.

interface IClassObjectFactory

Extends: zope.component.interfaces.IFactory

A factory named for the external class name of objects it works with.

interface IExternalObjectDecorator

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 IExternalObjectIO

Extends: nti.externalization.interfaces.IExternalObjectRepresenter, nti.externalization.interfaces.IExternalRepresentationReader

Something that can read and write external values.

interface IExternalObjectRepresenter

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.

Implementations should accept arbitrary keyword arguments, ignoring any they don’t understand.

interface IExternalReferenceResolver

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 IExternalRepresentationReader

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 IExternalStandardDictionaryDecorator

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 invoked to_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 of IInternalObjectExternalizer or default rules.

Returns:

Undefined.

interface IExternalizedObject

An object that has already been externalized and needs no further transformation.

interface IExternalizedObjectFactoryFinder

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, or None.

interface IInternalObjectExternalizer

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 IInternalObjectIO

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

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 IInternalObjectUpdater

An adapter that can be used to update an internal object from its externalized representation.

__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.

__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.

updateFromExternalObject(externalObject, context, **kwargs)

Update the object this is adapting from the external object.

Alternately, the signature can be updateFromExternalObject(externalObject) or simply updateFromExternalObject(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. If None, the caller should assume that the object was updated (to allow older code that doesn’t return at all.)

interface ILocatedExternalMapping

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

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.

interface IMimeObjectFactory

Extends: zope.component.interfaces.IFactory

A factory named for the external mime-type of objects it works with.

interface INamedExternalizedObjectFactoryFinder

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 to update_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 INonExternalizableReplacement

This interface may be applied to objects that serve as a replacement for a non-externalized object.

interface INonExternalizableReplacementFactory

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 IObjectModifiedFromExternalEvent

Extends: zope.lifecycleevent.interfaces.IObjectModifiedEvent

An object has been updated from an external value.

external_value

The external value

kwargs

The keyword arguments

interface IObjectWillUpdateFromExternalEvent

Extends: zope.interface.interfaces.IObjectEvent

An object will be updated from an external value.

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.

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.

class LocatedExternalDict(*args, **kwargs)

Bases: dict

A dictionary that implements ILocatedExternalMapping. Returned by to_standard_external_dictionary().

This class is not IContentTypeAware, and it indicates so explicitly by declaring a mime_type value of None.

class LocatedExternalList(iterable=(), /)

Bases: list

A list that implements ILocatedExternalSequence. Returned by to_external_object().

This class is not IContentTypeAware, and it indicates so explicitly by declaring a mimeType value of None.

class ObjectModifiedFromExternalEvent(obj, *descriptions, **kwargs)

Bases: ObjectModifiedEvent

Default implementation of IObjectModifiedFromExternalEvent.

Init with a list of modification descriptions.

class StandardExternalFields

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 and EXTERNAL_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

property 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.

property 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

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. Fills StandardExternalFields.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>

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>

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.