doc-store-client-dev 0.1.185__py3-none-any.whl

doc_store_client/owned_document_cleanup.py

@@ -0,0 +1,143 @@
+"""Ownership-scoped cleanup for documents created by a single verification run."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Protocol
+from uuid import UUID
+
+from .client import DocStoreClientError
+from .models import (
+    DocumentDeleteRequest,
+    DocumentDeleteResult,
+    DocumentGetRequest,
+    DocumentGetResult,
+)
+
+
+class OwnedDocumentCleanupError(RuntimeError):
+    """A verification fixture could not be removed through the public API."""
+
+
+class OwnedDocumentClient(Protocol):
+    """The narrow public-client surface required for owned fixture cleanup."""
+
+    async def get_document(self, request: DocumentGetRequest) -> DocumentGetResult:
+        """Read a document and its current mutation token."""
+
+    async def delete_document(
+        self, request: DocumentDeleteRequest, *, session_id: str | None = None
+    ) -> DocumentDeleteResult:
+        """Delete a document through the typed public command."""
+
+
+def _exact_uuid4(document_id: str) -> str:
+    """Return one canonical UUID4, refusing non-document identifiers early."""
+
+    try:
+        parsed = UUID(document_id)
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise ValueError("owned document id must be a UUID4") from exc
+    if parsed.version != 4:
+        raise ValueError("owned document id must be a UUID4")
+    return str(parsed)
+
+
+def _is_exact_not_found(error: DocStoreClientError, document_id: str) -> bool:
+    """Accept only an absence result bound to the document just deleted."""
+
+    server_error = error.error
+    details = server_error.details
+    detail_document_id: object | None = None
+    if isinstance(details, Mapping) and "document_id" in details:
+        detail_document_id = details["document_id"]
+        if detail_document_id != document_id:
+            return False
+
+    exact_message = f"NOT_FOUND: {document_id}"
+    if server_error.code == "NOT_FOUND":
+        return detail_document_id == document_id or server_error.message == exact_message
+    return server_error.code == "SERVER_ERROR" and server_error.message == exact_message
+
+
+@dataclass
+class OwnedDocumentCleanup:
+    """Track and delete only UUID4 documents created by this caller.
+
+    ``DocStoreClient`` resolves queued adapter delivery before it returns a typed
+    result.  Consequently this helper accepts only terminal ``deleted`` or
+    ``already_absent`` outcomes and rejects a queue acknowledgement as a
+    cleanup success.
+    """
+
+    client: OwnedDocumentClient
+    _owned_document_ids: set[str] = field(default_factory=set, init=False, repr=False)
+
+    @property
+    def owned_document_ids(self) -> tuple[str, ...]:
+        """Return the remaining owned IDs in deterministic order."""
+
+        return tuple(sorted(self._owned_document_ids))
+
+    def register(self, document_id: str) -> None:
+        """Register the exact UUID4 returned by this caller's successful create."""
+
+        self._owned_document_ids.add(_exact_uuid4(document_id))
+
+    async def cleanup(
+        self, document_id: str, *, session_id: str | None = None
+    ) -> DocumentDeleteResult:
+        """Delete one owned document and prove its public readback is absent."""
+
+        exact_id = _exact_uuid4(document_id)
+        if exact_id not in self._owned_document_ids:
+            raise PermissionError(f"refusing to clean up unowned document {exact_id}")
+
+        current = await self.client.get_document(DocumentGetRequest(document_id=exact_id))
+        if current.source_version is None:
+            raise OwnedDocumentCleanupError(
+                f"owned document {exact_id} has no current source_version for deletion"
+            )
+
+        delete_request = DocumentDeleteRequest(
+            document_id=exact_id,
+            version_token=str(current.source_version),
+        )
+        if session_id is None:
+            result = await self.client.delete_document(delete_request)
+        else:
+            result = await self.client.delete_document(delete_request, session_id=session_id)
+        if result.document_id != exact_id:
+            raise OwnedDocumentCleanupError(
+                f"document_delete returned {result.document_id!r} for owned {exact_id!r}"
+            )
+        if result.outcome not in {"deleted", "already_absent"}:
+            raise OwnedDocumentCleanupError(
+                f"document_delete did not reach a terminal outcome for {exact_id}: {result.outcome!r}"
+            )
+
+        try:
+            await self.client.get_document(DocumentGetRequest(document_id=exact_id))
+        except DocStoreClientError as exc:
+            if _is_exact_not_found(exc, exact_id):
+                self._owned_document_ids.remove(exact_id)
+                return result
+            raise OwnedDocumentCleanupError(
+                f"document_get failed after deleting owned {exact_id}: {exc}"
+            ) from exc
+        raise OwnedDocumentCleanupError(
+            f"owned document {exact_id} is still readable after document_delete"
+        )
+
+    async def cleanup_all(self, *, session_id: str | None = None) -> None:
+        """Attempt every owned cleanup and propagate every failure as one error."""
+
+        failures: list[str] = []
+        for document_id in self.owned_document_ids:
+            try:
+                await self.cleanup(document_id, session_id=session_id)
+            except Exception as exc:
+                failures.append(f"{document_id}: {exc}")
+        if failures:
+            raise OwnedDocumentCleanupError("; ".join(failures))

doc_store_client/text_verification.py

@@ -0,0 +1,21 @@
+"""Short deterministic phrases for verifying received text payloads."""
+
+from __future__ import annotations
+
+from hashlib import sha256
+
+_VERIFICATION_VERSION = "rx1"
+_DIGEST_HEX_CHARS = 24
+
+
+def text_verification_phrase(text: str) -> str:
+    """Return a short fingerprint of the exact UTF-8 text received by a command."""
+
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+    payload = text.encode("utf-8")
+    digest = sha256(payload).hexdigest()[:_DIGEST_HEX_CHARS]
+    return f"{_VERIFICATION_VERSION}:{len(payload)}:{digest}"
+
+
+__all__ = ["text_verification_phrase"]

doc_store_client_cli.py

@@ -0,0 +1,16 @@
+"""Installed console entrypoint kept dependency-light for --help and discovery."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+_CLI_PATH = Path(__file__).with_name("doc_store_client") / "cli.py"
+_SPEC = importlib.util.spec_from_file_location("_doc_store_client_cli", _CLI_PATH)
+if _SPEC is None or _SPEC.loader is None:
+    raise ImportError(f"Unable to load CLI implementation: {_CLI_PATH}")
+_MODULE = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(_MODULE)
+main = _MODULE.main
+

doc_store_client_dev-0.1.185.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: doc-store-client-dev
+Version: 0.1.185
+Summary: Client library for the doc-store documentation service.
+Author: Vasiliy Zdanovskiy
+License-Expression: MIT
+Keywords: documentation,client,search,json-rpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chunk-metadata-adapter>=3.5.1
+Requires-Dist: mcp-proxy-adapter>=8.11.11
+Provides-Extra: test
+Requires-Dist: pytest<10,>=9.2.0; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=1.4.1.post1; extra == "test"
+Provides-Extra: dev
+Requires-Dist: doc-store-client-dev[test]; extra == "dev"
+Requires-Dist: ruff>=0.17.4; extra == "dev"
+Requires-Dist: mypy>=2.4.1; extra == "dev"
+Requires-Dist: build<2,>=1.6.1; extra == "dev"
+
+# doc-store-client backup methods
+
+`DocStoreClient` exposes typed wrappers for the six backup commands supported by the server:
+
+| Method | Required arguments | Result type |
+| --- | --- | --- |
+| `backup_run` | None | `BackupRunResult` |
+| `backup_status` | None | `BackupStatusResult` |
+| `backup_points` | None | `BackupPointsResult` |
+| `backup_inspect` | `point` | `BackupInspectResult` |
+| `backup_restore` | `point` | `BackupRestoreResult` |
+| `backup_recover_catalog` | `destination`, `catalog_copy` | `BackupRecoverCatalogResult` |
+
+All six methods accept the optional `catalog_directory`. `backup_run` and `backup_restore` also
+accept `dry_run`; `backup_restore` accepts `replace`; `backup_recover_catalog` accepts `dry_run`.
+Omitted options remain absent from the command payload, allowing server configuration and command
+defaults to apply. Passing `catalog_directory=None` explicitly sends JSON null, which the server
+defines as unspecified. Boolean defaults are false on the server.
+
+The methods return the command's `data` object using the corresponding public `TypedDict` result
+type. In particular, `backup_points` includes committed points only, `backup_inspect` describes
+the requested saved point and its chain, and `backup_recover_catalog` reports `activated=False`:
+catalog recovery creates a separate catalog and never switches the active catalog.
+
+Queued commands (`backup_run`, `backup_restore`, and `backup_recover_catalog`) use the injected
+adapter's normal delivery and final-result handling. The client does not submit a second command
+or poll the queue a second time. Synchronous commands (`backup_status`, `backup_points`, and
+`backup_inspect`) return their result directly.
+
+Server parameter and backup-domain errors are surfaced through the adapter response. When an
+error response is represented by the standard client envelope, `DocStoreClientError.error`
+contains a `ServerError` with its code, message, and details. Adapter transport exceptions
+continue to propagate from the adapter. The wrappers do not convert failures into success-shaped
+results.
+
+Use `DocStoreClient.call(command, params)` when a caller needs to exercise invalid parameters or
+send a command that has no typed wrapper. The typed methods describe the valid command inputs;
+the server remains responsible for validating values and path relationships.
+
+## Write sessions and lock errors
+
+The 18 raw methods `document_create`, `document_update`, `document_delete`, `document_rebind`,
+`document_chunk`, `chunk_version_add`, `chunk_version_update`, `chunk_version_set_current`,
+`chunk_version_restore`, `chunk_version_retire`, `chunk_version_delete`,
+`semantic_chunk_metadata_update`, `entity_create`, `entity_update`, `entity_rebind_owner`,
+`entity_soft_delete`, `entity_undelete` and `entity_hard_delete`, and the 15 typed wrappers
+`create_document`, `update_document`, `delete_document`, `rebind_document`, `chunk_document`,
+`add_chunk_version`, `update_chunk_version`, `set_current_chunk_version`,
+`restore_chunk_version`, `retire_chunk_version`, `delete_chunk_version`, `soft_delete_entities`,
+`undelete_entities`, `hard_delete_entities` and `update_semantic_chunk_metadata`, take a
+keyword-only `session_id` with default `None`. `None` is not sent; any other value is sent
+unchanged. The client does not check the format; the server refuses a malformed value with
+-32602, raised by the adapter. A raw method given `session_id` as a keyword and inside `params`
+raises `ValueError` (`duplicate parameters: session_id`).
+
+`DocStoreClient` keeps no session, so pass `session_id` on every call, and repeat a CAS write-back
+with the same `session_id`. `DocStoreClient.call` passes a `session_id` inside `params` unchanged,
+the CLI takes `session_id` inside the `--params` JSON object (there is no extra flag), and
+`OwnedDocumentCleanup.cleanup` and `cleanup_all` take `session_id` and pass it to every
+`document_delete`. `cleanup_all` collects failures into one `OwnedDocumentCleanupError`; call
+`cleanup` per document to catch a typed lock error.
+
+`document_export` and every other non-gated method take no `session_id`; a `session_id` sent to
+them through `params` is refused by the server with -32602.
+
+A refused write raises one of three errors, all subclasses of `DocStoreClientError` and importable
+from `doc_store_client`:
+
+| class | code | properties |
+| --- | --- | --- |
+| `FileAlreadyLockedError` | `FILE_ALREADY_LOCKED` | `document_id`, `holder_session_id`, `holder_idle_seconds`, `seconds_left_before_timeout` |
+| `SessionNotFoundError` | `SESSION_NOT_FOUND` | `session_id` |
+| `LockServiceUnavailableError` | `LOCK_SERVICE_UNAVAILABLE` | `reason` |
+
+`error.code` and the message are kept. A missing field reads as `None`. Values come from the
+`data` mapping in `error.details`, else from `error.details`. A refused write changes nothing on
+the server. A failed queued `document_create` or `document_update` job with a lock code raises the
+typed error as well.
+
+The client never retries a refused write. React to each error yourself:
+
+- `FileAlreadyLockedError`: another session holds the document. Do not retry blindly; use
+  `holder_idle_seconds` and `seconds_left_before_timeout` to decide when to try again.
+- `SessionNotFoundError`: the session is unknown or expired. Open a new CAS session and repeat the
+  call with its id.
+- `LockServiceUnavailableError`: CAS did not answer or answered with an error, and the write was
+  refused. Retry later by your own decision; `reason` says why.
+
+## Missing target
+
+A command whose target does not exist (a document, chapter, paragraph, chunk, entity) is answered
+by the server with a structured error whose code is `NOT_FOUND` and whose message contains the
+missing id. The client raises `DocStoreNotFoundError`, a subclass of `DocStoreClientError`
+importable from `doc_store_client`:
+
+| class | code | properties |
+| --- | --- | --- |
+| `DocStoreNotFoundError` | `NOT_FOUND` | `code`, `missing_id` |
+
+`str(error)` is the server message (it contains the id), so callers that read the text keep
+working; `error.error.code` is `NOT_FOUND`. `missing_id` is read from the error data, else from the
+id in the message, else `None`. `entity_content_get` does not raise: it reports an absent id as an
+item with `error.code` `NOT_FOUND`.

doc_store_client_dev-0.1.185.dist-info/RECORD

@@ -0,0 +1,13 @@
+doc_store_client_cli.py,sha256=iXj4Ohif4SRb5PDJcrSeBWqt62xOQOlKFMRGLQ8kOdM,539
+doc_store_client/__init__.py,sha256=zIz7kfZNSwyrg3Mw-7soPTI7sy6AxveB0GMsLDkNwY4,5557
+doc_store_client/cli.py,sha256=IGRSVUiRxXBJvEOSevqPwtmk2N2DRcpUz-1EosPFFVA,7108
+doc_store_client/client.py,sha256=JliKYkDJL3E5MVGEc7BT_wbEWTLXkiUzSjKJKFeZgx0,53524
+doc_store_client/models.py,sha256=6qFNLA0fYSWbKGJJmZnyEViN5DkJQ5UVmzpM_ZRNihU,56172
+doc_store_client/owned_document_cleanup.py,sha256=KoaVdzuyza-WFALR-3JOSRYfZgHxo1mLH8vgEP8ZTwE,5552
+doc_store_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+doc_store_client/text_verification.py,sha256=B0n5RH8U23DE56qgQvWHLBQALqGtiPFZ7qf44_4TQM4,607
+doc_store_client_dev-0.1.185.dist-info/METADATA,sha256=IAe7ROhOHPTbqY1F5vqUV5-sO2hRKjgltGd3qgJheCs,7514
+doc_store_client_dev-0.1.185.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+doc_store_client_dev-0.1.185.dist-info/entry_points.txt,sha256=wchMyRXsuJAC6Ajt07CFkjQBGgfYb2ET16sVXRBqrFI,63
+doc_store_client_dev-0.1.185.dist-info/top_level.txt,sha256=MC4GKF-Wn-7Yanr8iePj-77t5NS0UPsr25IzdLp7JaA,38
+doc_store_client_dev-0.1.185.dist-info/RECORD,,

doc_store_client_dev-0.1.185.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

doc_store_client_dev-0.1.185.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+doc-store-client = doc_store_client_cli:main

doc_store_client_dev-0.1.185.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+doc_store_client
+doc_store_client_cli