Basics¶
nti.externalization
¶
The nti.externalization
module has the top-level APIs.
-
to_external_object
(obj, name=<default value>, registry=<default value>, catch_components=(), catch_component_action=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
andMAPPING_TYPES
for details on what we can handle by default.Parameters: - name (string) – 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 theDEFAULT_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.
- name (string) – The name of the adapter to
-
to_external_representation
(obj, ext_format='json', name=NotGiven) → str[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
orEXT_REPR_YAML
, or the name of some other utility that implementsIExternalObjectRepresenter
-
new_from_external_object
(external_object, *args, **kwargs)[source]¶ Like
update_from_external_object
, but creates a new object to update usingfind_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.
New in version 1.0a3.
-
update_from_external_object
(containedObject, externalObject, context=None, require_updater=False, notify=True)[source]¶ 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 anIObjectModifiedFromExternalEvent
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 adescriptions
list containing one or moreIAttributes
each withattributes
for each attribute we modify (assuming that the keys in theexternalObject
map one-to-one to an attribute; if this is the case and we can also find an interface declaring the attribute, then theIAttributes
will have the right value forinterface
as well). - pre_hook (callable) – If given, called with the before
update_from_external_object is called for every nested object.
Signature
f(k,x)
wherek
is either the key name, or None in the case of a sequence andx
is the external object. Deprecated.
Returns: containedObject after updates from externalObject
Notifies
IObjectModifiedFromExternalEvent
for each object that is modified, andIObjectWillUpdateFromExternalEvent
before doing so.See also
INamedExternalizedObjectFactoryFinder
Changed in version 1.0.0a2: Remove the
object_hook
parameter.Changed in version 1.1.3: Correctly file
IObjectWillUpdateFromExternalEvent
before updating each object.