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
59 """Register a formatter for a storageInterface subclass
63 cls : StorageInterface subclass
64 The type of StorageInterface the formatter is being registered for.
65 formatable : class object
66 The class object whose instances can be formatted by the formatter.
67 formatter : Formatter class
68 The formatter class that can be used by the StorageInterface instance to read and write the object
74 For each object type and StorageInterface subclass a formatter should only be registered once. If
75 a second registration occurs a RuntimeError is raised.
77 classFormatters = StorageInterface.formatters.setdefault(cls, {})
78 if formatable
in classFormatters:
79 raise RuntimeError((
"Registration of second formatter {} for formattable class {} in " +
80 " storageInterface {}").format(formatter, formatable, cls))
81 classFormatters[formatable] = formatter
84 def _getFormatter(cls, objType):
85 """Search in the registered formatters for the formatter for obj.
87 Will attempt to find formatters registered for the objec type, and then
88 for base classes of the object in resolution order.
93 The type of class to find a formatter for.
97 formatter class object
98 The formatter class object to instantiate & use to read/write the object from/into the
101 classFormatters = StorageInterface.formatters.get(cls,
None)
102 if classFormatters
is None:
104 return classFormatters.get(objType,
None)
107 def write(self, butlerLocation, obj):
108 """Writes an object to a location and persistence format specified by ButlerLocation
112 butlerLocation : ButlerLocation
113 The location & formatting for the object to be written.
114 obj : object instance
115 The object to be written.
119 def read(self, butlerLocation):
120 """Read from a butlerLocation.
124 butlerLocation : ButlerLocation
125 The location & formatting for the object(s) to be read.
129 A list of objects as described by the butler location. One item for
130 each location in butlerLocation.getLocations()
135 """Get a handle to a local copy of the file, downloading it to a
141 A path to the the file in storage, relative to root.
145 A handle to a local copy of the file. If storage is remote it will be
146 a temporary file. If storage is local it may be the original file or
147 a temporary file. The file name can be gotten via the 'name' property
148 of the returned object.
153 """Check if location exists.
157 location : ButlerLocation or string
158 A a string or a ButlerLocation that describes the location of an
159 object in this storage.
164 True if exists, else False.
169 """Search for the given path in this storage instance.
171 If the path contains an HDU indicator (a number in brackets before the
172 dot, e.g. 'foo.fits[1]', this will be stripped when searching and so
173 will match filenames without the HDU indicator, e.g. 'foo.fits'. The
174 path returned WILL contain the indicator though, e.g. ['foo.fits[1]'].
179 A filename (and optionally prefix path) to search for within root.
184 The location that was found, or None if no location was found.
190 """Look for the given path in the current root.
192 Also supports searching for the path in Butler v1 repositories by
193 following the Butler v1 _parent symlink
195 If the path contains an HDU indicator (a number in brackets, e.g.
196 'foo.fits[1]', this will be stripped when searching and so
197 will match filenames without the HDU indicator, e.g. 'foo.fits'. The
198 path returned WILL contain the indicator though, e.g. ['foo.fits[1]'].
203 The path to the root directory.
205 The path to the file within the root directory.
210 The location that was found, or None if no location was found.
215 """Copy a file from one location to another on the local filesystem.
219 fromLocation : string
220 Path and name of existing file.
222 Path and name of new file.
231 """Get the full path to the location.
236 Path to a location within the repository relative to repository
242 Absolute path to to the locaiton within the repository.
248 """Get a persisted RepositoryCfg
252 uri : URI or path to a RepositoryCfg
257 A RepositoryCfg instance or None
263 """Serialize a RepositoryCfg to a location.
265 When loc == cfg.root, the RepositoryCfg is to be written at the root
266 location of the repository. In that case, root is not written, it is
267 implicit in the location of the cfg. This allows the cfg to move from
268 machine to machine without modification.
272 cfg : RepositoryCfg instance
273 The RepositoryCfg to be serailized.
274 loc : string, optional
275 The URI location (can be relative path) to write the RepositoryCfg.
276 If loc is None, the location will be read from the root parameter
287 """Get the mapper class associated with a repository root.
292 The location of a persisted RepositoryCfg is (new style repos).
296 A class object or a class instance, depending on the state of the
297 mapper when the repository was created.
305 """Get a relative path from a location to a location.
310 A path at which to start. It can be a relative path or an
313 A target location. It can be a relative path or an absolute path.
318 A relative path that describes the path from fromPath to toPath.
327 """Get an absolute path for the path from fromUri to toUri
331 fromPath : the starting location
332 A location at which to start. It can be a relative path or an
334 relativePath : the location relative to fromPath
340 Path that is an absolute path representation of fromPath +
341 relativePath, if one exists. If relativePath is absolute or if
342 fromPath is not related to relativePath then relativePath will be