Slash3
Slash3 is a Python package for building and navigating Amazon Web Services S3 URIs.
What's an S3 URI?
An S3 URI (Uniform Resource Identifier) is a string that identifies a bucket, and optionally a key, in Amazon Web Services S3.
The pattern for an S3 URI is s3://BUCKET/KEY
.
For example:
- The bucket named "circus" can be described by the URI
s3://circus/
- The key prefix for all circus images can be described by the URI
s3://circus/images/
- The path to Steve's staff photograph can be described by the URI
s3://circus/images/steve.jpg
Installation
Slash3 requires Python 3.9 or later and can be installed from PyPI.
pip install slash3
Usage
Construct a URI from a URI
If you've already got a string URI then pass it directly to S3Uri
:
from slash3 import S3Uri
uri = S3Uri("s3://circus/")
uri.bucket # circus
uri.key #
uri = S3Uri("s3://circus/images/clowns.jpg")
uri.bucket # circus
uri.key # images/clowns.jpg
Construct a URI from a bucket and key
To construct an S3 URI from a bucket name and an optional key, call S3Uri.to_uri
:
from slash3 import S3Uri
uri = S3Uri.to_uri("circus")
# s3://circus/
uri = S3Uri.to_uri("circus", "images/clowns.jpg")
# s3://circus/images/clowns.jpg
Join a key suffix with a "/" delimiter
To join a key suffix with a "/" delimiter -- for example, to join an object's name to a key prefix -- call S3Uri.join()
or use the /
operator:
from slash3 import S3Uri
uri = S3Uri("s3://circus/")
images = uri / "images"
# s3://circus/images
clowns = images / "clowns.jpg"
# s3://circus/images/clowns.jpg
Slash3 will automatically normalise away any consecutive "/" delimiters.
Append a key suffix without a delimiter
To append a key suffix without a delimiter, call S3Uri.append()
or use the +
operator:
from slash3 import S3Uri
staff = S3Uri("s3://circus/staff-")
steve = staff + "steve.jpg"
# s3://circus/staff-steve.jpg
penny = staff + "penny.jpg"
# s3://circus/staff-penny.jpg
Get the parent key prefix
To get a URI's parent key prefix, call S3Uri.parent
:
from slash3 import S3Uri
steve = S3Uri("s3://circus/images/steve.jpg")
steve.parent
# s3://circus/images/
Get the key's leaf / file name
from slash3 import S3Uri
steve = S3Uri("s3://circus/images/steve.jpg")
steve.leaf
# steve.jpg
Get a relative key path
To discover the relative path between a specific URI and a parent URI, call S3Uri.relative_to
:
from slash3 import S3Uri
avatar = S3Uri("s3://circus/images/staff/steve.jpg")
images = "s3://circus/images/"
avatar.relative_to(images)
# staff/steve.jpg
Support
Please submit all your questions, feature requests and bug reports at github.com/cariad/slash3/issues. Thank you!
Licence
Slash3 is open-source and released under the MIT License.
You don't have to give attribution in your project, but -- as a freelance developer with rent to pay -- I appreciate it!
Author
Hello!
You can find me at cariad.earth, github/cariad, linkedin/cariad and on Mastodon at @cariad@tech.lgbt.