Release 2.0.0

CHANGELOG.md

@@ -6,6 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/).
 
 
+## 2.0.0 - 2024-01-06
+
+### Added
+
+- `s3pypi delete` command to delete packages from S3.
+- `s3pypi force-unlock` command to release a stuck lock in DynamoDB.
+- `--locks-table` option to customise the DynamoDB table name used for locking.
+
+### Changed
+
+- Moved default command to `s3pypi upload`.
+- Renamed `--unsafe-s3-website` option to `--index.html`.
+
+### Removed
+
+- `--acl` option. Use `--s3-put-args='ACL=...'` instead. [The use of ACLs is discouraged].
+- `--lock-indexes` option. Locking is enabled automatically if a DynamoDB table exists.
+
+[The use of ACLs is discouraged]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html
+
+
 ## 1.2.1 - 2023-12-31
 
 ### Fixed
@@ -46,8 +67,7 @@ and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/)
 
 ### Added
 
-- SHA-256 checksums of packages to URLs. [@andrei-shabanski](https://github.com/andrei-
-  shabanski)
+- SHA-256 checksums in URLs. [@andrei-shabanski](https://github.com/andrei-shabanski)
 - `--no-sign-request` option to disable S3 authentication.
   [@jaustinpage](https://github.com/jaustinpage)
 - Expand glob patterns in case they were not expanded by a shell.

Makefile

@@ -11,6 +11,9 @@ format:
 	poetry run isort --apply
 	poetry run black .
 
+profile:
+	poetry run pyinstrument -r html -m pytest tests/integration/test_main.py
+
 clean:
 	rm -rf .coverage .eggs/ .pytest_cache/ .tox/ \
 		build/ coverage/ dist/ pip-wheel-metadata/

README.md

@@ -3,6 +3,28 @@
 S3PyPI is a CLI for creating a Python Package Repository in an S3 bucket.
 
 
+## Why?
+
+The official [Python Package Index (PyPI)](https://pypi.org) is a public
+repository of Python software. It's used by `pip` to download packages.
+
+If you work at a company, you may wish to publish your packages somewhere
+private instead, and still have them be accessible via `pip install`. This
+requires hosting your own repository.
+
+S3PyPI enables hosting a private repository at a low cost. It requires only an
+[S3 bucket] for storage, and some way to serve files over HTTPS (e.g. [Amazon
+CloudFront]).
+
+Publishing packages and index pages to S3 is done using the `s3pypi` CLI.
+Creating the S3 bucket and CloudFront distribution is done using a provided
+[Terraform] configuration, which you can tailor to your own needs.
+
+[S3 bucket]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html
+[Amazon CloudFront]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html
+[Terraform]: https://www.terraform.io/
+
+
 ## Alternatives
 
 - [AWS CodeArtifact](https://aws.amazon.com/codeartifact/) is a fully managed
@@ -24,8 +46,8 @@ $ pip install s3pypi
 
 Before you can start using `s3pypi`, you must set up an S3 bucket for storing
 packages, and a CloudFront distribution for serving files over HTTPS. Both of
-these can be created using the [Terraform](https://www.terraform.io/)
-configuration provided in the `terraform/` directory:
+these can be created using the [Terraform] configuration provided in the
+`terraform/` directory:
 
 ```console
 $ git clone https://github.com/gorilla-co/s3pypi.git
@@ -138,9 +160,55 @@ be renamed to `<package>/`. You can do so using the provided script:
 $ scripts/migrate-s3-index.py example-bucket
 ```
 
+To instead keep using the old configuration with a publicly accessible S3
+website endpoint, pass the following options when uploading packages:
+
+```console
+$ s3pypi upload ... --index.html --s3-put-args='ACL=public-read'
+```
+
 [Origin Access Identity (OAI)]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html
 
 
+### Example IAM policy
+
+The `s3pypi` CLI requires the following IAM permissions to access S3 and
+(optionally) DynamoDB. Replace `example-bucket` by your S3 bucket name.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject",
+        "s3:DeleteObject"
+      ],
+      "Resource": "arn:aws:s3:::example-bucket/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:ListBucket"
+      ],
+      "Resource": "arn:aws:s3:::example-bucket"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "dynamodb:GetItem",
+        "dynamodb:PutItem",
+        "dynamodb:DeleteItem"
+      ],
+      "Resource": "arn:aws:dynamodb:*:*:table/example-bucket-locks"
+    }
+  ]
+}
+```
+
+
 ## Usage
 
 ### Distributing packages
@@ -151,7 +219,7 @@ You can now use `s3pypi` to upload packages to S3:
 $ cd /path/to/your-project/
 $ python setup.py sdist bdist_wheel
 
-$ s3pypi dist/* --bucket example-bucket [--prefix PREFIX] [--acl ACL]
+$ s3pypi upload dist/* --bucket example-bucket [--prefix PREFIX]
 ```
 
 See `s3pypi --help` for a description of all options.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "s3pypi"
-version = "1.2.1"
+version = "2.0.0"
 description = "CLI for creating a Python Package Repository in an S3 bucket"
 authors = [
     "Matteo De Wint <[email protected]>",
@@ -12,7 +12,7 @@ s3pypi = "s3pypi.__main__:main"
 
 [tool.poetry.dependencies]
 boto3 = "^1.34.11"
-boto3-stubs = {extras = ["s3"], version = "^1.34.11"}
+boto3-stubs = {extras = ["dynamodb", "s3"], version = "^1.34.11"}
 python = "^3.8"
 
 [tool.poetry.group.dev.dependencies]
@@ -22,6 +22,7 @@ flake8 = "^5.0.4"
 isort = "^5.13.2"
 moto = "^4.2.12"
 mypy = "^1.8.0"
+pyinstrument = "^4.6.1"
 pytest = "^7.4.3"
 pytest-cov = "^4.1.0"
 

s3pypi/__init__.py

@@ -1,2 +1,2 @@
 __prog__ = "s3pypi"
-__version__ = "1.2.1"
+__version__ = "2.0.0"