<img align="right" src="https://raw.github.com/cliffano/s3empty/main/avatar.jpg" alt="Avatar"/>
[](https://github.com/cliffano/s3empty/actions?query=workflow%3ACI)
[](https://snyk.io/test/github/cliffano/s3empty)
[](https://libraries.io/pypi/s3empty)
[](https://pypi.python.org/pypi/s3empty)
<br/>
S3Empty
-------
S3Empty is a Python CLI for conveniently emptying an AWS S3 bucket. It handles versioned and non-versioned S3 buckets.
This tool is useful when you want to delete all objects in a bucket before deleting the bucket itself, in order to address this error:
BucketNotEmpty: The bucket you tried to delete is not empty. You must delete all versions in the bucket.
Installation
------------
pip3 install s3empty
Usage
-----
Run S3Empty with specified bucket name:
s3empty --bucket-name some-bucket
Run S3Empty with a configuration file containing the bucket names:
s3empty --conf-file path/to/some-conf-file.yaml
By default, S3Empty will raise an error if the bucket does not exist. However, there will be scenarios where the S3 bucket you want to empty does not exist or no longer exists. You can use the `--allow-inexisting` flag to allow inexisting buckets and S3Empty will display a warning message and exits without raising any error:
s3empty --bucket-name some-bucket --allow-inexisting
Show help guide:
s3empty --help
Configuration
-------------
You can specify multiple bucket names in S3Empty configuration file and give it a name with `.yaml` extension, e.g. `some-conf-file.yaml` :
---
bucket_names:
- some-bucket-1
- some-bucket-2
And then call S3Empty:
s3empty --conf-file path/to/some-conf-file.yaml
The configuration file also supports Jinja template where environment variables are available for use. You can give this configuration template a name with `.yaml.j2` extension, e.g. `some-conf-file.yaml.j2` .
For example, if there is an environment variable `ACCOUNT_ID=1234567` , you can specify it in the configuration file:
---
bucket_names:
- some-{{ env.ACCOUNT_ID }}-bucket-1
- some-{{ env.ACCOUNT_ID }}-bucket-2
And then call S3Empty:
s3empty --conf-file path/to/some-conf-file.yaml.j2
Permission
----------
Here's an IAM policy with minimum permissions required by S3Empty:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3EmptyPolicy",
"Effect": "Allow",
"Action": [
"s3:GetBucketVersioning",
"s3:ListBucket",
"s3:ListBucketVersions",
"s3:DeleteObject",
"s3:DeleteObjectVersion",
],
"Resource": [
"arn:aws:s3:::some-bucket",
"arn:aws:s3:::some-bucket/*"
]
}
]
}
```
FAQ
---
Q: How about using [S3 Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to delete objects in the bucket?
A: S3 Lifecycle modifies the state of the S3 bucket by adding the lifecycle configuration. However, S3Empty aims to only modify the S3 objects without modifying the S3 bucket itself. Other than that, S3 Lifecycle has an [expiration delay](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-set-lifecycle-configuration-intro.html#lifecycle-considerations) which means, and I quote, "Amazon S3 might not actually delete these objects until days or even weeks later." S3Empty aims to start deleting the objects immediately.
Colophon
--------
[Developer's Guide](https://cliffano.github.io/developers_guide.html#python)
Build reports:
* [Lint report](https://cliffano.github.io/s3empty/lint/pylint/index.html)
* [Code complexity report](https://cliffano.github.io/s3empty/complexity/wily/index.html)
* [Unit tests report](https://cliffano.github.io/s3empty/test/pytest/index.html)
* [Test coverage report](https://cliffano.github.io/s3empty/coverage/coverage/index.html)
* [Integration tests report](https://cliffano.github.io/s3empty/test-integration/pytest/index.html)
* [API Documentation](https://cliffano.github.io/s3empty/doc/sphinx/index.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/cliffano/s3empty",
"name": "s3empty",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "s3empty, aws, bucket, empty, s3",
"author": "Cliffano Subagio",
"author_email": "cliffano@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a4/b1/b656ef6fbfdef549778f4b79018551e99317fe4d85039ff5b074e707ae8e/s3empty-1.3.0.tar.gz",
"platform": null,
"description": "<img align=\"right\" src=\"https://raw.github.com/cliffano/s3empty/main/avatar.jpg\" alt=\"Avatar\"/>\n\n[](https://github.com/cliffano/s3empty/actions?query=workflow%3ACI)\n[](https://snyk.io/test/github/cliffano/s3empty)\n[](https://libraries.io/pypi/s3empty)\n[](https://pypi.python.org/pypi/s3empty)\n<br/>\n\nS3Empty\n-------\n\nS3Empty is a Python CLI for conveniently emptying an AWS S3 bucket. It handles versioned and non-versioned S3 buckets.\n\nThis tool is useful when you want to delete all objects in a bucket before deleting the bucket itself, in order to address this error:\n\n BucketNotEmpty: The bucket you tried to delete is not empty. You must delete all versions in the bucket.\n\n![S3Empty console screenshot](https://raw.github.com/cliffano/s3empty/master/screenshots/console.jpg \"S3Empty console screenshot\")\n\nInstallation\n------------\n\n pip3 install s3empty\n\nUsage\n-----\n\nRun S3Empty with specified bucket name:\n\n s3empty --bucket-name some-bucket\n\nRun S3Empty with a configuration file containing the bucket names:\n\n s3empty --conf-file path/to/some-conf-file.yaml\n\nBy default, S3Empty will raise an error if the bucket does not exist. However, there will be scenarios where the S3 bucket you want to empty does not exist or no longer exists. You can use the `--allow-inexisting` flag to allow inexisting buckets and S3Empty will display a warning message and exits without raising any error:\n\n s3empty --bucket-name some-bucket --allow-inexisting\n\nShow help guide:\n\n s3empty --help\n\nConfiguration\n-------------\n\nYou can specify multiple bucket names in S3Empty configuration file and give it a name with `.yaml` extension, e.g. `some-conf-file.yaml` :\n\n ---\n bucket_names:\n - some-bucket-1\n - some-bucket-2\n\nAnd then call S3Empty:\n\n s3empty --conf-file path/to/some-conf-file.yaml\n\nThe configuration file also supports Jinja template where environment variables are available for use. You can give this configuration template a name with `.yaml.j2` extension, e.g. `some-conf-file.yaml.j2` .\n\nFor example, if there is an environment variable `ACCOUNT_ID=1234567` , you can specify it in the configuration file:\n\n ---\n bucket_names:\n - some-{{ env.ACCOUNT_ID }}-bucket-1\n - some-{{ env.ACCOUNT_ID }}-bucket-2\n\nAnd then call S3Empty:\n\n s3empty --conf-file path/to/some-conf-file.yaml.j2\n\nPermission\n----------\n\nHere's an IAM policy with minimum permissions required by S3Empty:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"S3EmptyPolicy\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"s3:GetBucketVersioning\",\n \"s3:ListBucket\",\n \"s3:ListBucketVersions\",\n \"s3:DeleteObject\",\n \"s3:DeleteObjectVersion\",\n ],\n \"Resource\": [\n \"arn:aws:s3:::some-bucket\",\n \"arn:aws:s3:::some-bucket/*\"\n ]\n }\n ]\n}\n```\n\nFAQ\n---\n\nQ: How about using [S3 Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to delete objects in the bucket?\n\nA: S3 Lifecycle modifies the state of the S3 bucket by adding the lifecycle configuration. However, S3Empty aims to only modify the S3 objects without modifying the S3 bucket itself. Other than that, S3 Lifecycle has an [expiration delay](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-set-lifecycle-configuration-intro.html#lifecycle-considerations) which means, and I quote, \"Amazon S3 might not actually delete these objects until days or even weeks later.\" S3Empty aims to start deleting the objects immediately.\n\nColophon\n--------\n\n[Developer's Guide](https://cliffano.github.io/developers_guide.html#python)\n\nBuild reports:\n\n* [Lint report](https://cliffano.github.io/s3empty/lint/pylint/index.html)\n* [Code complexity report](https://cliffano.github.io/s3empty/complexity/wily/index.html)\n* [Unit tests report](https://cliffano.github.io/s3empty/test/pytest/index.html)\n* [Test coverage report](https://cliffano.github.io/s3empty/coverage/coverage/index.html)\n* [Integration tests report](https://cliffano.github.io/s3empty/test-integration/pytest/index.html)\n* [API Documentation](https://cliffano.github.io/s3empty/doc/sphinx/index.html)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python CLI for convenient emptying of S3 bucket",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://github.com/cliffano/s3empty",
"Homepage": "https://github.com/cliffano/s3empty",
"Repository": "https://github.com/cliffano/s3empty"
},
"split_keywords": [
"s3empty",
" aws",
" bucket",
" empty",
" s3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c5d53859f11c099b8cc34bd2d3df11c411717b9e44a9d876a03763eef5ca84ad",
"md5": "b7c54e399f304b325892edcf9b5b9535",
"sha256": "e17b2ce909250fa716da083be3347e88dca2641dddb2ee6f9af68115975fa471"
},
"downloads": -1,
"filename": "s3empty-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7c54e399f304b325892edcf9b5b9535",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 8956,
"upload_time": "2024-12-21T11:28:48",
"upload_time_iso_8601": "2024-12-21T11:28:48.632663Z",
"url": "https://files.pythonhosted.org/packages/c5/d5/3859f11c099b8cc34bd2d3df11c411717b9e44a9d876a03763eef5ca84ad/s3empty-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a4b1b656ef6fbfdef549778f4b79018551e99317fe4d85039ff5b074e707ae8e",
"md5": "080b827498cf7073f6bd95e49b3edff1",
"sha256": "ef67b3c263a8e3e57a6c19abcfe01f9f243c6857abcae2d3512c4e8800717df2"
},
"downloads": -1,
"filename": "s3empty-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "080b827498cf7073f6bd95e49b3edff1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 8152,
"upload_time": "2024-12-21T11:28:50",
"upload_time_iso_8601": "2024-12-21T11:28:50.848954Z",
"url": "https://files.pythonhosted.org/packages/a4/b1/b656ef6fbfdef549778f4b79018551e99317fe4d85039ff5b074e707ae8e/s3empty-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-21 11:28:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cliffano",
"github_project": "s3empty",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "s3empty"
}
JSON
