s3urls

library0.0.3pypypi✓ verified 85d ago

s3urls is a small, dependency-free Python library designed to parse and build Amazon S3 URLs. It provides utility functions to extract bucket names and keys from S3 URIs (e.g., `s3://bucket/key`) and HTTP/HTTPS S3 object URLs, as well as to construct such URLs. The current version is 0.0.3, with its last release in 2018, indicating a stable but infrequently updated project.

aws serialization

pip install s3urls

github ↗package ↗

INSTALL

IMPORT

SIG · S3URLS

s3urls

awspythonv0.0.3

Install

1.6s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.011s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.007s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse_s3_url

✓ from s3urls import parse_s3_url

build_s3_url

✓ from s3urls import build_s3_url

This quickstart demonstrates how to use `s3urls` to parse various S3 URL formats (S3 URIs and HTTPS URLs) and how to build S3 URLs, including specifying the scheme, region, and style for HTTPS URLs.

from s3urls import parse_s3_url, build_s3_url # Example 1: Parsing an S3 URI s3_uri = 's3://my-bucket/path/to/object.txt' parsed = parse_s3_url(s3_uri) print(f"Parsed S3 URI - Bucket: {parsed['bucket']}, Key: {parsed['key']}") # Example 2: Parsing an HTTPS virtual-hosted style URL https_url = 'https://my-bucket.s3.us-east-1.amazonaws.com/another/file.csv' parsed = parse_s3_url(https_url) print(f"Parsed HTTPS URL - Bucket: {parsed['bucket']}, Key: {parsed['key']}, Region: {parsed['region']}") # Example 3: Building an S3 URI built_s3_uri = build_s3_url(bucket='my-new-bucket', key='data/results.json') print(f"Built S3 URI: {built_s3_uri}") # Example 4: Building an HTTPS virtual-hosted style URL with region built_https_url = build_s3_url(bucket='my-other-bucket', key='images/pic.jpg', region='eu-west-1', scheme='https', style='virtual-host') print(f"Built HTTPS URL: {built_https_url}")

Debug

Known issues

gotchaThe `s3urls` library performs rudimentary URL validation. It does NOT validate bucket names or object keys against the comprehensive rules defined in the AWS documentation. Users should ensure their bucket and key inputs adhere to AWS naming conventions to avoid issues with AWS services.

fix

Manually validate S3 bucket and object key names against AWS S3 naming rules before using them with `s3urls` if strict adherence is required.

affects: All versions

deprecatedAWS is deprecating path-style S3 URLs (e.g., `https://s3.amazonaws.com/<bucket>/<key>`) in favor of virtual-hosted-style URLs (e.g., `https://<bucket>.s3.amazonaws.com/<key>`) in new regions and for new buckets. While `s3urls` supports parsing path-style URLs, it's recommended to build and primarily use virtual-hosted-style URLs for future compatibility and best practice.

fix

When building URLs, explicitly set `style='virtual-host'` for HTTPS URLs. Review existing code for path-style URLs and migrate to virtual-hosted-style where possible.

affects: All versions (due to AWS S3 changes)

gotchaBe aware of similarly named but unrelated packages on PyPI, such as `s3url` (singular) or `s3-url-helper`. Ensure you are installing and importing from `s3urls` (plural) to use this specific library.

fix

Double-check `pip install` commands and `from ... import` statements to confirm you are using `s3urls`.

affects: All versions

Errors

Common errors & fixes

ValueError: Invalid S3 URL

The input string passed to `parse_s3_url` or `build_s3_url` does not conform to a recognized S3 URI format (e.g., `s3://bucket/key`) or HTTP/HTTPS S3 object URL (e.g., `https://bucket.s3.amazonaws.com/key`). This can happen with malformed URLs or unsupported S3 endpoint variations.

fix

Ensure the URL strictly follows one of the supported S3 URL formats. Verify that bucket names, keys, regions, schemes, and styles are correctly structured. For specific regional endpoints, manually construct the URL string if `build_s3_url`'s parameters don't cover the exact format.

Failed to resolve S3 endpoint or access S3 bucket with a specific regional URL format.

While `s3urls` can infer regions from many standard S3 HTTP/HTTPS URLs, it might not explicitly handle all legacy or highly specific regional S3 endpoint formats (e.g., `s3-<region>.amazonaws.com` vs `s3.<region>.amazonaws.com` for older regions) or specialized S3-compatible services. AWS has also had issues with `s3-<region>` vs `s3.<region>` in the past.

fix

When `s3urls`'s automatic parsing or building of regional URLs is problematic, explicitly specify the `region` parameter for `build_s3_url`. For complex cases or non-AWS S3-compatible services, consider using `urllib.parse` for basic component extraction or a dedicated AWS SDK (like `boto3`) for more robust, region-aware URL generation and interaction.

Upgrade

Version history

0.0.3latest on PyPI · released Jul 10, 2018

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/ButoVideo/s3urls ↗

packagehttps://pypi.org/project/s3urls/ ↗