Various documentation additions.
Better naming for handler subclasses.
In the data model documentation an erroneous link to the RunStart schema was corrected to a link to the EventDescriptor schema.
SingleRunDocumentRouterwas added with convenience methods for getting the start document, the descriptor document for an event document, and the stream name for an event document.
RunRouterwas changed to pass the RunStart document directly to its callbacks. To smooth the transition, any
Exceptionraised by the callbacks was squashed and a warning printed. With v1.15.0 these Exceptions are allowed to propagate. The warning is still printed.
RunRouterhands RunStart documents to its factory functions so they can decide which if any callbacks to subscribe for that run. Formerly, the
RunRouterleft it up to the factory functions to pass the RunStart document through to any callbacks the factory function returned. Now, the
RunRouterpasses the RunStart document to the callbacks directly, removing that responsibility from the factory. To smooth this transition, it does so inside a
try...exceptblock and warns if any
Exceptionis raised. This is a best effort at backward-compatibility with factories that are currently passing the RunStart document in, though it may not work in every case depending on the details of the callback. Likewise for subfactories: the callbacks that they return will be given the RunStart document and the relevant EventDescriptor document inside a
DocumentRouterconverts and routes Event and EventPage documents correctly if either one or both of the methods
event_pageis overridden in the subclass. Likewise for Datum and DatumPage and the methods
datum_page. The base class implementations all document-type methods now return the Python built-in sentinel
NotImplemented(not to be confused with the exception
This retry-with-backoff loop in
Filleris now applied to handler instantiation as well as handler calls. Either can involve I/O with a filesystem that may lag slightly behind the availability of the documents.
Filleraccepts an optional parameter
coercethat can be used to change the behavior of the handlers. This is useful for forcing the filled data to be an in-memory numpy array or a dask array, for example. The options accepted by
coercecan be configured at runtime using the new function
register_coersion(). The coersions registered by default are
NoFillerhas been added. It has the same interface as
Fillerbut it merely validates the filling-related documents rather than actually filling in the data. This is useful if the filling may be done later as a delayed computation but we want to know immediately that we have all the information we need to perform that computation.
It is sometimes convenient to make an instance of
Fillerbased on an existing instance but perhaps setting some options differently. The new method
clone()takes all the same parameters as Filler instantiation. If called with no arguments, it will make a “clone” with all the same options. Pass in arguments to override certain options.
NumpyEncoderspecial-cases dask arrays.
Several error messages have been made more specific and useful.
The code in
DocumentRouterthat dispatches based on document type has been factored out of
__call__into a new internal method,
_dispatch, which makes it easier for subclasses to modify
__call__but reuse the dispatch logic.
See the GitHub v1.13.0 milestone for a complete list of changes in this release.
RunRoutercan now “fill” documents that reference externally stored data. It accepts an optional
root_mapwhich it uses to create instances of
Fillerinternally. The default behavior of
RunRouterhas not changed because it defaults to
fill_or_fail=False, meaning that any external reference not found in
handler_registrywill be passed through unfilled. For advanced customizations—such as custom cache management—use the parameter
filler_classto specifiy an API-compatible alternative to
Filleris now a read-only view. It cannot be directly mutated. Instead, use the new methods
requirements.txtin source distribution.
UnresolveableForeignKeyErroris raised, it always includes a
keyattribute with the key in question.
Added new optional parameter
Added new methods
Consult the Event Descriptor document to infer which columns need to be filled if there is no explicit
'filled'key in the Event document.
This release requires
jsonschema>3. Previous releases required
schema_validatorsusing the new interface in jsonschema 3.0.
The counters in
num_eventsin the RunStop document were off by one.
Fix setup.py meta-data to include
python_requires. This prevents
the wheels from being installed on python < 3.6.