{"id":8614,"library":"s3urls","title":"Parse and Build Amazon S3 URLs","description":"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.","status":"active","version":"0.0.3","language":"en","source_language":"en","source_url":"https://github.com/ButoVideo/s3urls","tags":["aws","s3","url","parsing","utility","cloud storage"],"install":[{"cmd":"pip install s3urls","lang":"bash","label":"Install s3urls"}],"dependencies":[],"imports":[{"symbol":"parse_s3_url","correct":"from s3urls import parse_s3_url"},{"symbol":"build_s3_url","correct":"from s3urls import build_s3_url"}],"quickstart":{"code":"from s3urls import parse_s3_url, build_s3_url\n\n# Example 1: Parsing an S3 URI\ns3_uri = 's3://my-bucket/path/to/object.txt'\nparsed = parse_s3_url(s3_uri)\nprint(f\"Parsed S3 URI - Bucket: {parsed['bucket']}, Key: {parsed['key']}\")\n\n# Example 2: Parsing an HTTPS virtual-hosted style URL\nhttps_url = 'https://my-bucket.s3.us-east-1.amazonaws.com/another/file.csv'\nparsed = parse_s3_url(https_url)\nprint(f\"Parsed HTTPS URL - Bucket: {parsed['bucket']}, Key: {parsed['key']}, Region: {parsed['region']}\")\n\n# Example 3: Building an S3 URI\nbuilt_s3_uri = build_s3_url(bucket='my-new-bucket', key='data/results.json')\nprint(f\"Built S3 URI: {built_s3_uri}\")\n\n# Example 4: Building an HTTPS virtual-hosted style URL with region\nbuilt_https_url = build_s3_url(bucket='my-other-bucket', key='images/pic.jpg', region='eu-west-1', scheme='https', style='virtual-host')\nprint(f\"Built HTTPS URL: {built_https_url}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Manually validate S3 bucket and object key names against AWS S3 naming rules before using them with `s3urls` if strict adherence is required.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"AWS 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.","severity":"deprecated","affected_versions":"All versions (due to AWS S3 changes)"},{"fix":"Double-check `pip install` commands and `from ... import` statements to confirm you are using `s3urls`.","message":"Be 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"ValueError: Invalid S3 URL"},{"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.","cause":"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.","error":"Failed to resolve S3 endpoint or access S3 bucket with a specific regional URL format."}]}