kotharcomputing 0.96.0__tar.gz → 0.98.0__tar.gz

{kotharcomputing-0.96.0/src/kotharcomputing.egg-info → kotharcomputing-0.98.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kotharcomputing
-Version: 0.96.0
+Version: 0.98.0
 Summary: Python SDK for the Kothar API
 Author: Kothar Computing
 License-Expression: Apache-2.0

{kotharcomputing-0.96.0 → kotharcomputing-0.98.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kotharcomputing"
-version = "0.96.0"
+version = "0.98.0"
 description = "Python SDK for the Kothar API"
 readme = "README.md"
 requires-python = ">=3.11"

{kotharcomputing-0.96.0 → kotharcomputing-0.98.0}/src/kotharcomputing/__init__.py

@@ -109,7 +109,11 @@ from .files import (
 from .jobs import (
     CreateJobArgs,
     Job,
+    JobLaunchInstructionCommand,
+    JobLaunchInstructionMethod,
+    JobLaunchInstructions,
     JobStatus,
+    JobUploadedFile,
     UpdateJobArgs,
 )
 from .service_prices import ServicePrice
@@ -246,7 +250,11 @@ __all__ = [
     # Jobs
     "CreateJobArgs",
     "Job",
+    "JobLaunchInstructionCommand",
+    "JobLaunchInstructionMethod",
+    "JobLaunchInstructions",
     "JobStatus",
+    "JobUploadedFile",
     "UpdateJobArgs",
     # Service Prices
     "ServicePrice",

{kotharcomputing-0.96.0 → kotharcomputing-0.98.0}/src/kotharcomputing/files.py

@@ -51,6 +51,7 @@ class FileContent:
     data: bytes
     file_name: str
     etag: str | None = None
+    version_id: str | None = None
     mime_type: str | None = None
 
     def text(self, encoding: str = "utf-8") -> str:
@@ -63,6 +64,11 @@ class FileByPathClient:
         self._workspace_id = workspace_id
         self._path = path
 
+    def version(self, version_id: str) -> "FileByPathVersionClient":
+        return FileByPathVersionClient(
+            self._transport, self._workspace_id, self._path, version_id
+        )
+
     def get(self, *, etag: str | None = None) -> FileContent | None:
         response = self._transport.raw(
             "get",
@@ -80,6 +86,7 @@ class FileByPathClient:
             data=response.body,
             file_name=file_name,
             etag=response.headers.get("etag"),
+            version_id=response.headers.get("x-kothar-file-version-id"),
             mime_type=response.headers.get("content-type"),
         )
 
@@ -93,11 +100,14 @@ class FileByPathClient:
             search_params={"asFolder": as_folder},
             body=content,
         )
-        return {"etag": response.headers.get("etag")}
+        return {
+            "etag": response.headers.get("etag"),
+            "version_id": response.headers.get("x-kothar-file-version-id"),
+        }
 
     def update(
         self, *, content: bytes | str, etag: str | None = None
-    ) -> dict[str, str]:
+    ) -> dict[str, str | None]:
         response = self._transport.raw(
             "put",
             "v1/workspaces/:workspaceId/files/:filePath",
@@ -114,7 +124,10 @@ class FileByPathClient:
                     "status": response.status,
                 },
             )
-        return {"etag": response_etag}
+        return {
+            "etag": response_etag,
+            "version_id": response.headers.get("x-kothar-file-version-id"),
+        }
 
     def download_url(self) -> str:
         payload = cast(
@@ -127,6 +140,15 @@ class FileByPathClient:
         )
         return payload["url"]
 
+    def restore(self, version_id: str) -> dict[str, str | None]:
+        response = self._transport.raw(
+            "post",
+            "v1/workspaces/:workspaceId/files/$restore",
+            path_params={"workspaceId": self._workspace_id},
+            json_data={"path": self._path, "versionId": version_id},
+        )
+        return {"version_id": response.headers.get("x-kothar-file-version-id")}
+
     def move(self, target_path: str) -> None:
         self._transport.raw(
             "post",
@@ -155,6 +177,49 @@ class FileByPathClient:
         )
 
 
+class FileByPathVersionClient:
+    def __init__(
+        self, transport: ApiTransport, workspace_id: str, path: str, version_id: str
+    ) -> None:
+        self._transport = transport
+        self._workspace_id = workspace_id
+        self._path = path
+        self._version_id = version_id
+
+    def get(self, *, etag: str | None = None) -> FileContent | None:
+        response = self._transport.raw(
+            "get",
+            "v1/workspaces/:workspaceId/files/:filePath",
+            path_params={"workspaceId": self._workspace_id, "filePath": self._path},
+            search_params={"versionId": self._version_id},
+            headers={"if-none-match": etag} if etag else None,
+        )
+
+        if response.status == 304:
+            return None
+
+        content_disposition = response.headers.get("content-disposition", "")
+        file_name = extract_filename(content_disposition) or self._path.split("/")[-1]
+        return FileContent(
+            data=response.body,
+            file_name=file_name,
+            etag=response.headers.get("etag"),
+            version_id=response.headers.get("x-kothar-file-version-id"),
+            mime_type=response.headers.get("content-type"),
+        )
+
+    def download_url(self) -> str:
+        payload = cast(
+            dict[str, str],
+            self._transport.get_json(
+                "v1/workspaces/:workspaceId/files/$downloadUrl",
+                path_params={"workspaceId": self._workspace_id},
+                search_params={"path": self._path, "versionId": self._version_id},
+            ),
+        )
+        return payload["url"]
+
+
 class FilesClient:
     def __init__(self, transport: ApiTransport, workspace_id: str) -> None:
         self._transport = transport

{kotharcomputing-0.96.0 → kotharcomputing-0.98.0}/src/kotharcomputing/jobs.py

@@ -15,10 +15,25 @@ JobStatus: TypeAlias = Literal[
 ]
 
 
+class JobDependency(TypedDict):
+    path: str
+    versionId: NotRequired[str]
+    source: Literal["explicit", "detected"]
+
+
+class JobUploadedFile(TypedDict):
+    path: str
+    kind: Literal["file", "archive"]
+    action: Literal["created", "modified"]
+    hash: str
+    versionId: NotRequired[str]
+
+
 class Job(WithUser, WithAgent):
     id: str
     workspaceId: str
     path: str
+    versionId: NotRequired[str]
     status: JobStatus
     createdAt: str
     isTerminated: bool
@@ -32,13 +47,34 @@ class Job(WithUser, WithAgent):
     finishedAt: NotRequired[str]
     duration: NotRequired[str]
     lastPing: NotRequired[str]
+    launchInstructions: NotRequired[JobLaunchInstructions]
     consumedCredits: NotRequired[float]
     data: NotRequired[JSONValue]
+    uploadedFiles: NotRequired[list[JobUploadedFile]]
+    dependencies: NotRequired[list[JobDependency]]
+
+
+class JobLaunchInstructions(TypedDict):
+    launchJobBefore: str
+    methods: list[JobLaunchInstructionMethod]
+
+
+class JobLaunchInstructionMethod(TypedDict):
+    id: str
+    label: str
+    instructionMarkdown: str
+    commands: list[JobLaunchInstructionCommand]
+
+
+class JobLaunchInstructionCommand(TypedDict):
+    label: str
+    command: str
 
 
 class CreateJobArgs(TypedDict):
     agentId: str
     path: str
+    versionId: NotRequired[str]
     runtimeId: NotRequired[str]
     name: NotRequired[str]
     notes: NotRequired[str]

{kotharcomputing-0.96.0 → kotharcomputing-0.98.0/src/kotharcomputing.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kotharcomputing
-Version: 0.96.0
+Version: 0.98.0
 Summary: Python SDK for the Kothar API
 Author: Kothar Computing
 License-Expression: Apache-2.0

kotharcomputing-0.98.0/tests/test_fetch_url_building.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+from urllib import parse as urllib_parse
+
+import pytest
+
+SRC_DIR = Path(__file__).resolve().parents[1] / "src"
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+from kotharcomputing.fetch import ApiTransport, RawResponse
+from kotharcomputing.files import FileByPathClient
+
+
+def test_build_url_encodes_path_params_and_bool_query_values() -> None:
+    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
+
+    url = transport.build_url(
+        "v1/workspaces/:workspaceId/files/:filePath",
+        path_params={"workspaceId": "personal", "filePath": "folder/hello world.txt"},
+        search_params={"withUsernames": True, "limit": 25},
+    )
+
+    assert (
+        url
+        == "https://api.example.com/v1/workspaces/personal/files/folder%2Fhello%20world.txt?withUsernames=true&limit=25"
+    )
+
+
+def test_build_url_expands_list_query_params_and_skips_none_values() -> None:
+    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
+
+    url = transport.build_url(
+        "v1/users/me/credits/transactions",
+        search_params={
+            "references": ["job-1", "job-2"],
+            "active": False,
+            "next": None,
+        },
+    )
+
+    query_pairs = urllib_parse.parse_qsl(
+        urllib_parse.urlsplit(url).query, keep_blank_values=True
+    )
+    assert query_pairs == [
+        ("references", "job-1"),
+        ("references", "job-2"),
+        ("active", "false"),
+    ]
+
+
+def test_build_url_preserves_existing_query_and_appends_new_params() -> None:
+    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
+
+    url = transport.build_url(
+        "v1/jobs?next=cursor-1",
+        search_params={"withAgents": True},
+    )
+
+    assert (
+        url == "https://api.example.com/v1/jobs?next=cursor-1&withAgents=true"
+    )
+
+
+def test_build_url_rejects_absolute_url_outside_base_url() -> None:
+    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
+
+    with pytest.raises(ValueError, match="does not start with the base URL"):
+        transport.build_url(
+            "https://malicious.example.com/v1/jobs",
+            absolute_url=True,
+        )
+
+
+def test_files_client_sends_version_id_for_versioned_download_url() -> None:
+    class Transport:
+        def __init__(self) -> None:
+            self.calls: list[object] = []
+
+        def get_json(
+            self,
+            templated_url: str,
+            *,
+            path_params: object | None = None,
+            search_params: object | None = None,
+            headers: object | None = None,
+        ) -> object:
+            self.calls.append(
+                {
+                    "templated_url": templated_url,
+                    "path_params": path_params,
+                    "search_params": search_params,
+                    "headers": headers,
+                }
+            )
+            return {"url": "https://api.example.com/download"}
+
+    transport = Transport()
+    client = FileByPathClient(transport, "workspace", "folder/file.txt")  # type: ignore[arg-type]
+
+    url = client.version("version+1").download_url()
+
+    assert url == "https://api.example.com/download"
+    assert transport.calls == [
+        {
+            "templated_url": "v1/workspaces/:workspaceId/files/$downloadUrl",
+            "path_params": {"workspaceId": "workspace"},
+            "search_params": {
+                "path": "folder/file.txt",
+                "versionId": "version+1",
+            },
+            "headers": None,
+        }
+    ]
+
+
+def test_files_client_exposes_resolved_version_id_from_get_header() -> None:
+    class Transport:
+        def raw(
+            self,
+            method: str,
+            templated_url: str,
+            *,
+            path_params: object | None = None,
+            headers: object | None = None,
+        ) -> RawResponse:
+            return RawResponse(
+                status=200,
+                headers={
+                    "content-disposition": "inline; filename=file.txt",
+                    "x-kothar-file-version-id": "version-1",
+                },
+                body=b"content",
+            )
+
+    client = FileByPathClient(Transport(), "workspace", "file.txt")  # type: ignore[arg-type]
+
+    file = client.get()
+
+    assert file is not None
+    assert file.version_id == "version-1"
+
+
+def test_files_client_restores_versions_from_base_path_client() -> None:
+    class Transport:
+        def __init__(self) -> None:
+            self.call: object | None = None
+
+        def raw(
+            self,
+            method: str,
+            templated_url: str,
+            *,
+            path_params: object | None = None,
+            json_data: object | None = None,
+        ) -> RawResponse:
+            self.call = {
+                "method": method,
+                "templated_url": templated_url,
+                "path_params": path_params,
+                "json_data": json_data,
+            }
+            return RawResponse(
+                status=204,
+                headers={"x-kothar-file-version-id": "restored-version"},
+                body=b"",
+            )
+
+    transport = Transport()
+    client = FileByPathClient(transport, "workspace", "file.txt")  # type: ignore[arg-type]
+
+    result = client.restore("version-1")
+
+    assert transport.call == {
+        "method": "post",
+        "templated_url": "v1/workspaces/:workspaceId/files/$restore",
+        "path_params": {"workspaceId": "workspace"},
+        "json_data": {"path": "file.txt", "versionId": "version-1"},
+    }
+    assert result == {"version_id": "restored-version"}
+
+
+def test_files_client_exposes_write_version_headers() -> None:
+    class Transport:
+        def raw(
+            self,
+            method: str,
+            templated_url: str,
+            *,
+            path_params: object | None = None,
+            search_params: object | None = None,
+            headers: object | None = None,
+            body: object | None = None,
+        ) -> RawResponse:
+            return RawResponse(
+                status=204,
+                headers={
+                    "etag": "etag-1",
+                    "x-kothar-file-version-id": f"{method}-version",
+                },
+                body=b"",
+            )
+
+    client = FileByPathClient(Transport(), "workspace", "file.txt")  # type: ignore[arg-type]
+
+    assert client.create(content=b"content") == {
+        "etag": "etag-1",
+        "version_id": "post-version",
+    }
+    assert client.update(content=b"content") == {
+        "etag": "etag-1",
+        "version_id": "put-version",
+    }

{kotharcomputing-0.96.0 → kotharcomputing-0.98.0}/tests/test_public_api.py

@@ -119,7 +119,11 @@ def test_package_import_and_public_exports() -> None:
         # Jobs
         "CreateJobArgs",
         "Job",
+        "JobLaunchInstructionCommand",
+        "JobLaunchInstructionMethod",
+        "JobLaunchInstructions",
         "JobStatus",
+        "JobUploadedFile",
         "UpdateJobArgs",
         # Service Prices
         "ServicePrice",

kotharcomputing-0.96.0/tests/test_fetch_url_building.py

@@ -1,73 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-import sys
-from urllib import parse as urllib_parse
-
-import pytest
-
-SRC_DIR = Path(__file__).resolve().parents[1] / "src"
-if str(SRC_DIR) not in sys.path:
-    sys.path.insert(0, str(SRC_DIR))
-
-from kotharcomputing.fetch import ApiTransport
-
-
-def test_build_url_encodes_path_params_and_bool_query_values() -> None:
-    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
-
-    url = transport.build_url(
-        "v1/workspaces/:workspaceId/files/:filePath",
-        path_params={"workspaceId": "personal", "filePath": "folder/hello world.txt"},
-        search_params={"withUsernames": True, "limit": 25},
-    )
-
-    assert (
-        url
-        == "https://api.example.com/v1/workspaces/personal/files/folder%2Fhello%20world.txt?withUsernames=true&limit=25"
-    )
-
-
-def test_build_url_expands_list_query_params_and_skips_none_values() -> None:
-    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
-
-    url = transport.build_url(
-        "v1/users/me/credits/transactions",
-        search_params={
-            "references": ["job-1", "job-2"],
-            "active": False,
-            "next": None,
-        },
-    )
-
-    query_pairs = urllib_parse.parse_qsl(
-        urllib_parse.urlsplit(url).query, keep_blank_values=True
-    )
-    assert query_pairs == [
-        ("references", "job-1"),
-        ("references", "job-2"),
-        ("active", "false"),
-    ]
-
-
-def test_build_url_preserves_existing_query_and_appends_new_params() -> None:
-    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
-
-    url = transport.build_url(
-        "v1/jobs?next=cursor-1",
-        search_params={"withAgents": True},
-    )
-
-    assert (
-        url == "https://api.example.com/v1/jobs?next=cursor-1&withAgents=true"
-    )
-
-
-def test_build_url_rejects_absolute_url_outside_base_url() -> None:
-    transport = ApiTransport("https://api.example.com", access_token=None, timeout=30.0)
-
-    with pytest.raises(ValueError, match="does not start with the base URL"):
-        transport.build_url(
-            "https://malicious.example.com/v1/jobs",
-            absolute_url=True,
-        )