24 from abc
import ABCMeta, abstractmethod
32 """Defines the interface for a connection to a Storage location.
37 URI or path that is used as the storage location.
39 If True The StorageInterface subclass should create a new
40 repository at the root location. If False then a new repository
46 If create is False and a repository does not exist at the root
47 specified by uri then NoRepositroyAtRoot is raised.
49 __metaclass__ = ABCMeta
56 def write(self, butlerLocation, obj):
57 """Writes an object to a location and persistence format specified by ButlerLocation
61 butlerLocation : ButlerLocation
62 The location & formatting for the object to be written.
64 The object to be written.
68 def read(self, butlerLocation):
69 """Read from a butlerLocation.
73 butlerLocation : ButlerLocation
74 The location & formatting for the object(s) to be read.
78 A list of objects as described by the butler location. One item for
79 each location in butlerLocation.getLocations()
84 """Get a handle to a local copy of the file, downloading it to a
90 A path to the the file in storage, relative to root.
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.
102 """Check if location exists.
106 location : ButlerLocation or string
107 A a string or a ButlerLocation that describes the location of an
108 object in this storage.
113 True if exists, else False.
118 """Search for the given path in this storage instance.
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]'].
128 A filename (and optionally prefix path) to search for within root.
133 The location that was found, or None if no location was found.
139 """Look for the given path in the current root.
141 Also supports searching for the path in Butler v1 repositories by
142 following the Butler v1 _parent symlink
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]'].
152 The path to the root directory.
154 The path to the file within the root directory.
159 The location that was found, or None if no location was found.
164 """Copy a file from one location to another on the local filesystem.
168 fromLocation : string
169 Path and name of existing file.
171 Path and name of new file.
180 """Get the full path to the location.
185 Path to a location within the repository relative to repository
191 Absolute path to to the locaiton within the repository.
197 """Get a persisted RepositoryCfg
201 uri : URI or path to a RepositoryCfg
206 A RepositoryCfg instance or None
212 """Serialize a RepositoryCfg to a location.
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.
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
236 """Get the mapper class associated with a repository root.
241 The location of a persisted RepositoryCfg is (new style repos).
245 A class object or a class instance, depending on the state of the
246 mapper when the repository was created.
254 """Get a relative path from a location to a location.
259 A path at which to start. It can be a relative path or an
262 A target location. It can be a relative path or an absolute path.
267 A relative path that describes the path from fromPath to toPath.
276 """Get an absolute path for the path from fromUri to toUri
280 fromPath : the starting location
281 A location at which to start. It can be a relative path or an
283 relativePath : the location relative to fromPath
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