saia-python 0.7.0__tar.gz → 0.8.0__tar.gz

{saia_python-0.7.0/saia_python.egg-info → saia_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python wrapper for the GWDG SAIA platform REST API
 Author: Friedrich Schwarz
 License-Expression: AGPL-3.0-only

{saia_python-0.7.0 → saia_python-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "saia-python"
-version = "0.7.0"
+version = "0.8.0"
 description = "Python wrapper for the GWDG SAIA platform REST API"
 readme = "README.md"
 requires-python = ">=3.10"

{saia_python-0.7.0 → saia_python-0.8.0}/saia_python/arcana.py

@@ -415,6 +415,49 @@ class ArcanaService:
 
         return _json_or_none(resp)
 
+    def recreate(self, name: str, *, update_toml: bool = False) -> dict:
+        """Delete an arcana and recreate it **empty with the same ID**.
+
+        The minimal-call way to wipe an entire arcana: two requests
+        (:meth:`delete` + :meth:`create`) regardless of how many files it
+        holds, versus one :meth:`delete_file` per file (thousands of calls,
+        each its own read-timeout risk while the arcana is busy). The name —
+        including any UUID suffix — is preserved verbatim via
+        ``create(..., append_uuid=False)``, so a downstream pin on the full
+        ``owner/name-uuid`` ID stays valid.
+
+        Trade-offs versus emptying file-by-file (:meth:`delete_file` in a
+        loop, which keeps the container): there is a brief window between the
+        two calls where the arcana does **not exist**, and the recreated
+        arcana is brand-new — ``created_at``, sharing/permissions and any
+        other container settings reset to defaults. Only the name/ID carries
+        across.
+
+        Args:
+            name: The arcana name or full ``owner/name`` ID to recreate.
+            update_toml: Forwarded to :meth:`create`.
+
+        Returns:
+            The :meth:`create` result (``{"name", "id", "message"}``).
+
+        Raises:
+            APIError: If recreation fails *after* the delete already
+                succeeded — the arcana is then gone. The message says so
+                explicitly so the operator recreates it before any consumer
+                (adapter / manifest pin) points at the ID.
+        """
+        short = extract_arcana_name(name)
+        self.delete(name)
+        try:
+            return self.create(short, append_uuid=False, update_toml=update_toml)
+        except Exception as e:  # noqa: BLE001 — re-raise with a louder message
+            raise APIError(
+                f"arcana {short!r} was DELETED but could not be recreated: {e}. "
+                f"The arcana no longer exists — recreate it (e.g. "
+                f"create({short!r}, append_uuid=False)) before any consumer "
+                f"(adapter / manifest pin) points at its ID."
+            ) from e
+
     def list(self) -> list[dict]:
         """List all available arcanas.
 
@@ -742,6 +785,70 @@ class ArcanaService:
         raise_for_status(resp)
         return _json_or_none(resp)
 
+    def delete_files(
+        self,
+        name: str,
+        file_names: Iterable[str],
+        *,
+        verbose: bool = False,
+        on_result: Callable[[str, dict], None] | None = None,
+    ) -> list[dict]:
+        """Delete an explicit list of files from an arcana, by name.
+
+        The batch counterpart to :meth:`delete_file`: hand it the file names
+        (as returned by :meth:`list_files`) and it deletes each one,
+        capturing a per-file outcome instead of aborting on the first
+        failure. Unlike :meth:`delete_directory` no local directory is
+        consulted — the names come straight from the caller — so it can
+        target files that no longer exist on disk (e.g. a name list from a
+        CSV). Pairs with a thin CLI front-end that resolves *which* names to
+        delete; this method only does the deleting.
+
+        Args:
+            name: The arcana name or full ``owner/name`` ID.
+            file_names: The file names to delete (flat names, as listed by
+                :meth:`list_files`). Order is preserved; a repeated name is
+                attempted each time (a second delete just reports the
+                server's response / 404).
+            verbose: If ``True``, print per-file deletion status.
+            on_result: Optional callback invoked as ``on_result(file_name,
+                entry)`` after each file (``entry`` is that file's
+                ``{"file", "status", ["error"]}`` dict), for inline
+                per-file logging.
+
+        Returns:
+            A list of dicts with keys ``"file"`` (the name), ``"status"``
+            (``"deleted"`` or ``"failed"``), and ``"error"`` (only on
+            failure) — the same shape every batch op returns.
+        """
+        names = [str(n) for n in file_names]
+        # Arcana file names are flat (as listed by :meth:`list_files`). The
+        # batch executor below is Path-centric and targets ``Path(n).name``;
+        # a name containing ``/`` would silently collapse to its basename and
+        # delete the WRONG file. Refuse the whole batch up front — atomic, so
+        # nothing is deleted if any name is malformed (e.g. from a bad CSV).
+        bad = [n for n in names if "/" in n]
+        if bad:
+            raise ValueError(
+                f"ARCANA file names are flat (no '/'); refusing to delete "
+                f"{len(bad)} name(s) containing a path separator: {bad}"
+            )
+        # Reuse the shared batch executor (iteration, per-file error capture,
+        # progress bar, on_result, tally). With flat names ``Path(n).name ==
+        # n``, so the label/delete-target round-trips exactly.
+        return self._run_file_batch(
+            [Path(n) for n in names],
+            lambda fp: self.delete_file(name, fp.name),
+            default_status="deleted",
+            desc="Deleting",
+            verbose=verbose,
+            on_result=(
+                None
+                if on_result is None
+                else lambda fp, entry: on_result(fp.name, entry)
+            ),
+        )
+
     def download_file(self, name: str, file_name: str, output_path: str | Path) -> Path:
         """Download a file from an arcana to a local path.
 

{saia_python-0.7.0 → saia_python-0.8.0/saia_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python wrapper for the GWDG SAIA platform REST API
 Author: Friedrich Schwarz
 License-Expression: AGPL-3.0-only

{saia_python-0.7.0 → saia_python-0.8.0}/tests/test_arcana.py

@@ -513,3 +513,88 @@ class TestOnResultHook:
             on_result=lambda p, e: seen.__setitem__(p.name, e["status"]),
         )
         assert seen == {"new.txt": "uploaded", "keep.txt": "skipped"}
+
+
+class TestDeleteFiles:
+    """ArcanaService.delete_files — batch delete by an explicit name list."""
+
+    def test_deletes_each_name_and_returns_entries(self):
+        svc = _make_service()
+        svc.delete_file = MagicMock(return_value=None)
+        results = svc.delete_files("my-arcana", ["a.md", "b.md", "c.md"])
+        assert [r["file"] for r in results] == ["a.md", "b.md", "c.md"]
+        assert {r["status"] for r in results} == {"deleted"}
+        assert [c.args for c in svc.delete_file.call_args_list] == [
+            ("my-arcana", "a.md"),
+            ("my-arcana", "b.md"),
+            ("my-arcana", "c.md"),
+        ]
+
+    def test_failure_recorded_per_file_and_continues(self):
+        """A read-timeout on one name must not abort the rest — the whole
+        reason this is a batch op and not a bare loop that raises."""
+        svc = _make_service()
+
+        def fake_delete(arcana, fn):
+            if fn == "b.md":
+                raise requests.exceptions.ReadTimeout("read timed out")
+            return None
+
+        svc.delete_file = MagicMock(side_effect=fake_delete)
+        results = svc.delete_files("my-arcana", ["a.md", "b.md", "c.md"])
+        by = {r["file"]: r for r in results}
+        assert by["a.md"]["status"] == "deleted"
+        assert by["b.md"]["status"] == "failed" and "error" in by["b.md"]
+        assert by["c.md"]["status"] == "deleted"  # continued past the failure
+
+    def test_on_result_called_with_name_and_entry(self):
+        svc = _make_service()
+        svc.delete_file = MagicMock(return_value=None)
+        seen = []
+        svc.delete_files(
+            "my-arcana",
+            ["a.md", "b.md"],
+            on_result=lambda n, e: seen.append((n, e["status"])),
+        )
+        assert seen == [("a.md", "deleted"), ("b.md", "deleted")]
+
+    def test_empty_list_makes_no_calls(self):
+        svc = _make_service()
+        svc.delete_file = MagicMock()
+        assert svc.delete_files("my-arcana", []) == []
+        svc.delete_file.assert_not_called()
+
+    def test_name_with_path_separator_rejected_atomically(self):
+        """A '/' would make the Path-based executor delete only the basename
+        — refuse the whole batch up front, deleting nothing."""
+        svc = _make_service()
+        svc.delete_file = MagicMock()
+        with pytest.raises(ValueError, match="flat"):
+            svc.delete_files("my-arcana", ["ok.md", "sub/dir/bad.md"])
+        svc.delete_file.assert_not_called()  # atomic — nothing deleted
+
+
+class TestRecreate:
+    """ArcanaService.recreate — delete + recreate-empty-with-the-same-ID."""
+
+    def test_deletes_then_creates_same_name_without_uuid(self):
+        svc = _make_service()
+        svc.delete = MagicMock(return_value=None)
+        svc.create = MagicMock(return_value={"name": "kb-uuid", "id": "owner/kb-uuid"})
+        out = svc.recreate("owner/kb-uuid")
+        svc.delete.assert_called_once_with("owner/kb-uuid")
+        # name stripped of owner, UUID preserved, append_uuid OFF → same ID
+        svc.create.assert_called_once_with(
+            "kb-uuid", append_uuid=False, update_toml=False
+        )
+        assert out["id"] == "owner/kb-uuid"
+
+    def test_create_failure_after_delete_raises_loud_apierror(self):
+        """If create dies after delete already landed, the arcana is gone —
+        that must surface as a loud, unambiguous error, not the raw 500."""
+        svc = _make_service()
+        svc.delete = MagicMock(return_value=None)
+        svc.create = MagicMock(side_effect=RuntimeError("gateway down"))
+        with pytest.raises(APIError, match="was DELETED but could not be recreated"):
+            svc.recreate("owner/kb-uuid")
+        svc.delete.assert_called_once()  # the dangerous half already happened