{"id":3208,"library":"path","title":"Path.py (jaraco/path)","description":"The 'path' library provides an object-oriented approach to file system paths, building upon the functionality of `os.path`. Distinct from the built-in `pathlib.Path`, `path.Path` objects are implemented as subclasses of `str`, allowing them to often be passed directly to functions expecting string paths without explicit conversion. It offers a range of convenience methods for common file and directory operations, aiming for a more Pythonic and robust way to interact with the filesystem. The current version is 17.1.1, and the project maintains a fairly active release schedule with several updates per year.","status":"active","version":"17.1.1","language":"en","source_language":"en","source_url":"https://github.com/jaraco/path","tags":["filesystem","path manipulation","file I/O","object-oriented paths","os.path wrapper"],"install":[{"cmd":"pip install path","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import path","symbol":"Path","correct":"from path import Path"}],"quickstart":{"code":"from path import Path\nimport os\n\n# Get current working directory\ncurrent_dir = Path.cwd()\nprint(f\"Current directory: {current_dir}\")\n\n# Create a new path by joining components\n# The '/' operator is overloaded for path concatenation\nmy_dir = current_dir / \"temp_data\"\nmy_file = my_dir / \"example.txt\"\nprint(f\"Target file path: {my_file}\")\n\n# Ensure parent directories exist before creating the file\nmy_dir.makedirs_p() # Creates parent directories if they don't exist\n\n# Write content to a file\nmy_file.write_text(\"Hello, path.py!\\nThis is a test file.\", encoding='utf-8')\n\n# Read content from a file\ncontent = my_file.read_text(encoding='utf-8')\nprint(f\"Content of {my_file.name}:\\n{content}\")\n\n# Check if path exists\nif my_file.exists():\n    print(f\"'{my_file.name}' exists.\")\n\n# Iterate over files with a pattern (globbing)\nprint(\"Python files in current directory:\")\nfor f in current_dir.files(\"*.py\"):\n    print(f\"- {f.name}\")\n\n# Clean up: remove the created file and its parent directory\nmy_file.remove()\nmy_dir.rmdir_p() # Removes the directory and its parents if empty\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.5 or newer. The library currently requires Python >=3.9.","message":"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.","severity":"breaking","affected_versions":"<12.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=13.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}