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() and iterdir(), directly raise UnsupportedOperation

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 as posixpath or ntpath. This is used to implement lexical operations on paths such as joining and splitting. The default value is an instance of ParserBase, which causes all methods to raise UnsupportedOperation.

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 have st_mode, st_dev and st_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_socket()
PathBase.is_fifo()
PathBase.is_block_device()
PathBase.is_char_device()

The default implementations of these methods call stat().

PathBase.is_junction()

Returns True if the path points to a junction.

The default implementation of this method returns False rather than raising UnsupportedOperation, 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)
PathBase.write_text(data, encoding=None, errors=None, newline=None)

The default implementations of these methods call open().

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)
PathBase.walk(top_down=True, on_error=None, follow_symlinks=False)

The default implementations of these methods call iterdir() and is_dir().

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

Permissions

PathBase.chmod(mode, *, follow_symlinks=True)

Change the file permissions.

The default implementation of this method immediately raises UnsupportedOperation.

PathBase.lchmod(mode)

The default implementation of this method calls chmod().

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.touch(mode=0o666, exist_ok=True)
PathBase.mkdir(mode=0o777, parents=False, exist_ok=False)
PathBase.rename(target)
PathBase.replace(target)
PathBase.rmdir()

The default implementations of these methods immediately raise UnsupportedOperation.