{"id":2184,"library":"pathy","title":"Pathy: Cloud-Agnostic Pathlib","description":"Pathy extends Python's `pathlib.Path` to provide a unified, pathlib-compatible interface for interacting with local filesystems and various cloud storage services (S3, GCS, Azure Blob Storage). It aims to make file operations cloud-agnostic and seamless. The current stable version is 0.13.0, with frequent minor and patch updates.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/justindujardin/pathy","tags":["pathlib","cloud storage","s3","gcs","azure","filesystem","object storage"],"install":[{"cmd":"pip install pathy","lang":"bash","label":"Base installation"},{"cmd":"pip install \"pathy[s3]\"","lang":"bash","label":"With S3 support"},{"cmd":"pip install \"pathy[gcs]\"","lang":"bash","label":"With Google Cloud Storage support"},{"cmd":"pip install \"pathy[azure]\"","lang":"bash","label":"With Azure Blob Storage support"}],"dependencies":[{"reason":"Used for efficient reading/writing to remote filesystems.","package":"smart-open","optional":false},{"reason":"Required for AWS S3 backend.","package":"boto3","optional":true},{"reason":"Required for Google Cloud Storage backend.","package":"google-cloud-storage","optional":true},{"reason":"Required for Azure Blob Storage backend.","package":"azure-storage-blob","optional":true}],"imports":[{"symbol":"Pathy","correct":"from pathy import Pathy"},{"note":"Returned by .stat() methods for consistent metadata across local and cloud paths.","symbol":"BlobStat","correct":"from pathy import BlobStat"}],"quickstart":{"code":"from pathy import Pathy\nimport os\n\n# --- Local filesystem operations ---\nlocal_file_path = Pathy(\"./temp_pathy_local_file.txt\")\ntry:\n    local_file_path.write_text(\"Hello from Pathy on local filesystem!\")\n    print(f\"Local file content: '{local_file_path.read_text()}'\")\n    print(f\"Local file size: {local_file_path.stat().st_size} bytes\")\nfinally:\n    if local_file_path.exists():\n        local_file_path.unlink() # Clean up\n\n# --- Cloud storage operations (example: S3) ---\n# Replace with your bucket name and ensure AWS credentials are set as environment variables\ns3_bucket = os.environ.get(\"PATHY_TEST_S3_BUCKET\", \"my-pathy-test-bucket\")\ns3_path = Pathy(f\"s3://{s3_bucket}/example_dir/cloud_data.txt\")\n\n# Check if AWS credentials are likely available\nif os.environ.get(\"AWS_ACCESS_KEY_ID\") and os.environ.get(\"AWS_SECRET_ACCESS_KEY\"):\n    print(f\"\\nAttempting S3 operations on: {s3_path}\")\n    try:\n        # Create parent directories (no-op if they exist for cloud paths)\n        s3_path.parent.mkdir(parents=True, exist_ok=True)\n        s3_path.write_text(\"Hello from Pathy on S3!\")\n        print(f\"S3 file content: '{s3_path.read_text()}'\")\n        print(f\"S3 file size: {s3_path.stat().st_size} bytes\")\n    except Exception as e:\n        print(f\"Failed to perform S3 operations. Ensure 'pathy[s3]' is installed and credentials are correct. Error: {e}\")\n    finally:\n        if s3_path.exists():\n            s3_path.unlink() # Clean up\n            print(f\"Cleaned up S3 file: {s3_path}\")\nelse:\n    print(\"\\nSkipping S3 example: AWS_ACCESS_KEY_ID and/or AWS_SECRET_ACCESS_KEY environment variables not set.\")\n    print(\"Install 'pathy[s3]' and configure AWS credentials to run this example.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.11.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.11.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Upgrade your Python environment to 3.10 or later to use recent Pathy versions.","message":"Dropped support for Python 3.7. Pathy now requires Python 3.10 or newer.","severity":"breaking","affected_versions":">=0.11.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Ensure you install Pathy with the correct extras for the cloud storage you intend to use. Example: `pip install \"pathy[s3]\"`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}