Path.py (jaraco/path)

Warnings

• breaking Version 12.0 significantly changed compatibility, dropping support for Python 2.7 and Python 3.4. Code relying on these older Python versions will break.
  Fix: Upgrade your Python environment to 3.5 or newer. The library currently requires Python >=3.9.
• deprecated The `.text` method was deprecated in version 13.1.0 in favor of `.read_text()` (for text) and `.read_bytes()` (for binary data). Using `.text` might lead to incorrect newline handling or encoding issues, and it requires an `encoding` parameter if the default is insufficient.
  Fix: Replace `my_path.text()` with `my_path.read_text(encoding='utf-8')` for text files, or `my_path.read_bytes()` for binary files. Always specify `encoding` for text operations.
• breaking Version 7.0 introduced changes to `open`, `write_text`, and `text` methods. The `open` method now uses `io.open` and will consistently raise an `OSError` on failure. The `text` method always returns text (never bytes) and requires an `encoding` parameter if the default is not suitable for decoding file content.
  Fix: Review calls to `open`, `write_text`, and `text`. Explicitly provide `encoding` for text-based operations. Ensure error handling for `OSError` is in place for file operations.
• gotcha `path.Path` objects are subclasses of `str`, allowing direct use where strings are expected. However, for APIs expecting `pathlib.Path` objects, there might be subtle behavioral differences, although `path` aims for `pathlib` compatibility where possible. Be cautious when mixing with code heavily relying on `pathlib`'s specific object behavior or type checks.
  Fix: If migrating from `pathlib` or integrating with `pathlib`-centric code, test thoroughly. For strict `pathlib` APIs, consider explicit `pathlib.Path(str(my_path))` conversion if issues arise.
• gotcha When creating directories, `Path.mkdir()` does not automatically create parent directories nor does it have an `exist_ok` parameter like `pathlib.Path.mkdir()`. It will raise an error if parent directories do not exist or if the directory already exists.
  Fix: Use `my_path.makedirs_p()` to recursively create directories and handle existing ones gracefully (similar to `os.makedirs(..., exist_ok=True)`). Only use `my_path.mkdir()` if you are certain the parent directory exists and the target directory does not.

Install

• pip install path Install latest version

Imports

• Path

  from path import Path

  The primary Path object is directly accessible from the top-level 'path' package. Older versions or alternative conventions might have used 'import path' and then accessed `path.path`.

Quickstart

This quickstart demonstrates basic file system operations using `path.Path` objects, including creating paths, ensuring directories exist, writing to and reading from files, checking existence, globbing, and cleanup. It highlights the use of the `/` operator for joining paths and methods like `makedirs_p()` and `rmdir_p()` for directory management.

from path import Path
import os

# Get current working directory
current_dir = Path.cwd()
print(f"Current directory: {current_dir}")

# Create a new path by joining components
# The '/' operator is overloaded for path concatenation
my_dir = current_dir / "temp_data"
my_file = my_dir / "example.txt"
print(f"Target file path: {my_file}")

# Ensure parent directories exist before creating the file
my_dir.makedirs_p() # Creates parent directories if they don't exist

# Write content to a file
my_file.write_text("Hello, path.py!\nThis is a test file.", encoding='utf-8')

# Read content from a file
content = my_file.read_text(encoding='utf-8')
print(f"Content of {my_file.name}:\n{content}")

# Check if path exists
if my_file.exists():
    print(f"'{my_file.name}' exists.")

# Iterate over files with a pattern (globbing)
print("Python files in current directory:")
for f in current_dir.files("*.py"):
    print(f"- {f.name}")

# Clean up: remove the created file and its parent directory
my_file.remove()
my_dir.rmdir_p() # Removes the directory and its parents if empty