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.

Parameters:tags (iterable) – 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.

items()

Get category (key, value) tuples.

Returns:items – (key, value) tuples; corresponds to dict.items.
Return type:list
keys()

Get category keys.

Returns:keys – Keys present among categories.
Return type:list
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.
Return type:list