Universal Pathlib

Warnings

• breaking The `_protocol_dispatch=False` argument for extending the UPath API has been deprecated. Using it may lead to incorrect behavior or be removed in future versions.
  Fix: Migrate to subclassing `upath.extensions.ProxyUPath` for extending the API. Consult the official documentation for `ProxyUPath` usage examples.
• gotcha Attempting to instantiate a specific `UPath` subclass (e.g., `S3Path`) with a path string for a different protocol (e.g., `http://` or `file://`) will now raise a `TypeError` due to protocol incompatibility, rather than silently failing or using an incorrect backend.
  Fix: Ensure the protocol in the path string matches the `UPath` subclass being instantiated, or use the base `UPath` class which dispatches to the correct subclass based on the protocol.
• gotcha While `UPath` can attempt to handle any `fsspec`-compatible protocol, explicit implementations are tested and guaranteed. If no specialized `UPath` implementation exists for a given protocol, `UPath` will return a generic instance, but its behavior might not be fully reliable or tested.
  Fix: Prioritize using protocols with explicitly supported `UPath` implementations listed in the documentation. If using an untested protocol, thoroughly test its behavior and consider contributing an implementation if issues arise.

Install

• pip install universal-pathlib Basic Installation
• pip install universal-pathlib fsspec[s3,gcs] With S3 and GCS support

Imports

• UPath

  from upath import UPath

Quickstart

This quickstart demonstrates how to use `UPath` for both a remote S3 bucket and a local file. It shows common operations like writing text, reading text, checking existence, and iterating directory contents. For S3, ensure `s3fs` is installed and AWS credentials are configured (e.g., via environment variables or `~/.aws/credentials`). For actual usage, replace `your-test-s3-bucket` with an accessible S3 bucket.

import os
from upath import UPath

# Example for S3 (requires 's3fs' to be installed and AWS credentials configured)
# You can use environment variables for credentials or pass storage_options
S3_BUCKET = os.environ.get('S3_TEST_BUCKET', 'your-test-s3-bucket')
S3_KEY = 'example.txt'

# Create a UPath object for an S3 location
s3path = UPath(f"s3://{S3_BUCKET}") / S3_KEY

# Write content to the S3 file
try:
    s3path.write_text('Hello from Universal Pathlib!')
    print(f"Successfully wrote to {s3path}.")

    # Read content from the S3 file
    content = s3path.read_text()
    print(f"Content of {s3path}: '{content}'.")

    # Check if the path exists
    print(f"Does {s3path} exist? {s3path.exists()}.")

    # List contents of the parent directory (if bucket exists and is not empty)
    print(f"Listing contents of {s3path.parent}:")
    for p in s3path.parent.iterdir():
        print(f"  - {p}")

finally:
    # Clean up: delete the created file
    if s3path.exists():
        s3path.unlink()
        print(f"Cleaned up: deleted {s3path}.")

# Example for a local file (no additional fsspec backend needed)
local_path = UPath("local_example.txt")
local_path.write_text("This is a local file.")
print(f"Local file content: {local_path.read_text()}")
local_path.unlink()