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

sobe/aws.py

@@ -1,3 +1,5 @@
+"""Everything related to AWS. In the future, we may support other cloud providers."""
+
 import datetime
 import json
 import mimetypes
@@ -7,7 +9,7 @@ import time
 import boto3
 import botocore.exceptions
 
-from .config import AWSConfig
+from sobe.config import AWSConfig
 
 
 class AWS:
@@ -31,7 +33,7 @@ class AWS:
             obj.load()
             obj.delete()
             return True
-        except botocore.exceptions.ClientError as e:  # pragma: no cover - network edge
+        except botocore.exceptions.ClientError as e:
             if e.response.get("Error", {}).get("Code") == "404":
                 return False
             raise
@@ -44,7 +46,7 @@ class AWS:
         response = self._cloudfront.create_invalidation(DistributionId=distribution, InvalidationBatch=batch)
         invalidation = response["Invalidation"]["Id"]
         status = "Created"
-        while status != "Completed":  # pragma: no cover - polling side effect
+        while status != "Completed":
             yield status
             time.sleep(3)
             response = self._cloudfront.get_invalidation(DistributionId=distribution, Id=invalidation)
@@ -55,7 +57,7 @@ class AWS:
         try:
             sts = self._session.client("sts", **self.config.service)
             account_id = sts.get_caller_identity()["Account"]
-        except botocore.exceptions.ClientError:  # pragma: no cover - network edge
+        except botocore.exceptions.ClientError:
             account_id = "YOUR_ACCOUNT_ID"
 
         actions = """

sobe/config.py

@@ -1,4 +1,7 @@
+"""Everything related to user configuration file."""
+
 import tomllib
+from pathlib import Path
 from typing import Any, NamedTuple, Self
 
 from platformdirs import PlatformDirs
@@ -32,6 +35,13 @@ class Config(NamedTuple):
         )
 
 
+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
 
@@ -49,12 +59,12 @@ cloudfront = "E1111111111111"
 # aws_secret_access_key = "..."
 
 [aws.service]
-verify = true
+# verify = true
 """
 
 
 def load_config() -> Config:
-    path = PlatformDirs("sobe", "balbuena.ca").user_config_path / "config.toml"
+    path = PlatformDirs("sobe").user_config_path / "config.toml"
     if path.exists():
         with path.open("rb") as f:
             payload = tomllib.load(f)
@@ -62,12 +72,6 @@ def load_config() -> Config:
                 return Config.from_dict(payload)
 
     # create default file and exit for user to customize
-    defaults = "\n".join(line.strip() for line in DEFAULT_TEMPLATE.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)
-    raise SystemExit(1)
-
-
-CONFIG: Config = load_config()
+    path.write_text(DEFAULT_TEMPLATE.lstrip())
+    raise MustEditConfig(path)

sobe/main.py

@@ -1,14 +1,15 @@
+"""Command-line interface entry point: input validation and output to user."""
+
 import argparse
 import datetime
 import functools
 import pathlib
-import sys
 import warnings
 
 import urllib3.exceptions
 
-from .aws import AWS
-from .config import CONFIG
+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
@@ -17,10 +18,21 @@ warnings.filterwarnings("ignore", category=urllib3.exceptions.InsecureRequestWar
 
 def main() -> None:
     args = parse_args()
-    aws = AWS(CONFIG.aws)
+    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} ...")
+        write(f"{config.url}{args.year}/{path.name} ...")
         if args.delete:
             existed = aws.delete(args.year, path.name)
             print("deleted." if existed else "didn't exist.")
@@ -34,23 +46,31 @@ def main() -> None:
         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="generate 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:
-        aws = AWS(CONFIG.aws)
-        print(aws.generate_needed_permissions())
-        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]
     if not args.delete:
@@ -59,6 +79,6 @@ def parse_args() -> argparse.Namespace:
             print("The following files do not exist:")
             for p in missing:
                 print(f"  {p}")
-            sys.exit(1)
+            raise SystemExit(1)
 
     return args

{sobe-0.2.dist-info → sobe-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sobe
-Version: 0.2
+Version: 0.2.1
 Summary: AWS-based drop box uploader
 Author: Liz Balbuena
 License-Expression: MIT
@@ -16,20 +16,30 @@ 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
 
-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.
+[![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.
@@ -46,70 +56,29 @@ pip install sobe
 
 ## 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:
+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
-# sobe configuration
+url = "https://example.com/"
+[aws]
 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
-```
+[More information in the docs.](https://sobe.readthedocs.io/en/latest/configuration.html)
 
-Upload and invalidate CloudFront cache:
-```bash
-sobe -i file1.jpg
-```
-
-Delete files:
-```bash
-sobe -d file1.jpg
-```
+## Usage
 
-Get required AWS IAM policy:
+The basic example is uploading files to current year directory:
 ```bash
-sobe --policy
+$ sobe file1.jpg file2.pdf
+https://example.com/2025/file1.jpg ...ok.
+https://example.com/2025/file2.pdf ...ok.
 ```
 
-## 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
+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
 

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.2.dist-info → sobe-0.2.1.dist-info}/WHEEL

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

sobe-0.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-sobe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sobe/aws.py,sha256=X5r0MTCfSQPhqRMHun0710ecZSV-6eOd_4E38oxBSsY,3172
-sobe/config.py,sha256=a4lc7Rlw5Zs4QGdNRIhB8pscJxBn-ze2WHnzWV4d7ro,1882
-sobe/main.py,sha256=M40CqclSwlCZeJvFi52kiyBIqcQ8Z1C9b7QsWk-tvt4,2079
-sobe-0.2.dist-info/WHEEL,sha256=X16MKk8bp2DRsAuyteHJ-9qOjzmnY0x1aj0P1ftqqWA,78
-sobe-0.2.dist-info/entry_points.txt,sha256=a_cKExqUEzJ-t2MRWbxAHc8OavQIaL8a7JQ3obR2b-c,41
-sobe-0.2.dist-info/METADATA,sha256=vapxWrCS_zDIlXosohc-Px3k48Q_KG7KG-xswlWEqMM,3105
-sobe-0.2.dist-info/RECORD,,