{"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":"python","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,"search_vec":"'0.13.0':50 'agnost':4,42 'aim':35 'azur':31,62 'blob':32 'cloud':3,26,41,58 'cloud-agnost':2,40 'compat':17 'current':46 'extend':7 'file':38 'filesystem':23,63 'frequent':52 'gcs':30,61 'interact':20 'interfac':18 'local':22 'make':37 'minor':53 'object':64 'oper':39 'patch':55 'pathi':1,6 'pathlib':5,16,57 'pathlib-compat':15 'pathlib.path':10 'provid':12 'python':8 's3':29,60 'seamless':44 'servic':28 'stabl':47 'storag':27,33,59,65 'unifi':14 'updat':56 'various':25 'version':48","created_at":"2026-04-09T18:47:06.692310+00:00","updated_at":"2026-04-16T17:55:37.123422+00:00","problems":[{"fix":"Install the pathy library using pip: `pip install pathy`","cause":"The 'pathy' library is not installed in your current Python environment, or the Python interpreter cannot find it in its search path.","error":"ModuleNotFoundError: No module named 'pathy'"},{"fix":"Check the pathy documentation for the correct method name and its availability for the specific cloud storage backend you are using. If the method is from `pathlib.Path`, ensure it's supported by `pathy.Pathy` or adjust your logic accordingly.","cause":"You are attempting to access a method or attribute on a `pathy.Pathy` object that either does not exist, is misspelled, or is specific to `pathlib.Path` and not yet implemented or applicable for cloud paths within Pathy.","error":"AttributeError: 'Pathy' object has no attribute 'some_method'"},{"fix":"Verify that your cloud provider credentials (e.g., service account key file for GCS, AWS access key ID and secret access key for S3, Azure storage account name and key) are correctly configured and have the necessary permissions for the requested operation. Check environment variables or configuration files Pathy uses for credentials.","cause":"Pathy or the underlying cloud storage SDK (e.g., for GCS, S3, or Azure Blob Storage) failed to authenticate your request, often due to incorrect, expired, or missing credentials/access keys, or insufficient permissions.","error":"InvalidAuthentication: The provided authentication header is invalid."},{"fix":"Double-check the cloud path for correctness, including bucket name, prefixes, and object name. Ensure the file or directory actually exists in your cloud storage. You can use methods like `.exists()` on the `Pathy` object to programmatically check for existence before attempting operations.","cause":"The specified cloud file or directory path does not exist in the target cloud storage bucket, or there's a typo in the path.","error":"FileNotFoundError: No such file or directory: 'gs://your-bucket/nonexistent-file.txt'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.14.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/justindujardin/pathy","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pathy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","gcp","azure","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}