README

Bypassing Input
===============

In certain cases, it may be useful to skip using the butler's reading
machinery.  This should not be the case for PafStorage, PickleStorage,
ConfigStorage, FitsCatalogStorage, or any dataset type known to the Persistence
Framework (i.e. with a Formatter).  But other datasets, particularly ones that
are stored in FITS tables but are not LSST afw Source Tables (which use
FitsCatalogStorage) or ones that are derivatives of other dataset types (like
metadata headers extracted from a file or subimages from an image), may need
this capability.  It is also appropriate for "datasets" with no actual data
that can be computed solely on the basis of the data ids.

Add a `bypass_{dataset type}(self, datasetType, pythonType, location, dataId)`
method to the mapper subclass.  The `datasetType` argument is redundant but
preserved for compatibility.  The `pythonType` argument comes from the mapper;
it has already been imported.  The `location` argument is a `ButlerLocation`
object; substitution of fields using the `daf_persistence` `LogicalLocation`
facilities (which should rarely be necessary) has not been done yet, but all
other mapping and data id substitutions have been performed.  Typically, the
pathname of the first location in the list contained in the `ButlerLocation` is
what is needed: `location.getLocations()[0]`

The `bypass_{dataset type}` method must return the actual object (usually of
the specified `pythonType`) after retrieval.  This may still be proxied by
the butler.

Any standardization specified by `std_{dataset type}` methods is still
performed on the object returned by the bypass method.