code-analysis-client 1.0.0__tar.gz → 1.0.2__tar.gz

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.0.0
+Version: 1.0.2
 Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: mcp-proxy-adapter>=8.10.12
+Requires-Dist: mcp-proxy-adapter>=8.10.13
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
@@ -91,3 +91,14 @@ From the repository root:
 pip install -e ./client
 pytest tests/test_code_analysis_client.py
 ```
+
+### Releasing to PyPI (version = root ``code-analysis`` project)
+
+The client wheel version is read from ``client/code_analysis_client/version.txt``.
+That file must match ``[project].version`` in the **repository root**
+``pyproject.toml``. Sync before build:
+
+```bash
+python scripts/sync_code_analysis_client_version.py
+cd client && python -m build && twine check dist/* && twine upload dist/*
+```

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/README.md

@@ -79,3 +79,14 @@ From the repository root:
 pip install -e ./client
 pytest tests/test_code_analysis_client.py
 ```
+
+### Releasing to PyPI (version = root ``code-analysis`` project)
+
+The client wheel version is read from ``client/code_analysis_client/version.txt``.
+That file must match ``[project].version`` in the **repository root**
+``pyproject.toml``. Sync before build:
+
+```bash
+python scripts/sync_code_analysis_client_version.py
+cd client && python -m build && twine check dist/* && twine upload dist/*
+```

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/code_analysis_client/__init__.py

@@ -17,6 +17,7 @@ from code_analysis_client.config import (
     load_server_config,
 )
 from code_analysis_client.exceptions import ClientValidationError
+from code_analysis_client.file_session import FileSessionClient, SessionNotFoundError
 from code_analysis_client.server_schema import (
     fetch_command_schema_from_server,
     parse_schema_from_help_payload,
@@ -29,6 +30,8 @@ from code_analysis_client.validation import (
 __all__ = [
     "ClientValidationError",
     "CodeAnalysisAsyncClient",
+    "FileSessionClient",
+    "SessionNotFoundError",
     "ValidatedCommandsProxy",
     "adapter_settings_from_server_config",
     "adapter_settings_to_jsonrpc_kwargs",
@@ -39,6 +42,7 @@ __all__ = [
     "validate_params_against_schema",
 ]
 
+
 def _read_package_version() -> str:
     vf = Path(__file__).resolve().parent / "version.txt"
     if vf.is_file():

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/code_analysis_client/client.py

@@ -21,6 +21,7 @@ from code_analysis_client.config import (
     adapter_settings_to_jsonrpc_kwargs,
     load_server_config,
 )
+from code_analysis_client.file_session import FileSessionClient
 from code_analysis_client.server_schema import fetch_command_schema_from_server
 from code_analysis_client.validation import (
     prepare_params_for_schema,
@@ -119,6 +120,11 @@ class CodeAnalysisAsyncClient:
         """Drop cached command schemas (after ``reload`` or when server definitions change)."""
         self._command_schema_cache.clear()
 
+    @property
+    def file_sessions(self) -> FileSessionClient:
+        """Session-scoped download/upload and lock workflow (no CST/universal edit details)."""
+        return FileSessionClient(self)
+
     async def get_command_schema(
         self, command: str, *, refresh: bool = False
     ) -> Dict[str, Any]:

code_analysis_client-1.0.2/code_analysis_client/file_session.py

@@ -0,0 +1,385 @@
+"""
+High-level file transfer and session workflow on top of CodeAnalysisAsyncClient.
+
+Hides transfer/lock command names behind a small API: create a client session,
+download a project file with an advisory lock, upload changes with unlock, and
+lock/unlock indexed files without moving bytes.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+from code_analysis_client.exceptions import ClientValidationError
+
+if TYPE_CHECKING:
+    from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+class SessionNotFoundError(ClientValidationError):
+    """Raised when session_id is absent from client_sessions."""
+
+
+def _unwrap(data: Dict[str, Any]) -> Dict[str, Any]:
+    if data.get("success"):
+        inner = data.get("data")
+        return inner if isinstance(inner, dict) else data
+    code_raw = data.get("code")
+    message = data.get("message")
+    err = data.get("error")
+    if code_raw is None and isinstance(err, dict):
+        code_raw = err.get("code")
+        if message is None:
+            message = err.get("message")
+    elif code_raw is None and isinstance(err, str):
+        code_raw = err
+    code = str(code_raw or "COMMAND_FAILED")
+    if message is None:
+        message = str(data)
+    if code == "SESSION_NOT_FOUND":
+        raise SessionNotFoundError(message, field="session_id", details=data)
+    raise ClientValidationError(message, field="command", details=data)
+
+
+class FileSessionClient:
+    """Session-scoped file download/upload and lock helpers."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: CodeAnalysisAsyncClient) -> None:
+        self._client = client
+
+    async def create_session(
+        self,
+        comment: str,
+        *,
+        role_ids: Optional[List[str]] = None,
+    ) -> str:
+        """Create a client session (``session_create``) and return ``session_id``."""
+        params: Dict[str, Any] = {"comment": comment}
+        if role_ids is not None:
+            params["role_ids"] = role_ids
+        payload = _unwrap(await self._client.call_validated("session_create", params))
+        sid = str(payload.get("session_id") or "").strip()
+        if not sid:
+            raise ClientValidationError(
+                "session_create returned no session_id",
+                field="session_id",
+                details=payload,
+            )
+        return sid
+
+    async def assert_session_exists(self, session_id: str) -> None:
+        """Verify ``session_id`` is registered (touch via ``session_list_file_locks``)."""
+        sid = str(session_id).strip()
+        if not sid:
+            raise ClientValidationError("session_id is required", field="session_id")
+        _unwrap(
+            await self._client.call_validated(
+                "session_list_file_locks",
+                {"session_id": sid},
+            )
+        )
+
+    async def delete_session(
+        self, session_id: str, *, force: bool = False
+    ) -> Dict[str, Any]:
+        """Delete a client session (``session_delete``)."""
+        return _unwrap(
+            await self._client.call_validated(
+                "session_delete",
+                {"session_id": session_id, "force": force},
+            )
+        )
+
+    async def list_sessions(
+        self,
+        *,
+        session_id: Optional[str] = None,
+        stale_threshold_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """List client sessions (``session_list``)."""
+        params: Dict[str, Any] = {}
+        if session_id is not None:
+            params["session_id"] = session_id
+        if stale_threshold_seconds is not None:
+            params["stale_threshold_seconds"] = stale_threshold_seconds
+        return _unwrap(await self._client.call_validated("session_list", params))
+
+    async def lock_file(
+        self,
+        session_id: str,
+        project_id: str,
+        file_id: str,
+    ) -> Dict[str, Any]:
+        """Acquire a DB file lock without transfer (``session_open_file``)."""
+        await self.assert_session_exists(session_id)
+        return _unwrap(
+            await self._client.call_validated(
+                "session_open_file",
+                {
+                    "session_id": session_id,
+                    "project_id": project_id,
+                    "file_id": file_id,
+                },
+            )
+        )
+
+    async def unlock_file(
+        self,
+        session_id: str,
+        project_id: str,
+        file_id: str,
+    ) -> Dict[str, Any]:
+        """Release a DB file lock without transfer (``session_close_file``)."""
+        await self.assert_session_exists(session_id)
+        return _unwrap(
+            await self._client.call_validated(
+                "session_close_file",
+                {
+                    "session_id": session_id,
+                    "project_id": project_id,
+                    "file_id": file_id,
+                },
+            )
+        )
+
+    async def list_file_locks(self, session_id: str) -> Dict[str, Any]:
+        """Return locks held by the session (``session_list_file_locks``)."""
+        return _unwrap(
+            await self._client.call_validated(
+                "session_list_file_locks",
+                {"session_id": session_id},
+            )
+        )
+
+    async def lock_files_advisory(
+        self,
+        session_id: str,
+        project_id: str,
+        file_paths: List[str],
+        *,
+        lock_mode: str = "full",
+        timeout_seconds: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Cooperative flock + DB lease for paths (``project_file_advisory_lock_batch``)."""
+        await self.assert_session_exists(session_id)
+        items = [
+            {
+                "session_id": session_id,
+                "project_id": project_id,
+                "file_path": path,
+                "action": "lock",
+                "lock_mode": lock_mode,
+            }
+            for path in file_paths
+        ]
+        params: Dict[str, Any] = {
+            "items": items,
+            "allow_foreign_session": True,
+        }
+        if timeout_seconds is not None:
+            params["timeout_seconds"] = timeout_seconds
+        return _unwrap(
+            await self._client.call_validated(
+                "project_file_advisory_lock_batch",
+                params,
+            )
+        )
+
+    async def unlock_files_advisory(
+        self,
+        session_id: str,
+        project_id: str,
+        file_paths: List[str],
+    ) -> Dict[str, Any]:
+        """Release cooperative locks without transfer."""
+        await self.assert_session_exists(session_id)
+        items = [
+            {
+                "session_id": session_id,
+                "project_id": project_id,
+                "file_path": path,
+                "action": "unlock",
+            }
+            for path in file_paths
+        ]
+        return _unwrap(
+            await self._client.call_validated(
+                "project_file_advisory_lock_batch",
+                {
+                    "items": items,
+                    "allow_foreign_session": True,
+                },
+            )
+        )
+
+    async def begin_download_locked(
+        self,
+        session_id: str,
+        *,
+        project_id: Optional[str] = None,
+        file_id: Optional[str] = None,
+        file_path: Optional[str] = None,
+        compression: str = "identity",
+        lock_mode: str = "full",
+        chunk_size: Optional[int] = None,
+        include_backup_history: bool = False,
+    ) -> Dict[str, Any]:
+        """Start a chunked download and acquire an advisory lock (``project_file_transfer_download_begin``)."""
+        await self.assert_session_exists(session_id)
+        params: Dict[str, Any] = {
+            "session_id": session_id,
+            "compression": compression,
+            "lock_mode": lock_mode,
+            "include_backup_history": include_backup_history,
+        }
+        if project_id is not None:
+            params["project_id"] = project_id
+        if file_id is not None:
+            params["file_id"] = file_id
+        if file_path is not None:
+            params["file_path"] = file_path
+        if chunk_size is not None:
+            params["chunk_size"] = chunk_size
+        return _unwrap(
+            await self._client.call_validated(
+                "project_file_transfer_download_begin",
+                params,
+            )
+        )
+
+    async def download_to_path(
+        self,
+        transfer_id: str,
+        destination: Union[str, Path],
+    ) -> Any:
+        """Stream download chunks to ``destination`` via the adapter client."""
+        return await self._client.rpc.download_file(
+            str(transfer_id).strip(),
+            str(destination),
+        )
+
+    async def download_file_locked(
+        self,
+        session_id: str,
+        destination: Union[str, Path],
+        *,
+        project_id: Optional[str] = None,
+        file_id: Optional[str] = None,
+        file_path: Optional[str] = None,
+        compression: str = "identity",
+        lock_mode: str = "full",
+    ) -> Tuple[Dict[str, Any], Any]:
+        """Download + lock in one workflow; returns (begin_payload, download_receipt)."""
+        begin = await self.begin_download_locked(
+            session_id,
+            project_id=project_id,
+            file_id=file_id,
+            file_path=file_path,
+            compression=compression,
+            lock_mode=lock_mode,
+        )
+        transfer_id = str(begin.get("transfer_id") or "").strip()
+        if not transfer_id:
+            raise ClientValidationError(
+                "download begin returned no transfer_id",
+                field="transfer_id",
+                details=begin,
+            )
+        receipt = await self.download_to_path(transfer_id, destination)
+        return begin, receipt
+
+    async def upload_bytes(
+        self,
+        payload: bytes,
+        *,
+        filename: str,
+        compression: str = "identity",
+    ) -> Any:
+        """Upload raw bytes through the adapter buffer; returns upload receipt."""
+        dest = Path(filename)
+        dest.write_bytes(payload)
+        try:
+            return await self._client.rpc.upload_file(
+                str(dest),
+                filename=filename,
+                compression=compression,
+            )
+        finally:
+            if dest.is_file():
+                dest.unlink(missing_ok=True)
+
+    async def save_upload_and_unlock(
+        self,
+        session_id: str,
+        transfer_id: str,
+        *,
+        project_id: Optional[str] = None,
+        file_id: Optional[str] = None,
+        file_path: Optional[str] = None,
+        unlock_after_write: bool = True,
+        dry_run: bool = False,
+        backup: bool = True,
+    ) -> Dict[str, Any]:
+        """Persist uploaded buffer and release locks (``project_file_transfer_upload_save``)."""
+        await self.assert_session_exists(session_id)
+        params: Dict[str, Any] = {
+            "session_id": session_id,
+            "transfer_id": transfer_id,
+            "unlock_after_write": unlock_after_write,
+            "dry_run": dry_run,
+            "backup": backup,
+        }
+        if project_id is not None:
+            params["project_id"] = project_id
+        if file_id is not None:
+            params["file_id"] = file_id
+        if file_path is not None:
+            params["file_path"] = file_path
+        return _unwrap(
+            await self._client.call_validated(
+                "project_file_transfer_upload_save",
+                params,
+            )
+        )
+
+    async def upload_file_and_unlock(
+        self,
+        session_id: str,
+        payload: bytes,
+        *,
+        project_id: Optional[str] = None,
+        file_id: Optional[str] = None,
+        file_path: Optional[str] = None,
+        filename: Optional[str] = None,
+        compression: str = "identity",
+        unlock_after_write: bool = True,
+        backup: bool = True,
+    ) -> Dict[str, Any]:
+        """Upload bytes then save to the project file and unlock."""
+        name = filename or (Path(file_path).name if file_path else "payload.bin")
+        receipt = await self.upload_bytes(
+            payload,
+            filename=name,
+            compression=compression,
+        )
+        if not getattr(receipt, "completed", False):
+            raise ClientValidationError(
+                "upload did not complete",
+                field="transfer_id",
+                details={"receipt": repr(receipt)},
+            )
+        return await self.save_upload_and_unlock(
+            session_id,
+            str(receipt.transfer_id),
+            project_id=project_id,
+            file_id=file_id,
+            file_path=file_path,
+            unlock_after_write=unlock_after_write,
+            backup=backup,
+        )

code_analysis_client-1.0.2/code_analysis_client/version.txt

@@ -0,0 +1 @@
+1.0.2

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/code_analysis_client.egg-info/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.0.0
+Version: 1.0.2
 Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: mcp-proxy-adapter>=8.10.12
+Requires-Dist: mcp-proxy-adapter>=8.10.13
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
@@ -91,3 +91,14 @@ From the repository root:
 pip install -e ./client
 pytest tests/test_code_analysis_client.py
 ```
+
+### Releasing to PyPI (version = root ``code-analysis`` project)
+
+The client wheel version is read from ``client/code_analysis_client/version.txt``.
+That file must match ``[project].version`` in the **repository root**
+``pyproject.toml``. Sync before build:
+
+```bash
+python scripts/sync_code_analysis_client_version.py
+cd client && python -m build && twine check dist/* && twine upload dist/*
+```

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/code_analysis_client.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ code_analysis_client/client.py
 code_analysis_client/commands_proxy.py
 code_analysis_client/config.py
 code_analysis_client/exceptions.py
+code_analysis_client/file_session.py
 code_analysis_client/py.typed
 code_analysis_client/server_schema.py
 code_analysis_client/validation.py

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/code_analysis_client.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mcp-proxy-adapter>=8.10.12
+mcp-proxy-adapter>=8.10.13
 
 [dev]
 pytest>=8.0

{code_analysis_client-1.0.0 → code_analysis_client-1.0.2}/pyproject.toml

@@ -12,7 +12,7 @@ authors = [
     { name = "Vasiliy Zdanovskiy", email = "vasilyvz@gmail.com" },
 ]
 dependencies = [
-    "mcp-proxy-adapter>=8.10.12",
+    "mcp-proxy-adapter>=8.10.13",
 ]
 
 [project.optional-dependencies]

code_analysis_client-1.0.0/code_analysis_client/version.txt

@@ -1 +0,0 @@
-1.0.0