rw

Read and write related API.

class s3pathlib.core.rw.ReadAndWriteAPIMixin

A mixin class that implements the Text / Bytes, Read / Write methods.

read_bytes(version_id: str = Sentinel('NOTHING'), if_match: str = Sentinel('NOTHING'), if_modified_since: datetime = Sentinel('NOTHING'), if_none_match: str = Sentinel('NOTHING'), if_unmodified_since: datetime = Sentinel('NOTHING'), range: str = Sentinel('NOTHING'), response_cache_control: str = Sentinel('NOTHING'), response_content_disposition: str = Sentinel('NOTHING'), response_content_encoding: str = Sentinel('NOTHING'), response_content_language: str = Sentinel('NOTHING'), response_content_type: str = Sentinel('NOTHING'), response_expires: str = Sentinel('NOTHING'), sse_customer_algorithm: str = Sentinel('NOTHING'), sse_customer_key: str = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), part_number: int = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), checksum_mode: str = Sentinel('NOTHING'), bsm: BotoSesManager | None = None) → bytes

Read binary data from s3 object. A simple wrapper around get_object.

It also updates this S3Path object’s metadata and attributes like etag, size, version_id, etc with the get_object response.

Example:

>>> s3path = S3Path.from_s3_uri("s3://my-bucket/my-file.txt")
>>> s3path.write_bytes(b"hello", metadata={"creator": "me"})
>>> s3path.read_bytes()
b'hello'
>>> s3path.size
5
>>> s3path.metadata
{'creator': 'me'}

Parameters:

• version_id – See get_object.

• if_match – See get_object.

• if_modified_since – See get_object.

• if_none_match – See get_object.

• if_unmodified_since – See get_object.

• range – See get_object.

• response_cache_control – See get_object.

• response_content_disposition – See get_object.

• response_content_encoding – See get_object.

• response_content_language – See get_object.

• response_content_type – See get_object.

• response_expires – See get_object.

• sse_customer_algorithm – See get_object.

• sse_customer_key – See get_object.

• request_payer – See get_object.

• part_number – See get_object.

• expected_bucket_owner – See get_object.

• checksum_mode – See get_object.

• bsm – See bsm.

Returns:

the binary data.

New in version 1.0.3.

Changed in version 1.1.2: automatically store metadata in cache.

Changed in version 2.0.1: add version_id parameter, and now support full list of get_object arguments.

read_text(encoding='utf-8', errors='strict', version_id: str = Sentinel('NOTHING'), if_match: str = Sentinel('NOTHING'), if_modified_since: datetime = Sentinel('NOTHING'), if_none_match: str = Sentinel('NOTHING'), if_unmodified_since: datetime = Sentinel('NOTHING'), range: str = Sentinel('NOTHING'), response_cache_control: str = Sentinel('NOTHING'), response_content_disposition: str = Sentinel('NOTHING'), response_content_encoding: str = Sentinel('NOTHING'), response_content_language: str = Sentinel('NOTHING'), response_content_type: str = Sentinel('NOTHING'), response_expires: str = Sentinel('NOTHING'), sse_customer_algorithm: str = Sentinel('NOTHING'), sse_customer_key: str = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), part_number: int = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), checksum_mode: str = Sentinel('NOTHING'), bsm: BotoSesManager | None = None) → str

Read text data from s3 object. A simple wrapper around get_object.

It also updates this S3Path object’s metadata and attributes like etag, size, version_id, etc with the get_object response.

Example:

>>> s3path = S3Path("s3://my-bucket/my-file.txt")
>>> s3path.write_text("hello", metadata={"creator": "me"})
>>> s3path.read_text()
'hello'
>>> s3path.size
5
>>> s3path.metadata
{'creator': 'me'}

Parameters:

• encoding – See decode.

• errors – See decode.

• version_id – See get_object.

• if_match – See get_object.

• if_modified_since – See get_object.

• if_none_match – See get_object.

• if_unmodified_since – See get_object.

• range – See get_object.

• response_cache_control – See get_object.

• response_content_disposition – See get_object.

• response_content_encoding – See get_object.

• response_content_language – See get_object.

• response_content_type – See get_object.

• response_expires – See get_object.

• sse_customer_algorithm – See get_object.

• sse_customer_key – See get_object.

• request_payer – See get_object.

• part_number – See get_object.

• expected_bucket_owner – See get_object.

• checksum_mode – See get_object.

• bsm – See bsm.

Returns:

the string data.

New in version 1.0.3.

Changed in version 1.1.2: automatically store metadata in cache.

Changed in version 2.0.1: add version_id parameter, and now support full list of get_object arguments.

write_bytes(data: bytes, metadata: Dict[str, str] = Sentinel('NOTHING'), tags: Dict[str, str] = Sentinel('NOTHING'), acl: str = Sentinel('NOTHING'), cache_control: str = Sentinel('NOTHING'), content_disposition: str = Sentinel('NOTHING'), content_encoding: str = Sentinel('NOTHING'), content_language: str = Sentinel('NOTHING'), content_length: int = Sentinel('NOTHING'), content_md5: str = Sentinel('NOTHING'), content_type: str = Sentinel('NOTHING'), checksum_algorithm: str = Sentinel('NOTHING'), checksum_crc32: str = Sentinel('NOTHING'), checksum_crc32c: str = Sentinel('NOTHING'), checksum_sha1: str = Sentinel('NOTHING'), checksum_sha256: str = Sentinel('NOTHING'), expires_datetime: datetime = Sentinel('NOTHING'), grant_full_control: str = Sentinel('NOTHING'), grant_read: str = Sentinel('NOTHING'), grant_read_acp: str = Sentinel('NOTHING'), grant_write_acp: str = Sentinel('NOTHING'), server_side_encryption: str = Sentinel('NOTHING'), storage_class: str = Sentinel('NOTHING'), website_redirect_location: str = Sentinel('NOTHING'), sse_customer_algorithm: str = Sentinel('NOTHING'), sse_customer_key: str = Sentinel('NOTHING'), sse_kms_key_id: str = Sentinel('NOTHING'), sse_kms_encryption_context: str = Sentinel('NOTHING'), bucket_key_enabled: bool = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), object_lock_mode: str = Sentinel('NOTHING'), object_lock_retain_until_datetime: datetime = Sentinel('NOTHING'), object_lock_legal_hold_status: str = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), bsm: BotoSesManager | None = None) → S3Path

Write binary data to s3 object. A simple wrapper around put_object.

Example:

>>> s3path = S3Path("s3://my-bucket/my-file.txt")
>>> s3path.write_bytes(b"hello", metadata={"creator": "me"})
>>> s3path.size
5
>>> s3path.metadata
{'creator': 'me'}

Parameters:

• data – the text you want to write.

• metadata – the s3 object metadata in string key value pair dict.

• tags – the s3 object tags in string key value pair dict.

• acl – See put_object.

• cache_control – See put_object.

• content_disposition – See put_object.

• content_encoding – See put_object.

• content_language – See put_object.

• content_length – See put_object.

• content_md5 – See put_object.

• content_type – See put_object.

• checksum_algorithm – See put_object.

• checksum_crc32 – See put_object.

• checksum_crc32c – See put_object.

• checksum_sha1 – See put_object.

• checksum_sha256 – See put_object.

• expires_datetime – See put_object.

• grant_full_control – See put_object.

• grant_read – See put_object.

• grant_read_acp – See put_object.

• grant_write_acp – See put_object.

• server_side_encryption – See put_object.

• storage_class – See put_object.

• website_redirect_location – See put_object.

• sse_customer_algorithm – See put_object.

• sse_customer_key – See put_object.

• sse_kms_key_id – See put_object.

• sse_kms_encryption_context – See put_object.

• bucket_key_enabled – See put_object.

• request_payer – See put_object.

• object_lock_mode – See put_object.

• object_lock_retain_until_datetime – See put_object.

• object_lock_legal_hold_status – See put_object.

• expected_bucket_owner – See put_object.

• bsm – See bsm.

Returns:

A new S3Path object with the same bucket and key, but the new metadata representing the object you just put.

New in version 1.0.3.

Changed in version 1.1.1: add metadata and tags parameters.

write_text(data: str, encoding: str = 'utf-8', errors: str = 'strict', metadata: Dict[str, str] = Sentinel('NOTHING'), tags: Dict[str, str] = Sentinel('NOTHING'), acl: str = Sentinel('NOTHING'), cache_control: str = Sentinel('NOTHING'), content_disposition: str = Sentinel('NOTHING'), content_encoding: str = Sentinel('NOTHING'), content_language: str = Sentinel('NOTHING'), content_length: int = Sentinel('NOTHING'), content_md5: str = Sentinel('NOTHING'), content_type: str = Sentinel('NOTHING'), checksum_algorithm: str = Sentinel('NOTHING'), checksum_crc32: str = Sentinel('NOTHING'), checksum_crc32c: str = Sentinel('NOTHING'), checksum_sha1: str = Sentinel('NOTHING'), checksum_sha256: str = Sentinel('NOTHING'), expires_datetime: datetime = Sentinel('NOTHING'), grant_full_control: str = Sentinel('NOTHING'), grant_read: str = Sentinel('NOTHING'), grant_read_acp: str = Sentinel('NOTHING'), grant_write_acp: str = Sentinel('NOTHING'), server_side_encryption: str = Sentinel('NOTHING'), storage_class: str = Sentinel('NOTHING'), website_redirect_location: str = Sentinel('NOTHING'), sse_customer_algorithm: str = Sentinel('NOTHING'), sse_customer_key: str = Sentinel('NOTHING'), sse_kms_key_id: str = Sentinel('NOTHING'), sse_kms_encryption_context: str = Sentinel('NOTHING'), bucket_key_enabled: bool = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), object_lock_mode: str = Sentinel('NOTHING'), object_lock_retain_until_datetime: datetime = Sentinel('NOTHING'), object_lock_legal_hold_status: str = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), bsm: BotoSesManager | None = None) → S3Path

Write text to s3 object. A simple wrapper around put_object.

Example:

>>> s3path = S3Path("s3://my-bucket/my-file.txt")
>>> s3path.write_text("hello", metadata={"creator": "me"})
>>> s3path.size
5
>>> s3path.metadata
{'creator': 'me'}

Parameters:

• data – the text you want to write.

• encoding – See encode.

• errors – See encode.

• metadata – the s3 object metadata in string key value pair dict.

• tags – the s3 object tags in string key value pair dict.

• acl – See put_object.

• cache_control – See put_object.

• content_disposition – See put_object.

• content_encoding – See put_object.

• content_language – See put_object.

• content_length – See put_object.

• content_md5 – See put_object.

• content_type – See put_object.

• checksum_algorithm – See put_object.

• checksum_crc32 – See put_object.

• checksum_crc32c – See put_object.

• checksum_sha1 – See put_object.

• checksum_sha256 – See put_object.

• expires_datetime – See put_object.

• grant_full_control – See put_object.

• grant_read – See put_object.

• grant_read_acp – See put_object.

• grant_write_acp – See put_object.

• server_side_encryption – See put_object.

• storage_class – See put_object.

• website_redirect_location – See put_object.

• sse_customer_algorithm – See put_object.

• sse_customer_key – See put_object.

• sse_kms_key_id – See put_object.

• sse_kms_encryption_context – See put_object.

• bucket_key_enabled – See put_object.

• request_payer – See put_object.

• object_lock_mode – See put_object.

• object_lock_retain_until_datetime – See put_object.

• object_lock_legal_hold_status – See put_object.

• expected_bucket_owner – See put_object.

• bsm – See bsm.

Returns:

A new S3Path object with the same bucket and key, but the new metadata representing the object you just put.

New in version 1.0.3.

Changed in version 1.1.1: add metadata and tags parameters.

touch(exist_ok: bool = False, metadata: Dict[str, str] = Sentinel('NOTHING'), tags: Dict[str, str] = Sentinel('NOTHING'), acl: str = Sentinel('NOTHING'), cache_control: str = Sentinel('NOTHING'), content_disposition: str = Sentinel('NOTHING'), content_encoding: str = Sentinel('NOTHING'), content_language: str = Sentinel('NOTHING'), content_length: int = Sentinel('NOTHING'), content_md5: str = Sentinel('NOTHING'), content_type: str = Sentinel('NOTHING'), checksum_algorithm: str = Sentinel('NOTHING'), checksum_crc32: str = Sentinel('NOTHING'), checksum_crc32c: str = Sentinel('NOTHING'), checksum_sha1: str = Sentinel('NOTHING'), checksum_sha256: str = Sentinel('NOTHING'), expires_datetime: datetime = Sentinel('NOTHING'), grant_full_control: str = Sentinel('NOTHING'), grant_read: str = Sentinel('NOTHING'), grant_read_acp: str = Sentinel('NOTHING'), grant_write_acp: str = Sentinel('NOTHING'), server_side_encryption: str = Sentinel('NOTHING'), storage_class: str = Sentinel('NOTHING'), website_redirect_location: str = Sentinel('NOTHING'), sse_customer_algorithm: str = Sentinel('NOTHING'), sse_customer_key: str = Sentinel('NOTHING'), sse_kms_key_id: str = Sentinel('NOTHING'), sse_kms_encryption_context: str = Sentinel('NOTHING'), bucket_key_enabled: bool = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), object_lock_mode: str = Sentinel('NOTHING'), object_lock_retain_until_datetime: datetime = Sentinel('NOTHING'), object_lock_legal_hold_status: str = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), bsm: BotoSesManager | None = None)

Create an empty S3 object at the S3 location if the S3 object not exists. Do nothing if already exists.

Example:

>>> s3path = S3Path("s3://my-bucket/my-file.txt")
>>> s3path.write_text("hello", metadata={"creator": "me"})
>>> s3path.size
5
>>> s3path.metadata
{'creator': 'me'}

Parameters:

• exist_ok – if True, it won’t raise error when the S3 object already exists.

• data – the text you want to write.

• metadata – the s3 object metadata in string key value pair dict.

• tags – the s3 object tags in string key value pair dict.

• acl – See put_object.

• cache_control – See put_object.

• content_disposition – See put_object.

• content_encoding – See put_object.

• content_language – See put_object.

• content_length – See put_object.

• content_md5 – See put_object.

• content_type – See put_object.

• checksum_algorithm – See put_object.

• checksum_crc32 – See put_object.

• checksum_crc32c – See put_object.

• checksum_sha1 – See put_object.

• checksum_sha256 – See put_object.

• expires_datetime – See put_object.

• grant_full_control – See put_object.

• grant_read – See put_object.

• grant_read_acp – See put_object.

• grant_write_acp – See put_object.

• server_side_encryption – See put_object.

• storage_class – See put_object.

• website_redirect_location – See put_object.

• sse_customer_algorithm – See put_object.

• sse_customer_key – See put_object.

• sse_kms_key_id – See put_object.

• sse_kms_encryption_context – See put_object.

• bucket_key_enabled – See put_object.

• request_payer – See put_object.

• object_lock_mode – See put_object.

• object_lock_retain_until_datetime – See put_object.

• object_lock_legal_hold_status – See put_object.

• expected_bucket_owner – See put_object.

• bsm – See bsm.

New in version 1.0.6.

Changed in version 1.2.1: add metadata and tags parameters.

mkdir(exist_ok: bool = False, parents: bool = False, bsm: BotoSesManager | None = None)

Make an S3 folder (empty “/” file)

Example:

>>> s3dir = S3Path("s3://my-bucket/my-folder/").to_dir()
>>> s3dir.to_dir(exist_ok=True)

Parameters:

• exist_ok – If True, it won’t raise error when the S3 folder already exists.

• parents – If True, all parent folders will be created.

• bsm – See bsm.

New in version 1.0.6.