lsst.daf.persistence.policy.Policy Class Reference

Inheritance diagram for lsst.daf.persistence.policy.Policy:

Public Member Functions
def	__init__ (self, other=None)
def	ppprint (self)
def	__repr__ (self)
def	__getitem__ (self, name)
def	__setitem__ (self, name, value)
def	__contains__ (self, key)
def	update (self, other)
def	merge (self, other)
def	names (self, topLevelOnly=False)
def	asArray (self, name)
def	getValue (self, name)
def	setValue (self, name, value)
def	mergeDefaults (self, other)
def	exists (self, key)
def	getString (self, key)
def	getBool (self, key)
def	getPolicy (self, key)
def	getStringArray (self, key)
def	__lt__ (self, other)
def	__le__ (self, other)
def	__eq__ (self, other)
def	__ne__ (self, other)
def	__gt__ (self, other)
def	__ge__ (self, other)
def	dump (self, output)
	i/o # More...
def	dumpToFile (self, path)

Static Public Member Functions
def	defaultPolicyFile (productName, fileName, relativePath=None)

Public Attributes
	data

Detailed Description

Policy implements a datatype that is used by Butler for configuration parameters.
It is essentially a dict with key/value pairs, including nested dicts (as values). In fact, it can be
initialized with a dict. The only caveat is that keys may NOT contain dots ('.'). This is explained next:
Policy extends the dict api so that hierarchical values may be accessed with dot-delimited notiation.
That is, foo.getValue('a.b.c') is the same as foo['a']['b']['c'] is the same as foo['a.b.c'], and either
of these syntaxes may be used.

Storage formats supported:
- yaml: read and write is supported.
- pex policy: read is supported, although this is deprecated and will at some point be removed.

Definition at line 58 of file policy.py.

Constructor & Destructor Documentation

__init__()

def lsst.daf.persistence.policy.Policy.__init__	(		self,
			other = None
	)

Initialize the Policy. Other can be used to initialize the Policy in a variety of ways:
other (string) Treated as a path to a policy file on disk. Must end with '.paf' or '.yaml'.
other (Pex Policy) Initializes this Policy with the values in the passed-in Pex Policy.
other (Policy) Copies the other Policy's values into this one.
other (dict) Copies the values from the dict into this Policy.

Definition at line 71 of file policy.py.

    def __init__(self, other=None):
        """Initialize the Policy. Other can be used to initialize the Policy in a variety of ways:
        other (string) Treated as a path to a policy file on disk. Must end with '.paf' or '.yaml'.
        other (Pex Policy) Initializes this Policy with the values in the passed-in Pex Policy.
        other (Policy) Copies the other Policy's values into this one.
        other (dict) Copies the values from the dict into this Policy.
        """
        collections.UserDict.__init__(self)

        if other is None:
            return

        if isinstance(other, collections.abc.Mapping):
            self.update(other)
        elif isinstance(other, Policy):
            self.data = copy.deepcopy(other.data)
        elif isinstance(other, basestring):
            # if other is a string, assume it is a file path.
            self.__initFromFile(other)
        elif isinstance(other, pexPolicy.Policy):
            # if other is an instance of a Pex Policy, load it accordingly.
            self.__initFromPexPolicy(other)
        else:
            # if the policy specified by other could not be loaded raise a runtime error.
            raise RuntimeError("A Policy could not be loaded from other:%s" % other)

Member Function Documentation

__contains__()

def lsst.daf.persistence.policy.Policy.__contains__	(		self,
			key
	)

Definition at line 201 of file policy.py.

    def __contains__(self, key):
        d = self.data
        keys = key.split('.')
        for k in keys[0:-1]:
            if k in d:
                d = d[k]
            else:
                return False
        return keys[-1] in d

__eq__()

def lsst.daf.persistence.policy.Policy.__eq__	(		self,
			other
	)

Definition at line 392 of file policy.py.

    def __eq__(self, other):
        if isinstance(other, Policy):
            other = other.data
        return self.data == other

__ge__()

def lsst.daf.persistence.policy.Policy.__ge__	(		self,
			other
	)

Definition at line 407 of file policy.py.

    def __ge__(self, other):
        if isinstance(other, Policy):
            other = other.data
        return self.data >= other

__getitem__()

def lsst.daf.persistence.policy.Policy.__getitem__	(		self,
			name
	)

Definition at line 172 of file policy.py.

    def __getitem__(self, name):
        data = self.data
        for key in name.split('.'):
            if data is None:
                return None
            if key in data:
                data = data[key]
            else:
                return None
        if isinstance(data, collections.abc.Mapping):
            data = Policy(data)
        return data

__gt__()

def lsst.daf.persistence.policy.Policy.__gt__	(		self,
			other
	)

Definition at line 402 of file policy.py.

    def __gt__(self, other):
        if isinstance(other, Policy):
            other = other.data
        return self.data > other

__le__()

def lsst.daf.persistence.policy.Policy.__le__	(		self,
			other
	)

Definition at line 387 of file policy.py.

    def __le__(self, other):
        if isinstance(other, Policy):
            other = other.data
        return self.data <= other

__lt__()

def lsst.daf.persistence.policy.Policy.__lt__	(		self,
			other
	)

Definition at line 382 of file policy.py.

    def __lt__(self, other):
        if isinstance(other, Policy):
            other = other.data
        return self.data < other

__ne__()

def lsst.daf.persistence.policy.Policy.__ne__	(		self,
			other
	)

Definition at line 397 of file policy.py.

    def __ne__(self, other):
        if isinstance(other, Policy):
            other = other.data
        return self.data != other

__repr__()

def lsst.daf.persistence.policy.Policy.__repr__

(

self

)

Definition at line 106 of file policy.py.

    def __repr__(self):
        return self.data.__repr__()

__setitem__()

def lsst.daf.persistence.policy.Policy.__setitem__	(		self,
			name,
			value
	)

Definition at line 185 of file policy.py.

    def __setitem__(self, name, value):
        if isinstance(value, collections.abc.Mapping):
            keys = name.split('.')
            d = {}
            cur = d
            for key in keys[0:-1]:
                cur[key] = {}
                cur = cur[key]
            cur[keys[-1]] = value
            self.update(d)
        data = self.data
        keys = name.split('.')
        for key in keys[0:-1]:
            data = data.setdefault(key, {})
        data[keys[-1]] = value

asArray()

def lsst.daf.persistence.policy.Policy.asArray	(		self,
			name
	)

Get a value as an array. May contain one or more elements.

:param key:
:return:

Definition at line 289 of file policy.py.

    def asArray(self, name):
        """Get a value as an array. May contain one or more elements.

        :param key:
        :return:
        """
        val = self.get(name)
        if isinstance(val, basestring):
            val = [val]
        elif not isinstance(val, collections.abc.Container):
            val = [val]
        return val

defaultPolicyFile()

def lsst.daf.persistence.policy.Policy.defaultPolicyFile (   productName,   fileName,   relativePath = None  )

static

Get the path to a default policy file.

Determines a directory for the product specified by productName. Then Concatenates
productDir/relativePath/fileName (or productDir/fileName if relativePath is None) to find the path
to the default Policy file

@param productName (string) The name of the product that the default policy is installed as part of
@param fileName (string) The name of the policy file. Can also include a path to the file relative to
                 the directory where the product is installed.
@param relativePath (string) The relative path from the directior where the product is installed to
                     the location where the file (or the path to the file) is found. If None
                     (default), the fileName argument is relative to the installation
                     directory.

Definition at line 212 of file policy.py.

    def defaultPolicyFile(productName, fileName, relativePath=None):
        """Get the path to a default policy file.

        Determines a directory for the product specified by productName. Then Concatenates
        productDir/relativePath/fileName (or productDir/fileName if relativePath is None) to find the path
        to the default Policy file

        @param productName (string) The name of the product that the default policy is installed as part of
        @param fileName (string) The name of the policy file. Can also include a path to the file relative to
                                 the directory where the product is installed.
        @param relativePath (string) The relative path from the directior where the product is installed to
                                     the location where the file (or the path to the file) is found. If None
                                     (default), the fileName argument is relative to the installation
                                     directory.
        """
        basePath = lsst.utils.getPackageDir(productName)
        if not basePath:
            raise RuntimeError("No product installed for productName: %s" % basePath)
        if relativePath is not None:
            basePath = os.path.join(basePath, relativePath)
        fullFilePath = os.path.join(basePath, fileName)
        return fullFilePath

dump()

def lsst.daf.persistence.policy.Policy.dump	(		self,
			output
	)

i/o #

Writes the policy to a yaml stream.

:param stream:
:return:

Definition at line 415 of file policy.py.

    def dump(self, output):
        """Writes the policy to a yaml stream.

        :param stream:
        :return:
        """
        # First a set of known keys is handled and written to the stream in a specific order for readability.
        # After the expected/ordered keys are weritten to the stream the remainder of the keys are written to
        # the stream.
        data = copy.copy(self.data)
        keys = ['defects', 'needCalibRegistry', 'levels', 'defaultLevel', 'defaultSubLevels', 'camera',
                'exposures', 'calibrations', 'datasets']
        for key in keys:
            try:
                yaml.safe_dump({key: data.pop(key)}, output, default_flow_style=False)
                output.write('\n')
            except KeyError:
                pass
        if data:
            yaml.safe_dump(data, output, default_flow_style=False)

dumpToFile()

def lsst.daf.persistence.policy.Policy.dumpToFile	(		self,
			path
	)

Writes the policy to a file.

:param path:
:return:

Definition at line 436 of file policy.py.

    def dumpToFile(self, path):
        """Writes the policy to a file.

        :param path:
        :return:
        """
        with open(path, 'w') as f:
            self.dump(f)

exists()

def lsst.daf.persistence.policy.Policy.exists	(		self,
			key
	)

Query if a key exists in this Policy

:param key:
:return: True if the key exists, else false.

Definition at line 332 of file policy.py.

    def exists(self, key):
        """Query if a key exists in this Policy

        :param key:
        :return: True if the key exists, else false.
        """
        warnings.warn("Deprecated. Use 'key in object'", DeprecationWarning)
        return key in self

getBool()

def lsst.daf.persistence.policy.Policy.getBool	(		self,
			key
	)

Get the value of a key.

:param key:
:return: the value for key

Definition at line 350 of file policy.py.

    def getBool(self, key):
        """Get the value of a key.

        :param key:
        :return: the value for key
        """
        warnings.warn("Deprecated. Use []", DeprecationWarning)
        return bool(self[key])

getPolicy()

def lsst.daf.persistence.policy.Policy.getPolicy	(		self,
			key
	)

Get a subpolicy.

:param key:
:return:

Definition at line 359 of file policy.py.

    def getPolicy(self, key):
        """Get a subpolicy.

        :param key:
        :return:
        """
        warnings.warn("Deprecated. Use []", DeprecationWarning)
        return self[key]

getString()

def lsst.daf.persistence.policy.Policy.getString	(		self,
			key
	)

Get the string value of a key.

:param key:
:return: the value for key

Definition at line 341 of file policy.py.

    def getString(self, key):
        """Get the string value of a key.

        :param key:
        :return: the value for key
        """
        warnings.warn("Deprecated. Use []", DeprecationWarning)
        return str(self[key])

getStringArray()

def lsst.daf.persistence.policy.Policy.getStringArray	(		self,
			key
	)

Get a value as an array. May contain one or more elements.

:param key:
:return:

Definition at line 368 of file policy.py.

    def getStringArray(self, key):
        """Get a value as an array. May contain one or more elements.

        :param key:
        :return:
        """
        warnings.warn("Deprecated. Use asArray()", DeprecationWarning)
        val = self.get(key)
        if isinstance(val, basestring):
            val = [val]
        elif not isinstance(val, collections.abc.Container):
            val = [val]
        return val

getValue()

def lsst.daf.persistence.policy.Policy.getValue	(		self,
			name
	)

Get the value for a parameter name/key. See class notes about dot-delimited access.

:param name:
:return: the value for the given name.

Definition at line 305 of file policy.py.

    def getValue(self, name):
        """Get the value for a parameter name/key. See class notes about dot-delimited access.

        :param name:
        :return: the value for the given name.
        """
        warnings.warn_explicit("Deprecated. Use []", DeprecationWarning)
        return self[name]

merge()

def lsst.daf.persistence.policy.Policy.merge	(		self,
			other
	)

Like Policy.update, but will add keys & values from other that DO NOT EXIST in self. Keys and
values that already exist in self will NOT be overwritten.

:param other:
:return:

Definition at line 259 of file policy.py.

    def merge(self, other):
        """Like Policy.update, but will add keys & values from other that DO NOT EXIST in self. Keys and
        values that already exist in self will NOT be overwritten.

        :param other:
        :return:
        """
        otherCopy = copy.deepcopy(other)
        otherCopy.update(self)
        self.data = otherCopy.data

mergeDefaults()

def lsst.daf.persistence.policy.Policy.mergeDefaults	(		self,
			other
	)

For any keys in other that are not present in self, sets that key and its value into self.

:param other: another Policy
:return: None

Definition at line 323 of file policy.py.

    def mergeDefaults(self, other):
        """For any keys in other that are not present in self, sets that key and its value into self.

        :param other: another Policy
        :return: None
        """
        warnings.warn("Deprecated. Use .merge()", DeprecationWarning)
        self.merge(other)

names()

def lsst.daf.persistence.policy.Policy.names	(		self,
			topLevelOnly = False
	)

Get the dot-delimited name of all the keys in the hierarchy.
NOTE: this is different than the built-in method dict.keys, which will return only the first level
keys.

Definition at line 270 of file policy.py.

    def names(self, topLevelOnly=False):
        """Get the dot-delimited name of all the keys in the hierarchy.
        NOTE: this is different than the built-in method dict.keys, which will return only the first level
        keys.
        """
        if topLevelOnly:
            return list(self.keys())

        def getKeys(d, keys, base):
            for key in d:
                val = d[key]
                levelKey = base + '.' + key if base is not None else key
                keys.append(levelKey)
                if isinstance(val, collections.abc.Mapping):
                    getKeys(val, keys, levelKey)
        keys = []
        getKeys(self.data, keys, None)
        return keys

ppprint()

def lsst.daf.persistence.policy.Policy.ppprint

(

self

)

helper function for debugging, prints a policy out in a readable way in the debugger.

use: pdb> print myPolicyObject.pprint()
:return: a prettyprint formatted string representing the policy

Definition at line 97 of file policy.py.

    def ppprint(self):
        """helper function for debugging, prints a policy out in a readable way in the debugger.

        use: pdb> print myPolicyObject.pprint()
        :return: a prettyprint formatted string representing the policy
        """
        import pprint
        return pprint.pformat(self.data, indent=2, width=1)

setValue()

def lsst.daf.persistence.policy.Policy.setValue	(		self,
			name,
			value
	)

Set the value for a parameter name/key. See class notes about dot-delimited access.

:param name:
:return: None

Definition at line 314 of file policy.py.

    def setValue(self, name, value):
        """Set the value for a parameter name/key. See class notes about dot-delimited access.

        :param name:
        :return: None
        """
        warnings.warn("Deprecated. Use []", DeprecationWarning)
        self[name] = value

update()

def lsst.daf.persistence.policy.Policy.update	(		self,
			other
	)

Like dict.update, but will add or modify keys in nested dicts, instead of overwriting the nested
dict entirely.

For example, for the given code:
foo = {'a': {'b': 1}}
foo.update({'a': {'c': 2}})

If foo is a dict, then after the update foo == {'a': {'c': 2}}
But if foo is a Policy, then after the update foo == {'a': {'b': 1, 'c': 2}}

Definition at line 235 of file policy.py.

    def update(self, other):
        """Like dict.update, but will add or modify keys in nested dicts, instead of overwriting the nested
        dict entirely.

        For example, for the given code:
        foo = {'a': {'b': 1}}
        foo.update({'a': {'c': 2}})

        If foo is a dict, then after the update foo == {'a': {'c': 2}}
        But if foo is a Policy, then after the update foo == {'a': {'b': 1, 'c': 2}}
        """
        def doUpdate(d, u):
            for k, v in u.items():
                if isinstance(d, collections.abc.Mapping):
                    if isinstance(v, collections.abc.Mapping):
                        r = doUpdate(d.get(k, {}), v)
                        d[k] = r
                    else:
                        d[k] = u[k]
                else:
                    d = {k: u[k]}
            return d
        doUpdate(self.data, other)

Member Data Documentation

data

lsst.daf.persistence.policy.Policy.data

Definition at line 86 of file policy.py.

---

The documentation for this class was generated from the following file:

• /j/snowflake/release/lsstsw/stack/Linux64/daf_persistence/17.0.1-1-gfc6fb1f+20/python/lsst/daf/persistence/policy.py

---

Generated on Sat Jun 8 2019 08:10:02 for LSSTApplications by   1.8.13