API Reference¶
Exceptions¶
- exception UnsupportedOperation¶
An exception inheriting
NotImplementedError
that is raised when an unsupported operation is called on a path object.
Base classes¶
- class ParserBase¶
Abstract base class for low-level path syntax manipulation utilities.
This class provides abstract implementations for methods that derived classes can override selectively. The default implementations raise
UnsupportedOperation
.
- class PurePathBase(*pathsegments)¶
Abstract base class for path objects without I/O support.
This class does not provide several magic methods that are defined in its subclass
PurePath
. They are:__fspath__
,__bytes__
,__repr__
,__reduce__
,__hash__
,__eq__
,__lt__
,__le__
,__gt__
,__ge__
.
- class PathBase(*pathsegments)¶
Abstract base class for path objects with I/O support. This is a subclass of
PurePathBase
.This class provides abstract implementations for methods that derived classes can override selectively. The default implementations of the most basic methods, like
stat()
anditerdir()
, directly raiseUnsupportedOperation
Controlling path syntax¶
Path parsers provide a subset of the os.path
API, specifically those
functions needed to provide PurePathBase
functionality.
Python itself provides the posixpath
and ntpath
modules, which can be
assigned to PurePathBase.parser
to implement path objects with POSIX
or Windows syntax.
- PurePathBase.parser¶
Object implementing the
ParserBase
interface, such asposixpath
orntpath
. This is used to implement lexical operations on paths such as joining and splitting. The default value is an instance ofParserBase
, which causes all methods to raiseUnsupportedOperation
.
Users may provide a custom path syntax by subclassing ParserBase
, and
assigning an instance of their subclass to parser
.
Subclasses should implement the following attributes and methods:
- ParserBase.sep¶
The character used to separate path components.
- ParserBase.join(path, *paths)¶
Return a path formed by joining the path segments together.
- ParserBase.split(path)¶
Split the path into a pair
(head, tail)
, where head is everything before the final path separator, and tail is everything after. Either part may be empty.
- ParserBase.splitdrive(path)¶
Split the path into a 2-item tuple
(drive, tail)
, where drive is a device name or mount point, and tail is everything after the drive. Either part may be empty.
- ParserBase.normcase(path)¶
Return a path with its case normalized.
- ParserBase.isabs(path)¶
Return whether the path is absolute, i.e. unaffected by the current directory or drive.
Parsing and generating URIs¶
- classmethod PathBase.from_uri(uri)¶
Return a new path object from parsing a URI.
The default implementation of this method immediately raises
UnsupportedOperation
.
- PathBase.as_uri()¶
Represent the path as a URI.
The default implementation of this method immediately raises
UnsupportedOperation
.
Querying status and type¶
- PathBase.stat(*, follow_symlinks=True)¶
Returns information about the path. Implementations should return an object that resembles an
os.stat_result
it should at least havest_mode
,st_dev
andst_ino
attributes.The default implementation of this method immediately raises
UnsupportedOperation
.
- PathBase.lstat()¶
- PathBase.samefile(other_path)¶
- PathBase.exists(*, follow_symlinks=True)¶
- PathBase.is_dir(*, follow_symlinks=True)¶
- PathBase.is_file(*, follow_symlinks=True)¶
- PathBase.is_mount()¶
- PathBase.is_symlink()¶
- PathBase.is_socket()¶
- PathBase.is_fifo()¶
- PathBase.is_block_device()¶
- PathBase.is_junction()¶
Returns
True
if the path points to a junction.The default implementation of this method returns
False
rather than raisingUnsupportedOperation
, because junctions are almost never available in virtual filesystems.
Reading and writing files¶
- PathBase.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)¶
Opens the path as a file-like object.
The default implementation of this method immediately raises
UnsupportedOperation
.
- PathBase.read_bytes()¶
- PathBase.read_text(encoding=None, errors=None, newline=None)¶
- PathBase.write_bytes(data)¶
Iterating over directories¶
- PathBase.iterdir()¶
Yields path objects representing directory children.
The default implementation of this method immediately raises
UnsupportedOperation
.
- PathBase.glob(pattern, *, case_sensitive=None, recurse_symlinks=True)¶
- PathBase.rglob(pattern, *, case_sensitive=None, recurse_symlinks=True)¶
Making paths absolute¶
- PathBase.absolute()¶
Returns an absolute version of this path.
The default implementation of this method immediately raises
UnsupportedOperation
.
- classmethod PathBase.cwd()¶
The default implementation of this method calls
absolute()
.
Expanding home directories¶
- PathBase.expanduser()¶
Return a new path with expanded
~
and~user
constructs.The default implementation of this method immediately raises
UnsupportedOperation
.
- classmethod PathBase.home()¶
The default implementation of this method calls
expanduser()
.
Resolving symlinks¶
- PathBase.readlink()¶
Return the path to which the symbolic link points.
The default implementation of this method immediately raises
UnsupportedOperation
.
- PathBase.resolve(strict=False)¶
Resolves symlinks and eliminates
..
path components. If supported, make the path absolute.The default implementation of this method first calls
absolute()
, but suppresses any resultingUnsupportedOperation
exception; this allows paths to be resolved on filesystems that lack a notion of a working directory. It callsstat()
on each ancestor path, andreadlink()
when a stat result indicates a symlink.OSError
is raised if more than 40 symlinks are encountered while resolving a path; this is taken to indicate a loop.
Permissions¶
- PathBase.chmod(mode, *, follow_symlinks=True)¶
Change the file permissions.
The default implementation of this method immediately raises
UnsupportedOperation
.
Ownership¶
- PathBase.owner(*, follow_symlinks=True)¶
Return the name of the user owning the file.
The default implementation of this method immediately raises
UnsupportedOperation
.
- PathBase.group(*, follow_symlinks=True)¶
Return the name of the group owning the file.
The default implementation of this method immediately raises
UnsupportedOperation
.
Other methods¶
- PathBase.symlink_to(target, target_is_directory=False)¶
- PathBase.hardlink_to(target)¶
- PathBase.touch(mode=0o666, exist_ok=True)¶
- PathBase.mkdir(mode=0o777, parents=False, exist_ok=False)¶
- PathBase.rename(target)¶
- PathBase.replace(target)¶
- PathBase.unlink(missing_ok=False)¶
- PathBase.rmdir()¶
The default implementations of these methods immediately raise
UnsupportedOperation
.