API documentation

Top Level Functions

These functions make use of the criteria, e.g. the predefined project types.

dirmagic.find_root(path='.', criterion=None, return_reason=False, **kwargs)

Find the project’s root.

path - the start path - will be converted into an asbolute path

criterion - can be a specific criterion, one of the project types or None (default) for a collection of criteria as used in pyprojroot.

return_reason - if True: returns (root, result), otherwise returns the root only.

resolve_path- will use pathlib.Path.resolve() to get an absolute start path. Otherwise os.path.abspath() is used (default).

limit_parents if None (default) all parents are considered, a positive number will consider the next n parents. A negative number will limit the search to the -limit_parents level in the file system.

list_parents("/home/me/projects/fancy-project/src", limit_parents=-2)

will search only src, fancy-project, and projects. A value of 1 will search src and fancy-projects.

Raises FileNotFoundError if no criteria were met.

Return type:

Union[Path, Tuple[Path, str]]

Parameters:

  • path (str | Path) –

  • criterion (Any) –

  • return_reason (bool) –

  • kwargs (Any) –

dirmagic.find_projects(path, criterion, maxdepth=1)

Search through all sub-directories inside path returning the directories matching the criterion.

The sub-directories are searched breadth first. Once a directory is matched, it is not searched for sub-projects.

maxdepth: the maximal iteration depth, unlimited if negative, will always return [] when 0. Warning: The function is not protected against cyclic symbolic links.

Return type:

List[Path]

Parameters:

  • path (str | Path) –

  • criterion (Any) –

  • maxdepth (int) –

dirmagic.identify_project(path='.', types_to_test=None)

Determines which criteria matche on path.

Returns list of (project category, project name).

Return type:

List[Tuple[str, str]]

Parameters:

  • path (str | Path) –

  • types_to_test (Sequence[ProjectType] | None) –

Generic Criteria

dirmagic.generic_criteria.Exists

alias of HasEntry

class dirmagic.generic_criteria.HasBasename(basename)

The directory’s basename is equal to the name specified.

Parameters:

basename (str) – expected basename

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['basename']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.generic_criteria.HasDir(dirname)

Match if a directory of the given name is present.

Parameters:

dirname (str | Path) –

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['dirname']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.generic_criteria.HasEntry(entryname)

Match if a filesystem entry (file/directory/link/…) of this name exists.

Note:

/ or /. at the end of the entryname are stripped off, i.e. oddly myfile/ will match a file - this is a sideffect of python’s pathlib.Path.joinpath. Consider using HasDir instead.

Parameters:

entryname (str | Path) –

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['entryname']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.generic_criteria.HasEntryGlob(pattern)

Search for filesystem entry matching the glob pattern.

The glob pattern allows searching in subdirectories.

Parameters:

pattern (str) –

describe()

Describes the test criterion.

Return type:

str

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.generic_criteria.HasFile(filename, contents=None, n=-1, fixed=False)

Matches if the named file is present, optionally the file’s contents can be matched.

Parameters:

  • filename (Union[str, Path]) – name of the file (can be in a subdirectory, a/b.txt)

  • contents (Optional[str]) – is the matching string or regular expression

  • n (int) – limits the number of lines searched, -1 is unlimited.

  • fixed (bool) – if set to true, the contents is matched as string

  • if fixed is True, contents must match an entire line (wo the newline character).

  • if fixed is False if the contents is a regular expression matching a part of the line using re.search() (i.e. use the anchors ^, $ for start and end).

This is the reimplementation of has_file from rprojroot.

check_file_contents(file)

Check whether in the contents of the file meets the line match criterion.

Return type:

bool

Parameters:

file (str | Path) –

describe()

Describes the test criterion.

Return type:

str

describe_contents_matching()
Return type:

str

static read_lines_from_file(file)

Read the lines from the text file and retruns them without the newline character at the end.

Return type:

Iterator[str]

Parameters:

file (str | Path) –

template_attributes: Optional[List[str]] = ['filename']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.generic_criteria.HasFileGlob(pattern, contents=None, n=-1, fixed=False)

Check whether a file exists with a name matching the glob pattern and (optionally) with matching contents.

Parameters:

  • pattern (str) – Is the pattern any file path will be matched against by using pathlib.Path.glob(). The glob pattern allows searching in subdirectories.

  • contents (str | None) –

  • n (int) –

  • fixed (bool) –

This is a reimplementation of matches_glob of pyprojroot (see pyprojroot code)

See HasFile for the parameters matching the contents.

describe()

Describes the test criterion.

Return type:

str

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.generic_criteria.HasFilePattern(pattern, contents=None, n=-1, fixed=False)

Check whether a file exists with a name matching regular expression pattern and (optionally) with matching contents.

Parameters:

  • pattern (str) – is the regular expression pattern any full path name will be matched against using re.search(). It searches only for entries inside the directory tested.

  • contents (str | None) –

  • n (int) –

  • fixed (bool) –

See HasFile for the parameters matching the contents.

This is the reimplementation of has_file_pattern from rprojroot (see rprojroot reference).

describe()

Describes the test criterion.

Return type:

str

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

dirmagic.generic_criteria.as_root_criterion(criterion)

Converts its input into a Criterion.

Return type:

Criterion

Parameters:

criterion (Any) –

File Pattern Criteria

class dirmagic.pattern_criteria.AllMatchCriterion(pattern, criterion)

Tests a criterion on entries matching. Is successful when all matching entries are tested successfully.

Parameters:

  • pattern (str) – regular expression pattern to match entries

  • criterion (Criterion) – criterion to test on each match

describe()

Describes the test criterion.

Return type:

str

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.pattern_criteria.AnyMatchCriterion(pattern, criterion)

Tests a criterion on entries matching. Is successful when any matching entry is tested successfully.

Parameters:

  • pattern (str) – regular expression pattern to match entries

  • criterion (Criterion) – criterion to test on each match

describe()

Describes the test criterion.

Return type:

str

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.pattern_criteria.FileMimeType(filename, mimetype)

Use mimetypes.guess_type() to determine whether the mime type of the filename is as expected.

Parameters:

  • filename (Union[str, Path]) – the filename used to guess the mime type

  • mimetype (str) – the mime type expected

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['filename']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.pattern_criteria.IsIn(name_template, names)

Checks whether the name of the file is one of the listed names.

Parameters:

  • name_template (str) – name - expanded if used with pattern matching

  • names (List[str]) – names expected

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['name_template']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

class dirmagic.pattern_criteria.MatchesPattern(name_template, pattern)

Checks whether the path is matching the pattern.

Parameters:

  • name_template (str) – name to use, expanded on test

  • pattern (Union[str, Pattern[str]]) – pattern to match against

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['name_template']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

class dirmagic.pattern_criteria.SpyCriterion

Helps debugging criteria by printing all test arguments.

describe()

Describes the test criterion.

Return type:

str

test(dir, *args, **kwargs)

This test prints the test arguments to stdout and returns True. Link this crtierion with & to the criteria you want to debug.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.pattern_criteria.SuffixIsIn(name_template, suffixes)

Checks whether the suffix of the filename is one of the listed suffixes.

Parameters:

  • name_template (str) – name - expanded if used with pattern matching

  • suffixes (List[str]) – suffixes expected, contains the dot (like .txt)

describe()

Describes the test criterion.

Return type:

str

template_attributes: Optional[List[str]] = ['name_template']
test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

dirmagic.pattern_criteria.translate(pat)

Translate a shell PATTERN to a regular expression. There is no way to quote meta-characters.

This is fnmatch.translate(), but capturing each matched group.

Parameters:

pat (str) –

Return type:

str

Project Type Criteria

dirmagic.project_types.is_anaconda_project = <ProjectType: Ide, anaconda project>

Anaconda IDE project directory

dirmagic.project_types.is_conda_feedstock = <ProjectType: Packaging, conda feedstock>

Conda Package Feedstock project

dirmagic.project_types.is_drake_project = <ProjectType: Data pipelines, drake>

drake project directory

drake is superceded by targets, see below.

dirmagic.project_types.is_dvc_root = <ProjectType: Data pipelines, dvc project>

Data Version Control (DVC) project directory

dirmagic.project_types.is_git_root = <ProjectType: Version control, git>

git repository directory

dirmagic.project_types.is_idea_project = <ProjectType: Ide, intellij idea project>

IntelliJ IDEA project directory

dirmagic.project_types.is_pkgdown_project = <ProjectType: Misc, pkgdown>

pkgdown project directory

dirmagic.project_types.is_projectile_project = <ProjectType: Ide, projectile project>

Projectile project directory

dirmagic.project_types.is_python_project = <ProjectType: Packaging, python package>

Python package project

dirmagic.project_types.is_r_package = <ProjectType: Packaging, r package>

R source package directory

dirmagic.project_types.is_remake_project = <ProjectType: Data pipelines, remake>

remake project directory

dirmagic.project_types.is_rstudio_project = <ProjectType: Ide, rstudio/posit>

RStudio project directory

dirmagic.project_types.is_spyder_project = <ProjectType: Ide, spyder project>

Spyder IDE project directory

dirmagic.project_types.is_svn_root = <ProjectType: Version control, subversion>

SVN repository directory

dirmagic.project_types.is_targets_project = <ProjectType: Data pipelines, targets>

targets project directory

dirmagic.project_types.is_testthat = <ProjectType: Misc, testthat project>

testthat directory

dirmagic.project_types.is_vcs_root = <ProjectType: Version control, repository>

Any repository (git, svn, …) directory

dirmagic.project_types.is_vscode_project = <ProjectType: Ide, visual studio code project>

Visual Studio Code IDE directory

This criterion tests specifically for .vscode/settings.json as there is a .vscode directory in the user’s home directory.

Core Criteria

class dirmagic.core_criteria.AllCriteria(*criteria)

The directory matches when all criteria are met.

Criteria can be linked together with & to form AllCriteria.

Parameters:

criteria (Criterion) –

describe()

Describes the test criterion.

Return type:

str

expand_pattern(*args, **kwargs)

finalizes the criterion using the match and test for the criterion

Return type:

AllCriteria

Parameters:

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

class dirmagic.core_criteria.AnyCriteria(*criteria)

The directory matches when at least one of the criteria is met.

Criteria can be linked together with | to form AnyCriteria.

Parameters:

criteria (Criterion) –

describe()

Describes the test criterion.

Return type:

str

expand_pattern(*args, **kwargs)

finalizes the criterion using the match and test for the criterion

Return type:

AnyCriteria

Parameters:

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

class dirmagic.core_criteria.Criterion

Abstract base class of a test criterion for a directory.

The Criterion.test() method returns the result of a test.

Criteria can be combined wiht the logical operators &, |, ~.

describe()

Describes the test criterion.

Return type:

str

expand_pattern(*args, **kwargs)

Finalizes the criterion by expanding the templated attributes using str.format() with the arguments supplied.

Return type:

Criterion

Parameters:

  • args (Any) –

  • kwargs (Any) –

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

template_attributes: Optional[List[str]] = None
abstract test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Any) –

  • kwargs (Any) –

class dirmagic.core_criteria.CriterionFromTestFun(testfun, description=None)

Create a criterion by providing a test function and optional description.

Parameters:

  • testfun (Callable[[str | Path], bool]) –

  • description (str | None) –

describe()

Describes the test criterion.

Return type:

str

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

class dirmagic.core_criteria.CriterionResult(result: bool, criterion: Criterion, path: str | Path, sub_results: Tuple[CriterionResult, ...] = ())

Returns the result of the check and the tests the result is based on.

The truthiness of the object reflects the test result, so it can be used in conditions straight away:

if is_dvc_root.test(data_repo):
    with dvc.api.open(
        'data/my_data.csv',
        repo=data_repo
    ) as f:
        # ... f is a file-like object that can be processed normally.

The methods simple_tree(), rich_tree() and reason() help to inspect the result.

Parameters:
criterion: Criterion

test criterion

static indent_text(text, indent)
Return type:

str

Parameters:

  • text (str) –

  • indent (str) –

path: Union[str, Path]

path tested

reason()

The reason is a human readable text describing why the check gave the result as it did. If the check is successful, then the reason can be the same as the description. If the check fails, then the reason should contain a statement why it failed, i.e. the negation of the successful reason.

Return type:

str

result: bool

test result

rich_tree()

Result tree rendered with rich text layout using rich.tree.Tree.

Please install the rich package (see Optional Dependencies).

Return type:

Tree

simple_tree()

Simple result tree with (nested) indented lines

Return type:

str

sub_results: Tuple[CriterionResult, ...]

results of sub-tests to evaluate this criterion

class dirmagic.core_criteria.NotCriterion(criterion)
Parameters:

criterion (Criterion) –

describe()

Describes the test criterion.

Return type:

str

expand_pattern(*args, **kwargs)

finalizes the criterion using the match and test for the criterion

Return type:

NotCriterion

Parameters:

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –

dirmagic.core_criteria.PathSpec

Path types expected by the functions in this package.

alias of Union[str, Path]

class dirmagic.core_criteria.ProjectType(name, category, criterion)

Defines a project type with a name, a category and the test criterion.

Parameters:

  • name (str) –

  • category (str) –

  • criterion (Criterion) –

category: str

categories like: version control, packaging, IDE

criterion: Criterion

The criterion to test the directory

describe()

Describes the test criterion.

Return type:

str

name: str

project name

rich_tree()

Display the criterion as a rich.tree.Tree.

Return type:

rich.tree.Tree

test(dir, *args, **kwargs)

Tests whether the criterion is met for path.

Return type:

CriterionResult

Parameters:

  • dir (str | Path) –

  • args (Tuple[Any, ...]) –

  • kwargs (Dict[str, Any]) –