Treants¶
Treants are the core units of functionality of datreant
. They function as
specially marked directories with distinguishing characteristics. They are
designed to be subclassed.
Treant¶
The class datreant.Treant
is the central object of datreant
.
-
class
datreant.
Treant
(treant, categories=None, tags=None)¶ The Treant: a discoverable Tree with metadata.
treant should be the directory of a new or existing Treant. An existing Treant will be used if a .datreant directory is found inside. If no .datreant directory is found inside, a new Treant will be created.
A Tree object may also be used in the same way as a directory string.
Parameters: - treant (str or Tree) – Base directory of a new or existing Treant; may also be a Tree object
- categories (dict) – dictionary with user-defined keys and values; used to give Treants distinguishing characteristics
- tags (list) – list with user-defined strings; like categories, but useful for adding many distinguishing descriptors
-
abspath
¶ Absolute path of
self.path
.
-
children
(hidden=False)¶ Return a View of all files and directories in this Tree.
Parameters: hidden (bool) – If True, include hidden files and directories. Returns: A View with files and directories in this Tree as members. Return type: View
-
draw
(depth=None, hidden=False)¶ Print an ASCII-fied visual of the tree.
Parameters:
-
exists
¶ Check existence of this path in filesystem.
-
glob
(pattern)¶ Return a View of all child Leaves and Trees matching given globbing pattern.
Parameters: pattern – globbing pattern to match files and directories with
-
leafloc
¶ Get Leaf at relative path.
Use with getitem syntax, e.g.
.treeloc['some name']
Allowed inputs are: - A single name - A list or array of names
If the given path resolves to an existing directory, then a
ValueError
will be raised.
-
leaves
(hidden=False)¶ Return a View of the files in this Tree.
Parameters: hidden (bool) – If True, include hidden files. Returns: A View with files in this Tree as members. Return type: View
-
loc
¶ Get Tree/Leaf at relative path.
Use with getitem syntax, e.g.
.loc['some name']
Allowed inputs are: - A single name - A list or array of names
If directory/file does not exist at the given path, then whether a Tree or Leaf is given is determined by the path semantics, i.e. a trailing separator (“/”).
Using e.g.
Tree.loc['some name']
is equivalent to doingTree['some name']
..loc
is included for parity withView
andBundle
API semantics.
-
make
()¶ Make the directory if it doesn’t exist. Equivalent to
makedirs()
.Returns: This Tree. Return type: Tree
-
makedirs
()¶ Make all directories along path that do not currently exist.
Returns: This Tree. Return type: Tree
-
name
¶ The name of the Treant.
-
parent
¶ Parent directory for this path.
-
path
¶ Filesystem path as a
pathlib2.Path
.
-
relpath
¶ Relative path of
self.path
from current working directory.
-
sync
(other, mode='upload', compress=True, checksum=True, backup=False, dry=False, include=None, exclude=None, overwrite=False, rsync_path='/usr/bin/rsync')¶ Synchronize directories using rsync.
Parameters: The other options are described in the
datreant.rsync.rsync()
documentation.
-
treeloc
¶ Get Tree at relative path.
Use with getitem syntax, e.g.
.treeloc['some name']
Allowed inputs are: - A single name - A list or array of names
If the given path resolves to an existing file, then a
ValueError
will be raised.
-
trees
(hidden=False)¶ Return a View of the directories in this Tree.
Parameters: hidden (bool) – If True, include hidden directories. Returns: A View with directories in this Tree as members. Return type: View
-
walk
(topdown=True, onerror=None, followlinks=False)¶ Walk through the contents of the tree.
For each directory in the tree (including the root itself), yields a 3-tuple (dirpath, dirnames, filenames).
Parameters: - topdown (Boolean, optional) – If False, walks directories from the bottom-up.
- onerror (function, optional) – Optional function to be called on error.
- followlinks (Boolean, optional) – If False, excludes symbolic file links.
Returns: Wrapped scandir.walk() generator yielding datreant objects
Return type: generator
Tags¶
The class datreant.metadata.Tags
is the interface used by Treants to
access their tags.
-
class
datreant.metadata.
Tags
(tree)¶ Interface to tags.
-
add
(*tags)¶ Add any number of tags to the Treant.
Tags are individual strings that serve to differentiate Treants from one another. Sometimes preferable to categories.
Parameters: tags (str or list) – Tags to add. Must be strings or lists of strings.
-
clear
()¶ Remove all tags from Treant.
-
fuzzy
(tag, threshold=80)¶ Get a tuple of existing tags that fuzzily match a given one.
Parameters: Returns: matches – Tuple of tags that match.
Return type:
-
remove
(*tags)¶ Remove tags from Treant.
Any number of tags can be given as arguments, and these will be deleted.
Arguments: - tags
Tags to delete.
-
Categories¶
The class datreant.metadata.Categories
is the interface used by
Treants to access their categories.
-
class
datreant.metadata.
Categories
(tree)¶ Interface to categories.
-
add
(categorydict=None, **categories)¶ Add any number of categories to the Treant.
Categories are key-value pairs that serve to differentiate Treants from one another. Sometimes preferable to tags.
If a given category already exists (same key), the value given will replace the value for that category.
Keys must be strings.
Values may be ints, floats, strings, or bools.
None
as a value will delete the existing value for the key, if present, and is otherwise not allowed.Parameters:
-
clear
()¶ Remove all categories from Treant.
-
keys
()¶ Get category keys.
Returns: - keys
keys present among categories
-
remove
(*categories)¶ Remove categories from Treant.
Any number of categories (keys) can be given as arguments, and these keys (with their values) will be deleted.
Parameters: categories (str) – Categories to delete.
-
values
()¶ Get category values.
Returns: - values
values present among categories
-