stow.manager
Important
All Manager objects express the public interface defined below, so only the Manager interface is listed for reference.
You should not (and cannot) initialise this class.
For extending the class for bespoke managers, you should import and extend either the LocalManager or the RemoteManager. Information on how to do that can be found here.
Manager()
Manager Abstract base class - expressed the interface of a Manager which governs a storage option and allows extraction and placement of files in that storage container
ABCMeta— Metaclass for defining Abstract Base Classes (ABCs).
__getitem__(path)(artefact) — Fetch an artefact from the manager. In the event that it hasn't been cached, look it up on the underlying implementation and return a newly created object. If it doesn't exist raise an errorabspath(artefact)(str) — Return a normalized absolute version of the path or artefact given.basename(artefact)(str) — Return the base name of an artefact or path. This is the second element of the pair returned by passing path to the functionsplit().commonpath(paths)(str) — Return the longest common sub-path of each pathname in the sequence pathscommonprefix(paths)(str) — Return the longest common string literal for a collection of path/artefactscp(source,destination,overwrite)(Artefact) — Copy the artefacts at the source location to the provided destination location. Overwriting items at the destination.dirname(artefact)(str) — Return the directory name of path or artefact. Preserve the protocol of the path if a protocol is givenexists(artefact)(bool) — Return true if the given artefact is a member of the manager, or the path is correct for the manager and it leads to a File or Directory.expanduser(path)(str) — On Unix and Windows, return the argument with an initial component of ~ or ~user replaced by that user’s home directory.expandvars(path)(str) — Return the argument with environment variables expanded. Substrings of the form $name or ${name} are replaced by the value of environment variable name. Malformed variable names and references to non-existing variables are left unchanged.extension(artefact)(str) — Return the extension of an artefact or path.get(source,destination,overwrite)(typing.Union[typing.Any, bytes]) — Get a remote artefact from the storage option and write it to the destination path given.getatime(artefact)(timestamp) — Get the accessed time for the artefact as a UTC timestampgetctime(artefact)(timestamp) — Get the created time for the artefact as a UTC timestampgetmtime(artefact)(timestamp) — Get the modified time for the artefact as a UTC timestampisabs(path)(bool) — Return True if path is an absolute pathname. On Unix, that means it begins with a slash, on Windows that it begins with a (back)slash after chopping off a potential drive letter.isdir(artefact)(Bool) — Check if the artefact provided is a directoryisfile(artefact)(Bool) — Check if the artefact provided is a fileislink(artefact)(Bool) — Check if the artefact provided is a linkismount(artefact)(Bool) — Check if the artefact provided is a linkjoin(*paths,separator,joinAbsolutes)(str) — Join one or more path components intelligently. The return value is the concatenation of path and any members of *paths with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If a component is an absolute path, all previous components are thrown away and joining continues from the absolute path component.lexists(artefact)(bool) — Return true if the given artefact is a member of the manager, or the path is correct for the manager and it leads to a File or Directory.localise(artefact)(str) — Localise an artefact, ensure that there is an absolute path that reaches this artefact. For local artefacts this will be the direct abspath. Remote managers will get the artefact, and pass back the path to this local version.ls(art,recursive)({Artefact}) — List contents of the directory path/artefact given.md5(path)— TODOmkdir(path,ignoreExists,overwrite)(Directory) — Make a directory at the location of the path provided. By default - do nothing in the event that the location is already a directory object.mv(source,destination,overwrite)(Artefact) — Copy the artefacts at the source location to the provided destination location. Overwriting items at the destination.name(artefact)(str) — Return the name of an artefact or path (basename without extension).normcase(path)(str) — Normalize the case of a pathname. On Windows, convert all characters in the pathname to lowercase, and also convert forward slashes to backward slashes. On other operating systems, return the path unchanged.normpath(path)(str) — Normalize a pathname by collapsing redundant separators and up-level references so that A//B, A/B/, A/./B and A/foo/../B all become A/B.open(artefact,mode,**kwargs)(io.IOBase) — Open a file and create a stream to that file. Expose interface ofopenput(source,destination,overwrite)(Artefact) — Put a local artefact onto the remote at the location given.realpath(path)(str) — Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path (if they are supported by the operating system).relpath(path,start)(str) — Return a relative filepath to path either from the current directory or from an optional start directoryrm(artefact,recursive)— Remove an artefact from the manager using the artefact object or its relative path. If its a directory, remove it if it is empty, or all of its contents if recursive has been set to true.samefile(artefact1,artefact2)(bool) — Check if provided artefacts are represent the same data on disksameopenfile(handle1,handle2)(bool) — Return True if the file descriptors fp1 and fp2 refer to the same file.samestat(artefact1,artefact2)(bool) — Check if provided artefacts are represent the same data on disksplit(artefact)(dirname, basename) — Split the pathname path into a pair, (head, tail) where tail is the last pathname component and head is everything leading up to that.splitdrive(path)(drive, path) — Split the pathname path into a pair (drive, tail) where drive is either a mount point or the empty string.splitext(artefact)(root, ext) — Split the pathname path into a pair (root, ext) such that root + ext == path, and ext is empty or begins with a period and contains at most one period.submanager(uri)(SubManager) — Create a submanager at the given uri which shall behave like a conventional manager, however, its actions shall be relative to the given uri and shall update the main manager.sync(source,destination,overwrite,delete)— Put artefacts in the source location into the destination location if they have more recently been edittedtoConfig()(dict) — Generate a config which can be unpacked into theconnectinterface to initialise this manager. To be used to seralise and de-seralise a manager object.
abspath(artefact)
Return a normalized absolute version of the path or artefact given.
artefact(Artefact or str) — The path or object whose path is to be made absolute and returned
the absolute path of the artefact provided
ValueError— Cannot make a remote artefact object's path absolute
basename(artefact)
Return the base name of an artefact or path. This is the second element of the pair returned by passing path
to the function split().
artefact(Artefact or str) — The path or object whose path is to have its base name extracted
the basename
name(artefact)
Return the name of an artefact or path (basename without extension).
artefact(Artefact or str) — The path or object whose path is to have its base name extracted
the name e.g. /hello/there.txt => there
extension(artefact)
Return the extension of an artefact or path.
artefact(Artefact or str) — The path or object whose path is to have its base name extracted
the extension e.g. /hello/there.txt => txt
commonpath(paths)
Return the longest common sub-path of each pathname in the sequence paths
commonpath(["/foo/bar", "/foo/ban/pip"]) == "/foo"
paths(iterable of Artefact or str) — Artefact/paths who will have their paths comparied to find a common path
A valid owning directory path that is the shared owning directory for all paths
ValueError— If there is no crossover at all
commonprefix(paths)
Return the longest common string literal for a collection of path/artefacts
commonpath(["/foo/bar", "/foo/ban/pip"]) == "/foo/ba"
paths(iterable of Artefact or str) — Artefact/paths who will have their paths comparied to find a common path
A string that all paths startwith (may be empty string)
dirname(artefact)
Return the directory name of path or artefact. Preserve the protocol of the path if a protocol is given
artefact(Artefact or str) — The artefact or path whose directory path is to be returned
The directory path for the holding directory of the artefact
expanduser(path)
On Unix and Windows, return the argument with an initial component of ~ or ~user replaced by that user’s home directory.
On Unix, an initial ~ is replaced by the environment variable HOME if it is set; otherwise the current user’s home directory is looked up in the password directory through the built-in module pwd. An initial ~user is looked up directly in the password directory.
On Windows, USERPROFILE will be used if set, otherwise a combination of HOMEPATH and HOMEDRIVE will be used. An initial ~user is handled by stripping the last directory component from the created user path derived above.
If the expansion fails or if the path does not begin with a tilde, the path is returned unchanged.
path(str) — the path which may contain a home variable indicator to be expanded
A path with the home path factored in - if applicable
expandvars(path)
Return the argument with environment variables expanded. Substrings of the form $name or ${name} are replaced by the value of environment variable name. Malformed variable names and references to non-existing variables are left unchanged.
On Windows, %name% expansions are supported in addition to $name and ${name}.
path(str) — A path which might contain variables to be expanded
A string with any environment variables added
isabs(path) → bool
Return True if path is an absolute pathname. On Unix, that means it begins with a slash, on Windows that it begins with a (back)slash after chopping off a potential drive letter.
path(str) — the path to be checked for being absolute
join(*paths, separator='/', joinAbsolutes=False)
Join one or more path components intelligently. The return value is the concatenation of path and any members of *paths with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If a component is an absolute path, all previous components are thrown away and joining continues from the absolute path component.
Protocols/drive letters are perserved in the event that an absolute is passed in.
*paths(iterable of str) — segments of a path to be joined togetherseparator(optional) — The character to be used to join the path segmentsjoinAbsolutes(bool, optional) — Whether to stick to normal behaviour continue from absolute paths or join them in series
A joined path
normcase(path)
Normalize the case of a pathname. On Windows, convert all characters in the pathname to lowercase, and also convert forward slashes to backward slashes. On other operating systems, return the path unchanged.
path(str) — path to normalise
the path normalised
normpath(path)
Normalize a pathname by collapsing redundant separators and up-level references so that A//B, A/B/, A/./B and A/foo/../B all become A/B.
path(str) — the path whose to be
The path transformed
realpath(path)
Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path (if they are supported by the operating system).
path(str) — the path to have symbolic links corrected
the path with the symbolic links corrected
relpath(path, start='.') → str
Return a relative filepath to path either from the current directory or from an optional start directory
path(str) — the path to be made relativestart(optional) — the location to become relative to
samefile(artefact1, artefact2)
Check if provided artefacts are represent the same data on disk
artefact1(Artefact or str) — An artefact object or pathartefact2(Artefact or str) — An artefact object or path
True if the artefacts are the same
sameopenfile(handle1, handle2) → bool
Return True if the file descriptors fp1 and fp2 refer to the same file.
samestat(artefact1, artefact2)
Check if provided artefacts are represent the same data on disk
artefact1(Artefact or str) — An artefact object or pathartefact2(Artefact or str) — An artefact object or path
True if the artefacts are the same
split(artefact)
Split the pathname path into a pair, (head, tail) where tail is the last pathname component and head is everything leading up to that.
artefact(Artefact or str) — the artefact to be split
the split parts of the artefact
splitdrive(path)
Split the pathname path into a pair (drive, tail) where drive is either a mount point or the empty string.
path(str) — the path whose mount point/drive is to be removed
tuple with drive string separated from the path
splitext(artefact)
Split the pathname path into a pair (root, ext) such that root + ext == path, and ext is empty or begins with a period and contains at most one period.
artefact(Artefact or str) — the artefact to have the extension extracted
The root path without the extension and the extension
md5(path)
TODO
ABCMeta(name, bases, namespace, **kwargs)
Metaclass for defining Abstract Base Classes (ABCs).
Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete classes (even built-in classes) and unrelated ABCs as 'virtual subclasses' -- these and their descendants will be considered subclasses of the registering ABC by the built-in issubclass() function, but the registering ABC won't show up in their MRO (Method Resolution Order) nor will method implementations defined by the registering ABC be callable (not even via super()).
__instancecheck__(cls,instance)— Override for isinstance(instance, cls).__subclasscheck__(cls,subclass)— Override for issubclass(subclass, cls).register(cls,subclass)— Register a virtual subclass of an ABC.
register(cls, subclass)Register a virtual subclass of an ABC.
Returns the subclass, to allow usage as a class decorator.
__instancecheck__(cls, instance)Override for isinstance(instance, cls).
__subclasscheck__(cls, subclass)Override for issubclass(subclass, cls).
localise(artefact)
Localise an artefact, ensure that there is an absolute path that reaches this artefact. For local artefacts this will be the direct abspath. Remote managers will get the artefact, and pass back the path to this local version.
A path is still returned even if the artefact doesn't exist. It will be the responsibility of the calling method to handle what is localised.
artefact(Artefact or str) — The artefact path or artefact object
The abspath for the artefact
toConfig()
Generate a config which can be unpacked into the connect interface to initialise this manager. To be
used to seralise and de-seralise a manager object.
NOTE Defaulted values or environment variables are not guaranteed to be saved
A dictionary of the kwargs of the init of the manager
__getitem__(path)
Fetch an artefact from the manager. In the event that it hasn't been cached, look it up on the underlying implementation and return a newly created object. If it doesn't exist raise an error
managerPath— The manager relative path to fine the artefact with
The artefact at the provided location path
ArtefactNotFound— In the event that the path does not exist
isfile(artefact)
Check if the artefact provided is a file
artefact(Artefact or str) — The artefact to be checked
True or False in answer to the question
isdir(artefact)
Check if the artefact provided is a directory
artefact(Artefact or str) — The artefact to be checked
True or False in answer to the question
islink(artefact)
Check if the artefact provided is a link
Will check for local managers but will default to False for remote managers
artefact(Artefact or str) — The artefact to be checked
True or False in answer to the question
ismount(artefact)
Check if the artefact provided is a link
Will check for local managers but will default to False for remote managers
artefact(Artefact or str) — The artefact to be checked
True or False in answer to the question
getctime(artefact)
Get the created time for the artefact as a UTC timestamp
artefact(Artefact or str) — the artefact whose creation datetime is to be returned
a float timestamp of creation time if manager holds such information else None
ArtefactNotFound— If there is no artefact at the location
getmtime(artefact)
Get the modified time for the artefact as a UTC timestamp
artefact(Artefact or str) — the artefact whose modified datetime is to be returned
a float timestamp of modified time if manager holds such information else None
ArtefactNotFound— If there is no artefact at the location
getatime(artefact)
Get the accessed time for the artefact as a UTC timestamp
artefact(Artefact or str) — the artefact whose accessed datetime is to be returned
a float timestamp of accessed time if manager holds such information else None
ArtefactNotFound— If there is no artefact at the location
exists(artefact)
Return true if the given artefact is a member of the manager, or the path is correct for the manager and it leads to a File or Directory.
Does not handle protocols
artefact(Artefact or str) — Artefact or path whose existence is to be checked
True if artefact exists else False
lexists(artefact)
Return true if the given artefact is a member of the manager, or the path is correct for the manager and it leads to a File or Directory.
Does not handle protocols
artefact(Artefact or str) — Artefact or path whose existence is to be checked
True if artefact exists else False
get(source, destination=None, overwrite=False)
Get a remote artefact from the storage option and write it to the destination path given.
source(Artefact/str) — The remote's file object or its pathdestination(str) — The local path for the artefact to be written to
Return user defined response for get if file written to destination else return bytes if no destination given
put(source, destination, overwrite=False) → Artefact
Put a local artefact onto the remote at the location given.
overwrite(bool) — Whether to accept the overwriting of a target destination when it is a directorysrc_local(str) — The path to the local artefact that is to be put on the remotedest_remote(Artefact/str) — A file object to overwrite or the relative path to a destination on the remote
cp(source, destination, overwrite=False)
Copy the artefacts at the source location to the provided destination location. Overwriting items at the destination.
source(Artefact or str) — source path or artefactdestination(Artefact or str) — destination path or artefactoverwrite(bool, optional) — Whether to overwrite directories my move
The destination artefact object
mv(source, destination, overwrite=False)
Copy the artefacts at the source location to the provided destination location. Overwriting items at the destination.
source(Artefact or str) — source path or artefactdestination(Artefact or str) — destination path or artefactoverwrite(bool, optional) — Whether to overwrite directories my move
The destination artefact object (source object updated if source was on manager originally)
rm(artefact, recursive=False)
Remove an artefact from the manager using the artefact object or its relative path. If its a directory, remove it if it is empty, or all of its contents if recursive has been set to true.
artefact(typing.Union[Artefact, str]) — the object which is to be deletedrecursive(bool) — whether to accept the deletion of a directory which has contents
ls(art='/', recursive=False)
List contents of the directory path/artefact given.
art(Directory/str) — The Directory artefact or the relpath to the directory to be listedrecursive(bool) — Return subdirectory contents as well
The artefact objects which are within the directory
mkdir(path, ignoreExists=True, overwrite=False)
Make a directory at the location of the path provided. By default - do nothing in the event that the location is already a directory object.
path(str) — Relpath to the location where a directory is to be createdignoreExists(bool) — Whether to do nothing if a directory already existsoverwrite(bool) — Whether to overwrite the directory with an empty directory
The directory at the given location - it may have been created as per the call
OperationNotPermitted— In the event that you try to overwrite a directory that already exists without passing the overwrite flag
sync(source, destination, overwrite=False, delete=False)
Put artefacts in the source location into the destination location if they have more recently been editted
source(Directory) — source directory artefactdestination(Directory) — destination directory artefact on the managerdelete(bool, optional) — Togger the deletion of artefacts that are members of the destination which do not conflict with the source.
ArtefactNotFound— In the event that the source directory doesn't exist
open(artefact, mode='r', **kwargs)
Open a file and create a stream to that file. Expose interface of open
artefact(File or str) — The object that represents the file (or path to the file) to be openned by this managermode(str, optional) — The open methodkwargs— kwargs to be passed to the interface of open
An IO object depending on the mode for interacting with the file
submanager(uri)
Create a submanager at the given uri which shall behave like a conventional manager, however, its actions shall be relative to the given uri and shall update the main manager.
If a manager exists at the uri specified already, then it is returned.
uri(str) — The uri of the target location for the manager to be setup. If the uri does not exist, a directory shall be created. If it exists, the manager shall require it be a Directory object
A sub manager at the given uri
ArtefactTypeError— if there exists an object at the location which isn't a directoryValueError— Raised if uri is top level directory