access.py

Go to the documentation of this file.

#!/usr/bin/env python
#
# LSST Data Management System
# Copyright 2016 LSST Corporation.
#
# This product includes software developed by the
# LSST Project (http://www.lsst.org/).
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the LSST License Statement and
# the GNU General Public License along with this program.  If not,
# see <http://www.lsstcorp.org/LegalNotices/>.
#
from builtins import object, super

from lsst.daf.persistence import Policy

import yaml


class AccessCfg(Policy, yaml.YAMLObject):
    yaml_tag = u"!AccessCfg"

    def __init__(self, cls, storageCfg):
        super().__init__({'storageCfg': storageCfg, 'cls': cls})


class Access(object):
    """Implements an butler framework interface for Transport, Storage, and Registry

    .. warning::

        Access is 'wet paint' and very likely to change. Use of it in production
        code other than via the 'old butler' API is strongly discouraged.

    """

    @classmethod
    def cfg(cls, storageCfg):
        """Helper func to create a properly formatted Policy to configure an Access instance.

        :param storageCfg: a cfg to instantiate a storage.
        :return:
        """
        return AccessCfg(cls=cls, storageCfg=storageCfg)

    def __init__(self, cfg):
        """Initializer

        :param cfg: a Policy that defines the configuration for this class. It is recommended that the cfg be
                    created by calling Access.cfg()
        :return:
        """
        self.storage = cfg['storageCfg.cls'](cfg['storageCfg'])

    def __repr__(self):
        return 'Access(storage=%s)' % self.storage

    def mapperClass(self):
        """Get the mapper class associated with a repository root.

        :return: the mapper class
        """
        return self.storage.mapperClass()

    def root(self):
        """Get the repository root as defined by the Storage class, this refers to the 'top' of a persisted
        repository. The exact type of Root can vary based on Storage type.

        :return: the root of the persisted repository.
        """

        return self.storage.root

    def locationWithRoot(self, location):
        """Given a location, get a fully qualified handle to location including storage root.

        Note; at the time of this writing the only existing storage type is PosixStorage. This returns the
        root+location.
        :param location:
        :return:
        """
        return self.storage.locationWithRoot(location)

    def setCfg(self, repoCfg):
        """Writes the repository configuration to Storage.

        :param repoCfg: the Policy cfg to be written
        :return: None
        """
        self.storage.setCfg(repoCfg)

    def loadCfg(self):
        """Reads the repository configuration from Storage.

        :return: the Policy cfg
        """
        return self.storage.loadCfg()

    def write(self, butlerLocation, obj):
        """Passes an object to Storage to be written into the repository.

        :param butlerLocation: the location & formatting for the object to be written.
        :param obj: the object to be written.
        :return: None
        """
        self.storage.write(butlerLocation, obj)

    def read(self, butlerLocation):
        """Reads an object from storage

        :param butlerLocation: describes the location & how to load the object.
        :return:
        """
        return self.storage.read(butlerLocation=butlerLocation)

    def exists(self, location):
        """Query if a location exists.

        As of this writing the only storage type is PosixStorage, and it works to say that 'location' is a
        simple locaiton descriptor. In the case of PosixStorage that's a path. If this needs to become more
        complex it could be changed to be a butlerLocation, or something else, as needed.
        :param location: a simple location descriptor, type is dependent on Storage.
        :return: True if location exists, else False.
        """
        return self.storage.exists(location)

    def lookup(self, *args, **kwargs):
        """Perform a lookup in the registry.

        Returns a list of dataId for each valid lookup (right? TODO VERIFY)"""
        return self.storage.lookup(*args, **kwargs)