stow
Packages
stow.manager
Modules
stow.artefacts
Artefact— Artefacts are the items that are being stored - it is possible that through another mechanism that these items are deleted and they are no longer able to workFile— A filesystem file object - a container of bytes representing some dataSubFile— A file object of a submanager. Wrapper for a complete Manager FileDirectory— A directory represents an local filesystems directory or folder. Directories hold references to other directories or filesSubDirectory— A directory object of a submanager. Wrapper for a complete Manager directory
stow.exceptions
ArtefactNotFound— An artefact cannot be found at a locationArtefactNotMember— An artefact is not a member of aManagerorDirectoryArtefactTypeError— Expected an artefact of another typeArtefactNoLongerExists— The artefact cannot be accessed because its persistent representation has been deleted or moved.OperationNotPermitted— You do not have permission to perform this actionInvalidPath— Path given is not a valid stow path. See documentationArtefactNotAvailable— The artefact is not available to be able to fulfil the requested operation
Functions
find(manager)
Fetch the Manager class hosted on the 'stow_managers' entrypoint with the given name manager entry name.
manager(str) — The name of theManagerclass to be returned
The Manager class for the manager name provided
ValueError— In the event that a manager with the provided name couldn't be found
wrapper(manager, **kwargs)
parseURL(stowURL)
Parse the passed stow URL and return a ParsedURL a named tuple of manager and relpath
manager, relpath = stow.parseURL("s3://example-bucket/path/to/file)
result = stow.parseURL("s3://example-bucket/path/to/file) result.manager result.relpath
stowURL(str) — The path to be parsed and manager identified
Holding the manager and relative path of
artefact(stowPath)
Fetch an artefact object for the given path
Params: stowPath: Manager relative path to artefact
The artefact object
ArtefactNotFound— In the event that no artefact exists at the location given
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
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
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
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
touch(relpath)
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
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
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
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
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)
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
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
Variables
supports_unicode_filenames()
True if arbitrary Unicode strings can be used as file names (within limitations imposed by the file system).