Package plumbum.path

class plumbum.path.base.FSUser(val, name=None)

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)

class plumbum.path.base.Path

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

__repr__()

Return repr(self).

__truediv__(other: Any) → _PathImpl

Joins two paths

__getitem__(key)

Return self[key].

__floordiv__(expr)

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

__iter__()

Iterate over the files in this directory

__eq__(other: object) → bool

Return self==value.

__ne__(other)

Return self!=value.

__gt__(other)

Return self>value.

__ge__(other)

Return self>=value.

__lt__(other)

Return self<value.

__le__(other)

Return self<=value.

__hash__()

Return hash(self).

__fspath__()

Added for Python 3.6 support

__contains__(item)

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

up(count=1)

Go up in count directories (the default is 1)

walk(filter=<function Path.<lambda>>, dir_filter=<function Path.<lambda>>)

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 – the filter (predicate function) for matching results. Only paths matching this predicate are returned. Defaults to everything.

• dir_filter – the filter (predicate function) for matching directories. Only directories matching this predicate are recursed into. Defaults to everything.

abstract property name: str

The basename component of this path

property basename

Included for compatibility with older Plumbum code

abstract property stem: str

The name without an extension, or the last component of the path

abstract property dirname: _PathImpl

The dirname component of this path

abstract property root: str

The root of the file tree (/ on Unix)

abstract property drive: str

The drive letter (on Windows)

abstract property suffix: str

The suffix of this file

abstract property suffixes: List[str]

This is a list of all suffixes

abstract property uid: FSUser

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: FSUser

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

abstract as_uri(scheme: str | None = None) → str

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

abstract join(*parts: Any) → _PathImpl

Joins this path with any number of paths

abstract list() → List[_PathImpl]

Returns the files in this directory

abstract iterdir() → Iterable[_PathImpl]

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

abstract is_dir() → bool

Returns True if this path is a directory, False otherwise

isdir()

Included for compatibility with older Plumbum code

abstract is_file() → bool

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

isfile() → bool

Included for compatibility with older Plumbum code

islink()

Included for compatibility with older Plumbum code

abstract is_symlink() → bool

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

abstract exists() → bool

Returns True if this path exists, False otherwise

abstract stat() → stat_result

Returns the os.stats for a file

abstract with_name(name: Any) → _PathImpl

Returns a path with the name replaced

abstract with_suffix(suffix: str, depth: int | None = 1) → _PathImpl

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

preferred_suffix(suffix)

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

abstract glob(pattern: str | Iterable[str]) → List[_PathImpl]

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

abstract delete()

Deletes this path (recursively, if a directory)

abstract move(dst)

Moves this path to a different location

rename(newname)

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

abstract copy(dst, override=None)

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).

abstract mkdir(mode=511, parents=True, exist_ok=True)

Creates a directory at this path.

Parameters:

• mode – 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 – If this is true (the default), the directory’s parents will also be created if necessary.

• exist_ok – If this is true (the default), no exception will be raised if the directory already exists (otherwise OSError).

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.

abstract open(mode: str = 'r', *, encoding: str | None = None) → IOBase

opens this path as a file

abstract read(encoding: str | None = None) → str

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'

abstract write(data: AnyStr, encoding: str | None = None) → None

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'

abstract touch()

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

abstract chown(owner=None, group=None, recursive=None)

Change ownership of this path.

Parameters:

• owner – The owner to set (either uid or username), optional

• group – The group to set (either gid or groupname), optional

• recursive – 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.

abstract chmod(mode)

Change the mode of path to the numeric mode.

Parameters:

mode – file mode as for os.chmod

abstract access(mode: int | str = 0) → bool

Test file existence or permission bits

Parameters:

mode – 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

abstract link(dst)

Creates a hard link from self to dst

Parameters:

dst – the destination path

abstract symlink(dst)

Creates a symbolic link from self to dst

Parameters:

dst – the destination path

abstract unlink()

Deletes a symbolic link

split(*_args, **_kargs)

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

property parts

Splits the directory into parts, including the base directory, returns a tuple

relative_to(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]

__sub__(other)

Same as self.relative_to(other)

resolve(strict=False)

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

property parents

Pathlib like sequence of ancestors

property parent

Pathlib like parent of the path.

__weakref__

list of weak references to the object (if defined)

class plumbum.path.base.RelativePath(parts)

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)

__str__()

Return str(self).

__repr__()

Return repr(self).

__eq__(other)

Return self==value.

__ne__(other)

Return self!=value.

__gt__(other)

Return self>value.

__ge__(other)

Return self>=value.

__lt__(other)

Return self<value.

__le__(other)

Return self<=value.

__hash__()

Return hash(self).

__weakref__

list of weak references to the object (if defined)

class plumbum.path.local.LocalPath(*parts)

The class implementing local-machine paths

static __new__(cls, *parts)

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)

Joins this path with any number of paths

list()

Returns the files in this directory

iterdir()

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

is_dir()

Returns True if this path is a directory, False otherwise

is_file()

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

is_symlink()

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

exists()

Returns True if this path exists, False otherwise

stat()

Returns the os.stats for a file

with_name(name)

Returns a path with the name replaced

property stem

The name without an extension, or the last component of the path

with_suffix(suffix, depth=1)

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

glob(pattern)

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

delete()

Deletes this path (recursively, if a directory)

move(dst)

Moves this path to a different location

copy(dst, override=None)

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).

mkdir(mode=511, parents=True, exist_ok=True)

Creates a directory at this path.

Parameters:

• mode – 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 – If this is true (the default), the directory’s parents will also be created if necessary.

• exist_ok – If this is true (the default), no exception will be raised if the directory already exists (otherwise OSError).

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.

open(mode='r', encoding=None)

opens this path as a file

read(encoding=None, mode='r')

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'

write(data, encoding=None, mode=None)

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'

touch()

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

chown(owner=None, group=None, recursive=None)

Change ownership of this path.

Parameters:

• owner – The owner to set (either uid or username), optional

• group – The group to set (either gid or groupname), optional

• recursive – 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.

chmod(mode)

Change the mode of path to the numeric mode.

Parameters:

mode – file mode as for os.chmod

access(mode=0)

Test file existence or permission bits

Parameters:

mode – 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

link(dst)

Creates a hard link from self to dst

Parameters:

dst – the destination path

symlink(dst)

Creates a symbolic link from self to dst

Parameters:

dst – the destination path

unlink()

Deletes a symbolic link

as_uri(scheme='file')

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

property drive

The drive letter (on Windows)

property root

The root of the file tree (/ on Unix)

class plumbum.path.local.LocalWorkdir

Working directory manipulator

__hash__()

Return hash(self).

static __new__(cls)

chdir(newdir)

Changes the current working directory to the given one

Parameters:

newdir – The destination director (a string or a LocalPath)

getpath()

Returns the current working directory as a LocalPath object

__call__(newdir)

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

Parameters:

newdir – The destination directory (a string or a LocalPath)

class plumbum.path.remote.StatRes(tup)

POSIX-like stat result

__init__(tup)

__weakref__

list of weak references to the object (if defined)

class plumbum.path.remote.RemotePath(remote, *parts)

The class implementing remote-machine paths

static __new__(cls, remote, *parts)

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)

Joins this path with any number of paths

list()

Returns the files in this directory

iterdir()

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

is_dir()

Returns True if this path is a directory, False otherwise

is_file()

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

is_symlink()

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

exists()

Returns True if this path exists, False otherwise

stat()

Returns the os.stats for a file

with_name(name)

Returns a path with the name replaced

with_suffix(suffix, depth=1)

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

glob(pattern)

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

delete()

Deletes this path (recursively, if a directory)

unlink()

Deletes a symbolic link

move(dst)

Moves this path to a different location

copy(dst, override=False)

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).

mkdir(mode=None, parents=True, exist_ok=True)

Creates a directory at this path.

Parameters:

• mode – 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 – If this is true (the default), the directory’s parents will also be created if necessary.

• exist_ok – If this is true (the default), no exception will be raised if the directory already exists (otherwise OSError).

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.

read(encoding=None)

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'

write(data, encoding=None)

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'

touch()

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

chown(owner=None, group=None, recursive=None)

Change ownership of this path.

Parameters:

• owner – The owner to set (either uid or username), optional

• group – The group to set (either gid or groupname), optional

• recursive – 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.

chmod(mode)

Change the mode of path to the numeric mode.

Parameters:

mode – file mode as for os.chmod

access(mode=0)

Test file existence or permission bits

Parameters:

mode – 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

link(dst)

Creates a hard link from self to dst

Parameters:

dst – the destination path

symlink(dst)

Creates a symbolic link from self to dst

Parameters:

dst – the destination path

open(mode='r', bufsize=-1, *, encoding=None)

Opens this path as a file.

Only works for ParamikoMachine-associated paths for now.

as_uri(scheme='ssh')

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

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.RemoteWorkdir(remote)

Remote working directory manipulator

static __new__(cls, remote)

__hash__()

Return hash(self).

chdir(newdir)

Changes the current working directory to the given one

getpath()

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

__call__(newdir)

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

Parameters:

newdir – The destination director (a string or a RemotePath)

Utils

plumbum.path.utils.delete(*paths)

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)

plumbum.path.utils.move(src, dst)

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.

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

plumbum.path.utils.copy(src, dst)

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.

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

plumbum.path.utils.gui_open(filename)

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