s3pathlib is a Python package that provides an intuitive, object-oriented programming (OOP) interface for manipulating AWS S3 objects and directories. Its API closely resembles the Python standard library's `pathlib` module, making S3 interactions feel familiar and Pythonic. The library is actively maintained, with the current version being 2.3.6, and receives regular minor updates.
pip install s3pathlibVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize `s3pathlib` with AWS credentials, create an `S3Path` object, write content to S3, and read it back. It shows how to use `context.attach_boto_session` for explicit credential management.
Always capture the return value of write operations: `s3_path = s3_path.write_text('new content')`.To prevent accidental overwrites, explicitly check for file existence using `if not s3_path.exists():` before performing write operations.
Be mindful of trailing slashes (`/`) when defining S3 paths to denote directories, e.g., `S3Path('bucket', 'my-folder/')`. Use methods like `.to_dir()` if unsure.Avoid `isinstance(obj, pathlib.Path)` checks if you intend to support `S3Path`. Instead, check for `isinstance(obj, S3Path)` or rely on duck typing if only standard pathlib methods are used.
Explicitly configure and attach your `boto3` session using `from s3pathlib import context; context.attach_boto_session(your_boto3_session)` to ensure predictable AWS authentication and region behavior.
Install the package using pip: `pip install s3pathlib`
Configure AWS credentials using environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), AWS CLI config files (~/.aws/credentials), or by passing a boto3 session/client explicitly to S3Path.
Ensure the S3 bucket and key path are correct and that the AWS credentials have `s3:GetObject` permission for the target object. Verify the object's existence in S3.
Before calling `rmdir()`, ensure the S3 prefix is empty by deleting all objects within it, or use `delete_dir()` if you intend to recursively delete all contents.
To change path components, use methods like `with_name()`, `with_stem()`, `joinpath()`, or create a new `S3Path` object with the desired modifications.