Upgrading from WebCore 2

The fundamental architecture has not changed substantially between the two major versions, unlike between version one and two. The reason for the major version bump is in response to a substantial change in Python namespace package packaging that is incompatible with the Python 2 mechanism.

Modern Namespaces

Marrow projects utilize namespace packages extensively, to allow multiple independently installable projects to populate the same import tree. This helps prevent name collisions with other projects in a similar way to Microsoft needing to call the product "Microsoft Word", not just Word.

We've migrated from pkg_resources-style namespace packages ("magic" __init__.py files, registration in setup.py metadata) to native namespace packages (namespaces are directories without an __init__.py, declare actual packages in metadata, not namespaces). These approaches are not compatible; installing two contributors to a namespace each contributing via a different mechanism will have unpredictable results, guaranteed to be negative. However! The earlier style had some difficulty with in-development mixtures of "installed in-place" (pip install -e) and packaged installs not merging the spaces properly, which were points of frustration for new users.

Due to the compatibility issue, please do not forget to pin version numbers in your own project's dependencies! For this version, pin WebCore~=3.0.0.

Extension API Interface Method Name Changes

• mutate → collect

  The mutate callback offered to extensions has been re-named collect to better describe the use that point of extension is put to. The initial idea was to offer a way to "mutate" the incoming arguments before endpoint invocation, however the implementations using this predominantly implement query string, form-encoded POST body, and JSON body value extraction.

Dispatch Protocol Enhancements

The dispatch protocol has been enhanced to support discovery of available endpoints through live introspection.

To be elaborated upon.