Externalization

Functions related to actually externalizing objects.

Only import from this module. Sub-modules of this package are implementation details.

exception NonExternalizableObjectError[source]

Bases: TypeError

catch_replace_action(obj, exc)[source]

Replaces the external component object obj with an object noting a broken object.

get_created_time(context, default=None, policy=ExternalizationPolicy(use_iso8601_for_unix_timestamp=False), _write_into=None)[source]

Find and return a number representing the time since the epoch in fractional seconds at which the context was created. This is the same value that is used by to_standard_external_dictionary(), and takes into account whether something is nti.dataserver.interfaces.ILastModified or zope.dublincore.interfaces.IDCTimes.

Returns:

A number if it can be found, or the value of default

get_last_modified_time(context, default=None, policy=ExternalizationPolicy(use_iso8601_for_unix_timestamp=False), _write_into=None)[source]

Find and return a number representing the time since the epoch in fractional seconds at which the context was last modified. This is the same value that is used by to_standard_external_dictionary(), and takes into account whether something is nti.dataserver.interfaces.ILastModified or zope.dublincore.interfaces.IDCTimes.

Returns:

A number if it can be found, or the value of default

to_external_object(obj, name=<default value>, catch_components: tuple[type[BaseException], ...] | type[BaseException] = (), catch_component_action: ~collections.abc.Callable[[~typing.Any, BaseException], ~typing.Any] | None = None, request=<default value>, decorate=True, useCache=True, decorate_callback=<default value>, default_non_externalizable_replacer=<function DefaultNonExternalizableReplacer>, policy_name=<default value>, policy=<default value>)[source]

Translates the object into a form suitable for external distribution, through some data formatting process. See SEQUENCE_TYPES and MAPPING_TYPES for details on what we can handle by default.

Parameters:

  • name (str) – The name of the adapter to IInternalObjectExternalizer to look for. Defaults to the empty string (the default adapter). If you provide a name, and an adapter is not found, we will still look for the default name (unless the name you supply is None).

  • catch_components (tuple) – A tuple of exception classes to catch when externalizing sub-objects (e.g., items in a list or dictionary). If one of these exceptions is caught, then catch_component_action will be called to raise or replace the value. The default is to catch nothing.

  • catch_component_action (callable) – If given with catch_components, a function of two arguments, the object being externalized and the exception raised. May return a different object (already externalized) or re-raise the exception. There is no default, but catch_replace_action() is a good choice.

  • default_non_externalizable_replacer (callable) – If we are asked to externalize an object and cannot, and there is no INonExternalizableReplacer registered for it, then call this object and use the results.

  • request – If given, the request that the object is being externalized on behalf of. If given, then the object decorators will also look for subscribers to the object plus the request (like traversal adapters); this is a good way to separate out request or user specific code.

  • decorate_callback – Callable to be invoked in case there is no decaration

  • policy – The ExternalizationPolicy to use. Takes priority over policy_name. If this is not given (and neither is policy_name), the thread local state is consulted for the current policy established by the most recent caller to this method; if there is no such caller, then the DEFAULT_EXTERNALIZATION_POLICY is used.

  • policy_name (str) – If no policy is given, then this is used to lookup a utility. If this is used, the utility must exist.

Changed in version 3.1.0: Remove the deprecated registry argument.

to_minimal_standard_external_dictionary(self, mergeFrom: Mapping | None = None) → LocatedExternalDict[source]

Does no decoration. Useful for non-‘object’ types. self should have a mime_type field.

to_standard_external_dictionary(self, mergeFrom=None, decorate=True, request=NotGiven)[source]

Returns a dictionary representing the standard externalization of the object self. This function takes care of many of the standard external fields:

If the object has any IExternalStandardDictionaryDecorator subscribers registered for it, they will be called to decorate the result of this method before it returns (unless decorate is set to False; only do this if you know what you are doing! ) This is the only part of nti.externalization that invokes this decorator.

Custom externalization should begin by calling this function, or, preferably, by using an existing externalizer (which invokes this function, such as StandardInternalObjectExternalizer or InterfaceObjectIO ) or subclassing such an existing type and mutating the dictionary returned from super’s toExternalObject in your own implementation.

Parameters:

  • mergeFrom (dict) – For convenience, if mergeFrom is not None, then values it contains will be added to the dictionary created by this method. The keys and values in mergeFrom should already be external.

  • policy (ExternalizationPolicy) – The ExternalizationPolicy to use. Must not be None.

Returns:

A LocatedExternalDict. For further externalization, this object should be mutated in place.

Changed in version 1.0a1: Arbitrary keyword arguments not used by this function are deprecated and produce a warning.

Changed in version 2.1: Add the policy keyword.

Changed in version 3.1.0: Remove deprecated parameters.