handtruck

class handtruck.AwsObjectMeta(etag, key, last_modified, size, storage_class)[source]

Bases: NamedTuple

etag: str

Alias for field number 0

key: str

Alias for field number 1

last_modified: datetime

Alias for field number 2

size: int

Alias for field number 3

storage_class: str

Alias for field number 4

exception handtruck.ConflictError[source]

Bases: Exception

There was a conflict in a multipart operation.

class handtruck.S3Client(client: AsyncClient, url: URL | str, secret_access_key: str | None = None, access_key_id: str | None = None, session_token: str | None = None, region: str = '', credentials: AbstractCredentials | None = None)[source]

Bases: object

async delete(object_name: S3Object | S3Bucket, content_sha256='e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', **kwargs) → Response[source]

Delete an object.

async get(object_name: S3Object | S3Bucket, **kwargs) → Response[source]

Get an object.

Returns:

The object gotten.

async get_file_parallel(object_name: S3Object, file_path: str | PathLike, *, headers: Dict | None = None, range_step: int = 5242880, workers_count: int = 1, range_get_tries: int = 3, buffer_size: int = 131072, **kwargs) → None[source]

Download object in parallel with requests with Range. If file changed while download is in progress, an error will be raised.

Parameters:

  • object_name – s3 key to download

  • file_path – target file path

  • headers – additional headers

  • range_step – how much data will be downloaded in single HTTP request

  • workers_count – count of parallel workers

  • range_get_tries – count of tries to download each range

  • buffer_size – size of a buffer for on the fly data

async head(object_name: S3Object | S3Bucket, content_sha256='e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', **kwargs) → Response[source]

Get an object’s headers.

Returns:

The object gotten.

async list_objects(bucket: S3Bucket | None = None, *, prefix: str | None = None, delimiter: str | None = None, max_keys: int | None = None, start_after: str | None = None) → AsyncIterator[AwsObjectMeta][source]

List objects in bucket.

Parameters:

  • bucket – Name of the bucket to list, or None if the bucket is in the endpoint.

  • prefix – limits the response to keys that begin with the specified prefix

  • delimiter – a delimiter is a character you use to group keys

  • max_keys – maximum number of keys returned in the response

  • start_after – keys to start listing after

Returns:

Iterator over metadata objects

async list_objects_v2(object_name: str | URL | None = None, *, bucket: S3Bucket | None = None, prefix: str | Path | None = None, delimiter: str | None = None, max_keys: int | None = None, start_after: str | None = None) → AsyncIterator[List[AwsObjectMeta]][source]

List objects in bucket.

Parameters:

  • object_name – path to listing endpoint, defaults to '/'; a bucket value is prepended to this value if provided.

  • prefix – limits the response to keys that begin with the specified prefix

  • delimiter – a delimiter is a character you use to group keys

  • max_keys – maximum number of keys returned in the response

  • start_after – keys to start listing after

Returns:

An iterator over lists of metadata objects, each corresponding to an individual response result (typically limited to 1000 keys).

Note

Despite the name list_objects() is newer and probably more ergonomic.

async post(object_name: S3Object | S3Bucket, content: str | bytes | Iterable[bytes] | AsyncIterable[bytes] | None = None, **kwargs) → Response[source]
async put(object_name: S3Object | S3Bucket, content: str | bytes | Iterable[bytes] | AsyncIterable[bytes] | None, **kwargs) → Response[source]

Update an object.

async put_file(object_name: S3Object, file_path: str | PathLike, *, headers: Dict | None = None, chunk_size: int = 65536, content_sha256: str | None = None) → Response[source]

Update an object from a file (by path)

async put_file_multipart(object_name: S3Object, file_path: str | PathLike, *, headers: Dict | None = None, part_size: int = 5242880, workers_count: int = 1, max_size: int | None = None, part_upload_tries: int = 3, calculate_content_sha256: bool = True, **kwargs) → None[source]

Upload data from a file with multipart upload

Parameters:

  • object_name – key in s3

  • file_path – path to a file for upload

  • headers – additional headers, such as Content-Type

  • part_size – size of a chunk to send (recommended: >5Mb)

  • workers_count – count of coroutines for asyncronous parts uploading

  • max_size – maximum size of a queue with data to send (should be at least workers_count)

  • part_upload_tries – how many times trying to put part to s3 before fail

  • calculate_content_sha256 – whether to calculate sha256 hash of a part for integrity purposes

async put_multipart(object_name: S3Object, content: Iterable[bytes], *, headers: Dict | None = None, workers_count: int = 1, max_size: int | None = None, part_upload_tries: int = 3, calculate_content_sha256: bool = True, **kwargs) → None[source]

Send data from iterable with multipart upload

Parameters:

  • object_name – key in s3

  • data – any iterable that returns chunks of bytes

  • headers – additional headers, such as Content-Type

  • workers_count – count of coroutines for asyncronous parts uploading

  • max_size – maximum size of a queue with data to send (should be at least workers_count)

  • part_upload_tries – how many times trying to put part to s3 before fail

  • calculate_content_sha256 – whether to calculate sha256 hash of a part for integrity purposes

property url: URL

S3 Endpoint, see Buckets & URLs.

exception handtruck.S3Error(message, resource: str | None = None, request_id: str | None = None, **props)[source]

Bases: HTTPError

Parent class for errors reported by the server

response: Response