Basics

`nti.externalization`

The nti.externalization module has the top-level APIs.

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_external_representation(obj, ext_format='json', name=NotGiven, **repr_kwargs) → str | bytes[source]

Transforms (and returns) the obj into its external (string) representation.

Uses nti.externalization.to_external_object(), passing in the name.

Parameters:: ext_format (str) – One of EXT_REPR_JSON or EXT_REPR_YAML, or the name of some other utility that implements IExternalObjectRepresenter

The repr_kwargs are passed to the dump method of the representer.

Changed in version 3.0.0: Added repr_kwargs

Changed in version 3.1.0: Removed the deprecated ‘registry’ param

new_from_external_object(external_object, *args, **kwargs)[source]

Like update_from_external_object, but creates a new object to update using find_factory_for.

All remaining arguments are passed to update_from_external_object.

If no factory can be found, raises a zope.interface.interfaces.ComponentLookupError.

Returns the new object.

Added in version 1.0a3.

update_from_external_object(containedObject: MutableSequence, externalObject: MutableSequence, context=None, require_updater=False, notify=True) → MutableSequence[source]

update_from_external_object(containedObject: T, externalObject: MutableMapping, context=None, require_updater=False, notify=True) → T

update_from_external_object(containedObject, externalObject, context=None, require_updater=False, notify=True)

Central method for updating objects from external values.

Parameters:

containedObject – The object to update.
externalObject – The object (typically a mapping or sequence) to update the object from. Usually this is obtained by parsing an external format like JSON.
context – An object passed to the update methods.
require_updater – If True (not the default) an exception will be raised if no implementation of IInternalObjectUpdater can be found for the containedObject.
notify (bool) – If True (the default), then if the updater for the containedObject either has no preference (returns None) or indicates that the object has changed, then an IObjectModifiedFromExternalEvent will be fired. This may be a recursive process so a top-level call to this object may spawn multiple events. The events that are fired will have a descriptions list containing one or more IAttributes each with attributes for each attribute we modify (assuming that the keys in the externalObject map one-to-one to an attribute; if this is the case and we can also find an interface declaring the attribute, then the IAttributes will have the right value for interface as well).

Returns:

containedObject after updates from externalObject

Notifies IObjectModifiedFromExternalEvent for each object that is modified, and IObjectWillUpdateFromExternalEvent before doing so.

Basics

nti.externalization

`nti.externalization`