lsst.daf.persistence.butler.Butler Class Reference

Inheritance diagram for lsst.daf.persistence.butler.Butler:

Public Member Functions
def	__init__
def	getKeys
def	queryMetadata
def	datasetExists
def	get
def	put
def	subset
def	dataRef
def	__reduce__

Static Public Member Functions
def	getMapperClass

Public Attributes
	mapper
	persistence
	log

Private Member Functions
def	_combineDicts
def	_read

Detailed Description

Butler provides a generic mechanism for persisting and retrieving data using mappers.

A Butler manages a collection of datasets known as a repository.  Each
dataset has a type representing its intended usage and a location.  Note
that the dataset type is not the same as the C++ or Python type of the
object containing the data.  For example, an ExposureF object might be
used to hold the data for a raw image, a post-ISR image, a calibrated
science image, or a difference image.  These would all be different
dataset types.

A Butler can produce a collection of possible values for a key (or tuples
of values for multiple keys) if given a partial data identifier.  It can
check for the existence of a file containing a dataset given its type and
data identifier.  The Butler can then retrieve the dataset.  Similarly, it
can persist an object to an appropriate location when given its associated
data identifier.

Note that the Butler has two more advanced features when retrieving a data
set.  First, the retrieval is lazy.  Input does not occur until the data
set is actually accessed.  This allows datasets to be retrieved and
placed on a clipboard prospectively with little cost, even if the
algorithm of a stage ends up not using them.  Second, the Butler will call
a standardization hook upon retrieval of the dataset.  This function,
contained in the input mapper object, must perform any necessary
manipulations to force the retrieved object to conform to standards,
including translating metadata.

Public methods:

__init__(self, root, mapper=None, **mapperArgs)

getKeys(self, datasetType=None, level=None)

queryMetadata(self, datasetType, keys, format=None, dataId={}, **rest)

datasetExists(self, datasetType, dataId={}, **rest)

get(self, datasetType, dataId={}, immediate=False, **rest)

put(self, obj, datasetType, dataId={}, **rest)

subset(self, datasetType, level=None, dataId={}, **rest))

Definition at line 38 of file butler.py.

Constructor & Destructor Documentation

def lsst.daf.persistence.butler.Butler.__init__	(		self,
			root,
			mapper = None,
			mapperArgs
	)

Construct the Butler.  If no mapper class is provided, then a file
named "_mapper" is expected to be found in the repository, which
must be a filesystem path.  The first line in that file is read and
must contain the fully-qualified name of a Mapper subclass, which is
then imported and instantiated using the root and the mapperArgs.

@param root (str)       the repository to be managed (at least
                initially).  May be None if a mapper is
                provided.
@param mapper (Mapper)  if present, the Mapper subclass instance
                to be used as the butler's mapper.
@param **mapperArgs     arguments to be passed to the mapper's
                __init__ method, in addition to the root.

Definition at line 112 of file butler.py.

    def __init__(self, root, mapper=None, **mapperArgs):
        """Construct the Butler.  If no mapper class is provided, then a file
        named "_mapper" is expected to be found in the repository, which
        must be a filesystem path.  The first line in that file is read and
        must contain the fully-qualified name of a Mapper subclass, which is
        then imported and instantiated using the root and the mapperArgs.

        @param root (str)       the repository to be managed (at least
                                initially).  May be None if a mapper is
                                provided.
        @param mapper (Mapper)  if present, the Mapper subclass instance
                                to be used as the butler's mapper.
        @param **mapperArgs     arguments to be passed to the mapper's
                                __init__ method, in addition to the root."""

        if mapper is not None:
            self.mapper = mapper
        else:
            cls = Butler.getMapperClass(root)
            self.mapper = cls(root=root, **mapperArgs)

        # Always use an empty Persistence policy until we can get rid of it
        persistencePolicy = pexPolicy.Policy()
        self.persistence = Persistence.getPersistence(persistencePolicy)
        self.log = pexLog.Log(pexLog.Log.getDefaultLog(),
                "daf.persistence.butler")