Internalization

Functions for taking externalized objects and creating application model objects.

find_factory_for(externalized_object) → factory

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 its find_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.

Changed in version 3.1.0: Remove the registry argument.

new_from_external_object(external_object, *args, **kwargs)

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.

notify_modified(containedObject, externalObject, updater=None, external_keys=None, **kwargs)

Create and send an ObjectModifiedFromExternalEvent for containedObject using zope.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.

register_legacy_search_module(module_name)

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

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.

See also

INamedExternalizedObjectFactoryFinder

Changed in version 1.0.0a2: Remove the object_hook parameter.

Changed in version 1.1.3: Correctly fire IObjectWillUpdateFromExternalEvent before updating each object.

Changed in version 3.1.0: Remove the long-deprecated ‘pre_hook’ parameter. Remove the long-deprecated ‘registry’ parameter.

validate_field_value(self, field_name: str, field, value) → Callable[[], None]

Given a zope.schema.interfaces.IField object from a schema implemented by self, 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: str, value)

Given a zope.interface.Interface and the name of one of its attributes, validate that the given value is appropriate to set. See validate_field_value() for details.

Parameters:

field_name (str) – The name of a field contained in iface. May name a regular zope.interface.Attribute, or a zope.schema.interfaces.IField; if the latter, extra validation will be possible.

Returns:

A callable of no arguments to call to actually set the value.