Coverage for python/lsst/daf/butler/core/storageClass.py : 96%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# This file is part of daf_butler. # # Developed for the LSST Data Management System. # This product includes software developed by the LSST Project # (http://www.lsst.org). # See the COPYRIGHT file at the top-level directory of this distribution # for details of code ownership. # # 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 GNU General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>.
"""Class describing how a label maps to a particular Python type.
Parameters ---------- name : `str` Name to use for this class. pytype : `type` Python type (or name of type) to associate with the `StorageClass` components : `dict`, optional `dict` mapping name of a component to another `StorageClass`. parameters : `~collections.abc.Sequence` or `~collections.abc.Set` Parameters understood by this `StorageClass`. assembler : `str`, optional Fully qualified name of class supporting assembly and disassembly of a `pytype` instance. """
# if the assembler is not None also set it and clear the default # assembler # We set a default assembler for composites so that a class is # guaranteed to support something if it is a composite. else: # The types are created on demand and cached
def components(self): """Component names mapped to associated `StorageClass` """
def parameters(self): """`set` of names of parameters supported by this `StorageClass` """
def pytype(self): """Python type associated with this `StorageClass`.""" # Handle case where we did get a python type not string else:
def assemblerClass(self): """Class to use to (dis)assemble an object from components."""
"""Return an instance of an assembler.
Returns ------- assembler : `CompositeAssembler` Instance of the assembler associated with this `StorageClass`. Assembler is constructed with this `StorageClass`.
Raises ------ TypeError This StorageClass has no associated assembler. """
"""Boolean indicating whether this `StorageClass` is a composite or not.
Returns ------- isComposite : `bool` `True` if this `StorageClass` is a composite, `False` otherwise. """
"""Names to use when looking up this DatasetRef in a configuration.
The names are returned in order of priority.
Returns ------- names : `tuple` of `str` Tuple of solely the `StorageClass` name. """
"""Return set of all parameters known to this `StorageClass`
The set includes parameters understood by components of a composite.
Returns ------- known : `set` All parameter keys of this `StorageClass` and the component storage classes. """
"""Check that the parameters are known to this `StorageClass`
Does not check the values.
Parameters ---------- parameters : `~collections.abc.Collection`, optional Collection containing the parameters. Can be `dict`-like or `set`-like. The parameter values are not checked. If no parameters are supplied, always returns without error.
Raises ------ KeyError Some parameters are not understood by this `StorageClass`. """ # No parameters is always okay
# Extract the important information into a set. Works for dict and # list.
"""Filter out parameters that are not known to this StorageClass
Parameters ---------- parameters : `dict`, optional Candidate parameters. Can be `None` if no parameters have been provided. subset : `~collections.abc.Collection`, optional Subset of supported parameters that the caller is interested in using. The subset must be known to the `StorageClass` if specified.
Returns ------- filtered : `dict` Valid parameters. Empty `dict` if none are suitable. """ raise ValueError(f"Requested subset ({subset}) is not a subset of" f" known parameters ({known})")
"""Check that the supplied Python object has the expected Python type
Parameters ---------- instance : `object` Object to check.
Returns ------- isOk : `bool` True if the supplied instance object can be handled by this `StorageClass`, False otherwise. """
"""Equality checks name, pytype name, assembler name, and components"""
return False
# We must compare pytype and assembler by name since we do not want # to trigger an import of external module code here
# Ensure we have the same component keys in each
# Same parameters
# Ensure that all the components have the same type
# If we got to this point everything checks out
" parameters={})".format(type(self).__qualname__, self.name, self._pytypeName, self._assemblerClassName, list(self.components.keys()), self._parameters)
"""Factory for `StorageClass` instances.
This class is a singleton, with each instance sharing the pool of StorageClasses. Since code can not know whether it is the first time the instance has been created, the constructor takes no arguments. To populate the factory with storage classes, a call to `~StorageClassFactory.addFromConfig()` should be made.
Parameters ---------- config : `StorageClassConfig` or `str`, optional Load configuration. In a ButlerConfig` the relevant configuration is located in the ``storageClasses`` section. """
self.addFromConfig(config)
"""Indicates whether the storage class exists in the factory.
Parameters ---------- storageClassOrName : `str` or `StorageClass` If `str` is given existence of the named StorageClass in the factory is checked. If `StorageClass` is given existence and equality are checked.
Returns ------- in : `bool` True if the supplied string is present, or if the supplied `StorageClass` is present and identical.
Notes ----- The two different checks (one for "key" and one for "value") based on the type of the given argument mean that it is possible for StorageClass.name to be in the factory but StorageClass to not be in the factory. """
"""Add more `StorageClass` definitions from a config file.
Parameters ---------- config : `StorageClassConfig`, `Config` or `str` Storage class configuration. Can contain a ``storageClasses`` key if part of a global configuration. """
# Since we can not assume that we will get definitions of # components or parents before their classes are defined # we have a helper function that we can call recursively # to extract definitions from the configuration. # Maybe we've already processed this through recursion return
# Always create the storage class so we can ensure that # we are not trying to overwrite with a different definition processStorageClass(ctype, sconfig)
# Extract scalar items from dict that are needed for StorageClass Constructor
# Fill in other items
# Create the new storage class and register it processStorageClass(baseName, sconfig)
"""Create a new Python class as a subclass of `StorageClass`.
Parameters ---------- name : `str` Name to use for this class. baseClass : `type`, optional Base class for this `StorageClass`. Must be either `StorageClass` or a subclass of `StorageClass`. If `None`, `StorageClass` will be used.
Returns ------- newtype : `type` subclass of `StorageClass` Newly created Python type. """
# convert the arguments to use different internal names
# Some container items need to merge with the base class values # so that a child can inherit but override one bit. # lists (which you get from configs) are treated as sets for this to # work consistently. else:
# If we have parameters they should be a frozen set so that the # parameters in the class can not be modified.
"""Get a StorageClass instance associated with the supplied name.
Parameters ---------- storageClassName : `str` Name of the storage class to retrieve.
Returns ------- instance : `StorageClass` Instance of the correct `StorageClass`.
Raises ------ KeyError The requested storage class name is not registered. """
"""Store the `StorageClass` in the factory.
Will be indexed by `StorageClass.name` and will return instances of the supplied `StorageClass`.
Parameters ---------- storageClass : `StorageClass` Type of the Python `StorageClass` to register.
Raises ------ ValueError If a storage class has already been registered with storageClassName and the previous definition differs. """ f"differs from current definition ({existing})") else:
"""Remove the named StorageClass from the factory.
Parameters ---------- storageClassName : `str` Name of storage class to remove.
Raises ------ KeyError The named storage class is not registered.
Notes ----- This method is intended to simplify testing of StorageClassFactory functionality and it is not expected to be required for normal usage. """ |