Internalization¶
Functions for taking externalized objects and creating application model objects.
-
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.
-
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.
-
register_legacy_search_module
(module_name)[source]¶ The legacy creation search routines will use the modules registered by this method.
Note that there are no order guarantees about how the modules will be searched. Duplicate class names are thus undefined.
Parameters: module_name – Either the name of a module to look for at runtime in sys.modules
, or a module-like object having a__dict__
.Deprecated since version 1.0: Use explicit mime or class factories instead. See https://github.com/NextThought/nti.externalization/issues/35
-
find_factory_for
(externalized_object) → factory[source]¶ Given a
IExternalizedObject
, locate and return a factory to produce a Python object to hold its contents.If there is a
IExternalizedObjectFactoryFinder
adapter registered for the externalized object, we return the results of itsfind_factory
method. Note that since externalized objects are typically simple lists or dicts, such adapters have the capability to hijack all factory finding, probably unintentionally.Otherwise, we examine the contents of the object itself to find a registered factory based on MIME type (preferably) or class name.
Changed in version 1.0a10: The
registry
argument is deprecated and ignored.
-
notify_modified
(containedObject, externalObject, updater=None, external_keys=None, **kwargs)¶ Create and send an
ObjectModifiedFromExternalEvent
for containedObject usingzope.event.notify
.The containedObject is the subject of the event. The externalObject is the dictionary of data that was used to update the containedObject.
external_keys is list of keys from externalObject that actually changed containedObject. If this is not given, we assume that all keys in externalObject were changed. Note that these should to correspond to the interface fields of interfaces that the containedObject implements in order to properly be able to create and populate the
zope.lifecycleevent
IAttributes
.updater, if given, is the
IInternalObjectUpdater
instance that was used to handle the updates. If this object implements an_ext_adjust_modified_event
method, it will be called to adjust (and return) the event object that will be notified.kwargs are the keyword arguments passed to the event constructor.
Returns: The event object that was notified.
-
validate_field_value
(self, field_name, field, value)[source]¶ Given a
zope.schema.interfaces.IField
object from a schema implemented byself
, validates that the proposed value can be set. If the value needs to be adapted to the schema type for validation to work, this method will attempt that.Parameters: - field_name (str) – The name of the field we are setting. This implementation currently only uses this for informative purposes.
- field (
zope.schema.interfaces.IField
) – The schema field to use to validate (and set) the value.
Raises: zope.interface.Invalid – If the field cannot be validated, along with a good reason (typically better than simply provided by the field itself)
Returns: A callable of no arguments to call to actually set the value (necessary in case the value had to be adapted).
-
validate_named_field_value
(self, iface, field_name, value)[source]¶ Given a
zope.interface.Interface
and the name of one of its attributes, validate that the givenvalue
is appropriate to set. Seevalidate_field_value()
for details.Parameters: field_name (str) – The name of a field contained in iface
. May name a regularzope.interface.Attribute
, or azope.schema.interfaces.IField
; if the latter, extra validation will be possible.Returns: A callable of no arguments to call to actually set the value.