sobe 0.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

sobe/aws.py

@@ -0,0 +1,74 @@
+"""Everything related to AWS. In the future, we may support other cloud providers."""
+
+import datetime
+import json
+import mimetypes
+import pathlib
+import time
+
+import boto3
+import botocore.exceptions
+
+from sobe.config import AWSConfig
+
+
+class AWS:
+    def __init__(self, config: AWSConfig) -> None:
+        self.config = config
+        self._session = boto3.Session(**self.config.session)
+        self._s3_resource = self._session.resource("s3", **self.config.service)
+        self._bucket = self._s3_resource.Bucket(self.config.bucket)  # type: ignore[attr-defined]
+        self._cloudfront = self._session.client("cloudfront", **self.config.service)
+
+    def upload(self, year: str, local_path: pathlib.Path) -> None:
+        """Uploads a file."""
+        type_guess, _ = mimetypes.guess_type(local_path)
+        extra_args = {"ContentType": type_guess or "application/octet-stream"}
+        self._bucket.upload_file(str(local_path), f"{year}/{local_path.name}", ExtraArgs=extra_args)
+
+    def delete(self, year: str, remote_filename: str) -> bool:
+        """Delete a file, if it exists. Returns whether it did."""
+        obj = self._bucket.Object(f"{year}/{remote_filename}")
+        try:
+            obj.load()
+            obj.delete()
+            return True
+        except botocore.exceptions.ClientError as e:
+            if e.response.get("Error", {}).get("Code") == "404":
+                return False
+            raise
+
+    def invalidate_cache(self):
+        """Create and wait for a full-path CloudFront invalidation. Iterates until completion."""
+        ref = datetime.datetime.now().astimezone().isoformat()
+        batch = {"Paths": {"Quantity": 1, "Items": ["/*"]}, "CallerReference": ref}
+        distribution = self.config.cloudfront
+        response = self._cloudfront.create_invalidation(DistributionId=distribution, InvalidationBatch=batch)
+        invalidation = response["Invalidation"]["Id"]
+        status = "Created"
+        while status != "Completed":
+            yield status
+            time.sleep(3)
+            response = self._cloudfront.get_invalidation(DistributionId=distribution, Id=invalidation)
+            status = response["Invalidation"]["Status"]
+
+    def generate_needed_permissions(self) -> str:
+        """Return the minimal IAM policy statement required by the tool."""
+        try:
+            sts = self._session.client("sts", **self.config.service)
+            account_id = sts.get_caller_identity()["Account"]
+        except botocore.exceptions.ClientError:
+            account_id = "YOUR_ACCOUNT_ID"
+
+        actions = """
+            s3:PutObject s3:GetObject s3:ListBucket s3:DeleteObject
+            cloudfront:CreateInvalidation cloudfront:GetInvalidation
+        """.split()
+        resources = [
+            f"arn:aws:s3:::{self.config.bucket}",
+            f"arn:aws:s3:::{self.config.bucket}/*",
+            f"arn:aws:cloudfront::{account_id}:distribution/{self.config.cloudfront}",
+        ]
+        statement = {"Effect": "Allow", "Action": actions, "Resource": resources}
+        policy = {"Version": "2012-10-17", "Statement": [statement]}
+        return json.dumps(policy, indent=2)

sobe/config.py

@@ -0,0 +1,77 @@
+"""Everything related to user configuration file."""
+
+import tomllib
+from pathlib import Path
+from typing import Any, NamedTuple, Self
+
+from platformdirs import PlatformDirs
+
+
+class AWSConfig(NamedTuple):
+    bucket: str
+    cloudfront: str
+    session: dict[str, Any]
+    service: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> Self:
+        return cls(
+            bucket=raw.get("bucket", "example-bucket"),
+            cloudfront=raw.get("cloudfront", "E1111111111111"),
+            session=raw.get("session", {}),
+            service=raw.get("service", {}),
+        )
+
+
+class Config(NamedTuple):
+    url: str
+    aws: AWSConfig
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> Self:
+        return cls(
+            url=raw.get("url", "https://example.com/"),
+            aws=AWSConfig.from_dict(raw.get("aws", {})),
+        )
+
+
+class MustEditConfig(Exception):
+    """Config file must be edited before this tool can be used."""
+
+    def __init__(self, path: Path):
+        self.path = path
+
+
+DEFAULT_TEMPLATE = """
+# sobe configuration
+
+url = "https://example.com/"
+
+[aws]
+bucket = "example-bucket"
+cloudfront = "E1111111111111"
+
+[aws.session]
+# If you already have AWS CLI set up, don't fill keys here.
+# region_name = "..."
+# profile_name = "..."
+# aws_access_key_id = "..."
+# aws_secret_access_key = "..."
+
+[aws.service]
+# verify = true
+"""
+
+
+def load_config() -> Config:
+    path = PlatformDirs("sobe").user_config_path / "config.toml"
+    if path.exists():
+        with path.open("rb") as f:
+            payload = tomllib.load(f)
+            if payload.get("aws", {}).get("bucket", "example-bucket") != "example-bucket":
+                return Config.from_dict(payload)
+
+    # create default file and exit for user to customize
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(DEFAULT_TEMPLATE.lstrip())
+    raise MustEditConfig(path)

sobe/main.py

@@ -1,53 +1,16 @@
+"""Command-line interface entry point: input validation and output to user."""
+
 import argparse
 import datetime
 import functools
-import json
-import mimetypes
 import pathlib
-import sys
-import time
-import tomllib
 import warnings
 
-import boto3
-import botocore.exceptions
-import platformdirs
 import urllib3.exceptions
 
+from sobe.aws import AWS
+from sobe.config import MustEditConfig, load_config
 
-def load_config():
-    path = platformdirs.PlatformDirs("sobe", "balbuena.ca").user_config_path / "config.toml"
-    if path.exists():
-        with path.open("rb") as f:
-            payload = tomllib.load(f)
-            if payload["bucket"] != "example-bucket":
-                return payload
-
-    defaults = """
-        # sobe configuration
-        bucket = "example-bucket"
-        url = "https://example.com/"
-        cloudfront = "E1111111111111"
-
-        [aws_session]
-        # If you already have AWS CLI set up, don't fill keys here.
-        # region_name = "..."
-        # profile_name = "..."
-        # aws_access_key_id = "..."
-        # aws_secret_access_key = "..."
-
-        [aws_client]
-        verify = true
-    """
-    defaults = "\n".join(line.strip() for line in defaults.lstrip().splitlines())
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(defaults)
-    print("Created config file at the path below. You must edit it before use.")
-    print(path)
-    sys.exit(1)
-
-
-CONFIG = load_config()
 write = functools.partial(print, flush=True, end="")
 print = functools.partial(print, flush=True)  # type: ignore
 warnings.filterwarnings("ignore", category=urllib3.exceptions.InsecureRequestWarning)
@@ -55,99 +18,67 @@ warnings.filterwarnings("ignore", category=urllib3.exceptions.InsecureRequestWar
 
 def main() -> None:
     args = parse_args()
-    session = boto3.Session(**CONFIG["aws_session"])
-    bucket = session.resource("s3", **CONFIG["aws_client"]).Bucket(CONFIG["bucket"])
-    for path, key in zip(args.paths, args.keys):
+    try:
+        config = load_config()
+    except MustEditConfig as err:
+        print("Created config file at the path below. You must edit it before use.")
+        print(err.path)
+        raise SystemExit(1) from err
+
+    aws = AWS(config.aws)
+
+    if args.policy:
+        print(aws.generate_needed_permissions())
+        return
+
+    for path in args.paths:
+        write(f"{config.url}{args.year}/{path.name} ...")
         if args.delete:
-            delete(bucket, key)
+            existed = aws.delete(args.year, path.name)
+            print("deleted." if existed else "didn't exist.")
         else:
-            upload(bucket, path, key)
+            aws.upload(args.year, path)
+            print("ok.")
     if args.invalidate:
-        invalidate(session)
-
+        write("Clearing cache...")
+        for _ in aws.invalidate_cache():
+            write(".")
+        print("complete.")
 
-def upload(bucket, path: pathlib.Path, remote_path: str) -> None:
-    write(f"{CONFIG['url']}{remote_path} ...")
-    type_guess, _ = mimetypes.guess_type(path)
-    extra_args = {"ContentType": type_guess or "application/octet-stream"}
-    bucket.upload_file(str(path), remote_path, ExtraArgs=extra_args)
-    print("ok.")
 
-
-def delete(bucket, remote_path: str) -> None:
-    write(f"{CONFIG['url']}{remote_path} ...")
-    obj = bucket.Object(remote_path)
-    try:
-        obj.load()
-        obj.delete()
-        print("deleted.")
-    except botocore.exceptions.ClientError as e:
-        if e.response["Error"]["Code"] != "404":
-            raise
-        print("didn't exist.")
-
-
-def invalidate(session: boto3.Session) -> None:
-    write("Clearing cache ...")
-    ref = datetime.datetime.now().astimezone().isoformat()
-    cloudfront = session.client("cloudfront", **CONFIG["aws_client"])
-    batch = {"Paths": {"Quantity": 1, "Items": ["/*"]}, "CallerReference": ref}
-    invalidation = cloudfront.create_invalidation(DistributionId=CONFIG["cloudfront"], InvalidationBatch=batch)
-    write("ok.")
-    invalidation_id = invalidation["Invalidation"]["Id"]
-    status = ""
-    while status != "Completed":
-        time.sleep(3)
-        write(".")
-        response = cloudfront.get_invalidation(DistributionId=CONFIG["cloudfront"], Id=invalidation_id)
-        status = response["Invalidation"]["Status"]
-    print("complete.")
-
-
-def parse_args() -> argparse.Namespace:
+def parse_args(argv=None) -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Upload files to your AWS drop box.")
-    parser.add_argument("-y", "--year", type=int, default=datetime.date.today().year, help="change year directory")
+    parser.add_argument("-y", "--year", type=str, help="change year directory")
     parser.add_argument("-i", "--invalidate", action="store_true", help="invalidate CloudFront cache")
     parser.add_argument("-d", "--delete", action="store_true", help="delete instead of upload")
-    parser.add_argument("--policy", action="store_true", help="display IAM policy requirements and exit")
+    parser.add_argument("-p", "--policy", action="store_true", help="generate IAM policy requirements and exit")
     parser.add_argument("files", nargs="*", help="Source files.")
-    args = parser.parse_args()
+    args = parser.parse_args(argv)
 
     if args.policy:
-        dump_policy()
-        sys.exit(0)
+        if args.year or args.delete or args.invalidate or args.files:
+            parser.error("--policy cannot be used with other arguments")
+        return args
+
+    if args.year is None:
+        args.year = datetime.date.today().year
+    elif not args.files:
+        parser.error("--year requires files to be specified")
+
+    if args.delete and not args.files:
+        parser.error("--delete requires files to be specified")
 
     if not args.files and not args.invalidate:
         parser.print_help()
-        sys.exit(0)
+        raise SystemExit(0)
 
     args.paths = [pathlib.Path(p) for p in args.files]
-    args.keys = [f"{args.year}/{p.name}" for p in args.paths]
     if not args.delete:
         missing = [p for p in args.paths if not p.exists()]
         if missing:
             print("The following files do not exist:")
             for p in missing:
                 print(f"  {p}")
-            sys.exit(1)
+            raise SystemExit(1)
 
     return args
-
-
-def dump_policy() -> None:
-    session = boto3.Session(**CONFIG["aws_session"])
-    sts = session.client("sts", **CONFIG["aws_client"])
-    caller = sts.get_caller_identity()["Arn"]
-    account_id = caller.split(":")[4]
-    actions = """
-        s3:PutObject s3:GetObject s3:ListBucket s3:DeleteObject
-        cloudfront:CreateInvalidation cloudfront:GetInvalidation
-    """.split()
-    resources = [
-        f"arn:aws:s3:::{CONFIG['bucket']}",
-        f"arn:aws:s3:::{CONFIG['bucket']}/*",
-        f"arn:aws:cloudfront::{account_id}:distribution/{CONFIG['cloudfront']}",
-    ]
-    statement = {"Effect": "Allow", "Action": actions, "Resource": resources}
-    policy = {"Version": "2012-10-17", "Statement": [statement]}
-    print(json.dumps(policy, indent=2))

sobe-0.2.1.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: sobe
+Version: 0.2.1
+Summary: AWS-based drop box uploader
+Author: Liz Balbuena
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: Utilities
+Requires-Dist: boto3>=1.40.49
+Requires-Dist: platformdirs>=4.5.0
+Requires-Dist: furo>=2024.8.6 ; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0 ; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=2.0.0 ; extra == 'docs'
+Requires-Python: >=3.11
+Project-URL: Changelog, https://github.com/Liz4v/sobe/releases
+Project-URL: Documentation, https://github.com/Liz4v/sobe/blob/main/README.md
+Project-URL: Homepage, https://github.com/Liz4v/sobe
+Project-URL: Issues, https://github.com/Liz4v/sobe/issues
+Project-URL: Repository, https://github.com/Liz4v/sobe.git
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# sobe
+
+[![Documentation Status](https://readthedocs.org/projects/sobe/badge/?version=latest)](https://sobe.readthedocs.io/en/latest/)
+
+A simple command-line tool to upload files to an AWS S3 bucket that is publicly available through a CloudFront distribution. This is the traditional "drop box" use case that existed long before the advent of modern file sharing services.
+
+Full documentation: https://sobe.readthedocs.io/en/latest/
+
+It will upload any files you give it to your bucket, in a current year subdirectory, because that's the only easy way to organize chaos.
+
+"Sobe" is Portuguese for "take it up" (in the imperative), as in "upload".
+
+## Installation
+
+Use [uv](https://docs.astral.sh/uv/) to manage it.
+
+```bash
+uv tool install sobe
+```
+
+If you have Python ≥ 3.11, you can also install it via pip:
+
+```bash
+pip install sobe
+```
+
+## Configuration
+
+On first run, `sobe` will create its config file as appropriate to the platform and tell you its location. You'll need to edit this file with your AWS bucket and CloudFront details.
+
+Here's a minimal set up.
+
+```toml
+url = "https://example.com/"
+[aws]
+bucket = "your-bucket-name"
+cloudfront = "your-cloudfront-distribution-id"
+```
+
+[More information in the docs.](https://sobe.readthedocs.io/en/latest/configuration.html)
+
+## Usage
+
+The basic example is uploading files to current year directory:
+```bash
+$ sobe file1.jpg file2.pdf
+https://example.com/2025/file1.jpg ...ok.
+https://example.com/2025/file2.pdf ...ok.
+```
+
+You can call it with `--help` for all available options. You can delete files, clear the CloudFront cache (cached objects stay for 1 day by default), tweak the upload year. [The documentation contains better examples.](https://sobe.readthedocs.io/en/latest/usage.html#command-line-interface)
+
+## License
+
+See the [LICENSE](LICENSE) file for details.

sobe-0.2.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+sobe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sobe/aws.py,sha256=GcyN2A2NW74lYjNO0Lm8kecBTE89BwnCcLN6VX1JU5c,3151
+sobe/config.py,sha256=A1T0rMHCZYF2yr_WygkURrv6vh1gOs2nH12OhNgehp4,1916
+sobe/main.py,sha256=_p-FPPnDfM_iAmRuxnBqCOvP3mVDWldnFFepRwnqGVM,2811
+sobe-0.2.1.dist-info/WHEEL,sha256=k57ZwB-NkeM_6AsPnuOHv5gI5KM5kPD6Vx85WmGEcI0,78
+sobe-0.2.1.dist-info/entry_points.txt,sha256=a_cKExqUEzJ-t2MRWbxAHc8OavQIaL8a7JQ3obR2b-c,41
+sobe-0.2.1.dist-info/METADATA,sha256=NVODkko2xKNg2EDNOWjP9fvDuDhEg1uhh4sSTYrmYME,3054
+sobe-0.2.1.dist-info/RECORD,,

{sobe-0.1.dist-info → sobe-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.1
+Generator: uv 0.9.4
 Root-Is-Purelib: true
 Tag: py3-none-any

sobe-0.1.dist-info/METADATA

@@ -1,93 +0,0 @@
-Metadata-Version: 2.3
-Name: sobe
-Version: 0.1
-Summary: AWS-based drop box uploader
-Requires-Dist: boto3>=1.40.49
-Requires-Dist: platformdirs>=4.5.0
-Requires-Python: ==3.13.*
-Description-Content-Type: text/markdown
-
-# sobe
-
-A simple command-line tool for uploading files to an AWS S3 bucket that is publicly available through a CloudFront distribution. This is the traditional "drop box" use case that existed long before the advent of modern file sharing services.
-
-It will upload any files you give it to your bucket, in a current year subdirectory, because that's the only easy way to organize chaos.
-
-## Installation
-
-Use [uv](https://docs.astral.sh/uv/) to manage it.
-
-```bash
-uv tool install https://github.com/Liz4v/sobe.git
-```
-
-## Configuration
-
-On first run, `sobe` will create its config file as appropriate to the platform. You'll need to edit this file with your AWS bucket and CloudFront details:
-
-```toml
-# sobe configuration
-bucket = "your-bucket-name"
-url = "https://your-public-url/"
-cloudfront = "your-cloudfront-distribution-id"
-
-[aws_session]
-# If you already have AWS CLI set up, don't fill keys here.
-# region_name = "..."
-# profile_name = "..."
-# aws_access_key_id = "..."
-# aws_secret_access_key = "..."
-
-[aws_client]
-verify = true
-```
-
-## Usage
-
-```bash
-sobe [options] files...
-```
-
-### Options
-
-- `-y`, `--year`: Change the target year directory (default: current year)
-- `-i`, `--invalidate`: Invalidate CloudFront cache after upload
-- `-d`, `--delete`: Delete files instead of uploading
-- `-p`, `--policy`: Display required AWS IAM policy and exit
-
-### Examples
-
-Upload files to current year directory:
-```bash
-sobe file1.jpg file2.pdf
-```
-
-Upload files to a specific year:
-```bash
-sobe -y 2024 file1.jpg file2.pdf
-```
-
-Upload and invalidate CloudFront cache:
-```bash
-sobe -i file1.jpg
-```
-
-Delete files:
-```bash
-sobe -d file1.jpg
-```
-
-Get required AWS IAM policy:
-```bash
-sobe --policy
-```
-
-## AWS Permissions
-
-Use `sobe --policy` to generate the exact IAM policy required for your configuration. The tool needs permissions for:
-- S3: PutObject, GetObject, ListBucket, DeleteObject
-- CloudFront: CreateInvalidation, GetInvalidation
-
-## License
-
-See the [LICENSE](LICENSE) file for details.

sobe-0.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-sobe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sobe/main.py,sha256=3x3wsfo4l_rh7Nr-GEsL3jiqU8jTrYINkojzvKTB1eI,5232
-sobe-0.1.dist-info/WHEEL,sha256=ZbtZh9LqsQoZs-WmwRO6z-tavdkb5LzNxvrOv2F_OXE,78
-sobe-0.1.dist-info/entry_points.txt,sha256=a_cKExqUEzJ-t2MRWbxAHc8OavQIaL8a7JQ3obR2b-c,41
-sobe-0.1.dist-info/METADATA,sha256=pd-fXFiH_aB6x8dr-tav4oUE4vtgE4FSlQ-_1FJ0ZSw,2219
-sobe-0.1.dist-info/RECORD,,