Slash3 is a Python package for building and navigating Amazon Web Services S3 URIs.
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
Slash3 requires Python 3.9 or later and can be installed from PyPI.
pip install slash3
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
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
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.
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
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/
from slash3 import S3Uri
steve = S3Uri("s3://circus/images/steve.jpg")
steve.leaf
# steve.jpg
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
Please submit all your questions, feature requests and bug reports at github.com/cariad/slash3/issues. Thank you!
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!
Hello! 👋 I'm Cariad Eccleston, and I'm a freelance Amazon Web Services architect, DevOps evangelist, CI/CD pipeline engineer and backend developer.
You can find me at cariad.earth, github/cariad, linkedin/cariad and on Mastodon at @cariad@tech.lgbt.