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 format supported:
- yaml: read and write is supported.

Definition at line 48 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 '.yaml'.
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 60 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 '.yaml'.
        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, str):
            # if other is a string, assume it is a file path.
            self.__initFromFile(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 161 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 352 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 367 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 132 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 362 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 347 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 342 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 357 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 91 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 145 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 249 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, str):
            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 172 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 375 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 396 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 292 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 310 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 319 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 301 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 328 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, str):
            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 265 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 219 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 283 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 230 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 82 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 274 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 195 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 74 of file policy.py.

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/daf_persistence/22.0.1-4-g243d05b+871c1b8305/python/lsst/daf/persistence/policy.py