lsst.daf.persistence  13.0-17-gd5d205a+2
 All Classes Namespaces Files Functions Variables Typedefs Friends Macros
storageInterface.py
Go to the documentation of this file.
1 #!/usr/bin/env python
2 
3 #
4 # LSST Data Management System
5 # Copyright 2017 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 from abc import ABCMeta, abstractmethod
25 
26 
27 class NoRepositroyAtRoot(RuntimeError):
28  pass
29 
30 
32  """Defines the interface for a connection to a Storage location.
33 
34  Parameters
35  ----------
36  uri : string
37  URI or path that is used as the storage location.
38  create : bool
39  If True The StorageInterface subclass should create a new
40  repository at the root location. If False then a new repository
41  will not be created.
42 
43  Raises
44  ------
45  NoRepositroyAtRoot
46  If create is False and a repository does not exist at the root
47  specified by uri then NoRepositroyAtRoot is raised.
48  """
49  __metaclass__ = ABCMeta
50 
51  def __init__(self, uri, create):
52  """initialzer"""
53  pass
54 
55  @abstractmethod
56  def write(self, butlerLocation, obj):
57  """Writes an object to a location and persistence format specified by ButlerLocation
58 
59  Parameters
60  ----------
61  butlerLocation : ButlerLocation
62  The location & formatting for the object to be written.
63  obj : object instance
64  The object to be written.
65  """
66 
67  @abstractmethod
68  def read(self, butlerLocation):
69  """Read from a butlerLocation.
70 
71  Parameters
72  ----------
73  butlerLocation : ButlerLocation
74  The location & formatting for the object(s) to be read.
75 
76  Returns
77  -------
78  A list of objects as described by the butler location. One item for
79  each location in butlerLocation.getLocations()
80  """
81 
82  @abstractmethod
83  def getLocalFile(self, path):
84  """Get a handle to a local copy of the file, downloading it to a
85  temporary if needed.
86 
87  Parameters
88  ----------
89  path : string
90  A path to the the file in storage, relative to root.
91 
92  Returns
93  -------
94  A handle to a local copy of the file. If storage is remote it will be
95  a temporary file. If storage is local it may be the original file or
96  a temporary file. The file name can be gotten via the 'name' property
97  of the returned object.
98  """
99 
100  @abstractmethod
101  def exists(self, location):
102  """Check if location exists.
103 
104  Parameters
105  ----------
106  location : ButlerLocation or string
107  A a string or a ButlerLocation that describes the location of an
108  object in this storage.
109 
110  Returns
111  -------
112  bool
113  True if exists, else False.
114  """
115 
116  @abstractmethod
117  def instanceSearch(self, path):
118  """Search for the given path in this storage instance.
119 
120  If the path contains an HDU indicator (a number in brackets before the
121  dot, e.g. 'foo.fits[1]', this will be stripped when searching and so
122  will match filenames without the HDU indicator, e.g. 'foo.fits'. The
123  path returned WILL contain the indicator though, e.g. ['foo.fits[1]'].
124 
125  Parameters
126  ----------
127  path : string
128  A filename (and optionally prefix path) to search for within root.
129 
130  Returns
131  -------
132  string or None
133  The location that was found, or None if no location was found.
134  """
135 
136  @classmethod
137  @abstractmethod
138  def search(cls, root, path):
139  """Look for the given path in the current root.
140 
141  Also supports searching for the path in Butler v1 repositories by
142  following the Butler v1 _parent symlink
143 
144  If the path contains an HDU indicator (a number in brackets, e.g.
145  'foo.fits[1]', this will be stripped when searching and so
146  will match filenames without the HDU indicator, e.g. 'foo.fits'. The
147  path returned WILL contain the indicator though, e.g. ['foo.fits[1]'].
148 
149  Parameters
150  ----------
151  root : string
152  The path to the root directory.
153  path : string
154  The path to the file within the root directory.
155 
156  Returns
157  -------
158  string or None
159  The location that was found, or None if no location was found.
160  """
161 
162  @abstractmethod
163  def copyFile(self, fromLocation, toLocation):
164  """Copy a file from one location to another on the local filesystem.
165 
166  Parameters
167  ----------
168  fromLocation : string
169  Path and name of existing file.
170  toLocation : string
171  Path and name of new file.
172 
173  Returns
174  -------
175  None
176  """
177 
178  @abstractmethod
179  def locationWithRoot(self, location):
180  """Get the full path to the location.
181 
182  Parameters
183  ----------
184  location : string
185  Path to a location within the repository relative to repository
186  root.
187 
188  Returns
189  -------
190  string
191  Absolute path to to the locaiton within the repository.
192  """
193 
194  @classmethod
195  @abstractmethod
196  def getRepositoryCfg(cls, uri):
197  """Get a persisted RepositoryCfg
198 
199  Parameters
200  ----------
201  uri : URI or path to a RepositoryCfg
202  Description
203 
204  Returns
205  -------
206  A RepositoryCfg instance or None
207  """
208 
209  @classmethod
210  @abstractmethod
211  def putRepositoryCfg(cls, cfg, loc=None):
212  """Serialize a RepositoryCfg to a location.
213 
214  When loc == cfg.root, the RepositoryCfg is to be written at the root
215  location of the repository. In that case, root is not written, it is
216  implicit in the location of the cfg. This allows the cfg to move from
217  machine to machine without modification.
218 
219  Parameters
220  ----------
221  cfg : RepositoryCfg instance
222  The RepositoryCfg to be serailized.
223  loc : string, optional
224  The URI location (can be relative path) to write the RepositoryCfg.
225  If loc is None, the location will be read from the root parameter
226  of loc.
227 
228  Returns
229  -------
230  None
231  """
232 
233  @classmethod
234  @abstractmethod
235  def getMapperClass(cls, root):
236  """Get the mapper class associated with a repository root.
237 
238  Parameters
239  ----------
240  root : string
241  The location of a persisted RepositoryCfg is (new style repos).
242 
243  Returns
244  -------
245  A class object or a class instance, depending on the state of the
246  mapper when the repository was created.
247  """
248 
249  # Optional: Only needs to work if relative paths are sensical on this
250  # storage type and for the case where fromPath and toPath are of the same
251  # storage type.
252  @classmethod
253  def relativePath(cls, fromPath, toPath):
254  """Get a relative path from a location to a location.
255 
256  Parameters
257  ----------
258  fromPath : string
259  A path at which to start. It can be a relative path or an
260  absolute path.
261  toPath : string
262  A target location. It can be a relative path or an absolute path.
263 
264  Returns
265  -------
266  string
267  A relative path that describes the path from fromPath to toPath.
268  """
269  return toPath
270 
271  # Optional: Only needs to work if relative paths and absolute paths are
272  # sensical on this storage type and for the case where fromPath and toPath
273  # are of the same storage type.
274  @classmethod
275  def absolutePath(cls, fromPath, relativePath):
276  """Get an absolute path for the path from fromUri to toUri
277 
278  Parameters
279  ----------
280  fromPath : the starting location
281  A location at which to start. It can be a relative path or an
282  absolute path.
283  relativePath : the location relative to fromPath
284  A relative path.
285 
286  Returns
287  -------
288  string
289  Path that is an absolute path representation of fromPath +
290  relativePath, if one exists. If relativePath is absolute or if
291  fromPath is not related to relativePath then relativePath will be
292  returned.
293  """
294  return relativePath