delete

Delete S3 file or folder.

class s3pathlib.core.delete.DeleteAPIMixin

A mixin class that implements delete method.

delete(version_id: str = Sentinel('NOTHING'), mfa: str = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), bypass_governance_retention: bool = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), check_sum_algorithm: str = Sentinel('NOTHING'), is_hard_delete: bool = False, skip_prompt: bool = False, bsm: BotoSesManager | None = None) → S3Path

Can delete:

• an object.

• all objects in a directory.

• specific version or delete marker of an object.

• all historical versions and delete markers of an object.

• all objects, all versions in a directory.

It won’t raise any error if the object or the directory doesn’t exist.

Example:

>>> s3path = S3Path.from_s3_uri("s3://my-bucket/my-file.txt")
>>> s3dir = S3Path.from_s3_uri("s3://my-bucket/my-folder/")
# Delete an object
# for versioning enabled bucket, it just creates a delete maker
>>> s3path.delete()
# Delete all objects in a directory
# for versioning enabled bucket, it just creates delete makers for all objects
>>> s3path.delete()
# Delete specific version or delete marker of an object
>>> s3path.delete(version_id="v123456")
# Delete all historical versions and delete markers of an object
>>> s3path.delete(is_hard_delete=True)
# Delete all objects, all versions in a directory
>>> s3dir.delete(is_hard_delete=True)

Parameters:

• version_id – see delete_object.

• mfa – see delete_object.

• request_payer – see delete_object.

• bypass_governance_retention – see delete_object.

• expected_bucket_owner – see delete_object.

• check_sum_algorithm – See delete_object.

• is_hard_delete – if True, then it will delete all versions of the object, then the data is permanently deleted.

• skip_prompt – Default False, it will prompt you to confirm when deleting everything in an S3 bucket.

• bsm – See bsm.

Returns:

a new S3Path object representing the deleted object

• if it’s a file and the versioning is NOT enabled, then it will

  return the deleted file itself.

• if it’s a file and the versioning is ENABLED,

  • if version_id is not given, then it will return the

    S3Path representing the delete-marker.

  • if version_id is given, then it will return the S3Path

    representing the deleted version.

• if it’s a directory, then it will return the deleted folder itself.

New in version 2.0.1: Use this method to replace the DeleteAPIMixin.delete_if_exists() method.

delete_if_exists(version_id: str = Sentinel('NOTHING'), mfa: str = Sentinel('NOTHING'), request_payer: str = Sentinel('NOTHING'), bypass_governance_retention: bool = Sentinel('NOTHING'), expected_bucket_owner: str = Sentinel('NOTHING'), bsm: BotoSesManager | None = None) → int

Delete an object or an entire directory. Will do nothing if it doesn’t exist. You can delete a specific version of an object, or remove a delete-marker using the version_id parameter. Not that it will permanenatly delete the data.

Example:

>>> S3Path.from_s3_uri("s3://my-bucket/my-file.txt").delete_if_exists()
1 # number of object deleted
>>> S3Path.from_s3_uri("s3://my-bucket/my-folder/").delete_if_exists()
3 # number of object deleted

Parameters:

• mfa – see delete_object.

• version_id – see delete_object.

• request_payer – see delete_object.

• bypass_governance_retention – see delete_object.

• expected_bucket_owner – see delete_object.

• bsm – See bsm.

Returns:

number of object is deleted

New in version 1.0.1.

Deprecated since version 2.0.1: This method will be removed in 3.X. Use delete instead.