iphoto-sizer 0.1.0__tar.gz

iphoto_sizer-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.3
+Name: iphoto-sizer
+Version: 0.1.0
+Summary: Export and sort Apple Photos library metadata by file size
+Requires-Dist: osxphotos~=0.75.6
+Requires-Dist: pydantic~=2.12.5
+Requires-Dist: flask>=3.0 ; extra == 'web'
+Requires-Python: >=3.11
+Provides-Extra: web
+Description-Content-Type: text/markdown
+
+# iphoto-sizer
+
+Exports metadata from your macOS Apple Photos library to CSV or JSON, sorted by file size (largest first). Useful for finding what's eating your iCloud storage.
+
+Each record includes: filename, extension, media type (photo/video), size in bytes, human-readable size, creation date, UUID, and iCloud sync status (local vs cloud-only).
+
+## Prerequisites
+
+- macOS with the Photos app and a library present
+- Python 3.11+
+- Full Disk Access granted to your terminal (System Settings > Privacy & Security > Full Disk Access)
+
+## Install
+
+```bash
+# Clone and install with uv
+git clone https://github.com/spencerpresley/iPhotoSizer.git && cd iPhotoSizer
+uv sync
+```
+
+Or install with pip:
+
+```bash
+pip install .
+```
+
+## Usage
+
+After installing, an `iphoto-sizer` CLI command is available:
+
+```bash
+# Export everything to photos_report.csv in the current directory
+iphoto-sizer
+
+# Only items larger than 100 MB
+iphoto-sizer --min-size-mb 100
+
+# Write to a specific path
+iphoto-sizer -o ~/Desktop/large_files.csv
+
+# Export as JSON instead of CSV
+iphoto-sizer -f json -o ~/Desktop/photos.json
+
+# Combine options
+iphoto-sizer --min-size-mb 500 -f json -o ~/Desktop/big_ones.json
+```
+
+You can also run it as a module:
+
+```bash
+python -m iphoto_sizer
+```
+
+## CLI Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--min-size-mb` | Only include items at or above this size (MB) | `0` (all items) |
+| `-o`, `--output` | Output file path | `photos_report.csv` |
+| `-f`, `--format` | Output format: `csv` or `json` | `csv` |
+| `--web` | Launch the web UI in a browser | off |
+
+## Web UI
+
+An optional browser-based interface for browsing and filtering your library.
+
+### Install
+
+```bash
+pip install iphoto-sizer[web]
+```
+
+Or with uv:
+
+```bash
+uv sync --extra web
+```
+
+### Usage
+
+```bash
+iphoto-sizer --web
+```
+
+Opens a local web server in your browser. From there you can run a new scan, open an existing report, export results, and open individual photos in Photos.app.
+
+The web UI provides:
+- Summary stats (total items, total size, video/photo breakdown)
+- Sortable, filterable browsing of all library items
+- Export to CSV, JSON, or both from the browser
+- Open individual photos directly in Photos.app (experimental)
+
+## Output
+
+**CSV columns / JSON fields:**
+
+`filename`, `extension`, `media_type`, `size_bytes`, `size`, `creation_date`, `uuid`, `icloud_status`
+
+- `size` is human-readable (e.g. `"150.23 MB"`, `"1.50 GB"`)
+- `icloud_status` is `"local"` if the original file is on disk, `"cloud-only"` if it only exists in iCloud
+- Records are sorted by `size_bytes` descending
+
+A summary of total items, total size, and the 10 largest files is printed to stderr after export.
+
+## Notes
+
+- Initial library load takes 15-20 seconds on large libraries.
+- Photos that fail to parse are skipped with a warning; they don't stop the export.
+- The tool checks for at least 50 MB of free disk space before writing.

iphoto_sizer-0.1.0/README.md

@@ -0,0 +1,109 @@
+# iphoto-sizer
+
+Exports metadata from your macOS Apple Photos library to CSV or JSON, sorted by file size (largest first). Useful for finding what's eating your iCloud storage.
+
+Each record includes: filename, extension, media type (photo/video), size in bytes, human-readable size, creation date, UUID, and iCloud sync status (local vs cloud-only).
+
+## Prerequisites
+
+- macOS with the Photos app and a library present
+- Python 3.11+
+- Full Disk Access granted to your terminal (System Settings > Privacy & Security > Full Disk Access)
+
+## Install
+
+```bash
+# Clone and install with uv
+git clone https://github.com/spencerpresley/iPhotoSizer.git && cd iPhotoSizer
+uv sync
+```
+
+Or install with pip:
+
+```bash
+pip install .
+```
+
+## Usage
+
+After installing, an `iphoto-sizer` CLI command is available:
+
+```bash
+# Export everything to photos_report.csv in the current directory
+iphoto-sizer
+
+# Only items larger than 100 MB
+iphoto-sizer --min-size-mb 100
+
+# Write to a specific path
+iphoto-sizer -o ~/Desktop/large_files.csv
+
+# Export as JSON instead of CSV
+iphoto-sizer -f json -o ~/Desktop/photos.json
+
+# Combine options
+iphoto-sizer --min-size-mb 500 -f json -o ~/Desktop/big_ones.json
+```
+
+You can also run it as a module:
+
+```bash
+python -m iphoto_sizer
+```
+
+## CLI Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--min-size-mb` | Only include items at or above this size (MB) | `0` (all items) |
+| `-o`, `--output` | Output file path | `photos_report.csv` |
+| `-f`, `--format` | Output format: `csv` or `json` | `csv` |
+| `--web` | Launch the web UI in a browser | off |
+
+## Web UI
+
+An optional browser-based interface for browsing and filtering your library.
+
+### Install
+
+```bash
+pip install iphoto-sizer[web]
+```
+
+Or with uv:
+
+```bash
+uv sync --extra web
+```
+
+### Usage
+
+```bash
+iphoto-sizer --web
+```
+
+Opens a local web server in your browser. From there you can run a new scan, open an existing report, export results, and open individual photos in Photos.app.
+
+The web UI provides:
+- Summary stats (total items, total size, video/photo breakdown)
+- Sortable, filterable browsing of all library items
+- Export to CSV, JSON, or both from the browser
+- Open individual photos directly in Photos.app (experimental)
+
+## Output
+
+**CSV columns / JSON fields:**
+
+`filename`, `extension`, `media_type`, `size_bytes`, `size`, `creation_date`, `uuid`, `icloud_status`
+
+- `size` is human-readable (e.g. `"150.23 MB"`, `"1.50 GB"`)
+- `icloud_status` is `"local"` if the original file is on disk, `"cloud-only"` if it only exists in iCloud
+- Records are sorted by `size_bytes` descending
+
+A summary of total items, total size, and the 10 largest files is printed to stderr after export.
+
+## Notes
+
+- Initial library load takes 15-20 seconds on large libraries.
+- Photos that fail to parse are skipped with a warning; they don't stop the export.
+- The tool checks for at least 50 MB of free disk space before writing.

iphoto_sizer-0.1.0/pyproject.toml

@@ -0,0 +1,106 @@
+[project]
+name = "iphoto-sizer"
+version = "0.1.0"
+description = "Export and sort Apple Photos library metadata by file size"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "osxphotos~=0.75.6",
+    "pydantic~=2.12.5",
+]
+
+[project.optional-dependencies]
+web = ["flask>=3.0"]
+
+[project.scripts]
+iphoto-sizer = "iphoto_sizer.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.407",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.9",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.format]
+docstring-code-format = true
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  # Conflicts with formatter
+  "COM812",
+  "ISC001",
+
+  # Docstrings - too strict
+  "D100", # Missing docstring in public module
+  "D104", # Missing docstring in public package
+  "D107", # Missing docstring in __init__
+
+  # Annoying / not useful
+  "C90",    # McCabe complexity
+  "CPY",    # Copyright headers
+  "FIX002", # Line contains TODO
+  "PLR09",  # Too many arguments/statements/etc
+  "TD002",  # Missing author in TODO
+  "TD003",  # Missing issue link for TODO
+  "FBT",    # Boolean trap - internal APIs are fine
+  "PLW0603", # Global statement - config module pattern
+
+  # Doesn't play well with Pydantic
+  "RUF012", # Mutable class attrs
+  "TC001",  # Move import into TYPE_CHECKING
+  "TC002",  # Move import into TYPE_CHECKING
+  "TC003",  # Move import into TYPE_CHECKING
+
+  # May want to revisit
+  "BLE", # Blind exceptions
+]
+unfixable = [
+  "B028",    # warnings.warn() stacklevel - think about it
+  "PLW1510", # subprocess.run() check param - be explicit
+]
+fixable = ["ALL"]
+
+# Pydantic-friendly settings
+flake8-annotations.allow-star-arg-any = true
+flake8-annotations.mypy-init-return = true
+flake8-builtins.ignorelist = ["id", "type", "input"]
+flake8-type-checking.runtime-evaluated-base-classes = ["pydantic.BaseModel"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+ignore-var-parameters = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN", "D", "S", "PLR2004", "ARG", "PT", "T201", "FBT", "SLF001", "PLC0415", "ERA001"]
+"**/cli.py" = ["T201"]  # CLI tool — print to stderr is intentional
+"**/core.py" = ["T201"]  # load_photos_db prints status to stderr
+"**/web/*.py" = ["T201"]
+
+[tool.pyright]
+include = ["."]
+exclude = ["**/__pycache__", ".venv", "**/.venv", "output"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+
+venvPath = "."
+venv = ".venv"
+
+reportUnusedCallResult = "none"
+reportMissingTypeStubs = "none"
+reportPrivateUsage = "none"
+reportUnknownMemberType = "none"
+reportUnnecessaryTypeIgnoreComment = "warning"
+reportMissingTypeArgument = "none"

iphoto_sizer-0.1.0/src/iphoto_sizer/__init__.py

@@ -0,0 +1,45 @@
+"""iphoto-sizer — export Apple Photos library metadata sorted by file size."""
+
+from iphoto_sizer.core import apply_filters, load_photos_db, photo_to_record, scan_library
+from iphoto_sizer.models import (
+    BYTES_PER_GB,
+    BYTES_PER_MB,
+    CSV_COLUMNS,
+    DEFAULT_FORMAT,
+    DEFAULT_OUTPUT_FILE,
+    DEFAULT_OUTPUT_STEM,
+    ICLOUD_STATUS_CLOUD_ONLY,
+    ICLOUD_STATUS_LOCAL,
+    MEDIA_TYPE_PHOTO,
+    MEDIA_TYPE_VIDEO,
+    SUPPORTED_FORMATS,
+    OutputFormat,
+    PhotoRecord,
+    RecordWriter,
+    format_bytes,
+)
+from iphoto_sizer.writers import write_csv, write_json
+
+__all__ = [
+    "BYTES_PER_GB",
+    "BYTES_PER_MB",
+    "CSV_COLUMNS",
+    "DEFAULT_FORMAT",
+    "DEFAULT_OUTPUT_FILE",
+    "DEFAULT_OUTPUT_STEM",
+    "ICLOUD_STATUS_CLOUD_ONLY",
+    "ICLOUD_STATUS_LOCAL",
+    "MEDIA_TYPE_PHOTO",
+    "MEDIA_TYPE_VIDEO",
+    "SUPPORTED_FORMATS",
+    "OutputFormat",
+    "PhotoRecord",
+    "RecordWriter",
+    "apply_filters",
+    "format_bytes",
+    "load_photos_db",
+    "photo_to_record",
+    "scan_library",
+    "write_csv",
+    "write_json",
+]

iphoto_sizer-0.1.0/src/iphoto_sizer/__main__.py

@@ -0,0 +1,4 @@
+from iphoto_sizer.cli import main
+
+if __name__ == "__main__":
+    main()

iphoto_sizer-0.1.0/src/iphoto_sizer/cli.py

@@ -0,0 +1,222 @@
+"""CLI entry point for iphoto-sizer.
+
+.. code-block:: bash
+
+    # Export all items to photos_report.csv in the current directory
+    iphoto-sizer
+
+    # Or run as a module
+    python -m iphoto_sizer
+
+    # Export only items larger than 100 MB
+    iphoto-sizer --min-size-mb 100
+
+    # Export to a custom path
+    iphoto-sizer -o ~/Desktop/large_files.csv
+
+    # Export as JSON
+    iphoto-sizer -f json -o ~/Desktop/photos.json
+
+    # Combine options
+    iphoto-sizer --min-size-mb 500 -o ~/Desktop/big_ones.csv
+"""
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from iphoto_sizer.core import load_photos_db, scan_library
+from iphoto_sizer.models import (
+    BYTES_PER_MB,
+    DEFAULT_FORMAT,
+    DEFAULT_OUTPUT_FILE,
+    SUPPORTED_FORMATS,
+    PhotoRecord,
+    format_bytes,
+)
+from iphoto_sizer.writers import FORMAT_WRITERS
+
+_EXIT_CODE_ERROR = 1
+_EXIT_CODE_INTERRUPTED = 130
+_MIN_FREE_DISK_SPACE_MB = 50
+
+# Summary table column widths
+_COL_WIDTH_RANK = 3
+_COL_WIDTH_FILENAME = 40
+_COL_WIDTH_SIZE = 10
+_COL_WIDTH_MEDIA_TYPE = 5
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser.
+
+    Returns:
+        argparse.ArgumentParser: Configured parser with ``--min-size-mb``
+                                 and ``--output`` arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Export Apple Photos library metadata to CSV, sorted by file size."
+    )
+    parser.add_argument(
+        "--min-size-mb",
+        type=float,
+        default=0.0,
+        help="Only include items larger than this size in MB (default: include all)",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        default=DEFAULT_OUTPUT_FILE,
+        help=f"Output file path (default: {DEFAULT_OUTPUT_FILE})",
+    )
+    parser.add_argument(
+        "--format",
+        "-f",
+        type=str,
+        choices=SUPPORTED_FORMATS,
+        default=DEFAULT_FORMAT,
+        help=f"Output format (default: {DEFAULT_FORMAT})",
+    )
+    parser.add_argument(
+        "--web",
+        action="store_true",
+        default=False,
+        help="Launch the web UI instead of exporting to a file",
+    )
+    return parser
+
+
+def validate_output_path(output_path: str) -> Path:
+    """Validate and prepare the output file path.
+
+    Creates parent directories if they don't exist. Warns if an existing
+    file will be overwritten. Checks that the destination has enough disk
+    space for a reasonable CSV output.
+
+    Args:
+        output_path (str): Destination file path for the CSV.
+
+    Returns:
+        Path: The validated output path.
+
+    Raises:
+        SystemExit: If the parent directory cannot be created or there
+                    is insufficient disk space.
+    """
+    path = Path(output_path)
+
+    # Ensure parent directory exists
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        print(f"Cannot create output directory {path.parent}: {e}", file=sys.stderr)
+        sys.exit(_EXIT_CODE_ERROR)
+
+    if path.exists():
+        print(f"Note: overwriting existing file {path}", file=sys.stderr)
+
+    # Rough disk space check — a large library (100k items) produces
+    # roughly 15-20 MB of CSV, so 50 MB is a comfortable minimum
+    min_free_bytes = _MIN_FREE_DISK_SPACE_MB * BYTES_PER_MB
+    try:
+        free_bytes = shutil.disk_usage(path.parent).free
+    except OSError as e:
+        print(
+            f"Warning: could not check disk space for {path.parent}: {e}",
+            file=sys.stderr,
+        )
+        return path
+    if free_bytes < min_free_bytes:
+        print(
+            f"Insufficient disk space: {format_bytes(free_bytes)} free, "
+            f"need at least {format_bytes(min_free_bytes)}",
+            file=sys.stderr,
+        )
+        sys.exit(_EXIT_CODE_ERROR)
+
+    return path
+
+
+def print_summary(records: list[PhotoRecord], top_n: int = 10) -> None:
+    """Print a summary report to stderr.
+
+    Displays total item count, total size, and the largest items.
+
+    Args:
+        records (list[PhotoRecord]): Records to summarize, assumed pre-sorted
+                                     by size descending.
+        top_n (int): Number of largest items to display. Defaults to 10.
+    """
+    if not records:
+        print("No items found.", file=sys.stderr)
+        return
+
+    total_bytes = sum(r.size_bytes for r in records)
+
+    print(file=sys.stderr)
+    print("=== Photos Library Report ===", file=sys.stderr)
+    print(f"Total items: {len(records):,}", file=sys.stderr)
+    print(f"Total size:  {format_bytes(total_bytes)}", file=sys.stderr)
+    display_count = min(top_n, len(records))
+
+    print(file=sys.stderr)
+    print(f"Top {display_count} Largest Items:", file=sys.stderr)
+
+    for i, record in enumerate(records[:display_count], start=1):
+        print(
+            f"  {i:>{_COL_WIDTH_RANK}}. {record.filename:<{_COL_WIDTH_FILENAME}}"
+            f" {record.size:>{_COL_WIDTH_SIZE}}"
+            f"   {record.media_type:<{_COL_WIDTH_MEDIA_TYPE}}  {record.icloud_status}",
+            file=sys.stderr,
+        )
+
+
+def _start_web() -> None:
+    """Import and start the web UI. Raises ImportError if Flask is not installed."""
+    from iphoto_sizer.web import serve_web  # noqa: PLC0415
+
+    serve_web()
+
+
+def main() -> None:
+    """Run the full export pipeline: load, extract, filter, sort, write, summarize."""
+    try:
+        _run()
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        sys.exit(_EXIT_CODE_INTERRUPTED)
+
+
+def _run() -> None:
+    """Inner pipeline logic, separated so ``main()`` owns interrupt handling."""
+    args = build_arg_parser().parse_args()
+
+    if args.min_size_mb < 0:
+        print("Error: --min-size-mb cannot be negative", file=sys.stderr)
+        sys.exit(_EXIT_CODE_ERROR)
+
+    if args.web:
+        try:
+            _start_web()
+        except ImportError:
+            print(
+                "The --web flag requires the [web] extra.\n"
+                "Install it with: pip install iphoto-sizer[web]",
+                file=sys.stderr,
+            )
+            sys.exit(_EXIT_CODE_ERROR)
+        return
+
+    output_path = validate_output_path(args.output)
+    db = load_photos_db()
+
+    records, skipped = scan_library(db, min_size_mb=args.min_size_mb)
+    if skipped:
+        print(f"Skipped {skipped} item(s) due to errors.", file=sys.stderr)
+
+    writer = FORMAT_WRITERS[args.format]
+    writer(records, output_path)
+    print(f"{args.format.upper()} written to {output_path}", file=sys.stderr)
+    print_summary(records)