module

stow.artefacts

</>
Classes
  • 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 work
  • File — A filesystem file object - a container of bytes representing some data
  • SubFile — A file object of a submanager. Wrapper for a complete Manager File
  • Directory — A directory represents an local filesystems directory or folder. Directories hold references to other directories or files
  • SubDirectory — A directory object of a submanager. Wrapper for a complete Manager directory

Warning

Artefacts are created by managers - you should not initialise Artefact objects directly.

Classes

class

stow.artefacts.Artefact(manager, path)

</>

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 work

Parameters
  • manager (ManagerInterface) — The submanager this file belongs to
  • path (str) — The file's relative path
Attributes
  • accessedTime — UTC localised datetime of time file last modified by a write/append method
  • basename — Basename of the artefact - holding directory path removed leaving filename and extension
  • createdTime — UTC localised datetime of time file last modified by a write/append method
  • directory — Directory object this artefact exists within
  • manager — Return the manager object this Artefact belongs to
  • modifiedTime — UTC localised datetime of time file last modified by a write/append method
  • name — Name of artefact - for File this is without extension
  • path — Return the manager relative path to this Artefact
Methods
  • delete(force) — Delete this artefact from the disk
  • save(path, force) — Save the artefact to a local location
method

save(path, force=False)

</>

Save the artefact to a local location

Parameters
  • path (str) — A local path where the Artefact is to be saved
  • force (bool, optional) — Ignore artefacts at the destination location
Raises
  • OperationNotPermitted — If the location given is a Directory and the get is not enforced
method

delete(force=False)

</>

Delete this artefact from the disk

Parameters
  • force (bool, optional) — An "are you sure" for directories
Raises
  • OperationNotPermitted — If directory and deletion has not been deleted
class

stow.artefacts.File(manager, path, size, modifiedTime, createdTime=None, accessedTime=None)

</>
Bases
stow.artefacts.Artefact

A filesystem file object - a container of bytes representing some data

Parameters
  • manager (ManagerInterface) — The submanager this file belongs to
  • path (str) — The file's relative path
  • size (float) — The size in bytes of the file content
  • modifiedTime (datetime) — The time the file was last modified via a write/append operation
Attributes
  • accessedTime — UTC localised datetime of time file last modified by a write/append method
  • basename — Basename of the artefact - holding directory path removed leaving filename and extension
  • content (bytes) — file content as bytes
  • createdTime — UTC localised datetime of time file last modified by a write/append method
  • directory — Directory object this artefact exists within
  • extension — File extension string - extention indicates file purpose and associated applications
  • manager — Return the manager object this Artefact belongs to
  • modifiedTime — UTC localised datetime of time file last modified by a write/append method
  • path — Return the manager relative path to this Artefact
  • size — Size of file content in bytes
Methods
  • delete(force) — Delete this artefact from the disk
  • localise() (str) — Localise this File artefact
  • open(mode, **kwargs) — Context manager to allow the pulling down and opening of a file
  • save(path, force) — Save the artefact to a local location
method

save(path, force=False)

</>

Save the artefact to a local location

Parameters
  • path (str) — A local path where the Artefact is to be saved
  • force (bool, optional) — Ignore artefacts at the destination location
Raises
  • OperationNotPermitted — If the location given is a Directory and the get is not enforced
method

delete(force=False)

</>

Delete this artefact from the disk

Parameters
  • force (bool, optional) — An "are you sure" for directories
Raises
  • OperationNotPermitted — If directory and deletion has not been deleted
generator

localise()

</>

Localise this File artefact

Returns (str)

the absolute local path to the manager path

generator

open(mode='r', **kwargs)

</>

Context manager to allow the pulling down and opening of a file

class

stow.artefacts.Directory(manager, path, createdTime=None, modifiedTime=None, accessedTime=None)

</>
Bases
stow.artefacts.Artefact

A directory represents an local filesystems directory or folder. Directories hold references to other directories or files

Parameters
  • manager (stow.Manager) — The manager this directory object belongs to
  • path (str) — the manager relative path for the object
Attributes
  • accessedTime — UTC localised datetime of time file last modified by a write/append method
  • basename — Basename of the artefact - holding directory path removed leaving filename and extension
  • createdTime — UTC localised datetime of time file last modified by a write/append method
  • directory — Directory object this artefact exists within
  • manager — Return the manager object this Artefact belongs to
  • modifiedTime — UTC localised datetime of time file last modified by a write/append method
  • name — Name of artefact - for File this is without extension
  • path — Return the manager relative path to this Artefact
Methods
  • delete(force) — Delete this artefact from the disk
  • empty() — Empty the directory of contents
  • isEmpty() (bool) — Check whether the directory has contents
  • localise(path) (str) — Localise an artefact this directory or a child artefact with the provided path.
  • ls(path, recursive) (typing.Set[Artefact]) — List the contents of this directory, or directory's directories.
  • mkdir(path) (Directory) — Create a directory nested inside this Directory with the relative path given
  • open(path, mode, **kwargs) (io.IOBase) — Open a file and create a stream to that file. Expose interface of open
  • relpath(artefact) (str) — Assuming the artefact is a member of this directory, return a filepath which is relative to this directory
  • rm(path, recursive) — Remove an artefact at the given location
  • save(path, force) — Save the artefact to a local location
  • touch(path) (File) — Touch a file at given location relative to this Directory
method

save(path, force=False)

</>

Save the artefact to a local location

Parameters
  • path (str) — A local path where the Artefact is to be saved
  • force (bool, optional) — Ignore artefacts at the destination location
Raises
  • OperationNotPermitted — If the location given is a Directory and the get is not enforced
method

delete(force=False)

</>

Delete this artefact from the disk

Parameters
  • force (bool, optional) — An "are you sure" for directories
Raises
  • OperationNotPermitted — If directory and deletion has not been deleted
method

mkdir(path)

</>

Create a directory nested inside this Directory with the relative path given

Parameters
  • path (str) — Relative path to directory, path to new directory location
Returns (Directory)

The newly created directory object

method

touch(path)

</>

Touch a file at given location relative to this Directory

Parameters
  • path (str) — The relative path to directory to touch new file
Returns (File)

The newly created file object

method

relpath(artefact)

</>

Assuming the artefact is a member of this directory, return a filepath which is relative to this directory

Parameters
  • artefact (Artefact or str) — the artefact who's path will be made relative
Returns (str)

the relative path to the artefact from this directory

Raises
  • ArtefactNotMember — raised when artefact is not a member of the directory
generator

localise(path=None)

</>

Localise an artefact this directory or a child artefact with the provided path.

Parameters
  • path (str, optional) — Path of localisation
Returns (str)

the absolute local path to the manager path

generator

open(path, mode='r', **kwargs)

</>

Open a file and create a stream to that file. Expose interface of open

Parameters
  • path (str) — Path to directory object
  • mode (str, optional) — The open method
  • kwargs — kwargs to be passed to the interface of open
Yields (io.IOBase)

An IO object depending on the mode for interacting with the file

method

rm(path=None, recursive=False)

</>

Remove an artefact at the given location

Parameters
  • recursive (bool, optional) — If the target is a directory, whether to delete recursively the directories contents
  • artefact — Path that is to be deleted
Raises
  • OperationNotPermitted — In the even the target is a directory and recursive has not been toggled
method

ls(path=None, recursive=False)

</>

List the contents of this directory, or directory's directories.

Parameters
  • path (str, optional) — The path to sub directory whose contents is to be returned
  • recursive (bool, optional) — Whether to recursively fetch all child contents for child directories
Returns (typing.Set[Artefact])

The collection of objects within the targeted directory

method

isEmpty()

</>

Check whether the directory has contents

Returns (bool)

True when there is at least one item in the directory False when the directory is empty

method

empty()

</>

Empty the directory of contents