pathlib

Warnings

• gotcha Avoid converting `Path` objects to strings (`str(path_obj)`) too early, as this loses all the benefits of the `Path` object's methods and object-oriented features. Most modern Python functions and libraries (since Python 3.6, including `open()`, `shutil.copy()`, `json.load`/`json.dump`, `subprocess.run`) natively accept `Path` objects.
  Fix: Pass `Path` objects directly to functions that support `os.PathLike` (which `Path` implements). Convert to string only when absolutely necessary for older APIs that strictly require `str`.
• deprecated The `pathlib` PyPI backport (version 1.0.1) is no longer maintained. For Python 2.7, `pathlib2` is the recommended and more actively maintained backport to provide similar functionality to the standard library `pathlib`.
  Fix: For Python 2.7, use `pip install pathlib2` and `from pathlib2 import Path`. For Python 3.4+, use the built-in `pathlib` module directly.
• breaking The semantics of certain methods, like `Path.iterdir()`, can change between major Python versions. For instance, in Python 3.13, `Path.iterdir()` started evaluating a portion of the generator eagerly, potentially raising `FileNotFoundError` earlier if the directory doesn't exist, which was not the case in 3.12 (lazy evaluation).
  Fix: Always ensure the directory exists before calling `iterdir()` if the path might not exist. Be aware of potential subtle behavioral changes across Python versions when relying on specific iterator or generator evaluation timings.
• gotcha While `pathlib` provides `PurePosixPath` and `PureWindowsPath` for platform-agnostic path manipulation, using them explicitly can lead to `NotImplementedError` if you try to instantiate a platform-specific concrete path (e.g., `WindowsPath` on Unix) directly or if I/O operations are attempted with a `PurePath` object. Use `Path` for platform-appropriate concrete paths unless you specifically need pure path operations without I/O or cross-platform path *representation*.
  Fix: For general file system operations on the current system, always use `pathlib.Path` which instantiates the correct concrete path for the platform. Only use `PurePath`, `PurePosixPath`, or `PureWindowsPath` when you explicitly intend to manipulate paths purely computationally without touching the filesystem, or to represent paths for a different OS.
• gotcha Mixing `pathlib` objects with functions from the `os` or `os.path` modules can negate `pathlib`'s benefits, often requiring unnecessary `str()` conversions. `pathlib` aims to consolidate and replace most `os.path` functionality.
  Fix: Prioritize `pathlib` methods (e.g., `/` operator for joining, `.exists()`, `.is_file()`, `.glob()`, `.rglob()`, `.mkdir()`, `.unlink()`) over `os.path` functions. Only fall back to `os` or `shutil` when `pathlib` does not offer equivalent functionality (e.g., `shutil.copy` for copying files efficiently).

Install

• # For Python 3.4 and later, pathlib is part of the standard library and does not require installation. Python 3.4+
• pip install pathlib Python < 3.4 (backport)
• pip install pathlib2 Python 2.7 (recommended backport)

Imports

• Path

  from pathlib import Path

  Importing Path directly is generally preferred for brevity and clarity.

Quickstart

This quickstart demonstrates creating a `Path` object, ensuring a directory exists, writing and reading text to/from a file, and accessing common path properties. It concludes with a cleanup of the created directory and file.

import os
from pathlib import Path

# Create a path object
current_dir = Path.cwd()
example_dir = current_dir / "my_data"
example_file = example_dir / "report.txt"

# Ensure the directory exists
example_dir.mkdir(exist_ok=True)

# Write to a file
example_file.write_text("This is a test report.\n")
print(f"Created file: {example_file.resolve()}")

# Read from a file
content = example_file.read_text()
print(f"File content: {content.strip()}")

# Check properties
print(f"Is it a file? {example_file.is_file()}")
print(f"File name: {example_file.name}")
print(f"File suffix: {example_file.suffix}")
print(f"Parent directory: {example_file.parent.name}")

# Clean up (optional)
example_file.unlink()
example_dir.rmdir()
print("Cleaned up example directory and file.")