This document covers CPython's pathlib module, which provides an object-oriented interface for filesystem paths and file operations. The pathlib system includes pure path manipulation (without I/O), concrete path operations (with filesystem access), protocol-based virtual filesystem (VFS) support, and low-level OS integration for high-performance file operations.
The pathlib system is built on a hierarchical class structure that separates pure path manipulation from filesystem I/O operations. The design uses abstract base classes and protocols to define operations for different types of path objects. The architecture supports protocol-based virtual filesystem (VFS) operations and high-performance I/O wrappers.
The following diagram bridges the natural language concepts of "Pure" and "Concrete" paths to their specific code entities and the protocols they implement.
Title: Path Hierarchy and Protocol Integration
Sources: Lib/pathlib/__init__.py39-43 Lib/pathlib/__init__.py81-89 Lib/pathlib/_os.py201-217 Doc/library/pathlib.rst15-30 Lib/pathlib/types.py83-89 Lib/pathlib/types.py37-50 Lib/pathlib/types.py53-62
Pure paths provide path manipulation without filesystem I/O. The PurePath class and its subclasses handle path parsing, joining, and property access using string operations and internal parsing logic.
When a PurePath is instantiated, it stores raw segments and lazily parses them into drive, root, and tail components upon first access.
Title: PurePath Internal Data Flow
The PurePath class uses a parser attribute that references either posixpath or ntpath modules for platform-specific path operations Lib/pathlib/__init__.py126 Path parsing results are cached in internal slots such as _drv, _root, and _tail_cached to avoid redundant computations Lib/pathlib/__init__.py91-103 Construction handles os.PathLike objects via os.fspath() Lib/pathlib/__init__.py148-157
Sources: Lib/pathlib/__init__.py81-125 Lib/pathlib/__init__.py138-158 Lib/test/test_pathlib/test_pathlib.py187-196
Concrete paths extend pure paths with filesystem I/O operations. The Path class provides methods for reading, writing, and querying filesystem objects.
Concrete paths implement the os.PathLike interface, allowing them to be passed to low-level functions Doc/library/pathlib.rst170-172 Many I/O operations are routed through vfsopen to support virtual filesystem objects that implement the VFS protocol via methods like __open_reader__, __open_writer__, or __open_updater__ Lib/pathlib/_os.py201-213
| Method | Implementation Detail |
|---|---|
open() | Calls vfsopen(self, mode, ...) Lib/pathlib/_os.py201-202 |
read_text() | Opens file and reads content as string Doc/library/pathlib.rst90-93 |
iterdir() | Yields path objects for directory entries Doc/library/pathlib.rst59-63 |
resolve() | Resolves symlinks and eliminates .. components Doc/library/pathlib.rst79-80 |
exists() | Checks if path exists on the filesystem Doc/library/pathlib.rst82-83 |
The UnsupportedOperation exception (inheriting from NotImplementedError) is raised when an unsupported operation is called on a path object, such as calling I/O methods on a PurePath Doc/library/pathlib.rst99-105 Lib/pathlib/__init__.py46-49
Sources: Lib/pathlib/__init__.py41-43 Lib/pathlib/_os.py201-217 Doc/library/pathlib.rst31-43 Lib/test/test_pathlib/test_pathlib.py75-79
Pathlib utilizes a set of private Abstract Base Classes (ABCs) and protocols in pathlib.types to facilitate alternative filesystem implementations (like zip files).
_JoinablePath: Defines the base for pure path manipulation, including joinpath, with_name, and parts Lib/pathlib/types.py83-193_ReadablePath: Extends paths with reading capabilities like open(), read_text(), and iterdir() Lib/test/test_pathlib/test_read.py30-38PathInfo: A protocol for querying file metadata (e.g., is_dir, exists) without full path resolution Lib/pathlib/types.py53-62_PathParser: A protocol for low-level path manipulation (e.g., split, normcase) provided by os.path variants Lib/pathlib/types.py37-50The vfsopen() function in pathlib._os allows for opening objects that implement the __open_reader__, __open_writer__, or __open_updater__ protocols, bypassing standard OS file handles where necessary Lib/pathlib/_os.py201-217
Sources: Lib/pathlib/types.py37-106 Lib/pathlib/_os.py201-217 Lib/test/test_pathlib/support/zip_path.py118-162
The pathlib._os module provides platform-abstracted file operations and efficient file copying mechanisms.
The copyfileobj() function Lib/pathlib/_os.py113-167 attempts to use the most efficient OS-specific syscalls before falling back to a standard read/write loop.
_ficlone via fcntl.ioctl(..., FICLONE, ...) if available Lib/pathlib/_os.py42-49_fcopyfile via posix._fcopyfile Lib/pathlib/_os.py54-60_copy_file_range for filesystem-level cloning or server-side copy Lib/pathlib/_os.py65-83copyfile2 via _winapi.CopyFile2 Lib/pathlib/_os.py103-110read() and write() loop using a 1MiB buffer Lib/pathlib/_os.py161-165The block size for these operations is dynamically determined by _get_copy_blocksize, typically defaulting to at least 8 MiB, but truncated to 1 GiB on 32-bit architectures Lib/pathlib/_os.py23-39
Sources: Lib/pathlib/_os.py23-167
The pathlib system provides platform-specific path classes that handle the differences between POSIX and Windows filesystem semantics.
| Feature | POSIX (posixpath) | Windows (ntpath) |
|---|---|---|
| Separator | / Lib/test/test_pathlib/test_pathlib.py121 | \ Lib/test/test_pathlib/test_pathlib.py169 |
| Alt Separator | None Lib/test/test_pathlib/test_pathlib.py122 | / Lib/test/test_pathlib/test_pathlib.py122 |
| Case Sensitivity | Case-sensitive Doc/library/pathlib.rst211-212 | Case-insensitive Doc/library/pathlib.rst213-214 |
| Root Handling | Handles // Doc/library/pathlib.rst159-160 | Handles UNC and drives Doc/library/pathlib.rst190-195 |
The PurePath and Path classes are factory classes. Calling PurePath() on a Windows machine returns a PureWindowsPath, while on POSIX it returns a PurePosixPath Lib/pathlib/__init__.py134-136 For backward compatibility with older pickles, pathlib._local provides aliases for these classes to ensure they can be unpickled in versions 3.14+ Lib/pathlib/_local.py1-12
Sources: Lib/pathlib/__init__.py127-136 Lib/pathlib/_local.py1-12 Lib/test/test_pathlib/test_pathlib.py187-203
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.