paths
¶
Functions for paths and files.
Changed in version 1.0.0: Removed relpath2
.
Use domdf_python_tools.paths.relpath()
instead.
Classes:
|
Compare the content of |
|
Subclass of |
|
|
|
Securely creates a temporary directory using the same rules as |
|
|
Data:
Invariant |
|
Invariant |
|
A list of directories which will likely be unwanted when searching directory trees for files. |
Functions:
|
Append |
|
Write string to |
|
Compare the content of two directory trees. |
|
Alternative to |
|
Delete the file in the current directory. |
|
Context manager to change into the given directory for the duration of the |
|
Make the given file executable. |
|
Given a filename and a glob pattern, return whether the filename matches the glob. |
|
Create a directory at the given path, but only if the directory does not already exist. |
|
Returns the path of the parent directory for the given file or directory. |
|
Read a file in the current directory (in text mode). |
|
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 the |
|
Traverse the parents of the given directory until the desired file is found. |
|
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
anda
.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. Defaultfilecmp.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 aPathPlus
will return either aPosixPathPlus
or aWindowsPathPlus
. object. You can also instantiate aPosixPathPlus
orWindowsPath
directly, but cannot instantiate aWindowsPathPlus
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 afile
URI returned bypathlib.PurePath.as_uri()
.is_relative_to
(*other)Returns whether the path is relative to another path.
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 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
todst
.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.
-
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.
-
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'
.json_library (
JsonLibrary
) – The JSON serialisation library to use. Defaultjson
.compress (
bool
) – Whether to compress the JSON file using gzip. DefaultFalse
.**kwargs – Keyword arguments to pass to the JSON serialisation function.
Changed in version 1.0.0: Now uses
PathPlus.write_clean
rather thanPathPlus.write_text
, and as a result returnsNone
rather thanint
.Changed in version 1.9.0: Added the
compress
keyword-only argument.
-
classmethod
from_uri
(uri)[source]¶ Construct a
PathPlus
from afile
URI returned bypathlib.PurePath.as_uri()
.New in version 2.9.0.
-
is_relative_to
(*other)[source]¶ Returns whether the path is relative to another path.
New in version 0.3.8: for Python 3.9 and above.
New in version 1.4.0: for Python 3.6 and Python 3.7.
- Return type
-
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 bymatchglob()
. DefaultNone
.matchcase (
bool
) – Whether the filename’s case should match the pattern. DefaultTrue
.
- Return type
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'
.json_library (
JsonLibrary
) – The JSON serialisation library to use. Defaultjson
.decompress (
bool
) – Whether to decompress the JSON file using gzip. Will raise an exception if the file is not compressed. DefaultFalse
.**kwargs – Keyword arguments to pass to the JSON deserialisation function.
- Return type
- Returns
The deserialised JSON data.
Changed in version 1.9.0: Added the
compress
keyword-only argument.
-
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. Default511
.parents (
bool
) – IfFalse
(the default), a missing parent raises aFileNotFoundError
. IfTrue
, 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
todst
.self
may be a file or a directory.See
shutil.move()
for more details.New in version 3.2.0.
-
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
- Return type
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.
-
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.
-
stream
(chunk_size=1024)[source]¶ Stream the file in
chunk_size
sized chunks.- Parameters
chunk_size (
int
) – The chunk size, in bytes. Default1024
.
New in version 3.2.0.
-
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.
-
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
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
Changed in version 3.1.0: Added the
newline
argument to match Python 3.10. (see python/cpython#22420)- Return type
-
-
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 aPathPlus
object.New in version 2.4.0.
Methods:
cleanup
()Cleanup the temporary directory by removing it and its contents.
Attributes:
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 thewith
block.
-
name
¶ Type:
PathPlus
The temporary directory itself.
This will be assigned to the target of the
as
clause if theTemporaryPathPlus
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 topathlib.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 todomdf_python_tools.paths.PathPlus
.New in version 2.3.0.
-
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 adirs_exist_ok
argument, which has the same result.- Parameters
dst (
Union
[str
,Path
,PathLike
]) – Destination to copy file tosymlinks (
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 supportos.symlink()
. DefaultFalse
.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. DefaultNone
.
- Return type
-
in_directory
(directory)[source]¶ Context manager to change into the given directory for the duration of the
with
block.
-
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
- Return type
See also
Glob (programming)#Syntax on Wikipedia
Changed in version 2.5.0: Added the
matchcase
option.
-
maybe_make
(directory, mode=511, parents=False)[source]¶ Create a directory at the given path, but only if the directory does not already exist.
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()
.- Parameters
directory (
Union
[str
,Path
,PathLike
]) – Directory to createmode (
int
) – Combined with the process’s umask value to determine the file mode and access flags. Default511
.parents (
bool
) – IfFalse
(the default), a missing parent raises aFileNotFoundError
. IfTrue
, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIXmkdir -p
command).
Changed in version 1.6.0: Removed the
'exist_ok'
option, since it made no sense in this context.
-
parent_path
(path)[source]¶ Returns the path of the parent directory for the given file or directory.
-
relpath
(path, relative_to=None)[source]¶ 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.
-
traverse_to_file
(base_directory, *filename, height=- 1)[source]¶ Traverse the parents of the given directory until the desired file is found.
New in version 1.7.0.
-
unwanted_dirs
= ('.git', '.hg', 'venv', '.venv', '.mypy_cache', '__pycache__', '.pytest_cache', '.tox', '.tox4', '.nox', '__pypackages__')¶ Type:
tuple
A list of directories which will likely be unwanted when searching directory trees for files.
New in version 2.3.0.
Changed in version 2.9.0: Added
.hg
(mercurial)Changed in version 3.0.0: Added
__pypackages__
(PEP 582)Changed in version 3.2.0: Added
.nox
(https://nox.thea.codes/)