feat: add manifest summary command

Author: DhanashreePetare

README.md

@@ -20,6 +20,7 @@ Command-line and Python client for downloading and deploying datasets on DBpedia
   - [Delete](#cli-delete)
   - [Manifest](#cli-manifest)
     - [Replay](#cli-manifest-replay)
+    - [Summary](#cli-manifest-summary)
 - [Module Usage](#module-usage)
   - [Deploy](#module-deploy)
 - [Development & Contributing](#development--contributing)
@@ -682,6 +683,32 @@ databusclient manifest replay ./manifests/deploy-run.jsonld --apikey YOUR_API_KE
 ```
 Replaying redeploys the same version — if it already exists on Databus, it is updated. WebDAV/Nextcloud deploys cannot be replayed, since the originally uploaded local files may no longer exist at their original paths by the time replay runs.
 
+<a id="cli-manifest-summary"></a>
+#### Summary
+
+Print a readable summary of any recorded manifest without replaying it:
+
+```bash
+# Python
+databusclient manifest summary ./manifests/download-run.jsonld
+# Docker
+docker run --rm -v $(pwd):/data dbpedia/databus-python-client manifest summary ./manifests/download-run.jsonld
+```
+
+Example output:
+
+```
+Command  : download
+Executed : 2024-03-24T10:02:49.500418+00:00
+Endpoint : https://databus.dbpedia.org/sparql
+Auth     : vault_token
+Files    : 1 succeeded · 0 failed
+Total    : 100.0 MB
+Status   : completed
+```
+
+Only existing data already stored in the manifest is read — no new files are downloaded or written, and no network access happens.
+
 ## Module Usage
 
 <a id="module-deploy"></a>

databusclient/cli.py

@@ -10,7 +10,8 @@
 from databusclient.api.download import download as api_download, DownloadAuthError
 from databusclient.manifest.context import ManifestContext
 from databusclient.manifest.writer import ManifestWriter
-from databusclient.manifest.replay import ManifestReplayError, replay_manifest
+from databusclient.manifest.replay import ManifestReplayError, replay_manifest, _load_manifest
+from databusclient.manifest.summary import format_summary
 from databusclient.extensions import webdav
 
 
@@ -552,5 +553,20 @@ def manifest_replay(manifest_path, localdir, databus, vault_token, databus_key,
     except Exception as e:
         raise click.ClickException(str(e))
 
+@manifest.command("summary")
+@click.argument("manifest_path", type=click.Path(exists=True, dir_okay=False))
+def manifest_summary(manifest_path):
+    """
+    Print a readable summary of a recorded manifest operation.
+
+    Reads the existing summary data already stored in the manifest --
+    no new data is collected and no new file is written.
+    """
+    try:
+        manifest = _load_manifest(manifest_path)
+        click.echo(format_summary(manifest))
+    except ManifestReplayError as e:
+        raise click.ClickException(str(e))
+
 if __name__ == "__main__":
     app()

databusclient/manifest/summary.py

@@ -0,0 +1,75 @@
+"""manifest summary — formats an existing manifest as readable console output.
+
+Reads already-recorded fields from a manifest JSON-LD file and formats
+them for display. No new data is collected, no new file is written, and
+no network access happens here at all.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+def _format_bytes(total_bytes: int) -> str:
+    """Format a byte count as a human-readable MB value."""
+    mb = total_bytes / (1024 * 1024)
+    return f"{mb:.1f} MB"
+
+
+def _derive_status(manifest: Dict[str, Any]) -> str:
+    """Derive an overall status string for the operation.
+
+    - "failed" if a top-level dbus:operationError was recorded.
+    - "completed with errors" if some individual files failed but the
+      operation itself did not raise.
+    - "completed" otherwise.
+    """
+    if manifest.get("dbus:operationError"):
+        return "failed"
+
+    result = manifest.get("dbus:executionResult", {})
+    if result.get("dbus:failed", 0) > 0:
+        return "completed with errors"
+
+    return "completed"
+
+
+def format_summary(manifest: Dict[str, Any]) -> str:
+    """Format a loaded manifest dict as a readable multi-line summary string.
+
+    Args:
+        manifest: A manifest dict, as produced by loading a manifest
+            JSON-LD file (e.g. via replay._load_manifest).
+
+    Returns:
+        A formatted multi-line string ready to print to the console.
+    """
+    lines = []
+
+    command = manifest.get("dbus:command", "unknown")
+    lines.append(f"Command  : {command}")
+
+    issued = manifest.get("dcterms:issued", {}).get("@value")
+    if issued:
+        lines.append(f"Executed : {issued}")
+
+    endpoint = manifest.get("dbus:endpoint")
+    if endpoint:
+        lines.append(f"Endpoint : {endpoint}")
+
+    auth_method = manifest.get("dbus:authMethod")
+    if auth_method:
+        lines.append(f"Auth     : {auth_method}")
+
+    result = manifest.get("dbus:executionResult", {})
+    succeeded = result.get("dbus:succeeded", 0)
+    failed = result.get("dbus:failed", 0)
+    lines.append(f"Files    : {succeeded} succeeded \u00b7 {failed} failed")
+
+    total_bytes = result.get("dbus:totalBytes", 0)
+    if command == "download" and total_bytes:
+        lines.append(f"Total    : {_format_bytes(total_bytes)}")
+
+    lines.append(f"Status   : {_derive_status(manifest)}")
+
+    return "\n".join(lines)

tests/test_manifest_summary.py

@@ -0,0 +1,89 @@
+from databusclient.manifest.summary import format_summary
+
+
+def test_summary_full_download_manifest():
+    manifest = {
+        "dbus:command": "download",
+        "dcterms:issued": {"@value": "2024-03-24T10:00:00Z"},
+        "dbus:endpoint": "https://databus.dbpedia.org",
+        "dbus:authMethod": "vault_token",
+        "dbus:executionResult": {
+            "dbus:succeeded": 1,
+            "dbus:failed": 0,
+            "dbus:totalBytes": 104857600,
+        },
+    }
+    output = format_summary(manifest)
+    assert "Command  : download" in output
+    assert "Executed : 2024-03-24T10:00:00Z" in output
+    assert "Endpoint : https://databus.dbpedia.org" in output
+    assert "Auth     : vault_token" in output
+    assert "Files    : 1 succeeded \u00b7 0 failed" in output
+    assert "Total    : 100.0 MB" in output
+    assert "Status   : completed" in output
+
+
+def test_summary_omits_missing_optional_fields():
+    """Delete/deploy manifests without endpoint/authMethod omit those lines."""
+    manifest = {
+        "dbus:command": "delete",
+        "dcterms:issued": {"@value": "2024-03-24T10:00:00Z"},
+        "dbus:executionResult": {
+            "dbus:succeeded": 1,
+            "dbus:failed": 0,
+            "dbus:totalBytes": 0,
+        },
+    }
+    output = format_summary(manifest)
+    assert "Endpoint" not in output
+    assert "Auth" not in output
+    assert "Total" not in output
+    assert "Command  : delete" in output
+    assert "Status   : completed" in output
+
+
+def test_summary_shows_failed_files():
+    manifest = {
+        "dbus:command": "download",
+        "dcterms:issued": {"@value": "2024-03-24T10:00:00Z"},
+        "dbus:executionResult": {
+            "dbus:succeeded": 2,
+            "dbus:failed": 1,
+            "dbus:totalBytes": 2048,
+        },
+    }
+    output = format_summary(manifest)
+    assert "Files    : 2 succeeded \u00b7 1 failed" in output
+    assert "Status   : completed with errors" in output
+
+
+def test_summary_shows_operation_error_as_failed_status():
+    manifest = {
+        "dbus:command": "deploy",
+        "dcterms:issued": {"@value": "2024-03-24T10:00:00Z"},
+        "dbus:executionResult": {
+            "dbus:succeeded": 0,
+            "dbus:failed": 0,
+            "dbus:totalBytes": 0,
+        },
+        "dbus:operationError": {
+            "dbus:errorType": "DeployError",
+            "dbus:errorMessage": "bad API key",
+        },
+    }
+    output = format_summary(manifest)
+    assert "Status   : failed" in output
+
+
+def test_summary_total_omitted_for_non_download_command():
+    manifest = {
+        "dbus:command": "deploy",
+        "dcterms:issued": {"@value": "2024-03-24T10:00:00Z"},
+        "dbus:executionResult": {
+            "dbus:succeeded": 1,
+            "dbus:failed": 0,
+            "dbus:totalBytes": 12345,
+        },
+    }
+    output = format_summary(manifest)
+    assert "Total" not in output