v2.0.1: add storage_class_distribution to stats, --verbose flag for CLI

Author: eliask

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "farchive"
-version = "2.0.0"
+version = "2.0.1"
 description = "Local content-addressed archive with locator-scoped history for opaque bytes."
 requires-python = ">=3.11"
 dependencies = [

src/farchive/__init__.py

@@ -21,4 +21,4 @@
     "RepackStats",
     "StateSpan",
 ]
-__version__ = "2.0.0"
+__version__ = "2.0.1"

src/farchive/_archive.py

@@ -1379,6 +1379,18 @@ def stats(self) -> ArchiveStats:
                 entry["logical_stored"] = logical
             codec_dist[row[0]] = entry
 
+        storage_class_dist: dict[str, dict] = {}
+        for row in self._conn.execute(
+            "SELECT COALESCE(storage_class, '(none)'), COUNT(*), "
+            "SUM(raw_size), SUM(stored_self_size) "
+            "FROM blob GROUP BY storage_class",
+        ).fetchall():
+            storage_class_dist[row[0]] = {
+                "count": row[1],
+                "raw": row[2],
+                "stored": row[3],
+            }
+
         return ArchiveStats(
             locator_count=loc_count,
             blob_count=blob_count,
@@ -1388,6 +1400,7 @@ def stats(self) -> ArchiveStats:
             total_stored_bytes=total_stored,
             compression_ratio=(totals[0] / total_stored) if total_stored else None,
             codec_distribution=codec_dist,
+            storage_class_distribution=storage_class_dist,
             db_path=str(self._db_path),
             schema_version=db_version,
             chunk_count=chunk_count,

src/farchive/_cli.py

@@ -38,6 +38,24 @@ def _cmd_stats(args: argparse.Namespace) -> None:
                     f"  {key:<12} {d['count']:>8,} blobs  "
                     f"{d['raw']:>12,} raw  {d['stored']:>12,} stored  ({r:.1f}x)"
                 )
+    if st.storage_class_distribution:
+        classes = sorted(
+            st.storage_class_distribution.items(),
+            key=lambda kv: kv[1]["stored"],
+            reverse=True,
+        )
+        if not args.verbose:
+            classes = classes[:10]
+        print("\nStorage class distribution:")
+        for key, d in classes:
+            r = d["raw"] / d["stored"] if d["stored"] else 0
+            print(
+                f"  {key:<12} {d['count']:>8,} blobs  "
+                f"{d['raw']:>12,} raw  {d['stored']:>12,} stored  ({r:.1f}x)"
+            )
+        if not args.verbose and len(st.storage_class_distribution) > 10:
+            remaining = len(st.storage_class_distribution) - 10
+            print(f"  ... and {remaining} more class(es) (use --verbose to show all)")
 
 
 def _cmd_history(args: argparse.Namespace) -> None:
@@ -205,6 +223,9 @@ def main(argv: list[str] | None = None) -> None:
     # stats
     p = sub.add_parser("stats", help="Show archive statistics")
     p.add_argument("db", nargs="?", default=_DEFAULT_DB, help="DB path")
+    p.add_argument(
+        "-v", "--verbose", action="store_true", help="Show all storage classes"
+    )
 
     # history
     p = sub.add_parser("history", help="Show span history for a locator")

src/farchive/_types.py

@@ -111,6 +111,7 @@ class ArchiveStats:
     total_stored_bytes: int
     compression_ratio: float | None
     codec_distribution: dict[str, dict]
+    storage_class_distribution: dict[str, dict]
     db_path: str
     schema_version: int
     chunk_count: int