`paths`

Functions for paths and files.

Changed in version 1.0.0: Removed relpath2. Use domdf_python_tools.paths.relpath() instead.

Classes:

`DirComparator`(a, b[, ignore, hide])	Compare the content of `a` and `a`.
`PathPlus`(args, *kwargs)	Subclass of `pathlib.Path` with additional methods and a default encoding of UTF-8.
`PosixPathPlus`(args, *kwargs)	`PathPlus` subclass for non-Windows systems.
`TemporaryPathPlus`([suffix, prefix, dir])	Securely creates a temporary directory using the same rules as `tempfile.mkdtemp()`.
`WindowsPathPlus`(args, *kwargs)	`PathPlus` subclass for Windows systems.

Data:

`_P`	Invariant `TypeVar` bound to `pathlib.Path`.
`_PP`	Invariant `TypeVar` bound to `domdf_python_tools.paths.PathPlus`.
`unwanted_dirs`	A list of directories which will likely be unwanted when searching directory trees for files.

Functions:

`append`(var, filename, **kwargs)	Append `var` to the file `filename` in the current directory.
`clean_writer`(string, fp)	Write string to `fp` without trailing spaces.
`compare_dirs`(a, b)	Compare the content of two directory trees.
`copytree`(src, dst[, symlinks, ignore])	Alternative to `shutil.copytree()` to support copying to a directory that already exists.
`delete`(filename, **kwargs)	Delete the file in the current directory.
`in_directory`(directory)	Context manager to change into the given directory for the duration of the `with` block.
`make_executable`(filename)	Make the given file executable.
`matchglob`(filename, pattern[, matchcase])	Given a filename and a glob pattern, return whether the filename matches the glob.
`maybe_make`(directory[, mode, parents])	Create a directory at the given path, but only if the directory does not already exist.
`parent_path`(path)	Returns the path of the parent directory for the given file or directory.
`read`(filename, **kwargs)	Read a file in the current directory (in text mode).
`relpath`(path[, relative_to])	Returns the path for the given file or directory relative to the given directory or, if that would require path traversal, returns the absolute path.
`sort_paths`(*paths)	Sort the `paths` by directory, then by file.
`traverse_to_file`(base_directory, *filename)	Traverse the parents of the given directory until the desired file is found.
`write`(var, filename, **kwargs)	Write a variable to file in the current directory.

class DirComparator(a, b, ignore=None, hide=None)[source]

Bases: dircmp

Compare the content of a and a.

In contrast with filecmp.dircmp, this subclass compares the content of files with the same path.

New in version 2.7.0.

Parameters

a (Union[str, Path, PathLike]) – The “left” directory to compare.
b (Union[str, Path, PathLike]) – The “right” directory to compare.
ignore (Optional[Sequence[str]]) – A list of names to ignore. Default filecmp.DEFAULT_IGNORES.
hide (Optional[Sequence[str]]) – A list of names to hide. Default [ os.curdir, os.pardir ].

class PathPlus(*args, **kwargs)[source]

Bases: Path

Subclass of pathlib.Path with additional methods and a default encoding of UTF-8.

Path represents a filesystem path but, unlike pathlib.PurePath, also offers methods to do system calls on path objects. Depending on your system, instantiating a PathPlus will return either a PosixPathPlus or a WindowsPathPlus. object. You can also instantiate a PosixPathPlus or WindowsPath directly, but cannot instantiate a WindowsPathPlus on a POSIX system or vice versa.

New in version 0.3.8.

Changed in version 0.5.1: Defaults to Unix line endings (LF) on all platforms.

Methods:

`abspath`()	Return the absolute version of the path.
`append_text`(string[, encoding, errors])	Open the file in text mode, append the given string to it, and close the file.
`dump_json`(data[, encoding, errors, …])	Dump `data` to the file as JSON.
`from_uri`(uri)	Construct a `PathPlus` from a `file` URI returned by `pathlib.PurePath.as_uri()`.
`iterchildren`([exclude_dirs, match, matchcase])	Returns an iterator over all children (files and directories) of the current path object.
`load_json`([encoding, errors, json_library, …])	Load JSON data from the file.
`make_executable`()	Make the file executable.
`maybe_make`([mode, parents])	Create a directory at this path, but only if the directory does not already exist.
`move`(dst)	Recursively move `self` to `dst`.
`open`([mode, buffering, encoding, errors, …])	Open the file pointed by this path and return a file object, as the built-in `open()` function does.
`read_lines`([encoding, errors])	Open the file in text mode, return a list containing the lines in the file, and close the file.
`read_text`([encoding, errors])	Open the file in text mode, read it, and close the file.
`stream`([chunk_size])	Stream the file in `chunk_size` sized chunks.
`write_clean`(string[, encoding, errors])	Write to the file without trailing whitespace, and with a newline at the end of the file.
`write_lines`(data[, encoding, errors, …])	Write the given list of lines to the file without trailing whitespace.
`write_text`(data[, encoding, errors, newline])	Open the file in text mode, write to it, and close the file.

abspath()[source]

Return the absolute version of the path.

New in version 1.3.0.

Return type: PathPlus

append_text(string, encoding='UTF-8', errors=None)[source]

Open the file in text mode, append the given string to it, and close the file.

New in version 0.3.8.

Parameters

string (str)
encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.

dump_json(data, encoding='UTF-8', errors=None, json_library=<module 'json'>, *, compress=False, **kwargs)[source]

Dump data to the file as JSON.

New in version 0.5.0.

Parameters

data (Any) – The object to serialise to JSON.
encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.
json_library (JsonLibrary) – The JSON serialisation library to use. Default json.
compress (bool) – Whether to compress the JSON file using gzip. Default False.
**kwargs – Keyword arguments to pass to the JSON serialisation function.

Changed in version 1.0.0: Now uses PathPlus.write_clean rather than PathPlus.write_text, and as a result returns None rather than int.

Changed in version 1.9.0: Added the compress keyword-only argument.

classmethod from_uri(uri)[source]

Construct a PathPlus from a file URI returned by pathlib.PurePath.as_uri().

New in version 2.9.0.

Parameters: uri (str)
Return type: PathPlus

iterchildren(exclude_dirs=('.git', '.hg', 'venv', '.venv', '.mypy_cache', '__pycache__', '.pytest_cache', '.tox', '.tox4', '.nox', '__pypackages__'), match=None, matchcase=True)[source]

Returns an iterator over all children (files and directories) of the current path object.

New in version 2.3.0.

Parameters

exclude_dirs (Optional[Iterable[str]]) – A list of directory names which should be excluded from the output, together with their children. Default ('.git', '.hg', 'venv', '.venv', '.mypy_cache', '__pycache__', '.pytest_cache', '.tox', '.tox4', '.nox', '__pypackages__').
match (Optional[str]) – A pattern to match filenames against. The pattern should be in the format taken by matchglob(). Default None.
matchcase (bool) – Whether the filename’s case should match the pattern. Default True.

Return type

Iterator[~_PP]

Changed in version 2.5.0: Added the matchcase option.

load_json(encoding='UTF-8', errors=None, json_library=<module 'json'>, *, decompress=False, **kwargs)[source]

Load JSON data from the file.

New in version 0.5.0.

Parameters

encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.
json_library (JsonLibrary) – The JSON serialisation library to use. Default json.
decompress (bool) – Whether to decompress the JSON file using gzip. Will raise an exception if the file is not compressed. Default False.
**kwargs – Keyword arguments to pass to the JSON deserialisation function.

Return type

Any

Returns

The deserialised JSON data.

Changed in version 1.9.0: Added the compress keyword-only argument.

make_executable()[source]: Make the file executable.

New in version 0.3.8.

maybe_make(mode=511, parents=False)[source]

Create a directory at this path, but only if the directory does not already exist.

New in version 0.3.8.

Parameters

mode (int) – Combined with the process’ umask value to determine the file mode and access flags. Default 511.
parents (bool) – If False (the default), a missing parent raises a FileNotFoundError. If True, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command).

Changed in version 1.6.0: Removed the 'exist_ok' option, since it made no sense in this context.

Attention

This will fail silently if a file with the same name already exists. This appears to be due to the behaviour of os.mkdir().

move(dst)[source]

Recursively move self to dst.

self may be a file or a directory.

See shutil.move() for more details.

New in version 3.2.0.

Parameters: dst (Union[str, Path, PathLike])
Returns: The new location of self.
Return type: PathPlus

open(mode='r', buffering=- 1, encoding='UTF-8', errors=None, newline=NEWLINE_DEFAULT)[source]

Open the file pointed by this path and return a file object, as the built-in open() function does.

New in version 0.3.8.

Parameters

mode (str) – The mode to open the file in. Default 'r' (read only).
buffering (int) – Default -1.
encoding (Optional[str]) – Default 'UTF-8'.
errors (Optional[str]) – Default None.
newline (Optional[str]) – Default universal newlines for reading, Unix line endings (LF) for writing.

Return type

IO[Any]

Changed in version 0.5.1: Defaults to Unix line endings (LF) on all platforms.

read_lines(encoding='UTF-8', errors=None)[source]

Open the file in text mode, return a list containing the lines in the file, and close the file.

New in version 0.5.0.

Parameters

encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.

Return type

List[str]

Returns

The content of the file.

read_text(encoding='UTF-8', errors=None)[source]

Open the file in text mode, read it, and close the file.

New in version 0.3.8.

Parameters

encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.

Return type

str

Returns

The content of the file.

stream(chunk_size=1024)[source]

Stream the file in chunk_size sized chunks.

Parameters: chunk_size (int) – The chunk size, in bytes. Default 1024.

New in version 3.2.0.

Return type: Iterator[bytes]

write_clean(string, encoding='UTF-8', errors=None)[source]

Write to the file without trailing whitespace, and with a newline at the end of the file.

New in version 0.3.8.

Parameters

string (str)
encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.

write_lines(data, encoding='UTF-8', errors=None, *, trailing_whitespace=False)[source]

Write the given list of lines to the file without trailing whitespace.

New in version 0.5.0.

Parameters

data (Iterable[str])
encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.
trailing_whitespace (bool) – If True trailing whitespace is preserved. Default False.

Changed in version 2.4.0: Added the trailing_whitespace option.

write_text(data, encoding='UTF-8', errors=None, newline=NEWLINE_DEFAULT)[source]

Open the file in text mode, write to it, and close the file.

New in version 0.3.8.

Parameters

data (str)
encoding (Optional[str]) – The encoding to write to the file in. Default 'UTF-8'.
errors (Optional[str]) – Default None.
newline (Optional[str]) – Default universal newlines for reading, Unix line endings (LF) for writing.

Changed in version 3.1.0: Added the newline argument to match Python 3.10. (see python/cpython#22420)

Return type: int

class PosixPathPlus(*args, **kwargs)[source]

Bases: PathPlus, PurePosixPath

PathPlus subclass for non-Windows systems.

On a POSIX system, instantiating a PathPlus object should return an instance of this class.

New in version 0.3.8.

class TemporaryPathPlus(suffix=None, prefix=None, dir=None)[source]

Bases: TemporaryDirectory

Securely creates a temporary directory using the same rules as tempfile.mkdtemp(). The resulting object can be used as a context manager. On completion of the context or destruction of the object the newly created temporary directory and all its contents are removed from the filesystem.

Unlike tempfile.TemporaryDirectory() this class is based around a PathPlus object.

New in version 2.4.0.

Methods:

cleanup()

Cleanup the temporary directory by removing it and its contents.

Attributes:

name

The temporary directory itself.

cleanup()[source]

Cleanup the temporary directory by removing it and its contents.

If the TemporaryPathPlus is used as a context manager this is called when leaving the with block.

name

Type: PathPlus

The temporary directory itself.

This will be assigned to the target of the as clause if the TemporaryPathPlus is used as a context manager.

class WindowsPathPlus(*args, **kwargs)[source]

Bases: PathPlus, PureWindowsPath

PathPlus subclass for Windows systems.

On a Windows system, instantiating a PathPlus object should return an instance of this class.

New in version 0.3.8.

The following methods are unsupported on Windows:

_P = TypeVar(_P, bound=Path)

Type: TypeVar

Invariant TypeVar bound to pathlib.Path.

New in version 0.11.0.

Changed in version 1.7.0: Now bound to pathlib.Path.

_PP = TypeVar(_PP, bound=PathPlus)

Type: TypeVar

Invariant TypeVar bound to domdf_python_tools.paths.PathPlus.

New in version 2.3.0.

append(var, filename, **kwargs)[source]

Append var to the file filename in the current directory.

Parameters

var (str) – The value to append to the file
filename (Union[str, Path, PathLike]) – The file to append to

Return type

int

clean_writer(string, fp)[source]

Write string to fp without trailing spaces.

Parameters

string (str)
fp (IO)

compare_dirs(a, b)[source]

Compare the content of two directory trees.

New in version 2.7.0.

Parameters

a (Union[str, Path, PathLike]) – The “left” directory to compare.
b (Union[str, Path, PathLike]) – The “right” directory to compare.

Return type

bool

Returns

False if they differ, True is they are the same.

copytree(src, dst, symlinks=False, ignore=None)[source]

Alternative to shutil.copytree() to support copying to a directory that already exists.

Based on https://stackoverflow.com/a/12514470 by https://stackoverflow.com/users/23252/atzz

In Python 3.8 and above shutil.copytree() takes a dirs_exist_ok argument, which has the same result.

Parameters

src (Union[str, Path, PathLike]) – Source file to copy
dst (Union[str, Path, PathLike]) – Destination to copy file to
symlinks (bool) – Whether to represent symbolic links in the source as symbolic links in the destination. If false or omitted, the contents and metadata of the linked files are copied to the new tree. When symlinks is false, if the file pointed by the symlink doesn’t exist, an exception will be added in the list of errors raised in an Error exception at the end of the copy process. You can set the optional ignore_dangling_symlinks flag to true if you want to silence this exception. Notice that this option has no effect on platforms that don’t support os.symlink(). Default False.
ignore (Optional[Callable]) – A callable that will receive as its arguments the source directory, and a list of its contents. The ignore callable will be called once for each directory that is copied. The callable must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. shutil.ignore_patterns() can be used to create such a callable that ignores names based on glob-style patterns. Default None.

Return type

Union[str, Path, PathLike]

delete(filename, **kwargs)[source]

Delete the file in the current directory.

Parameters: filename (Union[str, Path, PathLike]) – The file to delete

in_directory(directory)[source]

Context manager to change into the given directory for the duration of the with block.

Parameters: directory (Union[str, Path, PathLike])

make_executable(filename)[source]

Make the given file executable.

Parameters: filename (Union[str, Path, PathLike])

matchglob(filename, pattern, matchcase=True)[source]

Given a filename and a glob pattern, return whether the filename matches the glob.

New in version 2.3.0.

Parameters

filename (Union[str, Path, PathLike])
pattern (str) – A pattern structured like a filesystem path, where each element consists of the glob syntax. Each element is matched by fnmatch. The special element ** matches zero or more files or directories.
matchcase (bool) – Whether the filename’s case should match the pattern. Default True.

Return type

bool

paths

`paths`