Pathlib Mate

1.3.2 · active · verified Sat Apr 11

Pathlib Mate (pathlib-mate) is a Python library that extends and enhances the standard `pathlib` module, providing more powerful and user-friendly methods and attributes for path manipulation. It offers convenient attribute accessors for path components, advanced file and directory search capabilities, and utility methods for common file operations. The library is actively maintained, with releases occurring infrequently, the latest being in January 2024.

Warnings

gotcha Always import `Path` from `pathlib_mate` (e.g., `from pathlib_mate import Path`) to ensure you access the extended functionality. Importing from the standard `pathlib` will result in a basic `Path` object without the `pathlib-mate` enhancements.
Fix: Ensure your import statement explicitly references `pathlib_mate`: `from pathlib_mate import Path`.
gotcha Avoid converting `pathlib_mate.Path` objects to strings (`str(path_obj)`) prematurely. Many Python functions and modern libraries (including `open()`, `shutil` operations, `json` functions, etc.) natively accept `Path` objects (since Python 3.6+). Converting to string too early can lead to loss of Path object methods, reduce type safety, and mask potential cross-platform issues.
Fix: Pass `Path` objects directly to functions whenever possible. Only convert to `str()` when interacting with older libraries that explicitly do not support `os.PathLike` objects.
gotcha While `pathlib-mate` extends `pathlib`, some file manipulation methods may have improved alternatives. For example, `pathlib-mate` introduces `Path.moveto()` as a more powerful and flexible alternative to the default `Path.rename()` method for moving/renaming files. Be aware of these specialized methods to leverage the full power of the library.
Fix: Review `pathlib-mate`'s documentation for enhanced file manipulation methods like `moveto()`, `copyto()`, and specialized `select_*()` methods, which often offer more control or simplified usage compared to their standard `pathlib` counterparts.
gotcha For extremely performance-critical operations involving thousands or millions of file system interactions in a tight loop, the object-oriented overhead of `pathlib` (and by extension `pathlib-mate`) *can* be slightly higher than raw string manipulation with `os.path`. For most applications, the benefits in readability and correctness outweigh this minor difference.
Fix: Profile your code if performance is a concern. If `pathlib-mate` operations are identified as a bottleneck in extreme scenarios, consider low-level `os.path` functions for that specific, optimized section, though this is rarely necessary.

Install

pip install pathlib-mate Install latest version
pip install --upgrade pathlib-mate Upgrade to latest version

Imports

Path
```
from pathlib_mate import Path
```
To access the extended functionality provided by pathlib-mate, you must import its `Path` class, not the standard library's `pathlib.Path`.

Quickstart

This quickstart demonstrates how to create a `Path` object from `pathlib-mate`, access its extended attributes like `abspath`, `basename`, `fname`, and `ext`, and perform powerful search operations using methods like `select_by_ext`. It creates and cleans up a temporary directory and files to illustrate functionality.

import os
from pathlib_mate import Path
import shutil

# Create a temporary directory and file for demonstration
test_dir = Path("pathlib_mate_demo_dir")
test_file = test_dir / "example.txt"

try:
    test_dir.mkdir(parents=True, exist_ok=True)
    test_file.write_text("Hello, pathlib-mate!")

    # 1. Basic Path Creation and Attribute Access
    p = Path(test_file.abspath)
    print(f"Absolute path: {p.abspath}")
    print(f"File name with extension: {p.basename}")
    print(f"File name without extension: {p.fname}")
    print(f"File extension: {p.ext}")
    print(f"Parent directory name: {p.dirname}")
    print(f"Parent directory path: {p.dirpath}")
    print(f"File size in bytes: {p.size}")
    print(f"File size (human readable): {p.size_in_text}")

    # 2. Powerful Path Search (example: find all text files)
    # Create another file for search demo
    (test_dir / "another.txt").write_text("Another file.")
    (test_dir / "image.jpg").write_bytes(b'fake_image_data')

    print("\nSearching for .txt files:")
    for txt_file in test_dir.select_by_ext(ext=".txt", recursive=True):
        print(f"  Found: {txt_file.basename}")

finally:
    # Clean up temporary directory
    if test_dir.exists():
        shutil.rmtree(test_dir.abspath)
    print("\nCleanup complete.")

view raw JSON →