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.

__repr__() <==> repr(x)[source]¶

__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

__eq__(other)[source]¶

x.__eq__(y) <==> x==y

__ne__(other)[source]¶

x.__ne__(y) <==> x!=y

__gt__(other)[source]¶

x.__gt__(y) <==> x>y

__ge__(other)[source]¶

x.__ge__(y) <==> x>=y

__lt__(other)[source]¶

x.__lt__(y) <==> x<y

__le__(other)[source]¶

x.__le__(y) <==> x<=y

__hash__() <==> hash(x)[source]¶

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

islink()[source]¶

Included for compatibility with older Plumbum code

is_symlink()[source]¶

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(mode=511, parents=True, exist_ok=True)[source]¶

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

link(dst)[source]¶

Creates a hard link from self to dst

Parameters:	dst – the destination path

symlink(dst)[source]¶

Creates a symbolic link from self to dst

Parameters:	dst – the destination path

unlink()[source]¶

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)

resolve()[source]¶

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

parents¶

Pathlib like sequence of ancestors

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]¶

x.__init__(…) initializes x; see help(type(x)) for signature

__str__() <==> str(x)[source]¶

__repr__() <==> repr(x)[source]¶

__eq__(other)[source]¶

x.__eq__(y) <==> x==y

__ne__(other)[source]¶

x.__ne__(y) <==> x!=y

__gt__(other)[source]¶

x.__gt__(y) <==> x>y

__ge__(other)[source]¶

x.__ge__(y) <==> x>=y

__lt__(other)[source]¶

x.__lt__(y) <==> x<y

__le__(other)[source]¶

x.__le__(y) <==> x<=y

__hash__() <==> hash(x)[source]¶

__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

is_symlink()[source]¶

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(mode=511, parents=True, exist_ok=True)[source]¶

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

link(dst)[source]¶

Creates a hard link from self to dst

Parameters:	dst – the destination path

symlink(dst)[source]¶

Creates a symbolic link from self to dst

Parameters:	dst – the destination path

unlink()[source]¶

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

__hash__() <==> hash(x)[source]¶

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__(**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

__init__(tup)[source]¶

x.__init__(…) initializes x; see help(type(x)) for signature

__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

is_symlink()[source]¶

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)

unlink()¶

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(mode=None, parents=True, exist_ok=True)[source]¶

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

link(dst)[source]¶

Creates a hard link from self to dst

Parameters:	dst – the destination path

symlink(dst)[source]¶

Creates a symbolic link from self to dst

Parameters:	dst – the destination path

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

Opens this path as a file.

Only works for ParamikoMachine-associated paths for now.

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

__hash__() <==> hash(x)[source]¶

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__(**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)