path.py

Overview

`path.py` provides a comprehensive, object-oriented interface for interacting with local filesystem paths. It abstracts many common filesystem operations (reading, writing, copying, moving files/directories, querying metadata, pattern matching, and importing Python modules) into the `LocalPath` class and supporting utilities.

This file is designed to enhance and simplify filesystem manipulation beyond the standard [os.path](/projects/286/67409) and `os` modules, with portable behavior across platforms (especially POSIX and Windows). It also includes numerous utility classes and functions to support path checking, visitation, pattern matching, and hashing.

The core functionality centers around the `LocalPath` class, which represents an absolute local filesystem path and exposes a rich API for file and directory operations. The file also defines helper classes like `Checkers` for path attribute checks, `Visitor` for recursive directory traversal with filtering, and `FNMatcher` to match pathnames against glob-like patterns.

Classes and Functions

Class: LocalPath

An object-oriented wrapper around local filesystem paths that provides extensive methods for filesystem operations, path manipulation, and querying.

Key Properties and Attributes

• strpath (str): The absolute path represented by the instance.

• sep (str): The native path separator (os.sep).

Initialization

LocalPath(path=None, expanduser=False)

• Parameters:

  • path (Optional): Initial path string or path-like object. Defaults to current working directory if None.

  • expanduser (bool): Whether to expand ~ to the user home directory.

• Behavior: Always stores an absolute path internally.

Path Manipulation Properties

• basename: Returns the base name of the path (last component).

• dirname: Returns the directory component of the path.

• purebasename: Returns the basename without extension.

• ext: Returns the file extension including the dot (.).

Path Manipulation Methods

• join(*args, abs=False) -> LocalPath
  Joins additional path components to this path. If abs=True, any absolute component resets the base path.

• new(**kwargs) -> LocalPath
  Returns a modified copy of the path, allowing changing basename, dirname, ext, etc.

• dirpath(*args, **kwargs) -> LocalPath
  Returns the directory path, optionally joined with extra components.

• relto(relpath) -> str
  Returns the relative path string from the given relpath to this path.

• common(other) -> LocalPath | None
  Returns the common ancestor path with another LocalPath.

• parts(reverse=False) -> list[LocalPath]
  Returns a list of this path and its ancestors, root-first (or reversed if reverse=True).

• __add__(other) -> LocalPath
  Adds a string to the basename, returning a new path.

File and Directory Operations

• exists() -> bool
  Returns True if path exists.

• isdir() -> bool
  Returns True if path is a directory.

• isfile() -> bool
  Returns True if path is a regular file.

• islink() -> bool
  Returns True if path is a symbolic link.

• check(**kwargs) -> bool
  Flexible checker for path properties such as file=1, dir=1, link=0, exists=1.

• listdir(fil=None, sort=None) -> list[LocalPath]
  Lists directory contents, optionally filtering with a callable or glob pattern, and sorting.

• visit(fil=None, rec=None, ignore=NeverRaised, bf=False, sort=False)
  Recursively yields paths below this path, filtered and optionally breadth-first.

• read_binary() -> bytes
  Reads and returns the file contents as bytes.

• read_text(encoding) -> str
  Reads and returns text from the file with the specified encoding.

• write(data, mode='w', ensure=False)
  Writes data to the file. Ensures directories if ensure=True.

• write_binary(data, ensure=False)
  Write bytes data ensuring directories if needed.

• write_text(data, encoding, ensure=False)
  Write text data with encoding, ensuring directories if needed.

• remove(rec=1, ignore_errors=False)
  Removes file or directory tree recursively.

• copy(target, mode=False, stat=False)
  Copies this path to target path, optionally copying permissions and metadata.

• rename(target)
  Renames/moves this path to target.

• mkdir(*args)
  Creates a directory at the joined path.

• chmod(mode, rec=0)
  Changes permission mode recursively if rec is true.

• setmtime(mtime=None)
  Sets file modification time.

Metadata and Stat

• stat(raising=True) -> Stat
  Returns stat info for the path. If raising=False returns None on failure.

• lstat() -> Stat
  Returns lstat info (does not follow symlinks).

• size() -> int
  Returns file size.

• mtime() -> float
  Returns modification time.

• atime() -> float
  Returns last access time.

Python Import Helpers

• pypkgpath() -> LocalPath | None
  Returns the closest containing Python package directory (with __init__.py).

• pyimport(modname=None, ensuresyspath=True)
  Imports the path as a Python module, optionally modifying sys.path to ensure importability.

Execution

• sysexec(*argv, **popen_opts) -> str
  Executes the file as a system process, returning stdout as text. Raises on nonzero exit.

Temporary Directory Helpers

• get_temproot() -> LocalPath
  Returns the system temporary directory.

• mkdtemp(rootdir=None) -> LocalPath
  Creates and returns a unique temporary directory.

• make_numbered_dir(prefix='session-', rootdir=None, keep=3, lock_timeout=172800) -> LocalPath
  Creates a unique numbered directory under rootdir with concurrency-safe locking and garbage collection of old directories.

Class: Checkers

Helper class that performs multiple attribute checks on a `LocalPath` instance (e.g., `file`, `dir`, `exists`, `link`).

• dotfile()
  Checks if basename starts with a dot.

• ext(arg)
  Checks if extension matches arg.

• basename(arg)
  Checks if basename equals arg.

• basestarts(arg)
  Checks if basename starts with arg.

• relto(arg)
  Checks if path is relative to arg.

• fnmatch(arg)
  Checks if path matches glob pattern.

• endswith(arg)
  Checks if path string ends with arg.

• _evaluate(kw)
  Evaluates a dictionary of checks, supporting negation with not prefix.

• dir(), file(), exists(), link()
  Check file type flags via stat.

Class: Visitor

Used internally by `LocalPath.visit()` to recursively generate paths filtered by filename and recursion criteria.

• Initialized with filters for filename (fil), recursion (rec), exception to ignore, breadth-first flag, and sorting flag.

• gen(path)
  Recursively yield matching paths from path.

Class: FNMatcher

Callable class to match paths against Unix shell-style wildcards (glob patterns).

• __init__(pattern)
  Stores pattern string.

• __call__(path)
  Returns True if path matches pattern, considering platform-specific path separators.

Class: Stat

Wrapper around `os.stat_result` with additional convenience methods:

• Properties:

  • size, mtime, owner, group

• Methods:

  • isdir(), isfile(), islink()

Utility Functions

• getuserid(user)
  Convert username or uid to numeric user id (POSIX).

• getgroupid(group)
  Convert group name or gid to numeric group id (POSIX).

• copymode(src, dest)
  Copy file permission bits.

• copystat(src, dest)
  Copy permission bits, timestamps, and flags.

• copychunked(src, dest)
  Copy file contents in chunks.

• isimportable(name)
  Returns True if string is a valid Python importable name.

• map_as_list(func, iter)
  Helper to apply a function over an iterable and return a list.

Important Implementation Details

• The LocalPath class always normalizes and stores absolute paths internally to avoid ambiguity.

• Platform-specific behavior is handled for Windows (e.g., path separator handling, ownership changes not implemented).

• Recursive directory traversal (visit) supports filtering at both the directory and filename levels, with optional breadth-first ordering.

• The make_numbered_dir method provides concurrency-safe creation of unique numbered directories with lockfiles, and automatic cleanup of old directories, useful for session or temp directories in multi-process environments.

• The pyimport method supports importing Python modules from arbitrary filesystem locations, even outside of packages, optionally adjusting sys.path as needed.

• The Checkers class supports negations by prefixing check names with not, enabling expressive file property queries.

• Handling of file permissions, symbolic links, and ownership is provided where supported by the platform.

Interaction with Other Parts of the System

• Relies on the error module (imported relatively as .error) for error-checked function calls and custom exceptions.

• Uses Python standard modules: os, sys, fnmatch, importlib.util, io, stat, subprocess, tempfile, atexit, uuid, and warnings.

• Designed to be a foundational utility for filesystem interactions, likely used by higher-level components requiring path abstractions, file operations, and dynamic Python module loading.

Usage Examples

from path import local

# Create a LocalPath instance
p = local("/tmp/example.txt")

# Read text content
content = p.read_text(encoding="utf-8")

# Write binary data ensuring directories exist
p.write_binary(b"hello world", ensure=True)

# Check if file exists and is a regular file
if p.check(file=1):
    print("File exists")

# List all Python files in a directory
py_files = p.dirpath().listdir("*.py", sort=True)

# Visit all files recursively matching a pattern
for file in p.dirpath().visit(fil="*.txt", rec="*"):
    print(file)

# Import a Python module from a path
mod = p.pyimport()

# Create a unique temporary directory
tempdir = local.mkdtemp()

# Compute md5 hash of a file
md5_hash = p.computehash("md5")

Mermaid Class Diagram

classDiagram
    class LocalPath {
        -strpath: str
        +sep: str
        +__init__(path=None, expanduser=False)
        +basename
        +dirname
        +purebasename
        +ext
        +join(*args, abs=False)
        +new(**kwargs)
        +dirpath(*args, **kwargs)
        +relto(relpath)
        +common(other)
        +parts(reverse=False)
        +exists()
        +isdir()
        +isfile()
        +islink()
        +check(**kw)
        +listdir(fil=None, sort=None)
        +visit(fil=None, rec=None, ignore=NeverRaised, bf=False, sort=False)
        +read_binary()
        +read_text(encoding)
        +write(data, mode="w", ensure=False)
        +write_binary(data, ensure=False)
        +write_text(data, encoding, ensure=False)
        +remove(rec=1, ignore_errors=False)
        +copy(target, mode=False, stat=False)
        +rename(target)
        +mkdir(*args)
        +chmod(mode, rec=0)
        +setmtime(mtime=None)
        +stat(raising=True)
        +lstat()
        +size()
        +mtime()
        +atime()
        +pypkgpath()
        +pyimport(modname=None, ensuresyspath=True)
        +sysexec(*argv, **popen_opts)
        +get_temproot()
        +mkdtemp(rootdir=None)
        +make_numbered_dir(prefix="session-", rootdir=None, keep=3, lock_timeout=172800)
    }
    class Checkers {
        -path: LocalPath
        -_statcache: Stat
        +dotfile()
        +ext(arg)
        +basename(arg)
        +basestarts(arg)
        +relto(arg)
        +fnmatch(arg)
        +endswith(arg)
        +_evaluate(kw)
        +_stat()
        +dir()
        +file()
        +exists()
        +link()
    }
    class Visitor {
        -fil: Callable or FNMatcher
        -rec: Callable or FNMatcher or None
        -ignore: Exception
        -breadthfirst: bool
        -optsort: Callable
        +__init__(fil, rec, ignore, bf, sort)
        +gen(path)
    }
    class FNMatcher {
        -pattern: str
        +__init__(pattern)
        +__call__(path)
    }
    class Stat {
        -path: LocalPath
        -_osstatresult: os.stat_result
        +size
        +mtime
        +owner
        +group
        +isdir()
        +isfile()
        +islink()
    }

    LocalPath "1" o-- "1" Checkers : uses
    LocalPath "1" o-- "*" Visitor : uses for visit()
    LocalPath "1" o-- "1" FNMatcher : uses for fnmatch
    LocalPath "1" o-- "1" Stat : uses for stat info

End of documentation for path.py