Pathy: Cloud-Agnostic Pathlib

Warnings

• breaking Pathy no longer inherits directly from `pathlib.Path`. This means some methods or properties specific to `pathlib.Path` might behave differently or be unavailable, and direct `isinstance(pathy_obj, pathlib.Path)` checks will fail.
  Fix: Review existing code for direct `pathlib.Path` inheritance assumptions or specific `pathlib` method calls. Pathy aims to maintain compatibility with `pathlib`'s public API, but internal structure has changed.
• breaking The `Pathy.key` property now returns a `str` instead of a `Pathy` instance. This changes the type of the key used to represent the path's identifier within a bucket or root.
  Fix: If you were chaining `.key` operations or expecting a `Pathy` object, update your code to handle a `str` return type. Convert back to `Pathy(key_string)` if a Pathy instance is needed.
• breaking The `Pathy.stat()` method now consistently returns a `pathy.BlobStat` object for both local and remote paths. Previously, local paths would return an `os.stat_result`.
  Fix: Update code that inspects `stat()` results to expect `BlobStat` attributes (e.g., `st_size`, `st_mtime`) which are compatible with `os.stat_result` but now provide a unified interface. Custom attribute access might need adjustment.
• breaking Dropped support for Python 3.7. Pathy now requires Python 3.10 or newer.
  Fix: Upgrade your Python environment to 3.10 or later to use recent Pathy versions.
• breaking Pathy's internal architecture, relying on `pathlib_abc`, underwent significant upgrades (0.3.x to 0.5.x). While primarily internal, users extending Pathy or relying on deep internal interfaces might experience breaking changes.
  Fix: If you have custom Pathy backends or complex extensions, review the `pathlib_abc` changes or the Pathy source for potential incompatibilities in abstract methods or internal types.
• gotcha Cloud provider support requires specific 'extras' to be installed (e.g., `pathy[s3]`, `pathy[gcs]`, `pathy[azure]`). Without these, attempts to access cloud paths will result in import errors or `ClientError`.
  Fix: Ensure you install Pathy with the correct extras for the cloud storage you intend to use. Example: `pip install "pathy[s3]"`.

Install

• pip install pathy Base installation
• pip install "pathy[s3]" With S3 support
• pip install "pathy[gcs]" With Google Cloud Storage support
• pip install "pathy[azure]" With Azure Blob Storage support

Imports

• Pathy

  from pathy import Pathy

• BlobStat

  from pathy import BlobStat

  Returned by .stat() methods for consistent metadata across local and cloud paths.

Quickstart

This example demonstrates basic file operations using Pathy for both local and cloud (S3) paths. For cloud operations, ensure the relevant `pathy` extras are installed (e.g., `pathy[s3]`) and environment variables for authentication are configured.

from pathy import Pathy
import os

# --- Local filesystem operations ---
local_file_path = Pathy("./temp_pathy_local_file.txt")
try:
    local_file_path.write_text("Hello from Pathy on local filesystem!")
    print(f"Local file content: '{local_file_path.read_text()}'")
    print(f"Local file size: {local_file_path.stat().st_size} bytes")
finally:
    if local_file_path.exists():
        local_file_path.unlink() # Clean up

# --- Cloud storage operations (example: S3) ---
# Replace with your bucket name and ensure AWS credentials are set as environment variables
s3_bucket = os.environ.get("PATHY_TEST_S3_BUCKET", "my-pathy-test-bucket")
s3_path = Pathy(f"s3://{s3_bucket}/example_dir/cloud_data.txt")

# Check if AWS credentials are likely available
if os.environ.get("AWS_ACCESS_KEY_ID") and os.environ.get("AWS_SECRET_ACCESS_KEY"):
    print(f"\nAttempting S3 operations on: {s3_path}")
    try:
        # Create parent directories (no-op if they exist for cloud paths)
        s3_path.parent.mkdir(parents=True, exist_ok=True)
        s3_path.write_text("Hello from Pathy on S3!")
        print(f"S3 file content: '{s3_path.read_text()}'")
        print(f"S3 file size: {s3_path.stat().st_size} bytes")
    except Exception as e:
        print(f"Failed to perform S3 operations. Ensure 'pathy[s3]' is installed and credentials are correct. Error: {e}")
    finally:
        if s3_path.exists():
            s3_path.unlink() # Clean up
            print(f"Cleaned up S3 file: {s3_path}")
else:
    print("\nSkipping S3 example: AWS_ACCESS_KEY_ID and/or AWS_SECRET_ACCESS_KEY environment variables not set.")
    print("Install 'pathy[s3]' and configure AWS credentials to run this example.")