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:	depth (int, optional) – Maximum directory depth to display. `None` indicates no limit. hidden (bool) – If True, show hidden files and directories.

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 doing Tree['some name']. .loc is included for parity with View and Bundle 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:	other (str or Tree) – Other end of the sync, can be either a path or another Tree. mode (str) – Either `"upload"` if uploading to other, or `"download"` if downloading from other

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:	tags (str or list) – Tag or tags to get fuzzy matches for. threshold (int) – Lowest match score to return. Setting to 0 will return every tag, while setting to 100 will return only exact matches.
Returns:	matches – Tuple of tags that match.
Return type:	tuple

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:	categorydict (dict) – Dict of categories to add; keys used as keys, values used as values. categories (dict) – Categories to add. Keyword used as key, value used as value.

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