sobe 0.3.0__py3-none-any.whl

sobe/aws.py

@@ -0,0 +1,108 @@
+"""Everything related to AWS. In the future, we may support other cloud providers."""
+
+import datetime
+import json
+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, prefix: str, local_path: pathlib.Path, *, content_type: str | None = None) -> None:
+        """Upload a file."""
+        extra_args = {"ContentType": content_type or guess_content_type(local_path)}
+        self._bucket.upload_file(str(local_path), f"{prefix}{local_path.name}", ExtraArgs=extra_args)
+
+    def delete(self, prefix: str, remote_filename: str) -> bool:
+        """Delete a file, if it exists. Returns whether it did."""
+        obj = self._bucket.Object(f"{prefix}{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 list(self, prefix: str) -> list[str]:
+        """Return a list of object filenames in the given prefix."""
+        objects = self._bucket.objects.filter(Prefix=prefix)
+        pos1 = len(prefix)
+        results = set()
+        for obj in objects:
+            if len(obj.key) == pos1:
+                continue  # skip the prefix entry itself
+            pos2 = obj.key.find("/", pos1)
+            if pos2 == -1:
+                results.add(obj.key[pos1:])
+            else:
+                results.add(obj.key[pos1:pos2] + "/")
+        return sorted(results)
+
+    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)
+
+
+def guess_content_type(path: pathlib.Path) -> str:
+    """Return a guessed content type for the given file."""
+    import mimetypes
+
+    # Guess based on filename using standard library
+    guess, _ = mimetypes.guess_type(path.name)
+    if guess:
+        return guess
+
+    import puremagic
+
+    # Guess based on file content using puremagic
+    for result in puremagic.magic_file(path):  # result is ordered by confidence
+        guess = getattr(result, "mime_type", None)
+        if guess:
+            return guess
+
+    # Fallback
+    return "application/octet-stream"

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

@@ -0,0 +1,108 @@
+"""Command-line interface entry point: input validation and output to user."""
+
+import argparse
+import datetime
+import functools
+import pathlib
+import warnings
+
+import urllib3.exceptions
+
+from sobe.aws import AWS
+from sobe.config import MustEditConfig, load_config
+
+write = functools.partial(print, flush=True, end="")
+print = functools.partial(print, flush=True)  # type: ignore
+warnings.filterwarnings("ignore", category=urllib3.exceptions.InsecureRequestWarning)
+
+
+def main() -> None:
+    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
+
+    args = parse_args()
+    aws = AWS(config.aws)
+
+    if args.policy:
+        print(aws.generate_needed_permissions())
+        return
+
+    if args.list:
+        files = aws.list(args.prefix)
+        if not files:
+            print(f"No files under {config.url}{args.prefix}")
+            return
+        for name in files:
+            print(f"{config.url}{args.prefix}{name}")
+        return
+
+    for path in args.paths:
+        write(f"{config.url}{args.prefix}{path.name} ...")
+        if args.delete:
+            existed = aws.delete(args.prefix, path.name)
+            print("deleted." if existed else "didn't exist.")
+        else:
+            aws.upload(args.prefix, path, content_type=args.content_type )
+            print("ok.")
+    if args.invalidate:
+        write("Clearing cache...")
+        for _ in aws.invalidate_cache():
+            write(".")
+        print("complete.")
+
+
+def parse_args(argv=None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Upload files to your AWS drop box.")
+    parser.add_argument("-y", "--year", type=str, help="set remote directory (usually a year)")
+    parser.add_argument("-t", "--content-type", type=str, help="override detected MIME type for uploaded files")
+    parser.add_argument("-l", "--list", action="store_true", help="list all files in the year")
+    parser.add_argument("-d", "--delete", action="store_true", help="delete instead of upload")
+    parser.add_argument("-i", "--invalidate", action="store_true", help="invalidate CloudFront cache")
+    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(argv)
+    num_arg_types = sum(map(bool, args.__dict__.values()))
+
+    if num_arg_types == 0:
+        parser.print_help()
+        raise SystemExit(0)
+
+    if args.policy:
+        if num_arg_types != 1:
+            parser.error("--policy cannot be used with other arguments")
+        return args
+
+    if args.year is None:
+        args.year = str(datetime.date.today().year)
+    elif not (args.files or args.list):
+        parser.error("--year requires files or --list to be specified")
+    args.prefix = args.year if args.year == "" or args.year.endswith("/") else f"{args.year}/"
+
+    if args.content_type:
+        if args.delete or args.list:
+            parser.error("--content-type cannot be used with --delete or --list")
+        if not args.files:
+            parser.error("--content-type requires files to be specified")
+    elif args.list:
+        if args.delete:
+            parser.error("--list and --delete cannot be used at the same time")
+        if args.files:
+            parser.error("--list does not support file filtering yet")
+    elif args.delete:
+        if not args.files:
+            parser.error("--delete requires files to be specified")
+
+    args.paths = [pathlib.Path(p) for p in args.files]
+    if not (args.delete or args.list):
+        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}")
+            raise SystemExit(1)
+
+    return args

sobe-0.3.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: sobe
+Version: 0.3.0
+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: puremagic>=1.30
+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, defaulting to a current year directory, 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 list files, delete them, clear the CloudFront cache (cached objects stay for 1 day by default), select a different upload directory. [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.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sobe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sobe/aws.py,sha256=qHgUOsh5Qu369nt8BjhCMNe248pqCK2zqjpjO0jbscc,4263
+sobe/config.py,sha256=A1T0rMHCZYF2yr_WygkURrv6vh1gOs2nH12OhNgehp4,1916
+sobe/main.py,sha256=BbxykyogqDEifhCXntrOWkxkdTbymlTJG315gWAa8Mw,3949
+sobe-0.3.0.dist-info/WHEEL,sha256=DpNsHFUm_gffZe1FgzmqwuqiuPC6Y-uBCzibcJcdupM,78
+sobe-0.3.0.dist-info/entry_points.txt,sha256=a_cKExqUEzJ-t2MRWbxAHc8OavQIaL8a7JQ3obR2b-c,41
+sobe-0.3.0.dist-info/METADATA,sha256=TO_vHtu2PptBOy7MuWf70jws-AiSQqSh3YpP19DLmGY,3118
+sobe-0.3.0.dist-info/RECORD,,

sobe-0.3.0.dist-info/WHEEL

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

sobe-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sobe = sobe.main:main
+