doc-store-client-dev 0.1.185__tar.gz

doc_store_client_dev-0.1.185/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,103 @@
+# 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/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=84.2.1", "wheel>=0.48.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "doc-store-client-dev"
+version = "0.1.185"
+description = "Client library for the doc-store documentation service."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Vasiliy Zdanovskiy" }]
+license = "MIT"
+keywords = ["documentation", "client", "search", "json-rpc"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "chunk-metadata-adapter>=3.5.1",
+  "mcp-proxy-adapter>=8.11.11",
+]
+
+[project.scripts]
+doc-store-client = "doc_store_client_cli:main"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=9.2.0,<10",
+  "pytest-asyncio>=1.4.1.post1,<2",
+]
+dev = [
+  "doc-store-client-dev[test]",
+  "ruff>=0.17.4",
+  "mypy>=2.4.1",
+  "build>=1.6.1,<2",
+]
+
+[tool.setuptools]
+include-package-data = true
+py-modules = ["doc_store_client_cli"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["doc_store_client*"]
+exclude = ["tests*", "test_environment*", "logs*"]
+
+[tool.setuptools.package-data]
+doc_store_client = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.mypy]
+python_version = "3.11"
+packages = ["doc_store_client"]
+
+[[tool.mypy.overrides]]
+module = ["chunk_metadata_adapter"]
+ignore_missing_imports = true

doc_store_client_dev-0.1.185/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

doc_store_client_dev-0.1.185/src/doc_store_client/__init__.py

@@ -0,0 +1,194 @@
+"""Public API for the transport-neutral doc-store client package."""
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+from pathlib import Path as _Path
+import tomllib as _tomllib
+
+from .client import (
+    DOC_STORE_COMMANDS,
+    DocStoreClient,
+    DocStoreClientError,
+    DocStoreNotFoundError,
+    FileAlreadyLockedError,
+    LockServiceUnavailableError,
+    SessionNotFoundError,
+)
+from .owned_document_cleanup import OwnedDocumentCleanup, OwnedDocumentCleanupError
+from .text_verification import text_verification_phrase
+from .models import (
+    BackupEmergencyResult,
+    BackupInspectFile,
+    BackupInspectResult,
+    BackupPoint,
+    BackupPointsResult,
+    BackupRecoverCatalogResult,
+    BackupRestoreResult,
+    BackupRunResult,
+    BackupStatusResult,
+    ChapterGetRequest,
+    ChapterGetResult,
+    ChapterTextGetRequest,
+    ChunkHistoryRequest,
+    ChunkHistoryResult,
+    ChunkVersionAddRequest,
+    ChunkVersionAddResult,
+    ChunkVersionDeleteRequest,
+    ChunkVersionDeleteResult,
+    ChunkVersionDiffRequest,
+    ChunkVersionDiffResult,
+    ChunkVersionGetRequest,
+    ChunkVersionGetResult,
+    ChunkVersionItem,
+    ChunkVersionListRequest,
+    ChunkVersionListResult,
+    ChunkVersionRestoreRequest,
+    ChunkVersionRestoreResult,
+    ChunkVersionRetireRequest,
+    ChunkVersionRetireResult,
+    ChunkVersionSetCurrentRequest,
+    ChunkVersionSetCurrentResult,
+    ChunkVersionTextMutationRequest,
+    ChunkVersionUpdateRequest,
+    ChunkVersionUpdateResult,
+    DocumentChunkRequest,
+    DocumentChunkResult,
+    DocumentCreateRequest,
+    DocumentCreateResult,
+    DocumentDeleteRequest,
+    DocumentDeleteResult,
+    DocumentGetRequest,
+    DocumentGetResult,
+    DocumentRebindRequest,
+    DocumentRebindResult,
+    DocumentUpdateRequest,
+    DocumentUpdateResult,
+    DocumentWriteRequest,
+    DocumentWriteResult,
+    EntityGetRequest,
+    EntityGetResult,
+    EntityTextGetRequest,
+    EntityTextGetResult,
+    EntityIdsRequest,
+    EntityLifecycleResult,
+    EntityListRequest,
+    EntityListResult,
+    EntityOwnerTreeRequest,
+    EntityOwnerTreeResult,
+    EntityReferencesRequest,
+    EntityReferencesResult,
+    OperationState,
+    ParagraphGetByNumberRequest,
+    ParagraphGetByNumberResult,
+    ParagraphGetRequest,
+    ParagraphGetResult,
+    ProcessingStatusRequest,
+    ProcessingStatusResult,
+    RankedSearchHit,
+    RetrievalRequest,
+    RetrievalResult,
+    SearchResult,
+    ServerError,
+    SemanticChunkMetadataUpdateRequest,
+    SemanticChunkMetadataUpdateResult,
+    SourceFileReconstructRequest,
+    TextReconstructionRequest,
+    TextReconstructionResult,
+)
+
+try:
+    __version__ = _distribution_version("doc-store-client")
+except _PackageNotFoundError:
+    _pyproject = _Path(__file__).resolve().parents[2] / "pyproject.toml"
+    __version__ = _tomllib.loads(_pyproject.read_text(encoding="utf-8"))["project"]["version"]
+
+# The package includes ``py.typed`` in its distribution metadata.
+__all__ = [
+    "BackupEmergencyResult",
+    "BackupInspectFile",
+    "BackupInspectResult",
+    "BackupPoint",
+    "BackupPointsResult",
+    "BackupRecoverCatalogResult",
+    "BackupRestoreResult",
+    "BackupRunResult",
+    "BackupStatusResult",
+    "ChapterGetRequest",
+    "ChapterGetResult",
+    "ChapterTextGetRequest",
+    "ChunkHistoryRequest",
+    "ChunkHistoryResult",
+    "ChunkVersionAddRequest",
+    "ChunkVersionAddResult",
+    "ChunkVersionDeleteRequest",
+    "ChunkVersionDeleteResult",
+    "ChunkVersionDiffRequest",
+    "ChunkVersionDiffResult",
+    "ChunkVersionGetRequest",
+    "ChunkVersionGetResult",
+    "ChunkVersionItem",
+    "ChunkVersionListRequest",
+    "ChunkVersionListResult",
+    "ChunkVersionRestoreRequest",
+    "ChunkVersionRestoreResult",
+    "ChunkVersionRetireRequest",
+    "ChunkVersionRetireResult",
+    "ChunkVersionSetCurrentRequest",
+    "ChunkVersionSetCurrentResult",
+    "ChunkVersionTextMutationRequest",
+    "ChunkVersionUpdateRequest",
+    "ChunkVersionUpdateResult",
+    "DOC_STORE_COMMANDS",
+    "DocStoreClient",
+    "DocStoreClientError",
+    "DocStoreNotFoundError",
+    "FileAlreadyLockedError",
+    "LockServiceUnavailableError",
+    "SessionNotFoundError",
+    "OwnedDocumentCleanup",
+    "OwnedDocumentCleanupError",
+    "DocumentCreateRequest",
+    "DocumentCreateResult",
+    "DocumentChunkRequest",
+    "DocumentChunkResult",
+    "DocumentDeleteRequest",
+    "DocumentDeleteResult",
+    "DocumentGetRequest",
+    "DocumentGetResult",
+    "DocumentRebindRequest",
+    "DocumentRebindResult",
+    "DocumentUpdateRequest",
+    "DocumentUpdateResult",
+    "DocumentWriteRequest",
+    "DocumentWriteResult",
+    "EntityGetRequest",
+    "EntityGetResult",
+    "EntityTextGetRequest",
+    "EntityTextGetResult",
+    "EntityIdsRequest",
+    "EntityLifecycleResult",
+    "EntityListRequest",
+    "EntityListResult",
+    "EntityOwnerTreeRequest",
+    "EntityOwnerTreeResult",
+    "EntityReferencesRequest",
+    "EntityReferencesResult",
+    "OperationState",
+    "ParagraphGetByNumberRequest",
+    "ParagraphGetByNumberResult",
+    "ParagraphGetRequest",
+    "ParagraphGetResult",
+    "ProcessingStatusRequest",
+    "ProcessingStatusResult",
+    "RankedSearchHit",
+    "RetrievalRequest",
+    "RetrievalResult",
+    "SearchResult",
+    "ServerError",
+    "SemanticChunkMetadataUpdateRequest",
+    "SemanticChunkMetadataUpdateResult",
+    "SourceFileReconstructRequest",
+    "TextReconstructionRequest",
+    "TextReconstructionResult",
+    "text_verification_phrase",
+]