lsst.daf.persistence  16.0-3-g3806c63+7
butler.py
Go to the documentation of this file.
1 #!/usr/bin/env python
2 
3 #
4 # LSST Data Management System
5 # Copyright 2008-2015 LSST Corporation.
6 #
7 # This product includes software developed by the
8 # LSST Project (http://www.lsst.org/).
9 #
10 # This program is free software: you can redistribute it and/or modify
11 # it under the terms of the GNU General Public License as published by
12 # the Free Software Foundation, either version 3 of the License, or
13 # (at your option) any later version.
14 #
15 # This program is distributed in the hope that it will be useful,
16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 # GNU General Public License for more details.
19 #
20 # You should have received a copy of the LSST License Statement and
21 # the GNU General Public License along with this program. If not,
22 # see <http://www.lsstcorp.org/LegalNotices/>.
23 #
24 
25 # -*- python -*-
26 
27 """This module defines the Butler class."""
28 from builtins import str, super
29 from past.builtins import basestring
30 from builtins import object
31 
32 import copy
33 import inspect
34 
35 import yaml
36 
37 from lsst.log import Log
38 import lsst.pex.policy as pexPolicy
39 from . import ReadProxy, ButlerSubset, ButlerDataRef, Persistence, \
40  Storage, Policy, NoResults, Repository, DataId, RepositoryCfg, \
41  RepositoryArgs, listify, setify, sequencify, doImport, ButlerComposite, genericAssembler, \
42  genericDisassembler, PosixStorage, ParentsMismatch
43 
44 preinitedMapperWarning = ("Passing an instantiated mapper into " +
45  "Butler.__init__ will prevent Butler from passing " +
46  "parentRegistry or repositoryCfg information to " +
47  "the mapper, which is done only at init time. " +
48  "It is better to pass a importable string or " +
49  "class object.")
50 
51 
52 class ButlerCfg(Policy, yaml.YAMLObject):
53  """Represents a Butler configuration.
54 
55  .. warning::
56 
57  cfg is 'wet paint' and very likely to change. Use of it in production
58  code other than via the 'old butler' API is strongly discouraged.
59  """
60  yaml_tag = u"!ButlerCfg"
61 
62  def __init__(self, cls, repoCfg):
63  super().__init__({'repoCfg': repoCfg, 'cls': cls})
64 
65 
66 class RepoData(object):
67  """Container object for repository data used by Butler
68 
69  Parameters
70  ----------
71  args : RepositoryArgs
72  The arguments that are used to find or create the RepositoryCfg.
73  role : string
74  "input", "output", or "parent", indicating why Butler loaded this repository.
75  * input: the Repository was passed as a Butler input.
76  * output: the Repository was passed as a Butler output.
77  * parent: the Repository was specified in the RepositoryCfg parents list of a readable repository.
78 
79  Attributes
80  ----------
81  cfg: RepositoryCfg
82  The configuration for the Repository.
83 
84  _cfgOrigin : string
85  "new", "existing", or "nested". Indicates the origin of the repository and its RepositoryCfg:
86  * new: it was created by this instance of Butler, and this instance of Butler will generate the
87  RepositoryCfg file.
88  * existing: it was found (via the root or cfgRoot argument)
89  * nested: the full RepositoryCfg was nested in another RepositoryCfg's parents list (this can happen
90  if parameters of an input specified by RepositoryArgs or dict does not entirely match an existing
91  RepositoryCfg).
92 
93  cfgRoot : string
94  Path or URI to the location of the RepositoryCfg file.
95 
96  repo : lsst.daf.persistence.Repository
97  The Repository class instance.
98 
99  parentRepoDatas : list of RepoData
100  The parents of this Repository, as indicated this Repository's RepositoryCfg. If this is a new
101  Repository then these are the inputs to this Butler (and will be saved in the RepositoryCfg). These
102  RepoData objects are not owned by this RepoData, these are references to peer RepoData objects in the
103  Butler's RepoDataContainer.
104 
105  isV1Repository : bool
106  True if this is an Old Butler repository. In this case the repository does not have a RepositoryCfg
107  file. It may have a _mapper file and may have a _parent symlink. It will never be treated as a "new"
108  repository, i.e. even though there is not a RepositoryCfg file, one will not be generated.
109  If False, this is a New Butler repository and is specified by RepositoryCfg file.
110 
111  tags : set
112  These are values that may be used to restrict the search of input repositories. Details are available
113  in the RepositoryArgs and DataId classes.
114 
115  role : string
116  "input", "output", or "parent", indicating why Butler loaded this repository.
117  * input: the Repository was passed as a Butler input.
118  * output: the Repository was passed as a Butler output.
119  * parent: the Repository was specified in the RepositoryCfg parents list of a readable repository.
120 
121  _repoArgs : RepositoryArgs
122  Contains the arguments that were used to specify this Repository.
123  """
124 
125  def __init__(self, args, role):
126  self.cfg = None
127  self._cfgOrigin = None
128  self.cfgRoot = None
129  self.repo = None
130  self.parentRepoDatas = []
131  self.isV1Repository = False
132  self.tags = set()
133  self.role = role
134  self.parentRegistry = None
135  self._repoArgs = args
136 
137  @property
138  def repoArgs(self):
139  return self._repoArgs
140 
141  @property
142  def repoData(self):
143  return self
144 
145  def __repr__(self):
146  return ("{}(id={},"
147  "repoArgs={}"
148  "cfg={!r},"
149  "cfgOrigin={},"
150  "cfgRoot={}," +
151  "repo={},"
152  "parentRepoDatas={}," +
153  "isV1Repository={},"
154  "role={}," +
155  "parentRegistry={})").format(
156  self.__class__.__name__,
157  id(self),
158  self.repoArgs,
159  self.cfg,
160  self.cfgOrigin,
161  self.cfgRoot,
162  self.repo,
163  [id(p) for p in self.parentRepoDatas],
164  self.isV1Repository,
165  self.role,
166  self.parentRegistry)
167 
168  def setCfg(self, cfg, origin, root, isV1Repository):
169  """Set information about the cfg into the RepoData
170 
171  Parameters
172  ----------
173  cfg : RepositoryCfg
174  The RepositoryCfg for the repo.
175  origin : string
176  'new', 'existing', or 'nested'
177  root : string
178  URI or absolute path to the location of the RepositoryCfg.yaml file.
179 
180  Returns
181  -------
182  None
183  """
184  if origin not in ('new', 'existing', 'nested'):
185  raise RuntimeError("Invalid value for origin:{}".format(origin))
186  self.cfg = cfg
187  self._cfgOrigin = origin
188  self.cfgRoot = root
189  self.isV1Repository = isV1Repository
190 
191  @property
192  def cfgOrigin(self):
193  return self._cfgOrigin
194 
195  @property
196  def isNewRepository(self):
197  return self.cfgOrigin == 'new'
198 
199  @property
200  def role(self):
201  return self._role
202 
203  @role.setter
204  def role(self, val):
205  if val not in ('input', 'output', 'parent'):
206  raise RuntimeError("Invalid value for role: {}".format(val))
207  self._role = val
208 
209  def getParentRepoDatas(self, context=None):
210  """Get the parents & grandparents etc of this repo data, in depth-first search order.
211 
212  Duplicate entries will be removed in cases where the same parent appears more than once in the parent
213  graph.
214 
215  Parameters
216  ----------
217  context : set, optional
218  Users should typically omit context and accept the default argument. Context is used to keep a set
219  of known RepoDatas when calling this function recursively, for duplicate elimination.
220 
221  Returns
222  -------
223  list of RepoData
224  A list of the parents & grandparents etc of a given repo data, in depth-first search order.
225  """
226  if context is None:
227  context = set()
228  parents = []
229  if id(self) in context:
230  return parents
231  context.add(id(self))
232  for parent in self.parentRepoDatas:
233  parents.append(parent)
234  parents += parent.getParentRepoDatas(context)
235  return parents
236 
237  def addParentRepoData(self, parentRepoData):
238  self.parentRepoDatas.append(parentRepoData)
239 
240  def addTags(self, tags):
241  self.tags = self.tags.union(tags)
242 
243 
244 class RepoDataContainer(object):
245  """Container object for RepoData instances owned by a Butler instance.
246 
247  Parameters
248  ----------
249  repoDataList : list of RepoData
250  repoData - RepoData instance to add
251  """
252 
253  def __init__(self, repoDataList):
254  self._inputs = None
255  self._outputs = None
256  self._all = repoDataList
257  self._buildLookupLists()
258 
259  def inputs(self):
260  """Get a list of RepoData that are used to as inputs to the Butler.
261  The list is created lazily as needed, and cached.
262 
263  Returns
264  -------
265  A list of RepoData with readable repositories, in the order to be used when searching.
266  """
267  if self._inputs is None:
268  raise RuntimeError("Inputs not yet initialized.")
269  return self._inputs
270 
271  def outputs(self):
272  """Get a list of RepoData that are used to as outputs to the Butler.
273  The list is created lazily as needed, and cached.
274 
275  Returns
276  -------
277  A list of RepoData with writable repositories, in the order to be use when searching.
278  """
279  if self._outputs is None:
280  raise RuntimeError("Outputs not yet initialized.")
281  return self._outputs
282 
283  def all(self):
284  """Get a list of all RepoData that are used to as by the Butler.
285  The list is created lazily as needed, and cached.
286 
287  Returns
288  -------
289  A list of RepoData with writable repositories, in the order to be use when searching.
290  """
291  return self._all
292 
293  def __repr__(self):
294  return "%s(_inputs=%r, \n_outputs=%s, \n_all=%s)" % (
295  self.__class__.__name__,
296  self._inputs,
297  self._outputs,
298  self._all)
299 
300  def _buildLookupLists(self):
301  """Build the inputs and outputs lists based on the order of self.all()."""
302 
303  def addToList(repoData, lst):
304  """Add a repoData and each of its parents (depth first) to a list"""
305  if id(repoData) in alreadyAdded:
306  return
307  lst.append(repoData)
308  alreadyAdded.add(id(repoData))
309  for parent in repoData.parentRepoDatas:
310  addToList(parent, lst)
311 
312  if self._inputs is not None or self._outputs is not None:
313  raise RuntimeError("Lookup lists are already built.")
314  inputs = [repoData for repoData in self.all() if repoData.role == 'input']
315  outputs = [repoData for repoData in self.all() if repoData.role == 'output']
316  self._inputs = []
317  alreadyAdded = set()
318  for repoData in outputs:
319  if 'r' in repoData.repoArgs.mode:
320  addToList(repoData.repoData, self._inputs)
321  for repoData in inputs:
322  addToList(repoData.repoData, self._inputs)
323  self._outputs = [repoData.repoData for repoData in outputs]
324 
325 
326 class Butler(object):
327  """Butler provides a generic mechanism for persisting and retrieving data using mappers.
328 
329  A Butler manages a collection of datasets known as a repository. Each dataset has a type representing its
330  intended usage and a location. Note that the dataset type is not the same as the C++ or Python type of the
331  object containing the data. For example, an ExposureF object might be used to hold the data for a raw
332  image, a post-ISR image, a calibrated science image, or a difference image. These would all be different
333  dataset types.
334 
335  A Butler can produce a collection of possible values for a key (or tuples of values for multiple keys) if
336  given a partial data identifier. It can check for the existence of a file containing a dataset given its
337  type and data identifier. The Butler can then retrieve the dataset. Similarly, it can persist an object to
338  an appropriate location when given its associated data identifier.
339 
340  Note that the Butler has two more advanced features when retrieving a data set. First, the retrieval is
341  lazy. Input does not occur until the data set is actually accessed. This allows datasets to be retrieved
342  and placed on a clipboard prospectively with little cost, even if the algorithm of a stage ends up not
343  using them. Second, the Butler will call a standardization hook upon retrieval of the dataset. This
344  function, contained in the input mapper object, must perform any necessary manipulations to force the
345  retrieved object to conform to standards, including translating metadata.
346 
347  Public methods:
348 
349  __init__(self, root, mapper=None, **mapperArgs)
350 
351  defineAlias(self, alias, datasetType)
352 
353  getKeys(self, datasetType=None, level=None)
354 
355  queryMetadata(self, datasetType, format=None, dataId={}, **rest)
356 
357  datasetExists(self, datasetType, dataId={}, **rest)
358 
359  get(self, datasetType, dataId={}, immediate=False, **rest)
360 
361  put(self, obj, datasetType, dataId={}, **rest)
362 
363  subset(self, datasetType, level=None, dataId={}, **rest)
364 
365  dataRef(self, datasetType, level=None, dataId={}, **rest)
366 
367  Initialization:
368 
369  The preferred method of initialization is to use the `inputs` and `outputs` __init__ parameters. These
370  are described in the parameters section, below.
371 
372  For backward compatibility: this initialization method signature can take a posix root path, and
373  optionally a mapper class instance or class type that will be instantiated using the mapperArgs input
374  argument. However, for this to work in a backward compatible way it creates a single repository that is
375  used as both an input and an output repository. This is NOT preferred, and will likely break any
376  provenance system we have in place.
377 
378  Parameters
379  ----------
380  root : string
381  .. note:: Deprecated in 12_0
382  `root` will be removed in TBD, it is replaced by `inputs` and `outputs` for
383  multiple-repository support.
384  A file system path. Will only work with a PosixRepository.
385  mapper : string or instance
386  .. note:: Deprecated in 12_0
387  `mapper` will be removed in TBD, it is replaced by `inputs` and `outputs` for
388  multiple-repository support.
389  Provides a mapper to be used with Butler.
390  mapperArgs : dict
391  .. note:: Deprecated in 12_0
392  `mapperArgs` will be removed in TBD, it is replaced by `inputs` and `outputs` for
393  multiple-repository support.
394  Provides arguments to be passed to the mapper if the mapper input argument is a class type to be
395  instantiated by Butler.
396  inputs : RepositoryArgs, dict, or string
397  Can be a single item or a list. Provides arguments to load an existing repository (or repositories).
398  String is assumed to be a URI and is used as the cfgRoot (URI to the location of the cfg file). (Local
399  file system URI does not have to start with 'file://' and in this way can be a relative path). The
400  `RepositoryArgs` class can be used to provide more parameters with which to initialize a repository
401  (such as `mapper`, `mapperArgs`, `tags`, etc. See the `RepositoryArgs` documentation for more
402  details). A dict may be used as shorthand for a `RepositoryArgs` class instance. The dict keys must
403  match parameters to the `RepositoryArgs.__init__` function.
404  outputs : RepositoryArgs, dict, or string
405  Provides arguments to load one or more existing repositories or create new ones. The different types
406  are handled the same as for `inputs`.
407 
408  The Butler init sequence loads all of the input and output repositories.
409  This creates the object hierarchy to read from and write to them. Each
410  repository can have 0 or more parents, which also get loaded as inputs.
411  This becomes a DAG of repositories. Ultimately, Butler creates a list of
412  these Repositories in the order that they are used.
413 
414  Initialization Sequence
415  =======================
416 
417  During initialization Butler creates a Repository class instance & support structure for each object
418  passed to `inputs` and `outputs` as well as the parent repositories recorded in the `RepositoryCfg` of
419  each existing readable repository.
420 
421  This process is complex. It is explained below to shed some light on the intent of each step.
422 
423  1. Input Argument Standardization
424  ---------------------------------
425 
426  In `Butler._processInputArguments` the input arguments are verified to be legal (and a RuntimeError is
427  raised if not), and they are converted into an expected format that is used for the rest of the Butler
428  init sequence. See the docstring for `_processInputArguments`.
429 
430  2. Create RepoData Objects
431  --------------------------
432 
433  Butler uses an object, called `RepoData`, to keep track of information about each repository; each
434  repository is contained in a single `RepoData`. The attributes are explained in its docstring.
435 
436  After `_processInputArguments`, a RepoData is instantiated and put in a list for each repository in
437  `outputs` and `inputs`. This list of RepoData, the `repoDataList`, now represents all the output and input
438  repositories (but not parent repositories) that this Butler instance will use.
439 
440  3. Get `RepositoryCfg`s
441  -----------------------
442 
443  `Butler._getCfgs` gets the `RepositoryCfg` for each repository the `repoDataList`. The behavior is
444  described in the docstring.
445 
446  4. Add Parents
447  --------------
448 
449  `Butler._addParents` then considers the parents list in the `RepositoryCfg` of each `RepoData` in the
450  `repoDataList` and inserts new `RepoData` objects for each parent not represented in the proper location
451  in the `repoDataList`. Ultimately a flat list is built to represent the DAG of readable repositories
452  represented in depth-first order.
453 
454  5. Set and Verify Parents of Outputs
455  ------------------------------------
456 
457  To be able to load parent repositories when output repositories are used as inputs, the input repositories
458  are recorded as parents in the `RepositoryCfg` file of new output repositories. When an output repository
459  already exists, for consistency the Butler's inputs must match the list of parents specified the already-
460  existing output repository's `RepositoryCfg` file.
461 
462  In `Butler._setAndVerifyParentsLists`, the list of parents is recorded in the `RepositoryCfg` of new
463  repositories. For existing repositories the list of parents is compared with the `RepositoryCfg`'s parents
464  list, and if they do not match a `RuntimeError` is raised.
465 
466  6. Set the Default Mapper
467  -------------------------
468 
469  If all the input repositories use the same mapper then we can assume that mapper to be the
470  "default mapper". If there are new output repositories whose `RepositoryArgs` do not specify a mapper and
471  there is a default mapper then the new output repository will be set to use that default mapper.
472 
473  This is handled in `Butler._setDefaultMapper`.
474 
475  7. Cache References to Parent RepoDatas
476  ---------------------------------------
477 
478  In `Butler._connectParentRepoDatas`, in each `RepoData` in `repoDataList`, a list of `RepoData` object
479  references is built that matches the parents specified in that `RepoData`'s `RepositoryCfg`.
480 
481  This list is used later to find things in that repository's parents, without considering peer repository's
482  parents. (e.g. finding the registry of a parent)
483 
484  8. Set Tags
485  -----------
486 
487  Tags are described at https://ldm-463.lsst.io/v/draft/#tagging
488 
489  In `Butler._setRepoDataTags`, for each `RepoData`, the tags specified by its `RepositoryArgs` are recorded
490  in a set, and added to the tags set in each of its parents, for ease of lookup when mapping.
491 
492  9. Find Parent Registry and Instantiate RepoData
493  ------------------------------------------------
494 
495  At this point there is enough information to instantiate the `Repository` instances. There is one final
496  step before instantiating the Repository, which is to try to get a parent registry that can be used by the
497  child repository. The criteria for "can be used" is spelled out in `Butler._setParentRegistry`. However,
498  to get the registry from the parent, the parent must be instantiated. The `repoDataList`, in depth-first
499  search order, is built so that the most-dependent repositories are first, and the least dependent
500  repositories are last. So the `repoDataList` is reversed and the Repositories are instantiated in that
501  order; for each RepoData a parent registry is searched for, and then the Repository is instantiated with
502  whatever registry could be found."""
503 
504  def __init__(self, root=None, mapper=None, inputs=None, outputs=None, **mapperArgs):
505  self._initArgs = {'root': root, 'mapper': mapper, 'inputs': inputs, 'outputs': outputs,
506  'mapperArgs': mapperArgs}
507 
508  self.log = Log.getLogger("daf.persistence.butler")
509  # Always use an empty Persistence policy until we can get rid of it
510  persistencePolicy = pexPolicy.Policy()
511  self.persistence = Persistence.getPersistence(persistencePolicy)
512 
513  inputs, outputs = self._processInputArguments(
514  root=root, mapper=mapper, inputs=inputs, outputs=outputs, **mapperArgs)
515 
516  # convert the RepoArgs into RepoData
517  inputs = [RepoData(args, 'input') for args in inputs]
518  outputs = [RepoData(args, 'output') for args in outputs]
519  repoDataList = outputs + inputs
520 
521  self._getCfgs(repoDataList)
522 
523  self._addParents(repoDataList)
524 
525  self._setAndVerifyParentsLists(repoDataList)
526 
527  self._setDefaultMapper(repoDataList)
528 
529  self._connectParentRepoDatas(repoDataList)
530 
531  self._repos = RepoDataContainer(repoDataList)
532 
533  self._setRepoDataTags()
534 
535  for repoData in repoDataList:
536  self._initRepo(repoData)
537 
538  def _initRepo(self, repoData):
539  if repoData.repo is not None:
540  # this repository may have already been initialized by its children, in which case there is
541  # nothing more to do.
542  return
543  for parentRepoData in repoData.parentRepoDatas:
544  if parentRepoData.cfg.mapper != repoData.cfg.mapper:
545  continue
546  if parentRepoData.repo is None:
547  self._initRepo(parentRepoData)
548  parentRegistry = parentRepoData.repo.getRegistry()
549  repoData.parentRegistry = parentRegistry if parentRegistry else parentRepoData.parentRegistry
550  if repoData.parentRegistry:
551  break
552  repoData.repo = Repository(repoData)
553 
554  def _processInputArguments(self, root=None, mapper=None, inputs=None, outputs=None, **mapperArgs):
555  """Process, verify, and standardize the input arguments.
556  * Inputs can not be for Old Butler (root, mapper, mapperArgs) AND New Butler (inputs, outputs)
557  `root`, `mapper`, and `mapperArgs` are Old Butler init API.
558  `inputs` and `outputs` are New Butler init API.
559  Old Butler and New Butler init API may not be mixed, Butler may be initialized with only the Old
560  arguments or the New arguments.
561  * Verify that if there is a readable output that there is exactly one output. (This restriction is in
562  place because all readable repositories must be parents of writable repositories, and for
563  consistency the DAG of readable repositories must always be the same. Keeping the list of parents
564  becomes very complicated in the presence of multiple readable output repositories. It is better to
565  only write to output repositories, and then create a new Butler instance and use the outputs as
566  inputs, and write to new output repositories.)
567  * Make a copy of inputs & outputs so they may be modified without changing the passed-in arguments.
568  * Convert any input/output values that are URI strings to RepositoryArgs.
569  * Listify inputs & outputs.
570  * Set default RW mode on inputs & outputs as needed.
571 
572  Parameters
573  ----------
574  Same as Butler.__init__
575 
576  Returns
577  -------
578  (list of RepositoryArgs, list of RepositoryArgs)
579  First item is a list to use as inputs.
580  Second item is a list to use as outputs.
581 
582  Raises
583  ------
584  RuntimeError
585  If Old Butler and New Butler arguments are both used this will raise.
586  If an output is readable there is more than one output this will raise.
587  """
588  # inputs and outputs may be modified, do not change the external value.
589  inputs = copy.deepcopy(inputs)
590  outputs = copy.deepcopy(outputs)
591 
592  isV1Args = inputs is None and outputs is None
593  if isV1Args:
594  inputs, outputs = self._convertV1Args(root=root,
595  mapper=mapper,
596  mapperArgs=mapperArgs or None)
597  elif root or mapper or mapperArgs:
598  raise RuntimeError(
599  'Butler version 1 API (root, mapper, **mapperArgs) may ' +
600  'not be used with version 2 API (inputs, outputs)')
602 
603  self.storage = Storage()
604 
605  # make sure inputs and outputs are lists, and if list items are a string convert it RepositoryArgs.
606  inputs = listify(inputs)
607  outputs = listify(outputs)
608  inputs = [RepositoryArgs(cfgRoot=args)
609  if not isinstance(args, RepositoryArgs) else args for args in inputs]
610  outputs = [RepositoryArgs(cfgRoot=args)
611  if not isinstance(args, RepositoryArgs) else args for args in outputs]
612  # Set the default value of inputs & outputs, verify the required values ('r' for inputs, 'w' for
613  # outputs) and remove the 'w' from inputs if needed.
614  for args in inputs:
615  if args.mode is None:
616  args.mode = 'r'
617  elif 'rw' == args.mode:
618  args.mode = 'r'
619  elif 'r' != args.mode:
620  raise RuntimeError("The mode of an input should be readable.")
621  for args in outputs:
622  if args.mode is None:
623  args.mode = 'w'
624  elif 'w' not in args.mode:
625  raise RuntimeError("The mode of an output should be writable.")
626  # check for class instances in args.mapper (not allowed)
627  for args in inputs + outputs:
628  if (args.mapper and not isinstance(args.mapper, basestring) and
629  not inspect.isclass(args.mapper)):
630  self.log.warn(preinitedMapperWarning)
631  # if the output is readable, there must be only one output:
632  for o in outputs:
633  if 'r' in o.mode:
634  if len(outputs) > 1:
635  raise RuntimeError("Butler does not support multiple output repositories if any of the "
636  "outputs are readable.")
637 
638  # Handle the case where the output is readable and is also passed in as one of the inputs by removing
639  # the input. This supports a legacy use case in pipe_tasks where the input is also passed as the
640  # output, to the command line parser.
641  def inputIsInOutputs(inputArgs, outputArgsList):
642  for o in outputArgsList:
643  if ('r' in o.mode and
644  o.root == inputArgs.root and
645  o.mapper == inputArgs.mapper and
646  o.mapperArgs == inputArgs.mapperArgs and
647  o.tags == inputArgs.tags and
648  o.policy == inputArgs.policy):
649  self.log.debug(("Input repositoryArgs {} is also listed in outputs as readable; " +
650  "throwing away the input.").format(inputArgs))
651  return True
652  return False
653 
654  inputs = [args for args in inputs if not inputIsInOutputs(args, outputs)]
655  return inputs, outputs
656 
657  @staticmethod
658  def _getParentVal(repoData):
659  """Get the value of this repoData as it should appear in the parents
660  list of other repositories"""
661  if repoData.isV1Repository:
662  return repoData.cfg
663  if repoData.cfgOrigin == 'nested':
664  return repoData.cfg
665  else:
666  return repoData.cfg.root
667 
668  @staticmethod
669  def _getParents(ofRepoData, repoInfo):
670  """Create a parents list of repoData from inputs and (readable) outputs."""
671  parents = []
672  # get the parents list of repoData:
673  for repoData in repoInfo:
674  if repoData is ofRepoData:
675  continue
676  if 'r' not in repoData.repoArgs.mode:
677  continue
678  parents.append(Butler._getParentVal(repoData))
679  return parents
680 
681  @staticmethod
682  def _getOldButlerRepositoryCfg(repositoryArgs):
683  if not Storage.isPosix(repositoryArgs.cfgRoot):
684  return None
685  if not PosixStorage.v1RepoExists(repositoryArgs.cfgRoot):
686  return None
687  if not repositoryArgs.mapper:
688  repositoryArgs.mapper = PosixStorage.getMapperClass(repositoryArgs.cfgRoot)
689  cfg = RepositoryCfg.makeFromArgs(repositoryArgs)
690  parent = PosixStorage.getParentSymlinkPath(repositoryArgs.cfgRoot)
691  if parent:
692  parent = Butler._getOldButlerRepositoryCfg(RepositoryArgs(cfgRoot=parent, mode='r'))
693  if parent is not None:
694  cfg.addParents([parent])
695  return cfg
696 
697  def _getRepositoryCfg(self, repositoryArgs):
698  """Try to get a repository from the location described by cfgRoot.
699 
700  Parameters
701  ----------
702  repositoryArgs : RepositoryArgs or string
703  Provides arguments to load an existing repository (or repositories). String is assumed to be a URI
704  and is used as the cfgRoot (URI to the location of the cfg file).
705 
706  Returned
707  --------
708  (RepositoryCfg or None, bool)
709  The RepositoryCfg, or None if one cannot be found, and True if the RepositoryCfg was created by
710  reading an Old Butler repository, or False if it is a New Butler Repository.
711  """
712  if not isinstance(repositoryArgs, RepositoryArgs):
713  repositoryArgs = RepositoryArgs(cfgRoot=repositoryArgs, mode='r')
714 
715  cfg = self.storage.getRepositoryCfg(repositoryArgs.cfgRoot)
716  isOldButlerRepository = False
717  if cfg is None:
718  cfg = Butler._getOldButlerRepositoryCfg(repositoryArgs)
719  if cfg is not None:
720  isOldButlerRepository = True
721  return cfg, isOldButlerRepository
722 
723  def _getCfgs(self, repoDataList):
724  """Get or make a RepositoryCfg for each RepoData, and add the cfg to the RepoData.
725  If the cfg exists, compare values. If values match then use the cfg as an "existing" cfg. If the
726  values do not match, use the cfg as a "nested" cfg.
727  If the cfg does not exist, the RepositoryArgs must be for a writable repository.
728 
729  Parameters
730  ----------
731  repoDataList : list of RepoData
732  The RepoData that are output and inputs of this Butler
733 
734  Raises
735  ------
736  RuntimeError
737  If the passed-in RepositoryArgs indicate an existing repository but other cfg parameters in those
738  RepositoryArgs don't
739  match the existing repository's cfg a RuntimeError will be raised.
740  """
741  def cfgMatchesArgs(args, cfg):
742  """Test if there are any values in an RepositoryArgs that conflict with the values in a cfg"""
743  if args.mapper is not None and cfg.mapper != args.mapper:
744  return False
745  if args.mapperArgs is not None and cfg.mapperArgs != args.mapperArgs:
746  return False
747  if args.policy is not None and cfg.policy != args.policy:
748  return False
749  return True
750 
751  for repoData in repoDataList:
752  cfg, isOldButlerRepository = self._getRepositoryCfg(repoData.repoArgs)
753  if cfg is None:
754  if 'w' not in repoData.repoArgs.mode:
755  raise RuntimeError(
756  "No cfg found for read-only input repository at {}".format(repoData.repoArgs.cfgRoot))
757  repoData.setCfg(cfg=RepositoryCfg.makeFromArgs(repoData.repoArgs),
758  origin='new',
759  root=repoData.repoArgs.cfgRoot,
760  isV1Repository=isOldButlerRepository)
761  else:
762 
763  # This is a hack fix for an issue introduced by DM-11284; Old Butler parent repositories used
764  # to be stored as a path to the repository in the parents list and it was changed so that the
765  # whole RepositoryCfg, that described the Old Butler repository (including the mapperArgs that
766  # were used with it), was recorded as a "nested" repository cfg. That checkin did not account
767  # for the fact that there were repositoryCfg.yaml files in the world with only the path to
768  # Old Butler repositories in the parents list.
769  if cfg.parents:
770  for i, parent in enumerate(cfg.parents):
771  if isinstance(parent, RepositoryCfg):
772  continue
773  parentCfg, parentIsOldButlerRepository = self._getRepositoryCfg(parent)
774  if parentIsOldButlerRepository:
775  parentCfg.mapperArgs = cfg.mapperArgs
776  self.log.info(("Butler is replacing an Old Butler parent repository path '{}' "
777  "found in the parents list of a New Butler repositoryCfg: {} "
778  "with a repositoryCfg that includes the child repository's "
779  "mapperArgs: {}. This affects the instantiated RepositoryCfg "
780  "but does not change the persisted child repositoryCfg.yaml file."
781  ).format(parent, cfg, parentCfg))
782  cfg._parents[i] = cfg._normalizeParents(cfg.root, [parentCfg])[0]
783 
784  if 'w' in repoData.repoArgs.mode:
785  # if it's an output repository, the RepositoryArgs must match the existing cfg.
786  if not cfgMatchesArgs(repoData.repoArgs, cfg):
787  raise RuntimeError(("The RepositoryArgs and RepositoryCfg must match for writable " +
788  "repositories, RepositoryCfg:{}, RepositoryArgs:{}").format(
789  cfg, repoData.repoArgs))
790  repoData.setCfg(cfg=cfg, origin='existing', root=repoData.repoArgs.cfgRoot,
791  isV1Repository=isOldButlerRepository)
792  else:
793  # if it's an input repository, the cfg can overwrite the in-repo cfg.
794  if cfgMatchesArgs(repoData.repoArgs, cfg):
795  repoData.setCfg(cfg=cfg, origin='existing', root=repoData.repoArgs.cfgRoot,
796  isV1Repository=isOldButlerRepository)
797  else:
798  repoData.setCfg(cfg=cfg, origin='nested', root=None,
799  isV1Repository=isOldButlerRepository)
800 
801  def _addParents(self, repoDataList):
802  """For each repoData in the input list, see if its parents are the next items in the list, and if not
803  add the parent, so that the repoDataList includes parents and is in order to operate depth-first 0..n.
804 
805  Parameters
806  ----------
807  repoDataList : list of RepoData
808  The RepoData for the Butler outputs + inputs.
809 
810  Raises
811  ------
812  RuntimeError
813  Raised if a RepositoryCfg can not be found at a location where a parent repository should be.
814  """
815  repoDataIdx = 0
816  while True:
817  if repoDataIdx == len(repoDataList):
818  break
819  repoData = repoDataList[repoDataIdx]
820  if 'r' not in repoData.repoArgs.mode:
821  repoDataIdx += 1
822  continue # the repoData only needs parents if it's readable.
823  if repoData.isNewRepository:
824  repoDataIdx += 1
825  continue # if it's new the parents will be the inputs of this butler.
826  if repoData.cfg.parents is None:
827  repoDataIdx += 1
828  continue # if there are no parents then there's nothing to do.
829  for repoParentIdx, repoParent in enumerate(repoData.cfg.parents):
830  parentIdxInRepoDataList = repoDataIdx + repoParentIdx + 1
831  if not isinstance(repoParent, RepositoryCfg):
832  repoParentCfg, isOldButlerRepository = self._getRepositoryCfg(repoParent)
833  if repoParentCfg is not None:
834  cfgOrigin = 'existing'
835  else:
836  isOldButlerRepository = False
837  repoParentCfg = repoParent
838  cfgOrigin = 'nested'
839  if (parentIdxInRepoDataList < len(repoDataList) and
840  repoDataList[parentIdxInRepoDataList].cfg == repoParentCfg):
841  continue
842  args = RepositoryArgs(cfgRoot=repoParentCfg.root, mode='r')
843  role = 'input' if repoData.role == 'output' else 'parent'
844  newRepoInfo = RepoData(args, role)
845  newRepoInfo.repoData.setCfg(cfg=repoParentCfg, origin=cfgOrigin, root=args.cfgRoot,
846  isV1Repository=isOldButlerRepository)
847  repoDataList.insert(parentIdxInRepoDataList, newRepoInfo)
848  repoDataIdx += 1
849 
850  def _setAndVerifyParentsLists(self, repoDataList):
851  """Make a list of all the input repositories of this Butler, these are the parents of the outputs.
852  For new output repositories, set the parents in the RepositoryCfg. For existing output repositories
853  verify that the RepositoryCfg's parents match the parents list.
854 
855  Parameters
856  ----------
857  repoDataList : list of RepoData
858  All the RepoDatas loaded by this butler, in search order.
859 
860  Raises
861  ------
862  RuntimeError
863  If an existing output repository is loaded and its parents do not match the parents of this Butler
864  an error will be raised.
865  """
866  def getIOParents(ofRepoData, repoDataList):
867  """make a parents list for repo in `ofRepoData` that is comprised of inputs and readable
868  outputs (not parents-of-parents) of this butler"""
869  parents = []
870  for repoData in repoDataList:
871  if repoData.role == 'parent':
872  continue
873  if repoData is ofRepoData:
874  continue
875  if repoData.role == 'output':
876  if 'r' in repoData.repoArgs.mode:
877  raise RuntimeError("If an output is readable it must be the only output.")
878  # and if this is the only output, this should have continued in
879  # "if repoData is ofRepoData"
880  continue
881  parents.append(self._getParentVal(repoData))
882  return parents
883 
884  for repoData in repoDataList:
885  if repoData.role != 'output':
886  continue
887  parents = getIOParents(repoData, repoDataList)
888  # if repoData is new, add the parent RepositoryCfgs to it.
889  if repoData.cfgOrigin == 'new':
890  repoData.cfg.addParents(parents)
891  elif repoData.cfgOrigin in ('existing', 'nested'):
892  if repoData.cfg.parents != parents:
893  try:
894  repoData.cfg.extendParents(parents)
895  except ParentsMismatch as e:
896  raise RuntimeError(("Inputs of this Butler:{} do not match parents of existing " +
897  "writable cfg:{} (ParentMismatch exception: {}").format(
898  parents, repoData.cfg.parents, e))
899 
900  def _setDefaultMapper(self, repoDataList):
901  """Establish a default mapper if there is one and assign it to outputs that do not have a mapper
902  assigned.
903 
904  If all inputs have the same mapper it will be used as the default mapper.
905 
906  Parameters
907  ----------
908  repoDataList : list of RepoData
909  All the RepoDatas loaded by this butler, in search order.
910 
911  Raises
912  ------
913  RuntimeError
914  If a default mapper can not be established and there is an output that does not have a mapper.
915  """
916  needyOutputs = [rd for rd in repoDataList if rd.role == 'output' and rd.cfg.mapper is None]
917  if len(needyOutputs) is 0:
918  return
919  mappers = set([rd.cfg.mapper for rd in repoDataList if rd.role == 'input'])
920  if len(mappers) != 1:
921  inputs = [rd for rd in repoDataList if rd.role == 'input']
922  raise RuntimeError(
923  ("No default mapper could be established from inputs:{} and no mapper specified " +
924  "for outputs:{}").format(inputs, needyOutputs))
925  defaultMapper = mappers.pop()
926  for repoData in needyOutputs:
927  repoData.cfg.mapper = defaultMapper
928 
929  def _connectParentRepoDatas(self, repoDataList):
930  """For each RepoData in repoDataList, find its parent in the repoDataList and cache a reference to it.
931 
932  Parameters
933  ----------
934  repoDataList : list of RepoData
935  All the RepoDatas loaded by this butler, in search order.
936 
937  Raises
938  ------
939  RuntimeError
940  When a parent is listed in the parents list but not found in the repoDataList. This is not
941  expected to ever happen and would indicate an internal Butler error.
942  """
943  for repoData in repoDataList:
944  for parent in repoData.cfg.parents:
945  parentToAdd = None
946  for otherRepoData in repoDataList:
947  if isinstance(parent, RepositoryCfg):
948  if otherRepoData.repoData.repoData.cfg == parent:
949  parentToAdd = otherRepoData.repoData
950  break
951  elif otherRepoData.repoData.cfg.root == parent:
952  parentToAdd = otherRepoData.repoData
953  break
954  if parentToAdd is None:
955  raise RuntimeError(
956  "Could not find a parent matching {} to add to {}".format(parent, repoData))
957  repoData.addParentRepoData(parentToAdd)
958 
959  @staticmethod
960  def _getParentRepoData(parent, repoDataList):
961  """get a parent RepoData from a cfg from a list of RepoData
962 
963  Parameters
964  ----------
965  parent : string or RepositoryCfg
966  cfgRoot of a repo or a cfg that describes the repo
967  repoDataList : list of RepoData
968  list to search in
969 
970  Returns
971  -------
972  RepoData or None
973  A RepoData if one can be found, else None
974  """
975  repoData = None
976  for otherRepoData in repoDataList:
977  if isinstance(parent, RepositoryCfg):
978  if otherRepoData.cfg == parent:
979  repoData = otherRepoData
980  break
981  elif otherRepoData.cfg.root == parent:
982  repoData = otherRepoData
983  break
984  return repoData
985 
986  def _setRepoDataTags(self):
987  """Set the tags from each repoArgs into all its parent repoArgs so that they can be included in tagged
988  searches."""
989  def setTags(repoData, tags, context):
990  if id(repoData) in context:
991  return
992  repoData.addTags(tags)
993  context.add(id(repoData))
994  for parentRepoData in repoData.parentRepoDatas:
995  setTags(parentRepoData, tags, context)
996  for repoData in self._repos.outputs() + self._repos.inputs():
997  setTags(repoData.repoData, repoData.repoArgs.tags, set())
998 
999  def _convertV1Args(self, root, mapper, mapperArgs):
1000  """Convert Old Butler RepositoryArgs (root, mapper, mapperArgs) to New Butler RepositoryArgs
1001  (inputs, outputs)
1002 
1003  Parameters
1004  ----------
1005  root : string
1006  Posix path to repository root
1007  mapper : class, class instance, or string
1008  Instantiated class, a class object to be instantiated, or a string that refers to a class that
1009  can be imported & used as the mapper.
1010  mapperArgs : dict
1011  RepositoryArgs & their values used when instantiating the mapper.
1012 
1013  Returns
1014  -------
1015  tuple
1016  (inputs, outputs) - values to be used for inputs and outputs in Butler.__init__
1017  """
1018  if (mapper and not isinstance(mapper, basestring) and
1019  not inspect.isclass(mapper)):
1020  self.log.warn(preinitedMapperWarning)
1021  inputs = None
1022  if root is None:
1023  if hasattr(mapper, 'root'):
1024  # in legacy repositories, the mapper may be given the root directly.
1025  root = mapper.root
1026  else:
1027  # in the past root="None" could be used to mean root='.'
1028  root = '.'
1029  outputs = RepositoryArgs(mode='rw',
1030  root=root,
1031  mapper=mapper,
1032  mapperArgs=mapperArgs)
1033  return inputs, outputs
1034 
1035  def __repr__(self):
1036  return 'Butler(datasetTypeAliasDict=%s, repos=%s, persistence=%s)' % (
1037  self.datasetTypeAliasDict, self._repos, self.persistence)
1038 
1039  def _getDefaultMapper(self):
1040 
1041  """Get the default mapper. Currently this means if all the repositories use exactly the same mapper,
1042  that mapper may be considered the default.
1043 
1044  This definition may be changing; mappers may be able to exclude themselves as candidates for default,
1045  and they may nominate a different mapper instead. Also, we may not want to look at *all* the
1046  repositories, but only a depth-first search on each of the input & output repositories, and use the
1047  first-found mapper for each of those. TBD.
1048 
1049  Parameters
1050  ----------
1051  inputs : TYPE
1052  Description
1053 
1054  Returns
1055  -------
1056  Mapper class or None
1057  Returns the class type of the default mapper, or None if a default
1058  mapper can not be determined.
1059  """
1060  defaultMapper = None
1061 
1062  for inputRepoData in self._repos.inputs():
1063  mapper = None
1064  if inputRepoData.cfg.mapper is not None:
1065  mapper = inputRepoData.cfg.mapper
1066  # if the mapper is:
1067  # * a string, import it.
1068  # * a class instance, get its class type
1069  # * a class, do nothing; use it
1070  if isinstance(mapper, basestring):
1071  mapper = doImport(mapper)
1072  elif not inspect.isclass(mapper):
1073  mapper = mapper.__class__
1074  # If no mapper has been found, note the first found mapper.
1075  # Then, if a mapper has been found and each next mapper matches it,
1076  # continue looking for mappers.
1077  # If a mapper has been found and another non-matching mapper is
1078  # found then we have no default, return None.
1079  if defaultMapper is None:
1080  defaultMapper = mapper
1081  elif mapper == defaultMapper:
1082  continue
1083  elif mapper is not None:
1084  return None
1085  return defaultMapper
1086 
1087  def _assignDefaultMapper(self, defaultMapper):
1088  for repoData in self._repos.all().values():
1089  if repoData.cfg.mapper is None and (repoData.isNewRepository or repoData.isV1Repository):
1090  if defaultMapper is None:
1091  raise RuntimeError(
1092  "No mapper specified for %s and no default mapper could be determined." %
1093  repoData.args)
1094  repoData.cfg.mapper = defaultMapper
1095 
1096  @staticmethod
1097  def getMapperClass(root):
1098  """posix-only; gets the mapper class at the path specified by root (if a file _mapper can be found at
1099  that location or in a parent location.
1100 
1101  As we abstract the storage and support different types of storage locations this method will be
1102  moved entirely into Butler Access, or made more dynamic, and the API will very likely change."""
1103  return Storage.getMapperClass(root)
1104 
1105  def defineAlias(self, alias, datasetType):
1106  """Register an alias that will be substituted in datasetTypes.
1107 
1108  Parameters
1109  ----------
1110  alias - string
1111  The alias keyword. It may start with @ or not. It may not contain @ except as the first character.
1112  datasetType - string
1113  The string that will be substituted when @alias is passed into datasetType. It may not contain '@'
1114  """
1115  # verify formatting of alias:
1116  # it can have '@' as the first character (if not it's okay, we will add it) or not at all.
1117  atLoc = alias.rfind('@')
1118  if atLoc == -1:
1119  alias = "@" + str(alias)
1120  elif atLoc > 0:
1121  raise RuntimeError("Badly formatted alias string: %s" % (alias,))
1122 
1123  # verify that datasetType does not contain '@'
1124  if datasetType.count('@') != 0:
1125  raise RuntimeError("Badly formatted type string: %s" % (datasetType))
1126 
1127  # verify that the alias keyword does not start with another alias keyword,
1128  # and vice versa
1129  for key in self.datasetTypeAliasDict:
1130  if key.startswith(alias) or alias.startswith(key):
1131  raise RuntimeError("Alias: %s overlaps with existing alias: %s" % (alias, key))
1132 
1133  self.datasetTypeAliasDict[alias] = datasetType
1134 
1135  def getKeys(self, datasetType=None, level=None, tag=None):
1136  """Get the valid data id keys at or above the given level of hierarchy for the dataset type or the
1137  entire collection if None. The dict values are the basic Python types corresponding to the keys (int,
1138  float, string).
1139 
1140  Parameters
1141  ----------
1142  datasetType - string
1143  The type of dataset to get keys for, entire collection if None.
1144  level - string
1145  The hierarchy level to descend to. None if it should not be restricted. Use an empty string if the
1146  mapper should lookup the default level.
1147  tags - any, or list of any
1148  Any object that can be tested to be the same as the tag in a dataId passed into butler input
1149  functions. Applies only to input repositories: If tag is specified by the dataId then the repo
1150  will only be read from used if the tag in the dataId matches a tag used for that repository.
1151 
1152  Returns
1153  -------
1154  Returns a dict. The dict keys are the valid data id keys at or above the given level of hierarchy for
1155  the dataset type or the entire collection if None. The dict values are the basic Python types
1156  corresponding to the keys (int, float, string).
1157  """
1158  datasetType = self._resolveDatasetTypeAlias(datasetType)
1159 
1160  keys = None
1161  tag = setify(tag)
1162  for repoData in self._repos.inputs():
1163  if not tag or len(tag.intersection(repoData.tags)) > 0:
1164  keys = repoData.repo.getKeys(datasetType, level)
1165  # An empty dict is a valid "found" condition for keys. The only value for keys that should
1166  # cause the search to continue is None
1167  if keys is not None:
1168  break
1169  return keys
1170 
1171  def queryMetadata(self, datasetType, format, dataId={}, **rest):
1172  """Returns the valid values for one or more keys when given a partial
1173  input collection data id.
1174 
1175  Parameters
1176  ----------
1177  datasetType - string
1178  The type of dataset to inquire about.
1179  format - str, tuple
1180  Key or tuple of keys to be returned.
1181  dataId - DataId, dict
1182  The partial data id.
1183  **rest -
1184  Keyword arguments for the partial data id.
1185 
1186  Returns
1187  -------
1188  A list of valid values or tuples of valid values as specified by the
1189  format.
1190  """
1191 
1192  datasetType = self._resolveDatasetTypeAlias(datasetType)
1193  dataId = DataId(dataId)
1194  dataId.update(**rest)
1195  format = sequencify(format)
1196 
1197  tuples = None
1198  for repoData in self._repos.inputs():
1199  if not dataId.tag or len(dataId.tag.intersection(repoData.tags)) > 0:
1200  tuples = repoData.repo.queryMetadata(datasetType, format, dataId)
1201  if tuples:
1202  break
1203 
1204  if not tuples:
1205  return []
1206 
1207  if len(format) == 1:
1208  ret = []
1209  for x in tuples:
1210  try:
1211  ret.append(x[0])
1212  except TypeError:
1213  ret.append(x)
1214  return ret
1215 
1216  return tuples
1217 
1218  def datasetExists(self, datasetType, dataId={}, write=False, **rest):
1219  """Determines if a dataset file exists.
1220 
1221  Parameters
1222  ----------
1223  datasetType - string
1224  The type of dataset to inquire about.
1225  dataId - DataId, dict
1226  The data id of the dataset.
1227  write - bool
1228  If True, look only in locations where the dataset could be written,
1229  and return True only if it is present in all of them.
1230  **rest keyword arguments for the data id.
1231 
1232  Returns
1233  -------
1234  exists - bool
1235  True if the dataset exists or is non-file-based.
1236  """
1237  datasetType = self._resolveDatasetTypeAlias(datasetType)
1238  dataId = DataId(dataId)
1239  dataId.update(**rest)
1240  locations = self._locate(datasetType, dataId, write=write)
1241  if not write: # when write=False, locations is not a sequence
1242  if locations is None:
1243  return False
1244  locations = [locations]
1245 
1246  if not locations: # empty list
1247  return False
1248 
1249  for location in locations:
1250  # If the location is a ButlerComposite (as opposed to a ButlerLocation),
1251  # verify the component objects exist.
1252  if isinstance(location, ButlerComposite):
1253  for name, componentInfo in location.componentInfo.items():
1254  if componentInfo.subset:
1255  subset = self.subset(datasetType=componentInfo.datasetType, dataId=location.dataId)
1256  exists = all([obj.datasetExists() for obj in subset])
1257  else:
1258  exists = self.datasetExists(componentInfo.datasetType, location.dataId)
1259  if exists is False:
1260  return False
1261  else:
1262  if not location.repository.exists(location):
1263  return False
1264  return True
1265 
1266  def _locate(self, datasetType, dataId, write):
1267  """Get one or more ButlerLocations and/or ButlercComposites.
1268 
1269  Parameters
1270  ----------
1271  datasetType : string
1272  The datasetType that is being searched for. The datasetType may be followed by a dot and
1273  a component name (component names are specified in the policy). IE datasetType.componentName
1274 
1275  dataId : dict or DataId class instance
1276  The dataId
1277 
1278  write : bool
1279  True if this is a search to write an object. False if it is a search to read an object. This
1280  affects what type (an object or a container) is returned.
1281 
1282  Returns
1283  -------
1284  If write is False, will return either a single object or None. If write is True, will return a list
1285  (which may be empty)
1286  """
1287  repos = self._repos.outputs() if write else self._repos.inputs()
1288  locations = []
1289  for repoData in repos:
1290  # enforce dataId & repository tags when reading:
1291  if not write and dataId.tag and len(dataId.tag.intersection(repoData.tags)) == 0:
1292  continue
1293  components = datasetType.split('.')
1294  datasetType = components[0]
1295  components = components[1:]
1296  try:
1297  location = repoData.repo.map(datasetType, dataId, write=write)
1298  except NoResults:
1299  continue
1300  if location is None:
1301  continue
1302  location.datasetType = datasetType # todo is there a better way than monkey patching here?
1303  if len(components) > 0:
1304  if not isinstance(location, ButlerComposite):
1305  raise RuntimeError("The location for a dotted datasetType must be a composite.")
1306  # replace the first component name with the datasetType
1307  components[0] = location.componentInfo[components[0]].datasetType
1308  # join components back into a dot-delimited string
1309  datasetType = '.'.join(components)
1310  location = self._locate(datasetType, dataId, write)
1311  # if a component location is not found, we can not continue with this repo, move to next repo.
1312  if location is None:
1313  break
1314  # if reading, only one location is desired.
1315  if location:
1316  if not write:
1317  # If there is a bypass function for this dataset type, we can't test to see if the object
1318  # exists in storage, because the bypass function may not actually use the location
1319  # according to the template. Instead, execute the bypass function and include its results
1320  # in the bypass attribute of the location. The bypass function may fail for any reason,
1321  # the most common case being that a file does not exist. If it raises an exception
1322  # indicating such, we ignore the bypass function and proceed as though it does not exist.
1323  if hasattr(location.mapper, "bypass_" + location.datasetType):
1324  bypass = self._getBypassFunc(location, dataId)
1325  try:
1326  bypass = bypass()
1327  location.bypass = bypass
1328  except (NoResults, IOError):
1329  self.log.debug("Continuing dataset search while evaluating "
1330  "bypass function for Dataset type:{} Data ID:{} at "
1331  "location {}".format(datasetType, dataId, location))
1332  # If a location was found but the location does not exist, keep looking in input
1333  # repositories (the registry may have had enough data for a lookup even thought the object
1334  # exists in a different repository.)
1335  if (isinstance(location, ButlerComposite) or hasattr(location, 'bypass') or
1336  location.repository.exists(location)):
1337  return location
1338  else:
1339  try:
1340  locations.extend(location)
1341  except TypeError:
1342  locations.append(location)
1343  if not write:
1344  return None
1345  return locations
1346 
1347  @staticmethod
1348  def _getBypassFunc(location, dataId):
1349  pythonType = location.getPythonType()
1350  if pythonType is not None:
1351  if isinstance(pythonType, basestring):
1352  pythonType = doImport(pythonType)
1353  bypassFunc = getattr(location.mapper, "bypass_" + location.datasetType)
1354  return lambda: bypassFunc(location.datasetType, pythonType, location, dataId)
1355 
1356  def get(self, datasetType, dataId=None, immediate=True, **rest):
1357  """Retrieves a dataset given an input collection data id.
1358 
1359  Parameters
1360  ----------
1361  datasetType - string
1362  The type of dataset to retrieve.
1363  dataId - dict
1364  The data id.
1365  immediate - bool
1366  If False use a proxy for delayed loading.
1367  **rest
1368  keyword arguments for the data id.
1369 
1370  Returns
1371  -------
1372  An object retrieved from the dataset (or a proxy for one).
1373  """
1374  datasetType = self._resolveDatasetTypeAlias(datasetType)
1375  dataId = DataId(dataId)
1376  dataId.update(**rest)
1377 
1378  location = self._locate(datasetType, dataId, write=False)
1379  if location is None:
1380  raise NoResults("No locations for get:", datasetType, dataId)
1381  self.log.debug("Get type=%s keys=%s from %s", datasetType, dataId, str(location))
1382 
1383  if hasattr(location, 'bypass'):
1384  # this type loader block should get moved into a helper someplace, and duplications removed.
1385  def callback():
1386  return location.bypass
1387  else:
1388  def callback():
1389  return self._read(location)
1390  if location.mapper.canStandardize(location.datasetType):
1391  innerCallback = callback
1392 
1393  def callback():
1394  return location.mapper.standardize(location.datasetType, innerCallback(), dataId)
1395  if immediate:
1396  return callback()
1397  return ReadProxy(callback)
1398 
1399  def put(self, obj, datasetType, dataId={}, doBackup=False, **rest):
1400  """Persists a dataset given an output collection data id.
1401 
1402  Parameters
1403  ----------
1404  obj -
1405  The object to persist.
1406  datasetType - string
1407  The type of dataset to persist.
1408  dataId - dict
1409  The data id.
1410  doBackup - bool
1411  If True, rename existing instead of overwriting.
1412  WARNING: Setting doBackup=True is not safe for parallel processing, as it may be subject to race
1413  conditions.
1414  **rest
1415  Keyword arguments for the data id.
1416  """
1417  datasetType = self._resolveDatasetTypeAlias(datasetType)
1418  dataId = DataId(dataId)
1419  dataId.update(**rest)
1420 
1421  for location in self._locate(datasetType, dataId, write=True):
1422  if isinstance(location, ButlerComposite):
1423  disassembler = location.disassembler if location.disassembler else genericDisassembler
1424  disassembler(obj=obj, dataId=location.dataId, componentInfo=location.componentInfo)
1425  for name, info in location.componentInfo.items():
1426  if not info.inputOnly:
1427  self.put(info.obj, info.datasetType, location.dataId, doBackup=doBackup)
1428  else:
1429  if doBackup:
1430  location.getRepository().backup(location.datasetType, dataId)
1431  location.getRepository().write(location, obj)
1432 
1433  def subset(self, datasetType, level=None, dataId={}, **rest):
1434  """Return complete dataIds for a dataset type that match a partial (or empty) dataId.
1435 
1436  Given a partial (or empty) dataId specified in dataId and **rest, find all datasets that match the
1437  dataId. Optionally restrict the results to a given level specified by a dataId key (e.g. visit or
1438  sensor or amp for a camera). Return an iterable collection of complete dataIds as ButlerDataRefs.
1439  Datasets with the resulting dataIds may not exist; that needs to be tested with datasetExists().
1440 
1441  Parameters
1442  ----------
1443  datasetType - string
1444  The type of dataset collection to subset
1445  level - string
1446  The level of dataId at which to subset. Use an empty string if the mapper should look up the
1447  default level.
1448  dataId - dict
1449  The data id.
1450  **rest
1451  Keyword arguments for the data id.
1452 
1453  Returns
1454  -------
1455  subset - ButlerSubset
1456  Collection of ButlerDataRefs for datasets matching the data id.
1457 
1458  Examples
1459  -----------
1460  To print the full dataIds for all r-band measurements in a source catalog
1461  (note that the subset call is equivalent to: `butler.subset('src', dataId={'filter':'r'})`):
1462 
1463  >>> subset = butler.subset('src', filter='r')
1464  >>> for data_ref in subset: print(data_ref.dataId)
1465  """
1466  datasetType = self._resolveDatasetTypeAlias(datasetType)
1467 
1468  # Currently expected behavior of subset is that if specified level is None then the mapper's default
1469  # level should be used. Convention for level within Butler is that an empty string is used to indicate
1470  # 'get default'.
1471  if level is None:
1472  level = ''
1473 
1474  dataId = DataId(dataId)
1475  dataId.update(**rest)
1476  return ButlerSubset(self, datasetType, level, dataId)
1477 
1478  def dataRef(self, datasetType, level=None, dataId={}, **rest):
1479  """Returns a single ButlerDataRef.
1480 
1481  Given a complete dataId specified in dataId and **rest, find the unique dataset at the given level
1482  specified by a dataId key (e.g. visit or sensor or amp for a camera) and return a ButlerDataRef.
1483 
1484  Parameters
1485  ----------
1486  datasetType - string
1487  The type of dataset collection to reference
1488  level - string
1489  The level of dataId at which to reference
1490  dataId - dict
1491  The data id.
1492  **rest
1493  Keyword arguments for the data id.
1494 
1495  Returns
1496  -------
1497  dataRef - ButlerDataRef
1498  ButlerDataRef for dataset matching the data id
1499  """
1500 
1501  datasetType = self._resolveDatasetTypeAlias(datasetType)
1502  dataId = DataId(dataId)
1503  subset = self.subset(datasetType, level, dataId, **rest)
1504  if len(subset) != 1:
1505  raise RuntimeError("No unique dataset for: Dataset type:%s Level:%s Data ID:%s Keywords:%s" %
1506  (str(datasetType), str(level), str(dataId), str(rest)))
1507  return ButlerDataRef(subset, subset.cache[0])
1508 
1509  def getUri(self, datasetType, dataId=None, write=False, **rest):
1510  """Return the URI for a dataset
1511 
1512  .. warning:: This is intended only for debugging. The URI should
1513  never be used for anything other than printing.
1514 
1515  .. note:: In the event there are multiple URIs for read, we return only
1516  the first.
1517 
1518  .. note:: getUri() does not currently support composite datasets.
1519 
1520  Parameters
1521  ----------
1522  datasetType : `str`
1523  The dataset type of interest.
1524  dataId : `dict`, optional
1525  The data identifier.
1526  write : `bool`, optional
1527  Return the URI for writing?
1528  rest : `dict`, optional
1529  Keyword arguments for the data id.
1530 
1531  Returns
1532  -------
1533  uri : `str`
1534  URI for dataset.
1535  """
1536  datasetType = self._resolveDatasetTypeAlias(datasetType)
1537  dataId = DataId(dataId)
1538  dataId.update(**rest)
1539  locations = self._locate(datasetType, dataId, write=write)
1540  if locations is None:
1541  raise NoResults("No locations for getUri: ", datasetType, dataId)
1542 
1543  if write:
1544  # Follow the write path
1545  # Return the first valid write location.
1546  for location in locations:
1547  if isinstance(location, ButlerComposite):
1548  for name, info in location.componentInfo.items():
1549  if not info.inputOnly:
1550  return self.getUri(info.datasetType, location.dataId, write=True)
1551  else:
1552  return location.getLocationsWithRoot()[0]
1553  # fall back to raise
1554  raise NoResults("No locations for getUri(write=True): ", datasetType, dataId)
1555  else:
1556  # Follow the read path, only return the first valid read
1557  return locations.getLocationsWithRoot()[0]
1558 
1559  def _read(self, location):
1560  """Unpersist an object using data inside a ButlerLocation or ButlerComposite object.
1561 
1562  Parameters
1563  ----------
1564  location : ButlerLocation or ButlerComposite
1565  A ButlerLocation or ButlerComposite instance populated with data needed to read the object.
1566 
1567  Returns
1568  -------
1569  object
1570  An instance of the object specified by the location.
1571  """
1572  self.log.debug("Starting read from %s", location)
1573 
1574  if isinstance(location, ButlerComposite):
1575  for name, componentInfo in location.componentInfo.items():
1576  if componentInfo.subset:
1577  subset = self.subset(datasetType=componentInfo.datasetType, dataId=location.dataId)
1578  componentInfo.obj = [obj.get() for obj in subset]
1579  else:
1580  obj = self.get(componentInfo.datasetType, location.dataId, immediate=True)
1581  componentInfo.obj = obj
1582  assembler = location.assembler or genericAssembler
1583  results = assembler(dataId=location.dataId, componentInfo=location.componentInfo,
1584  cls=location.python)
1585  return results
1586  else:
1587  results = location.repository.read(location)
1588  if len(results) == 1:
1589  results = results[0]
1590  self.log.debug("Ending read from %s", location)
1591  return results
1592 
1593  def __reduce__(self):
1594  ret = (_unreduce, (self._initArgs, self.datasetTypeAliasDict))
1595  return ret
1596 
1597  def _resolveDatasetTypeAlias(self, datasetType):
1598  """Replaces all the known alias keywords in the given string with the alias value.
1599 
1600  Parameters
1601  ----------
1602  datasetType - string
1603  A datasetType string to search & replace on
1604 
1605  Returns
1606  -------
1607  datasetType - string
1608  The de-aliased string
1609  """
1610  for key in self.datasetTypeAliasDict:
1611  # if all aliases have been replaced, bail out
1612  if datasetType.find('@') == -1:
1613  break
1614  datasetType = datasetType.replace(key, self.datasetTypeAliasDict[key])
1615 
1616  # If an alias specifier can not be resolved then throw.
1617  if datasetType.find('@') != -1:
1618  raise RuntimeError("Unresolvable alias specifier in datasetType: %s" % (datasetType))
1619 
1620  return datasetType
1621 
1622 
1623 def _unreduce(initArgs, datasetTypeAliasDict):
1624  mapperArgs = initArgs.pop('mapperArgs')
1625  initArgs.update(mapperArgs)
1626  butler = Butler(**initArgs)
1627  butler.datasetTypeAliasDict = datasetTypeAliasDict
1628  return butler
def _resolveDatasetTypeAlias(self, datasetType)
Definition: butler.py:1597
def datasetExists(self, datasetType, dataId={}, write=False, rest)
Definition: butler.py:1218
def _convertV1Args(self, root, mapper, mapperArgs)
Definition: butler.py:999
def __init__(self, root=None, mapper=None, inputs=None, outputs=None, mapperArgs)
Definition: butler.py:504
def setCfg(self, cfg, origin, root, isV1Repository)
Definition: butler.py:168
def _getRepositoryCfg(self, repositoryArgs)
Definition: butler.py:697
def getParentRepoDatas(self, context=None)
Definition: butler.py:209
def _getCfgs(self, repoDataList)
Definition: butler.py:723
def subset(self, datasetType, level=None, dataId={}, rest)
Definition: butler.py:1433
def __init__(self, cls, repoCfg)
Definition: butler.py:62
def _initRepo(self, repoData)
Definition: butler.py:538
def _setDefaultMapper(self, repoDataList)
Definition: butler.py:900
def getUri(self, datasetType, dataId=None, write=False, rest)
Definition: butler.py:1509
def defineAlias(self, alias, datasetType)
Definition: butler.py:1105
def _connectParentRepoDatas(self, repoDataList)
Definition: butler.py:929
def _addParents(self, repoDataList)
Definition: butler.py:801
def getKeys(self, datasetType=None, level=None, tag=None)
Definition: butler.py:1135
def doImport(pythonType)
Definition: utils.py:109
def _getBypassFunc(location, dataId)
Definition: butler.py:1348
def put(self, obj, datasetType, dataId={}, doBackup=False, rest)
Definition: butler.py:1399
def queryMetadata(self, datasetType, format, dataId={}, rest)
Definition: butler.py:1171
def _processInputArguments(self, root=None, mapper=None, inputs=None, outputs=None, mapperArgs)
Definition: butler.py:554
def addParentRepoData(self, parentRepoData)
Definition: butler.py:237
def _locate(self, datasetType, dataId, write)
Definition: butler.py:1266
def _setAndVerifyParentsLists(self, repoDataList)
Definition: butler.py:850
def get(self, datasetType, dataId=None, immediate=True, rest)
Definition: butler.py:1356
def __init__(self, args, role)
Definition: butler.py:125