delete

Delete S3 file or folder.

class s3pathlib.core.delete.DeleteAPIMixin[source]

A mixin class that implements delete method.

delete(version_id: str = OPT, mfa: str = OPT, request_payer: str = OPT, bypass_governance_retention: bool = OPT, expected_bucket_owner: str = OPT, check_sum_algorithm: str = OPT, is_hard_delete: bool = False, skip_prompt: bool = False, bsm: BotoSesManager | S3Client | None = None) → S3Path[source]

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.

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

delete_if_exists(version_id: str = OPT, mfa: str = OPT, request_payer: str = OPT, bypass_governance_retention: bool = OPT, expected_bucket_owner: str = OPT, bsm: BotoSesManager | S3Client | None = None) → int[source]

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:
Returns:

number of object is deleted

Added in version 1.0.1.

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