Buckets & URLs

Handtruck has a few ways to specify buckets and objects in URLs.

Note

Handtruck currently only supports subdomain/virtual host-based bucket access when used with a bucketful root.

Standard

The “typical” way is to specify just an endpoint and give the bucket and object name in the API call:

client = S3Client(url="http://your-s3-host",
              client=httpx.AsyncClient())
resp = await client.put("bucket/key", gen())

Bucketful Root

You can also specify the bucket in the root:

client = S3Client(url="http://bucket.your-s3-host",
                  client=httpx.AsyncClient())
resp = await client.put("key", gen())

client = S3Client(url="http://your-s3-host/bucket",
                  client=httpx.AsyncClient())
resp = await client.put("key", gen())

Note

Handtruck can’t know if your URL already includes the bucket name or is just at a weird endpoint. If you use a bucketful root, make sure none of your method calls include the bucket name.

URLs

If you use an httpx.URL, it’s treated in a more explicit fashion.

S3 URLS

If your URL has a s3 scheme (or s3+stuff or stuff+s3, eg s3+aws), it’s interpreted as having the form of s3://<bucket>/<object>. Bucketless URLs can be written as s3:/<object>.

URLs in the form of s3:<object> are not supported–they’re relative to something undefined.

HTTP URLs

If you pass in a URL with an http or https scheme, it is not interprted and is just joined to the endpoint URL, using the standard relative URL rules.