API Reference

Functions

This package offers the following functions:

pathlib_abc.vfspath(obj)

Return the virtual filesystem path (a string) of the given object. Unlike the os.fspath() function, this function calls the object’s __vfspath__() method.

pathlib_abc.vfsopen(obj, mode='r' buffering=-1, encoding=None, errors=None, newline=None)

Open the given object and return a file object. Unlike the built-in open() function, this function additionally calls the object’s __open_reader__(), __open_writer__() or __open_updater__() method, as appropriate for the given mode.

Protocols

This package offers the following protocols:

class pathlib_abc.PathParser

Protocol for path parser objects, which split and join string paths.

Subclasses of JoinablePath should provide a path parser object as an attribute named parser.

Path parsers provide a subset of the os.path API. Python itself provides the posixpath and ntpath modules, which can be assigned to parser to implement path objects with POSIX or Windows syntax.

sep

Character used to separate path components.

altsep

Alternative path separator character, or None.

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.

Note

Trailing slashes are meaningful in posixpath and ntpath, so P('foo/').parent is P('foo'), and its name is the empty string.

splitext(name)

Split the filename into a pair (stem, ext), where ext is a file extension beginning with a dot and containing at most one dot, and stem is everything before the extension.

normcase(path)

Return the path with its case normalized.

Note

This method is used to detect case sensitivity in JoinablePath.full_match() and ReadablePath.glob(), where it’s called with the string containing a mix of upper and lowercase letters. Case-sensitive filesystems should return the string unchanged, whereas case-insensitive filesystems should return the string with its case modified (e.g. with upper() or lower().)

class pathlib_abc.PathInfo

Protocol for path information objects, which provide file type info.

Subclasses of ReadablePath should provide a path information object as an attribute named info.

exists(*, follow_symlinks=True)

Return True if the path is an existing file or directory, or any other kind of file; return False if the path doesn’t exist.

If follow_symlinks is False, return True for symlinks without checking if their targets exist.

is_dir(*, follow_symlinks=True)

Return True if the path is a directory, or a symbolic link pointing to a directory; return False if the path is (or points to) any other kind of file, or if it doesn’t exist.

If follow_symlinks is False, return True only if the path is a directory (without following symlinks); return False if the path is any other kind of file, or if it doesn’t exist.

is_file(*, follow_symlinks=True)

Return True if the path is a file, or a symbolic link pointing to a file; return False if the path is (or points to) a directory or other non-file, or if it doesn’t exist.

If follow_symlinks is False, return True only if the path is a file (without following symlinks); return False if the path is a directory or other other non-file, or if it doesn’t exist.

is_symlink()

Return True if the path is a symbolic link (even if broken); return False if the path is a directory or any kind of file, or if it doesn’t exist.

Abstract base classes

This package offers the following abstract base classes:

ABC	Inherits from	Abstract methods	Mixin methods
JoinablePath		parser __vfspath__() with_segments()	parts anchor parent parents name stem suffix suffixes with_name() with_stem() with_suffix() joinpath() __truediv__() __rtruediv__() relative_to() is_relative_to() full_match()
ReadablePath	JoinablePath	info __open_reader__() iterdir() readlink()	read_bytes() read_text() copy() copy_into() glob() walk()
WritablePath	JoinablePath	__open_writer__() mkdir() symlink_to()	write_bytes() write_text() _copy_from()

class pathlib_abc.JoinablePath

Abstract base class for path objects without I/O support.

parser

(Abstract attribute.) Implementation of PathParser used for low-level splitting and joining.

__vfspath__()

(Abstract method.) Return a string representation of the path, suitable for passing to methods of the parser.

with_segments(*pathsegments)

(Abstract method.) Create a new path object of the same type by combining the given pathsegments. This method is called whenever a derivative path is created, such as from parent and with_name().

parts

Tuple of path components. The default implementation repeatedly calls PathParser.split() to decompose the path.

anchor

The path’s irreducible prefix. The default implementation repeatedly calls PathParser.split() until the directory name stops changing.

parent

The path’s lexical parent. The default implementation calls PathParser.split() once.

parents

Sequence of the path’s lexical parents, beginning with the immediate parent. The default implementation repeatedly calls PathParser.split().

name

The path’s base name. The name is empty if the path has only an anchor, or ends with a slash. The default implementation calls PathParser.split() once.

stem

The path’s base name with the file extension omitted. The default implementation calls PathParser.splitext() on name.

suffix

The path’s file extension. The default implementation calls PathParser.splitext() on name.

suffixes

Sequence of the path’s file extensions. The default implementation repeatedly calls PathParser.splitext() on name.

with_name(name)

Return a new path with a different name. The name may be empty. The default implementation calls PathParser.split() to remove the old name, and with_segments() to create the new path object.

with_stem(stem)

Return a new path with a different stem, similarly to with_name().

with_suffix(suffix)

Return a new path with a different suffix, similarly to with_name().

joinpath(*pathsegments)

Return a new path with the given path segments joined onto the end. The default implementation calls with_segments() with the combined segments.

__truediv__(pathsegment)

Return a new path with the given path segment joined on the end.

__rtruediv__(pathsegment)

Return a new path with the given path segment joined on the beginning.

relative_to(other, *, walk_up=False)

Return a new relative path from other to this path. The default implementation compares this path and the parents of other; __eq__() must be implemented for this to work correctly.

is_relative_to(other)

Returns True is this path is relative to other, False otherwise. The default implementation compares this path and the parents of other; __eq__() must be implemented for this to work correctly.

full_match(pattern)

Return true if the path matches the given glob-style pattern, false otherwise. The default implementation uses PathParser.normcase() to establish case sensitivity.

class pathlib_abc.ReadablePath

Abstract base class for path objects with support for reading data. This is a subclass of JoinablePath

info

(Abstract attribute.) Implementation of PathInfo that supports querying the file type.

__open_reader__()

(Abstract method.) Open the path for reading in binary mode, and return a file object.

iterdir()

(Abstract method.) Yield path objects for the directory contents.

readlink()

(Abstract method.) Return the symlink target as a new path object.

read_bytes()

Return the binary contents of the path. The default implementation calls vfsopen().

read_text(encoding=None, errors=None, newline=None)

Return the text contents of the path. The default implementation calls vfsopen().

copy(target, **kwargs)

Copy the path to the given target, which should be an instance of WritablePath. The default implementation calls WritablePath._copy_from(), passing along keyword arguments.

copy_into(target_dir, **kwargs)

Copy the path into the given target directory, which should be an instance of WritablePath. See copy().

glob(pattern, *, recurse_symlinks=True)

Yield path objects in the file tree that match the given glob-style pattern. The default implementation uses info and iterdir().

Warning

For performance reasons, the default value for recurse_symlinks is True in this base class, but for historical reasons, the default is False in pathlib.Path. Furthermore, True is the only acceptable value for recurse_symlinks in this base class.

For maximum compatibility, users should supply recurse_symlinks=True explicitly when globbing recursively.

walk(top_down=True, on_error=None, follow_symlinks=False)

Yield a (dirpath, dirnames, filenames) triplet for each directory in the file tree, like os.walk(). The default implementation uses info and iterdir().

class pathlib_abc.WritablePath

Abstract base class for path objects with support for writing data. This is a subclass of JoinablePath

__open_writer__(mode)

(Abstract method.) Open the path for writing in binary mode, and return a file object. The mode argument is either 'w', 'a', or 'x'.

mkdir()

(Abstract method.) Create this path as a directory.

symlink_to(target, target_is_directory=False)

(Abstract method.) Create this path as a symlink to the given target.

write_bytes(data)

Write the given binary data to the path, and return the number of bytes written. The default implementation calls vfsopen().

write_text(data, encoding=None, errors=None, newline=None)

Write the given text data to the path, and return the number of bytes written. The default implementation calls vfsopen().

_copy_from(source, *, follow_symlinks=True)

Copy the path from the given source, which should be an instance of ReadablePath. The default implementation uses ReadablePath.info to establish the type of the source path. It uses vfsopen() to copy regular files; iterdir() and mkdir() to copy directories; and readlink() and symlink_to() to copy symlinks when follow_symlinks is false.