Nti.externalization

====================

- Avoid a ``TypeError`` from ``validate_named_field_value`` when
external objects have unicode keys.

- ``LocatedExternalDict`` objects accept more constructor arguments
and allow arbitrary attributes.

====================

- ``InterfaceObjectIO`` only returns an anonymous factory for ``IDict``
fields when it wants objects for the value.

- ``StandardExternalFields`` and ``StandardInternalFields`` are
deprecated aliases in ``nti.externalization.externalization``.

- ``update_from_external_object`` properly handles the case where
``INamedExternalizedObjectFactoryFinder`` and
``IInternalObjectUpdater`` are registered with different levels of
specificity, and the finder also implements
``IInternalObjectUpdater``. Before, the finder would, perhaps
incorrectly, be used as the updater.

====================

- Objects inheriting from ``InterfaceObjectIO`` and registered with
the component registry (in ZCML) for ``IInternalObjectIO`` can still
be found and used as ``INamedExternalizedObjectFactoryFinder``, an
interface implemented by ``InterfaceObjectIO`` through
``IInternalObjectIOFinder``. A warning will be issued to update the
registration (which generally means removing the ``provides`` line
in ZCML).

- ``ExternalizableInstanceDict`` no longer inherits from
``AbstractDynamicIO``, it just implements the same interface (with
the exception of many of the ``_ext`` methods). This class is deprecated.

- Formally document the ``notify_modified`` member of
``nti.externalization.internalization``. ``notifyModified`` is a
deprecated alias.

====================

- Make ``InterfaceObjectIO._ext_self`` readable from Python, even
though that is not documented (and may change again in the future).
Document the intended API, ``_ext_replacement()``. See `issue 73
<https://github.com/NextThought/nti.externalization/issues/73>`_.

- Make ``AbstractDynamicObjectIO._ext_getattr`` handle a default
value, and add ``_ext_replacement_getattr`` for when it will only
be called once. See `issue 73
<https://github.com/NextThought/nti.externalization/issues/73>`_.

====================

- The ``NoPickle`` decorator also works with ``Persistent``
subclasses (and may or may not work with multiple-inheritance
subclasses of ``Persistent``, depending on the MRO,
but that's always been the case for regular objects). A
``Persistent`` subclass being decorated with ``NoPickle`` doesn't
make much sense, so a ``RuntimeWarning`` is issued. A warning is
also issued if the class directly implements one of the pickle
protocol methods.

- Updating objects that use ``createFieldProperties`` or otherwise
have ``FieldProperty`` objects in their type is at least 10% faster
thanks to avoiding double-validation due to a small monkey-patch on
``FieldProperty``. See `issue 67
<https://github.com/NextThought/nti.externalization/issues/67>`_.

- Proxies around objects that implement ``toExternalObject`` are
allowed again; the proxied object's ``toExternalObject`` will be called.

- The signature for ``updateFromExternalObject()`` has been tightened.
It should be ``(self, external_object, context, **kwargs)``, where
``**kwargs`` is optional, as is context. ``**kwargs`` currently
contains nothing useful. Uses of ``dataserver=None`` in the
signature will generate a warning. This may be tightened further in
the future. See `issue 30
<https://github.com/NextThought/nti.externalization/issues/30>`_.

- ``__ext_ignore_updateFromExternalObject__`` is officially
deprecated and generates a warning.

- ``update_from_external_object`` caches certain information about the
types of the updater objects, making it 8-25% faster.

- ``update_from_external_object`` mutates sequences contained in a
dict in-place instead of overwriting with a new list.

- ``update_from_external_object`` mutates sequences at the top level
instead of returning a new list.

- Add support for finding factories for incoming data which do not
specify a MIME type or class field based on the key they are
assigned to. This aids in consuming data produced by foreign systems
or using ``Dict`` schema fields that require modelled
values. See `issue 51
<https://github.com/NextThought/nti.externalization/issues/51>`_ and
`PR 68
<https://github.com/NextThought/nti.externalization/pull/68>`_.

- Schemas that use ``InterfaceObjectIO`` (including through the ZCML
directive ``registerAutoPackageIO``) can use ``Dict`` fields more
easily on internalization (externalization has always worked): They
automatically internalize their values by treating the ``Dict`` as
anonymous external data.

- Strings can automatically be adapted into ``ITimeDelta`` objects.

====================

- The low levels of externalization no longer catch and hide
POSKeyError. This indicates a problem with the database. See
https://github.com/NextThought/nti.externalization/issues/60

- Remove support for ``object_hook`` in
``update_from_external_object``. See
https://github.com/NextThought/nti.externalization/issues/29.

- A number of deprecated aliases for moved functions have been
removed.

- On CPython, some of the modules are compiled as extension modules
using Cython for a 10-30% increase in speed. Set the ``PURE_PYTHON``
environment variable to disable this at runtime.

- The unused, undocumented method
``stripSyntheticKeysFromExternalDictionary`` was removed from
instances of ``ExternalizableDictionaryMixin``. Use the import instead.

- Unused keyword arguments for ``to_standard_external_dictionary``
and ``to_minimal_standard_external_dictionary`` now produce a warning.
In the future, extra keyword arguments will be an error.

- ``notifyModified`` no longer accepts the ``eventFactory`` argument.

- The ``notify_modified`` alias for ``notifyModified`` has been removed.

- Decorating external mappings and external objects handled
``decorate_callback`` differently. This argument is only used when
``decorate`` is false. This argument is also confusing and should be
considered deprecated.

- ``choose_field`` no longer has the undocumented conversion behaviour for the
CREATOR external field name.