Package plumbum.path¶

class plumbum.path.base.FSUser(val, name=None)[source]¶

A special object that represents a file-system user. It derives from int, so it behaves just like a number (uid/gid), but also have a .name attribute that holds the string-name of the user, if given (otherwise None)

static __new__(cls, val, name=None)[source]¶

Return type:: Self

class plumbum.path.base.Path[source]¶

An abstraction over file system paths. This class is abstract, and the two implementations are LocalPath and RemotePath.

__repr__()[source]¶

Return repr(self).

Return type:: str

__truediv__(other)[source]¶

Joins two paths

Return type:: Self

__rtruediv__(other)[source]¶

Joins two paths when this path appears on the right-hand side.

Return type:: Self

__getitem__(key)[source]¶

Overloads:

self, key (str | Path) → Self
self, key (SupportsIndex | slice) → str

Return self[key].

__floordiv__(expr)[source]¶

Returns a (possibly empty) list of paths that matched the glob-pattern under this path

Return type:: list[Self]

__iter__()[source]¶

Iterate over the files in this directory

Return type:: Iterator[Self]

__eq__(other)[source]¶

Return self==value.

Return type:: bool

__ne__(other)[source]¶

Return self!=value.

Return type:: bool

__gt__(other)[source]¶

Return self>value.

Return type:: bool

__ge__(other)[source]¶

Return self>=value.

Return type:: bool

__lt__(other)[source]¶

Return self<value.

Return type:: bool

__le__(other)[source]¶

Return self<=value.

Return type:: bool

__hash__()[source]¶

Return hash(self).

Return type:: int

__fspath__()[source]¶

Added for Python 3.6 support

Return type:: str

__contains__(item)[source]¶

Paths should support checking to see if an file or folder is in them.

Return type:: bool

up(count=1)[source]¶

Go up in count directories (the default is 1)

Return type:: Self

joinpath(*others)[source]¶

Pathlib-compatible alias of join().

Added in version 2.0.

Return type:: Self

walk(filter=<function Path.<lambda>>, dir_filter=<function Path.<lambda>>)[source]¶

traverse all (recursive) sub-elements under this directory, that match the given filter. By default, the filter accepts everything; you can provide a custom filter function that takes a path as an argument and returns a boolean

Parameters:

filter (Callable[[Self], bool]) – the filter (predicate function) for matching results. Only paths matching this predicate are returned. Defaults to everything.
dir_filter (Callable[[Self], bool]) – the filter (predicate function) for matching directories. Only directories matching this predicate are recursed into. Defaults to everything.

Return type:

Generator[Self, None, None]

abstract property name¶: The basename component of this path

abstract property stem¶: The name without an extension, or the last component of the path

abstract property dirname¶: The dirname component of this path

abstract property root¶: The root of the file tree (/ on Unix)

abstract property drive¶: The drive letter (on Windows)

abstract property suffix¶: The suffix of this file

abstract property suffixes¶: This is a list of all suffixes

abstract property uid¶: The user that owns this path. The returned value is a FSUser object which behaves like an int (as expected from uid), but it also has a .name attribute that holds the string-name of the user

abstract property gid¶: The group that owns this path. The returned value is a FSUser object which behaves like an int (as expected from gid), but it also has a .name attribute that holds the string-name of the group

abstractmethod as_uri(scheme=Ellipsis)[source]¶

Returns a universal resource identifier. Use scheme to force a scheme.

Return type:: str

abstractmethod join(*parts)[source]¶

Joins this path with any number of paths

Return type:: Self

abstractmethod list()[source]¶

Returns the files in this directory

Return type:: list[Self]

abstractmethod iterdir()[source]¶

Returns an iterator over the directory. Might be slightly faster on Python 3.5 than .list()

Return type:: Iterable[Self]

abstractmethod is_dir()[source]¶

Returns True if this path is a directory, False otherwise

Return type:: bool

abstractmethod is_file()[source]¶

Returns True if this path is a regular file, False otherwise

Return type:: bool

abstractmethod is_symlink()[source]¶

Returns True if this path is a symbolic link, False otherwise

Return type:: bool

abstractmethod exists()[source]¶

Returns True if this path exists, False otherwise

Return type:: bool

abstractmethod stat()[source]¶

Returns the os.stats for a file

Return type:: stat_result

abstractmethod with_name(name)[source]¶

Returns a path with the name replaced

Return type:: Self

abstractmethod with_suffix(suffix, depth=1)[source]¶

Returns a path with the suffix replaced. Up to last depth suffixes will be replaced. None will replace all suffixes. If there are less than depth suffixes, this will replace all suffixes. .tar.gz is an example where depth=2 or depth=None is useful

Return type:: Self

preferred_suffix(suffix)[source]¶

Adds a suffix if one does not currently exist (otherwise, no change). Useful for loading files with a default suffix

Return type:: Self

with_stem(stem)[source]¶

Returns a path with the stem replaced.

Added in version 2.0.

Return type:: Self

abstractmethod glob(pattern)[source]¶

Returns a (possibly empty) list of paths that matched the glob-pattern under this path

Return type:: list[Self]

abstractmethod delete()[source]¶

Deletes this path (recursively, if a directory)

Return type:: None

abstractmethod move(dst)[source]¶

Moves this path to a different location

Return type:: Self

rename(newname)[source]¶

Renames this path to the new name (only the basename is changed)

Return type:: Self

rmdir()[source]¶

Removes this directory if it is empty.

Added in version 2.0.

Return type:: None

abstractmethod copy(dst, override=None)[source]¶

Copies this path (recursively, if a directory) to the destination path “dst”. Raises TypeError if dst exists and override is False. Will overwrite if override is True. Will silently fail to copy if override is None (the default).

Return type:: Self

abstractmethod mkdir(mode=511, parents=True, exist_ok=True)[source]¶

Creates a directory at this path.

Parameters:

mode (int) – Currently only implemented for local paths! Numeric mode to use for directory creation, which may be ignored on some systems. The current implementation reproduces the behavior of os.mkdir (i.e., the current umask is first masked out), but this may change for remote paths. As with os.mkdir, it is recommended to call chmod() explicitly if you need to be sure.
parents (bool) – If this is true (the default), the directory’s parents will also be created if necessary.
exist_ok (bool) – If this is true (the default), no exception will be raised if the directory already exists (otherwise OSError).

Return type:

None

Note that the defaults for parents and exist_ok are the opposite of what they are in Python’s own pathlib - this is to maintain backwards-compatibility with Plumbum’s behaviour from before they were implemented.

abstractmethod open(mode='r', *, encoding=None)[source]¶

opens this path as a file

Return type:: IO[str] | IO[bytes]

read_bytes()[source]¶

Returns the contents of this file as bytes.

Added in version 2.0.

Return type:: bytes

read_text(encoding=None, errors=None)[source]¶

Returns the contents of this file as str.

Added in version 2.0.

Return type:: str

abstractmethod read(encoding=None)[source]¶

returns the contents of this file as a str. By default the data is read as text, but you can specify the encoding, e.g., 'latin1' or 'utf8'

Return type:: str | bytes

abstractmethod write(data, encoding=None)[source]¶

writes the given data to this file. By default the data is written as-is (either text or binary), but you can specify the encoding, e.g., 'latin1' or 'utf8'

Return type:: None

write_bytes(data)[source]¶

Writes bytes to this file and returns the number of bytes written.

Added in version 2.0.

Return type:: int

write_text(data, encoding=None, errors=None, newline=None)[source]¶

Writes text to this file and returns the number of characters written.

Added in version 2.0.

Return type:: int

abstractmethod touch()[source]¶

Update the access time. Creates an empty file if none exists.

Return type:: None

abstractmethod chown(owner=None, group=None, recursive=None)[source]¶

Change ownership of this path.

Parameters:

owner (int | str | None) – The owner to set (either uid or username), optional
group (int | str | None) – The group to set (either gid or groupname), optional
recursive (bool | None) – whether to change ownership of all contained files and subdirectories. Only meaningful when self is a directory. If None, the value will default to True if self is a directory, False otherwise.

Return type:

None

abstractmethod chmod(mode)[source]¶

Change the mode of path to the numeric mode.

Parameters:: mode (int) – file mode as for os.chmod
Return type:: None

abstractmethod access(mode=0)[source]¶

Test file existence or permission bits

Parameters:: mode (int | str) – a bitwise-or of access bits, or a string-representation thereof: 'f', 'x', 'r', 'w' for os.F_OK, os.X_OK, os.R_OK, os.W_OK
Return type:: bool

abstractmethod link(dst)[source]¶

Creates a hard link from self to dst

Parameters:: dst (Self | str) – the destination path
Return type:: None

abstractmethod symlink(dst)[source]¶

Creates a symbolic link from self to dst

Parameters:: dst (Self | str) – the destination path
Return type:: None

symlink_to(target)[source]¶

Pathlib-compatible symbolic-link creation.

Creates a symbolic link at self that points to target.

Added in version 2.0.

Return type:: None

hardlink_to(target)[source]¶

Pathlib-compatible hard-link creation.

Creates a hard link at self that points to target.

Added in version 2.0.

Return type:: None

abstractmethod unlink()[source]¶

Deletes a symbolic link

Return type:: None

lstat()[source]¶

Like stat(). Backends may override for symlink-specific behavior.

Added in version 2.0.

Return type:: stat_result

split(*_args, **_kargs)[source]¶

Splits the path on directory separators, yielding a list of directories, e.g, "/var/log/messages" will yield ['var', 'log', 'messages'].

Return type:: list[str]

property parts¶: Splits the directory into parts, including the base directory, returns a tuple

property anchor¶: Pathlib-compatible anchor (drive + root).

Added in version 2.0.

as_posix()[source]¶

Returns the path string with POSIX separators.

Added in version 2.0.

Return type:: str

absolute()[source]¶

Returns an absolute version of this path.

Added in version 2.0.

Return type:: Self

is_absolute()[source]¶

Returns True if this path is absolute.

Added in version 2.0.

Return type:: bool

is_relative_to(other)[source]¶

Returns True when this path is within other.

Added in version 2.0.

Return type:: bool

samefile(other)[source]¶

Returns True if this path and other point to the same file.

Added in version 2.0.

Return type:: bool

match(pattern)[source]¶

Tests if this path matches a glob-style pattern.

Added in version 2.0.

Return type:: bool

rglob(pattern)[source]¶

Recursively glob under this path.

Added in version 2.0.

Return type:: list[Self]

relative_to(source)[source]¶

Computes the “relative path” require to get from source to self. They satisfy the invariant source_path + (target_path - source_path) == target_path. For example:

/var/log/messages - /var/log/messages = []
/var/log/messages - /var              = [log, messages]
/var/log/messages - /                 = [var, log, messages]
/var/log/messages - /var/tmp          = [.., log, messages]
/var/log/messages - /opt              = [.., var, log, messages]
/var/log/messages - /opt/lib          = [.., .., var, log, messages]

Return type:: RelativePath

__sub__(other)[source]¶

Same as self.relative_to(other)

Return type:: RelativePath

resolve(strict=False)[source]¶

Added to allow pathlib like syntax. Does nothing since Plumbum paths are always absolute. Does not (currently) resolve symlinks.

Return type:: Self

property parents¶: Pathlib like sequence of ancestors

property parent¶: Pathlib like parent of the path.

class plumbum.path.base.RelativePath(parts)[source]¶

Relative paths are the “delta” required to get from one path to another. Note that relative path do not point at anything, and thus are not paths. Therefore they are system agnostic (but closed under addition) Paths are always absolute and point at “something”, whether existent or not.

Relative paths are created by subtracting paths (Path.relative_to)

__init__(parts)[source]¶

__str__()[source]¶

Return str(self).

Return type:: str

__repr__()[source]¶

Return repr(self).

Return type:: str

__eq__(other)[source]¶

Return self==value.

Return type:: bool

__ne__(other)[source]¶

Return self!=value.

Return type:: bool

__gt__(other)[source]¶

Return self>value.

Return type:: bool

__ge__(other)[source]¶

Return self>=value.

Return type:: bool

__lt__(other)[source]¶

Return self<value.

Return type:: bool

__le__(other)[source]¶

Return self<=value.

Return type:: bool

__hash__()[source]¶

Return hash(self).

Return type:: int

class plumbum.path.local.LocalPath(*parts)[source]¶

The class implementing local-machine paths

static __new__(cls, *parts)[source]¶

Return type:: Self

property name¶: The basename component of this path

property dirname¶: The dirname component of this path

property suffix¶: The suffix of this file

property suffixes¶: This is a list of all suffixes

property uid¶: The user that owns this path. The returned value is a FSUser object which behaves like an int (as expected from uid), but it also has a .name attribute that holds the string-name of the user

property gid¶: The group that owns this path. The returned value is a FSUser object which behaves like an int (as expected from gid), but it also has a .name attribute that holds the string-name of the group

join(*others)[source]¶

Joins this path with any number of paths

Return type:: LocalPath

list()[source]¶

Returns the files in this directory

Return type:: list[LocalPath]

iterdir()[source]¶

Returns an iterator over the directory. Might be slightly faster on Python 3.5 than .list()

Return type:: Iterator[LocalPath]

is_dir()[source]¶

Returns True if this path is a directory, False otherwise

Return type:: bool

is_file()[source]¶

Returns True if this path is a regular file, False otherwise

Return type:: bool

is_symlink()[source]¶

Returns True if this path is a symbolic link, False otherwise

Return type:: bool

exists()[source]¶

Returns True if this path exists, False otherwise

Return type:: bool

stat()[source]¶

Returns the os.stats for a file

Return type:: stat_result

with_name(name)[source]¶

Returns a path with the name replaced

Return type:: LocalPath

property stem¶: The name without an extension, or the last component of the path

with_suffix(suffix, depth=1)[source]¶

Return type:: LocalPath

glob(pattern)[source]¶

Returns a (possibly empty) list of paths that matched the glob-pattern under this path

Return type:: list[LocalPath]

delete()[source]¶

Deletes this path (recursively, if a directory)

Return type:: None

move(dst)[source]¶

Moves this path to a different location

Return type:: LocalPath

copy(dst, override=None)[source]¶

Return type:: LocalPath

mkdir(mode=511, parents=True, exist_ok=True)[source]¶

Creates a directory at this path.

Parameters:

mode (int) – Currently only implemented for local paths! Numeric mode to use for directory creation, which may be ignored on some systems. The current implementation reproduces the behavior of os.mkdir (i.e., the current umask is first masked out), but this may change for remote paths. As with os.mkdir, it is recommended to call chmod() explicitly if you need to be sure.
parents (bool) – If this is true (the default), the directory’s parents will also be created if necessary.
exist_ok (bool) – If this is true (the default), no exception will be raised if the directory already exists (otherwise OSError).

Return type:

None

open(mode='r', encoding=None)[source]¶

opens this path as a file

Return type:: IO[str] | IO[bytes]

read(encoding=None, mode='r')[source]¶

returns the contents of this file as a str. By default the data is read as text, but you can specify the encoding, e.g., 'latin1' or 'utf8'

Return type:: str | bytes

write(data, encoding=None, mode=None)[source]¶

writes the given data to this file. By default the data is written as-is (either text or binary), but you can specify the encoding, e.g., 'latin1' or 'utf8'

Return type:: None

touch()[source]¶

Update the access time. Creates an empty file if none exists.

Return type:: None

chown(owner=None, group=None, recursive=None)[source]¶

Change ownership of this path.

Parameters:

owner (int | str | None) – The owner to set (either uid or username), optional
group (int | str | None) – The group to set (either gid or groupname), optional
recursive (bool | None) – whether to change ownership of all contained files and subdirectories. Only meaningful when self is a directory. If None, the value will default to True if self is a directory, False otherwise.

Return type:

None

chmod(mode)[source]¶

Change the mode of path to the numeric mode.

Parameters:: mode (int) – file mode as for os.chmod
Return type:: None

access(mode=0)[source]¶

Test file existence or permission bits

Parameters:: mode (int | str) – a bitwise-or of access bits, or a string-representation thereof: 'f', 'x', 'r', 'w' for os.F_OK, os.X_OK, os.R_OK, os.W_OK
Return type:: bool

link(dst)[source]¶

Creates a hard link from self to dst

Parameters:: dst (LocalPath | str) – the destination path
Return type:: None

symlink(dst)[source]¶

Creates a symbolic link from self to dst

Parameters:: dst (LocalPath | str) – the destination path
Return type:: None

unlink()[source]¶

Deletes a symbolic link

Return type:: None

as_uri(scheme='file')[source]¶

Returns a universal resource identifier. Use scheme to force a scheme.

Return type:: str

property drive¶: The drive letter (on Windows)

property root¶: The root of the file tree (/ on Unix)

class plumbum.path.local.LocalWorkdir[source]¶

Working directory manipulator

__hash__ = None¶

static __new__(cls)[source]¶

Return type:: Self

chdir(newdir)[source]¶

Changes the current working directory to the given one

Parameters:: newdir (LocalPath | str) – The destination director (a string or a LocalPath)
Return type:: LocalWorkdir

getpath()[source]¶

Returns the current working directory as a LocalPath object

Return type:: LocalPath

__call__(newdir)[source]¶

A context manager used to chdir into a directory and then chdir back to the previous location; much like pushd/popd.

Parameters:: newdir (LocalPath | str) – The destination directory (a string or a LocalPath)
Return type:: Generator[LocalWorkdir, None, None]

class plumbum.path.remote.RemotePath(remote, *parts_str)[source]¶

The class implementing remote-machine paths

static __new__(cls, remote, *parts_str)[source]¶

Return type:: Self

property name¶: The basename component of this path

property dirname¶: The dirname component of this path

property suffix¶: The suffix of this file

property suffixes¶: This is a list of all suffixes

property uid¶: The user that owns this path. The returned value is a FSUser object which behaves like an int (as expected from uid), but it also has a .name attribute that holds the string-name of the user

property gid¶: The group that owns this path. The returned value is a FSUser object which behaves like an int (as expected from gid), but it also has a .name attribute that holds the string-name of the group

join(*parts)[source]¶

Joins this path with any number of paths

Return type:: RemotePath

list()[source]¶

Returns the files in this directory

Return type:: list[RemotePath]

iterdir()[source]¶

Returns an iterator over the directory. Might be slightly faster on Python 3.5 than .list()

Return type:: Iterable[RemotePath]

is_dir()[source]¶

Returns True if this path is a directory, False otherwise

Return type:: bool

is_file()[source]¶

Returns True if this path is a regular file, False otherwise

Return type:: bool

is_symlink()[source]¶

Returns True if this path is a symbolic link, False otherwise

Return type:: bool

exists()[source]¶

Returns True if this path exists, False otherwise

Return type:: bool

stat()[source]¶

Returns the os.stats for a file

Return type:: RemoteStatRes

with_name(name)[source]¶

Returns a path with the name replaced

Return type:: RemotePath

with_suffix(suffix, depth=1)[source]¶

Return type:: RemotePath

glob(pattern)[source]¶

Returns a (possibly empty) list of paths that matched the glob-pattern under this path

Return type:: list[RemotePath]

delete()[source]¶

Deletes this path (recursively, if a directory)

Return type:: None

unlink()¶

Deletes a symbolic link

Return type:: None

move(dst)[source]¶

Moves this path to a different location

Return type:: RemotePath

copy(dst, override=False)[source]¶

Return type:: RemotePath

mkdir(mode=None, parents=True, exist_ok=True)[source]¶

Creates a directory at this path.

Parameters:

mode (int | None) – Currently only implemented for local paths! Numeric mode to use for directory creation, which may be ignored on some systems. The current implementation reproduces the behavior of os.mkdir (i.e., the current umask is first masked out), but this may change for remote paths. As with os.mkdir, it is recommended to call chmod() explicitly if you need to be sure.
parents (bool) – If this is true (the default), the directory’s parents will also be created if necessary.
exist_ok (bool) – If this is true (the default), no exception will be raised if the directory already exists (otherwise OSError).

Return type:

None

read(encoding=None)[source]¶

returns the contents of this file as a str. By default the data is read as text, but you can specify the encoding, e.g., 'latin1' or 'utf8'

Return type:: str | bytes

write(data, encoding=None)[source]¶

writes the given data to this file. By default the data is written as-is (either text or binary), but you can specify the encoding, e.g., 'latin1' or 'utf8'

Return type:: None

touch()[source]¶

Update the access time. Creates an empty file if none exists.

Return type:: None

chown(owner=None, group=None, recursive=None)[source]¶

Change ownership of this path.

Parameters:

owner (int | str | None) – The owner to set (either uid or username), optional
group (int | str | None) – The group to set (either gid or groupname), optional
recursive (bool | None) – whether to change ownership of all contained files and subdirectories. Only meaningful when self is a directory. If None, the value will default to True if self is a directory, False otherwise.

Return type:

None

chmod(mode)[source]¶

Change the mode of path to the numeric mode.

Parameters:: mode (int) – file mode as for os.chmod
Return type:: None

access(mode=0)[source]¶

Test file existence or permission bits

Parameters:: mode (int | str) – a bitwise-or of access bits, or a string-representation thereof: 'f', 'x', 'r', 'w' for os.F_OK, os.X_OK, os.R_OK, os.W_OK
Return type:: bool

link(dst)[source]¶

Creates a hard link from self to dst

Parameters:: dst (RemotePath | str) – the destination path
Return type:: None

symlink(dst)[source]¶

Creates a symbolic link from self to dst

Parameters:: dst (RemotePath | str) – the destination path
Return type:: None

open(mode='r', bufsize=-1, *, encoding=None)[source]¶

Opens this path as a file.

Only works for ParamikoMachine-associated paths for now.

Return type:: IO[str] | IO[bytes]

as_uri(scheme='ssh')[source]¶

Returns a universal resource identifier. Use scheme to force a scheme.

Return type:: str

property stem¶: The name without an extension, or the last component of the path

property root¶: The root of the file tree (/ on Unix)

property drive¶: The drive letter (on Windows)

class plumbum.path.remote.RemoteStatRes(tup)[source]¶: Remote POSIX-like stat result

class plumbum.path.remote.RemoteWorkdir(remote)[source]¶

Remote working directory manipulator

static __new__(cls, remote)[source]¶

Return type:: Self

__hash__ = None¶

chdir(newdir)[source]¶

Changes the current working directory to the given one

Return type:: Self

getpath()[source]¶

Returns the current working directory as a remote path <plumbum.path.remote.RemotePath> object

Return type:: RemotePath

__call__(newdir)[source]¶

A context manager used to chdir into a directory and then chdir back to the previous location; much like pushd/popd.

Parameters:: newdir (RemotePath | str) – The destination director (a string or a RemotePath)
Return type:: Generator[RemotePath, None, None]

class plumbum.path.remote.StatRes(tup)[source]¶

POSIX-like stat result

__init__(tup)[source]¶

Utils¶

plumbum.path.utils.copy(src, dst)[source]¶

Copy (recursively) the source path onto the destination path; src and dst can be either strings, LocalPaths or RemotePath; any combination of the three will work.

Added in version 1.3: src can also be a list of strings/paths, in which case dst must not exist or be a directory.

Return type:: Path

plumbum.path.utils.delete(*paths)[source]¶

Deletes the given paths. The arguments can be either strings, local paths, remote paths, or iterables of such. No error is raised if any of the paths does not exist (it is silently ignored)

Return type:: None

plumbum.path.utils.gui_open(filename)[source]¶

This selects the proper gui open function. This can also be achieved with webbrowser, but that is not supported.

Return type:: None

plumbum.path.utils.move(src, dst)[source]¶

Moves the source path onto the destination path; src and dst can be either strings, LocalPaths or RemotePath; any combination of the three will work.

Added in version 1.3: src can also be a list of strings/paths, in which case dst must not exist or be a directory.

Return type:: Path