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 (otherwiseNone
)
-
class
plumbum.path.base.
Path
[source]¶ An abstraction over file system paths. This class is abstract, and the two implementations are
LocalPath
andRemotePath
.-
__truediv__
(other)¶ Joins two paths
-
__floordiv__
(expr)[source]¶ Returns a (possibly empty) list of paths that matched the glob-pattern under this path
-
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 – 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
¶ The basename component of this path
-
property
basename
¶ Included for compatibility with older Plumbum code
-
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 anint
(as expected fromuid
), 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 anint
(as expected fromgid
), but it also has a.name
attribute that holds the string-name of the group
-
abstract
as_uri
(scheme=None)[source]¶ Returns a universal resource identifier. Use
scheme
to force a scheme.
-
abstract
iterdir
()[source]¶ Returns an iterator over the directory. Might be slightly faster on Python 3.5 than .list()
-
abstract
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 thandepth
suffixes, this will replace all suffixes..tar.gz
is an example wheredepth=2
ordepth=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
-
abstract
glob
(pattern)[source]¶ Returns a (possibly empty) list of paths that matched the glob-pattern under this path
-
abstract
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).
-
abstract
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 withos.mkdir
, it is recommended to callchmod()
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
andexist_ok
are the opposite of what they are in Python’s ownpathlib
- this is to maintain backwards-compatibility with Plumbum’s behaviour from before they were implemented.
-
abstract
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'
-
abstract
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'
-
abstract
chown
(owner=None, group=None, recursive=None)[source]¶ Change ownership of this path.
- Parameters
owner – The owner to set (either
uid
orusername
), optionalgroup – The group to set (either
gid
orgroupname
), optionalrecursive – whether to change ownership of all contained files and subdirectories. Only meaningful when
self
is a directory. IfNone
, the value will default toTrue
ifself
is a directory,False
otherwise.
-
abstract
chmod
(mode)[source]¶ Change the mode of path to the numeric mode.
- Parameters
mode – file mode as for os.chmod
-
abstract
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'
foros.F_OK
,os.X_OK
,os.R_OK
,os.W_OK
-
abstract
link
(dst)[source]¶ Creates a hard link from
self
todst
- Parameters
dst – the destination path
-
abstract
symlink
(dst)[source]¶ Creates a symbolic link from
self
todst
- Parameters
dst – the destination path
-
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']
.
-
property
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
toself
. They satisfy the invariantsource_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]
-
resolve
(strict=False)[source]¶ 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)[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
(*parts)[source]¶ The class implementing local-machine paths
-
static
__new__
(cls, *parts)[source]¶ Create and return a new object. See help(type) for accurate signature.
-
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 anint
(as expected fromuid
), 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 anint
(as expected fromgid
), but it also has a.name
attribute that holds the string-name of the group
-
iterdir
()[source]¶ Returns an iterator over the directory. Might be slightly faster on Python 3.5 than .list()
-
property
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 thandepth
suffixes, this will replace all suffixes..tar.gz
is an example wheredepth=2
ordepth=None
is useful
-
glob
(pattern)[source]¶ Returns a (possibly empty) list of paths that matched the glob-pattern under this path
-
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).
-
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 withos.mkdir
, it is recommended to callchmod()
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
andexist_ok
are the opposite of what they are in Python’s ownpathlib
- this is to maintain backwards-compatibility with Plumbum’s behaviour from before they were implemented.
-
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'
-
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'
-
chown
(owner=None, group=None, recursive=None)[source]¶ Change ownership of this path.
- Parameters
owner – The owner to set (either
uid
orusername
), optionalgroup – The group to set (either
gid
orgroupname
), optionalrecursive – whether to change ownership of all contained files and subdirectories. Only meaningful when
self
is a directory. IfNone
, the value will default toTrue
ifself
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'
foros.F_OK
,os.X_OK
,os.R_OK
,os.W_OK
-
symlink
(dst)[source]¶ Creates a symbolic link from
self
todst
- Parameters
dst – the destination path
-
as_uri
(scheme='file')[source]¶ 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)
-
static
-
class
plumbum.path.local.
LocalWorkdir
[source]¶ Working directory manipulator
-
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
(remote, *parts)[source]¶ The class implementing remote-machine paths
-
static
__new__
(cls, remote, *parts)[source]¶ Create and return a new object. See help(type) for accurate signature.
-
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 anint
(as expected fromuid
), 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 anint
(as expected fromgid
), but it also has a.name
attribute that holds the string-name of the group
-
iterdir
()[source]¶ Returns an iterator over the directory. Might be slightly faster on Python 3.5 than .list()
-
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 thandepth
suffixes, this will replace all suffixes..tar.gz
is an example wheredepth=2
ordepth=None
is useful
-
glob
(pattern)[source]¶ Returns a (possibly empty) list of paths that matched the glob-pattern under this path
-
unlink
()¶ Deletes this path (recursively, if a directory)
-
copy
(dst, override=False)[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).
-
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 withos.mkdir
, it is recommended to callchmod()
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
andexist_ok
are the opposite of what they are in Python’s ownpathlib
- 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 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)[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'
-
chown
(owner=None, group=None, recursive=None)[source]¶ Change ownership of this path.
- Parameters
owner – The owner to set (either
uid
orusername
), optionalgroup – The group to set (either
gid
orgroupname
), optionalrecursive – whether to change ownership of all contained files and subdirectories. Only meaningful when
self
is a directory. IfNone
, the value will default toTrue
ifself
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'
foros.F_OK
,os.X_OK
,os.R_OK
,os.W_OK
-
symlink
(dst)[source]¶ Creates a symbolic link from
self
todst
- 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.
-
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)
-
static
-
class
plumbum.path.remote.
RemoteWorkdir
(remote)[source]¶ Remote working directory manipulator
-
static
__new__
(cls, remote)[source]¶ Create and return a new object. See help(type) for accurate signature.
-
getpath
()[source]¶ Returns the current working directory as a remote path <plumbum.path.remote.RemotePath> object
-
__call__
(newdir)[source]¶ A context manager used to
chdir
into a directory and thenchdir
back to the previous location; much likepushd
/popd
.- Parameters
newdir – The destination director (a string or a
RemotePath
)
-
static
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
anddst
can be either strings,LocalPaths
orRemotePath
; any combination of the three will work.New in version 1.3:
src
can also be a list of strings/paths, in which casedst
must not exist or be a directory.
-
plumbum.path.utils.
copy
(src, dst)[source]¶ Copy (recursively) the source path onto the destination path;
src
anddst
can be either strings,LocalPaths
orRemotePath
; any combination of the three will work.New in version 1.3:
src
can also be a list of strings/paths, in which casedst
must not exist or be a directory.