Package plumbum.path

class plumbum.path.base.FSUser[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)

__weakref__

list of weak references to the object (if defined)

class plumbum.path.base.Path[source]

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

__div__(other)[source]

Joins two paths

__truediv__(other)

Joins two paths

__floordiv__(expr)[source]

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

__iter__()[source]

Iterate over the files in this directory

__fpath__()[source]

Added for Python 3.6 support

__contains__(item)[source]

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

up(count=1)[source]

Go up in count directories (the default is 1)

walk(filter=<function <lambda>>, dir_filter=<function <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 – 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.
name

The basename component of this path

basename

Included for compatibility with older Plumbum code

stem

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

dirname

The dirname component of this path

root

The root of the file tree (/ on Unix)

drive

The drive letter (on Windows)

suffix

The suffix of this file

suffixes

This is a list of all suffixes

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

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

as_uri(scheme=None)[source]

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

join(*parts)[source]

Joins this path with any number of paths

list()[source]

Returns the files in this directory

iterdir()[source]

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

is_dir()[source]

Returns True if this path is a directory, False otherwise

isdir()[source]

Included for compatibility with older Plumbum code

is_file()[source]

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

isfile()[source]

Included for compatibility with older Plumbum code

Included for compatibility with older Plumbum code

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

exists()[source]

Returns True if this path exists, False otherwise

stat()[source]

Returns the os.stats for a file

with_name(name)[source]

Returns a path with the name replaced

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

preferred_suffix(suffix)[source]

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

glob(pattern)[source]

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

delete()[source]

Deletes this path (recursively, if a directory)

move(dst)[source]

Moves this path to a different location

rename(newname)[source]

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

copy(dst, override=False)[source]

Copies this path (recursively, if a directory) to the destination path. Raises TypeError if dst exists and override is False.

mkdir()[source]

Creates a directory at this path; if the directory already exists, silently ignore

open(mode='r')[source]

opens this path as a file

read(encoding=None)[source]

returns the contents of this file. By default the data is binary (bytes), but you can specify the encoding, e.g., 'latin1' or 'utf8'

write(data, encoding=None)[source]

writes the given data to this file. By default the data is expected to be binary (bytes), but you can specify the encoding, e.g., 'latin1' or 'utf8'

touch()[source]

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

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

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)[source]

Change the mode of path to the numeric mode.

Parameters:mode – file mode as for os.chmod
access(mode=0)[source]

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

Creates a hard link from self to dst

Parameters:dst – the destination path

Creates a symbolic link from self to dst

Parameters:dst – the destination path

Deletes a symbolic link

split(*dummy_args, **dummy_kargs)[source]

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

parts

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

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]
__sub__(other)[source]

Same as self.relative_to(other)

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)

__weakref__

list of weak references to the object (if defined)

class plumbum.path.local.LocalPath[source]

The class implementing local-machine paths

name

The basename component of this path

dirname

The dirname component of this path

suffix

The suffix of this file

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

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

list()[source]

Returns the files in this directory

iterdir()[source]

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

is_dir()[source]

Returns True if this path is a directory, False otherwise

is_file()[source]

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

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

exists()[source]

Returns True if this path exists, False otherwise

stat()[source]

Returns the os.stats for a file

with_name(name)[source]

Returns a path with the name replaced

stem

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

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

glob(pattern)[source]

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

delete()[source]

Deletes this path (recursively, if a directory)

move(dst)[source]

Moves this path to a different location

copy(dst, override=False, overwrite=True)[source]

Copies this path (recursively, if a directory) to the destination path. Raises TypeError if dst exists and override is False.

mkdir()[source]

Creates a directory at this path; if the directory already exists, silently ignore

open(mode='r')[source]

opens this path as a file

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

returns the contents of this file. By default the data is binary (bytes), but you can specify the encoding, e.g., 'latin1' or 'utf8'

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

writes the given data to this file. By default the data is expected to be binary (bytes), but you can specify the encoding, e.g., 'latin1' or 'utf8'

touch()[source]

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

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

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)[source]

Change the mode of path to the numeric mode.

Parameters:mode – file mode as for os.chmod
access(mode=0)[source]

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

Creates a hard link from self to dst

Parameters:dst – the destination path

Creates a symbolic link from self to dst

Parameters:dst – the destination path

Deletes a symbolic link

as_uri(scheme='file')[source]

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

drive

The drive letter (on Windows)

root

The root of the file tree (/ on Unix)

class plumbum.path.local.LocalWorkdir[source]

Working directory manipulator

chdir(newdir)[source]

Changes the current working directory to the given one

Parameters:newdir – The destination director (a string or a LocalPath)
getpath()[source]

Returns the current working directory as a LocalPath object

__call__(*args, **kwds)[source]

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)[source]

POSIX-like stat result

__weakref__

list of weak references to the object (if defined)

class plumbum.path.remote.RemotePath[source]

The class implementing remote-machine paths

name

The basename component of this path

dirname

The dirname component of this path

suffix

The suffix of this file

suffixes

This is a list of all suffixes

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

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

list()[source]

Returns the files in this directory

iterdir()[source]

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

is_dir()[source]

Returns True if this path is a directory, False otherwise

is_file()[source]

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

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

exists()[source]

Returns True if this path exists, False otherwise

stat()[source]

Returns the os.stats for a file

with_name(name)[source]

Returns a path with the name replaced

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

glob(pattern)[source]

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

delete()[source]

Deletes this path (recursively, if a directory)

Deletes this path (recursively, if a directory)

move(dst)[source]

Moves this path to a different location

copy(dst, override=False)[source]

Copies this path (recursively, if a directory) to the destination path. Raises TypeError if dst exists and override is False.

mkdir()[source]

Creates a directory at this path; if the directory already exists, silently ignore

read(encoding=None)[source]

returns the contents of this file. By default the data is binary (bytes), but you can specify the encoding, e.g., 'latin1' or 'utf8'

write(data, encoding=None)[source]

writes the given data to this file. By default the data is expected to be binary (bytes), but you can specify the encoding, e.g., 'latin1' or 'utf8'

touch()[source]

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

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

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)[source]

Change the mode of path to the numeric mode.

Parameters:mode – file mode as for os.chmod
access(mode=0)[source]

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

Creates a hard link from self to dst

Parameters:dst – the destination path

Creates a symbolic link from self to dst

Parameters:dst – the destination path
as_uri(scheme='ssh')[source]

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

stem

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

root

The root of the file tree (/ on Unix)

drive

The drive letter (on Windows)

class plumbum.path.remote.RemoteWorkdir[source]

Remote working directory manipulator

chdir(newdir)[source]

Changes the current working directory to the given one

getpath()[source]

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

__call__(*args, **kwds)[source]

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

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.

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

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)[source]

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