API Reference

Directory

class Dir(entries=None)

Directory layout class. See Use cases for examples.

Example

>>> from dirlay import Dir

>>> Dir({'docs/index.rst': '', 'src': {}, 'pyproject.toml': '\n'}).data
{'docs': {'index.rst': ''}, 'src': {}, 'pyproject.toml': '\n'}

>>> Dir({'a/b/c/d/e/f.txt': '', 'a/b/c/d/ee': {}}).data
{'a': {'b': {'c': {'d': {'e': {'f.txt': ''}, 'ee': {}}}}}}

__contains__(path)

Check whether directory layout object contains path defined.

__enter__()

Enter context manager.

__eq__(other)

Two directory layouts are equal if they have:

• equal files and directories (both path and data)

• equal basedir

__exit__(exc_type, exc_val, exc_tb)

Exit context manager.

__floordiv__(path)

Return absolute Path object for sub-path; equivalent to tree[path].abspath.

Directory layout must be linked to the file system.

__getitem__(path)

Return Node object from string path.

__ior__(entries)

Append dict of entries to self.

Equivalent to self.update(entries).

__iter__()

Iterate over tuples of path and value.

__or__(entries)

Append dict of entries to a copy of self.

Equivalent to x = self.copy(); x.update(entries).

__truediv__(path)

Return relative Path object; equivalent to tree[path].relpath.

as_rich(real_basedir=False, show_data=False, **kwargs)

Return Tree representation; rich must be installed. See Print as tree for examples.

Parameters:

• real_basedir (bool) – Whether to show real base directory name instead of '.'; defaults to False.

• show_data (bool) – Whether to include file content in the box under the file name; defaults to False.

• kwargs (Any) – Optional keyword arguments passed to Tree.

Returns:

Tree

chdir(path=None)

Change current directory to a subdirectory relative to layout base.

Parameters:

path (Path | str | None) – Relative path to subdirectory to be chdir’ed to; if None (default), basedir will be used.

Returns:

None

Raises:

ValueError – If path is absolute.

copy()

Return a deep copy of self.

items()

Iterate over tuples of str and Node objects relative to layout root.

keys()

Get all string paths relative to layout root.

leaves()

Get all Node objects representing files or empty directories.

mktree(basedir=None, chdir=None)

Create directories and files in given or temporary directory.

Parameters:

• basedir (Path | str | None, optional) – Path to base directory under which directories and files will be created; if None (default), temporary directory is used. After the directory structure is created, basedir value is available as basedir attribute.

• chdir (Path | str | bool | None, optional) – Change the current directory to given path. If None (default) or False, directory is not changed; True is equivalent to '.'.

Returns:

None

Raises:

FileExistsError – If basedir path already exists.

print_rich(real_basedir=False, show_data=False, **kwargs)

Print Tree representation. See as_rich.

Returns:

None

rmtree()

Remove directory and all its contents.

If basedir was created, it will be removed. If chdir argument was passed, current working directory will be restored to the original one.

Returns:

None

root()

Get root Node object.

update(entries)

Update or add entries from dictionary.

values()

Get all Node objects relative to layout root.

property basedir

Base filesystem directory as Path object.

When None, directory layout object is not instantiated (not created on the file system).

property data

Internal data mapping.

Node

class Node(key, base, basedir)

Node proxy object representing directory or file.

key

String path relative to Dir root, and also a mapping key:

>>> tree = Dir({'a': {'b.md': 'B'}})
>>> tree[tree['a/b.md'].key] == tree['a/b.md']
True

Type:

str

data

In-memory file content if the node is a file, or, if isdir is True, a dictionary, representing directory structure.

Type:

str | dict[str, str | dict]

abspath

Absolute node path, if directory layout is linked to the filesystem, or None otherwise.

Type:

Path | None

relpath

Node path relative to basedir of parent Dir; corresponds to key

Type:

Path

isdir

Whether the node is a directory.

Type:

bool

Utilities

getcwd()

Get current working directory.

Works for Python 2 and 3.

Returns:

Path

Type aliases

>>> from dirlay.types import DictTree, DictNode

DictTree

User representation of directory structure to be provided as input to Dir constructor or update method and operations:

>>> tree = Dir({'a': {'b.md': 'b file content'}})
>>> tree |= {'c.md': 'c file content'}

Type:

TypeAlias

alias of Mapping[str, DictNode]

DictNode

User representation of directory node — a file or a directory.

Type:

TypeAlias

alias of str | Mapping[str, DictNode]