contree-sdk 0.0.1.dev11__py3-none-any.whl

contree_sdk/__init__.py

@@ -0,0 +1,5 @@
+from contree_sdk.sdk.client._async import Contree
+from contree_sdk.sdk.client._sync import ContreeSync
+
+
+__all__ = ["Contree", "ContreeSync"]

contree_sdk/_internals/README.md

@@ -0,0 +1,17 @@
+# _internals
+
+Low-level HTTP client layer and other utils. Not part of the public API.
+
+## Structure
+
+- `client/` - HTTP client classes and API endpoints
+- `lib/` - `@apied` decorator, request/response handling, async/sync mixins
+- `models/` - Response dataclasses for API responses
+- `utils/` - AsyncWrapper for sync client support
+
+## Does NOT belong here
+
+- Config (endpoint URLs) → `contree_sdk/config.py`
+- Public types → `sdk/` or `utils/`
+
+Everything here is subject to change without notice.

contree_sdk/_internals/client/client.py

@@ -0,0 +1,14 @@
+from abc import ABC
+
+from contree_sdk._internals.client.v1.common import V1Mixin
+from contree_sdk._internals.lib.client_base import ClientBase
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+
+
+class ContreeClientBase(ClientBase, V1Mixin, ABC): ...
+
+
+class ContreeClient(AsyncClientMixin, ContreeClientBase): ...
+
+
+class ContreeSyncClient(SyncClientMixin, ContreeClientBase): ...

contree_sdk/_internals/client/v1/common.py

@@ -0,0 +1,15 @@
+from contree_sdk._internals.client.v1.files import FilesMixin
+from contree_sdk._internals.client.v1.images import ImagesMixin
+from contree_sdk._internals.client.v1.inspect import InspectMixin
+from contree_sdk._internals.client.v1.instances import InstancesMixin
+from contree_sdk._internals.client.v1.operations import OperationsMixin
+
+
+class V1Mixin(
+    ImagesMixin,
+    FilesMixin,
+    InstancesMixin,
+    OperationsMixin,
+    InspectMixin,
+):
+    pass

contree_sdk/_internals/client/v1/files.py

@@ -0,0 +1,34 @@
+from typing import Annotated, overload
+
+from contree_sdk._internals.lib.api_decorator import get, head, post
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+from contree_sdk._internals.lib.types import FileContent, OctetFile
+from contree_sdk.utils.models.file import UploadedFile
+
+
+class FilesMixin:
+    @overload
+    async def get_file_by_sha256(self: AsyncClientMixin, sha256: str) -> UploadedFile: ...
+    @overload
+    def get_file_by_sha256(self: SyncClientMixin, sha256: str) -> UploadedFile: ...
+
+    @get("/v1/files", json=True)
+    def get_file_by_sha256(self, sha256: str) -> UploadedFile: ...
+
+    @overload
+    async def check_file_exists(self: AsyncClientMixin, uuid: str) -> bool: ...
+    @overload
+    def check_file_exists(self: SyncClientMixin, uuid: str) -> bool: ...
+
+    @head("/v1/files")
+    def check_file_exists(self, uuid: str) -> bool: ...
+
+    @overload
+    async def upload_file(self: AsyncClientMixin, data: Annotated[FileContent, OctetFile]) -> UploadedFile: ...
+    @overload
+    def upload_file(self: SyncClientMixin, data: Annotated[FileContent, OctetFile]) -> UploadedFile: ...
+
+    @post("/v1/files", json=True)
+    def upload_file(self, data: Annotated[FileContent, OctetFile]) -> UploadedFile: ...
+
+    # todo add error templates to response

contree_sdk/_internals/client/v1/images.py

@@ -0,0 +1,52 @@
+from typing import Annotated, Literal, overload
+
+from contree_sdk._internals.lib.api_decorator import get, post
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+from contree_sdk._internals.lib.types import Body
+from contree_sdk._internals.models.image import ContreeImageModel
+from contree_sdk._internals.models.image_import import ImageImportRequest
+from contree_sdk.utils.models.image import ImageKind
+
+
+class ImagesMixin:
+    @overload
+    async def get_images(
+        self: AsyncClientMixin,
+        kind: ImageKind | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        tagged: Literal[0, 1] | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> list[ContreeImageModel]: ...
+    @overload
+    def get_images(
+        self: SyncClientMixin,
+        kind: ImageKind | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        tagged: Literal[0, 1] | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> list[ContreeImageModel]: ...
+
+    @get("/v1/images", json=["images"])
+    def get_images(
+        self,
+        kind: ImageKind | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        tagged: Literal[0, 1] | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> list[ContreeImageModel]: ...
+
+    @overload
+    async def start_import_image(self: AsyncClientMixin, request: Annotated[ImageImportRequest, Body]) -> str: ...
+    @overload
+    def start_import_image(self: SyncClientMixin, request: Annotated[ImageImportRequest, Body]) -> str: ...
+    @post("/v1/images/import", json=["uuid"])
+    def start_import_image(self, request: Annotated[ImageImportRequest, Body]) -> str: ...
+
+
+# todo later use like this MainV1Client(ImagesMixin['/images'], OtherMixin, ContreeClientBase) and have all in one

contree_sdk/_internals/client/v1/inspect.py

@@ -0,0 +1,46 @@
+from pathlib import PurePosixPath
+from typing import overload
+from uuid import UUID
+
+from contree_sdk._internals.lib.api_decorator import get
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+from contree_sdk._internals.models.file import FileItemModel
+from contree_sdk._internals.models.image import ContreeImageModel
+
+
+class InspectMixin:
+    @overload
+    async def list_image_files(
+        self: AsyncClientMixin, image_uuid: str, path: str | PurePosixPath
+    ) -> list[FileItemModel]: ...
+    @overload
+    def list_image_files(self: SyncClientMixin, image_uuid: str, path: str | PurePosixPath) -> list[FileItemModel]: ...
+
+    @get("/v1/inspect/{image_uuid}/list", json=["files"])
+    def list_image_files(self, image_uuid: str, path: str | PurePosixPath) -> list[FileItemModel]: ...
+
+    @overload
+    async def download_image_file(
+        self: AsyncClientMixin, image_uuid: str | UUID, path: str | PurePosixPath
+    ) -> bytes: ...
+    @overload
+    def download_image_file(self: SyncClientMixin, image_uuid: str | UUID, path: str | PurePosixPath) -> bytes: ...
+
+    @get("/v1/inspect/{image_uuid}/download", json=False)
+    def download_image_file(self, image_uuid: str | UUID, path: str | PurePosixPath) -> bytes: ...
+
+    @overload
+    async def get_image_by_uuid(self: AsyncClientMixin, image_uuid: str) -> ContreeImageModel: ...
+    @overload
+    def get_image_by_uuid(self: SyncClientMixin, image_uuid: str) -> ContreeImageModel: ...
+
+    @get("/v1/inspect/{image_uuid}", json=True)
+    def get_image_by_uuid(self, image_uuid: str) -> ContreeImageModel: ...
+
+    @overload
+    async def get_image_by_tag(self: AsyncClientMixin, tag: str) -> ContreeImageModel: ...
+    @overload
+    def get_image_by_tag(self: SyncClientMixin, tag: str) -> ContreeImageModel: ...
+
+    @get("/v1/inspect", json=True)
+    def get_image_by_tag(self, tag: str) -> ContreeImageModel: ...

contree_sdk/_internals/client/v1/instances.py

@@ -0,0 +1,15 @@
+from typing import Annotated, overload
+
+from contree_sdk._internals.lib.api_decorator import post
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+from contree_sdk._internals.lib.types import Body
+from contree_sdk._internals.models.instance import InstanceSpawnRequest
+
+
+class InstancesMixin:
+    @overload
+    async def spawn_instance(self: AsyncClientMixin, request: Annotated[InstanceSpawnRequest, Body]) -> str: ...
+    @overload
+    def spawn_instance(self: SyncClientMixin, request: Annotated[InstanceSpawnRequest, Body]) -> str: ...
+    @post("/v1/instances", json=["uuid"])
+    def spawn_instance(self, request: Annotated[InstanceSpawnRequest, Body]) -> str: ...

contree_sdk/_internals/client/v1/operations.py

@@ -0,0 +1,24 @@
+from typing import overload
+from uuid import UUID
+
+from contree_sdk._internals.lib.api_decorator import delete, get
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+from contree_sdk._internals.models.operation import OperationModel
+
+
+class OperationsMixin:
+    @overload
+    async def get_operation_status(self: AsyncClientMixin, operation_id: str | UUID) -> OperationModel: ...
+    @overload
+    def get_operation_status(self: SyncClientMixin, operation_id: str | UUID) -> OperationModel: ...
+
+    @get("/v1/operations/{operation_id}", json=True)
+    def get_operation_status(self, operation_id: str | UUID) -> OperationModel: ...
+
+    @overload
+    async def cancel_operation(self: AsyncClientMixin, operation_id: str | UUID) -> None: ...
+    @overload
+    def cancel_operation(self: SyncClientMixin, operation_id: str | UUID) -> None: ...
+
+    @delete("/v1/operations/{operation_id}")
+    def cancel_operation(self, operation_id: str | UUID) -> None: ...

contree_sdk/_internals/lib/api_decorator.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from functools import partial, wraps
+from string import Formatter
+from typing import TYPE_CHECKING
+
+from contree_sdk._internals.lib.helpers import args_kwargs_to_kwargs
+from contree_sdk._internals.lib.types import ApiEndpointInfo, ReturnType
+
+
+if TYPE_CHECKING:
+    from contree_sdk._internals.client.client import ContreeClientBase
+
+_formatter = Formatter()
+
+
+def apied(method: str, path: str, *, json: bool | Iterable[str] = False):
+    """Define an API endpoint on a client method.
+
+    Builds ApiEndpointInfo from the function signature and annotations, then
+    replaces the method with a wrapper calling `_handle_api_call`.
+
+    Args:
+        method: HTTP method name.
+        path: Endpoint path with `{param}` placeholders.
+        json:
+            False — no JSON handling,
+            True — whole response as JSON,
+            iterable — JSON path to extract.
+
+    Returns:
+        A decorator that wraps a client method and routes the call through
+        `ContreeClientBase._handle_api_call`.
+
+    """
+    match json:
+        case False:
+            json_path = None
+        case True:
+            json_path = []
+        case _:
+            json_path = list(json)
+
+    def decorator(func: Callable[..., ReturnType]):
+        endpoint_info = ApiEndpointInfo.from_func(
+            method=method,
+            path=path,
+            json_path=json_path,
+            func=func,
+        )
+
+        @wraps(func)
+        def wrapper(self: ContreeClientBase, *args, **kwargs):
+            data = args_kwargs_to_kwargs(endpoint_info.all_params, args, kwargs)
+            return self._handle_api_call(endpoint_info=endpoint_info, data=data)
+
+        return wrapper
+
+    return decorator
+
+
+get = partial(apied, "get")
+post = partial(apied, "post")
+put = partial(apied, "put")
+head = partial(apied, "head")
+delete = partial(apied, "delete")

contree_sdk/_internals/lib/client_base.py

@@ -0,0 +1,74 @@
+from abc import ABC, abstractmethod
+from typing import overload
+
+import httpx
+from httpx import Request, Response
+from httpx._config import DEFAULT_TIMEOUT_CONFIG, Timeout
+
+from contree_sdk._internals.lib.helpers import convert_data_to_type
+from contree_sdk._internals.lib.mixins import AsyncClientMixin, SyncClientMixin
+from contree_sdk._internals.lib.types import EMPTY, ApiEndpointInfo, ReturnType
+from contree_sdk._internals.utils.config import build_user_agent
+
+
+class ClientBase(ABC):
+    _client_class: type[httpx._client.BaseClient]
+
+    def __init__(self, token: str, base_url: str, transport_timeout: float = DEFAULT_TIMEOUT_CONFIG.connect) -> None:
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "User-Agent": build_user_agent(),
+        }
+        self._client = self._client_class(
+            headers=headers, base_url=base_url, timeout=Timeout(timeout=transport_timeout)
+        )
+
+    def _build_request(self, endpoint_info: ApiEndpointInfo, data: dict) -> Request:
+        kwargs = endpoint_info.get_file_upload_kwargs(data)
+        return self._client.build_request(
+            method=endpoint_info.method.upper(),
+            url=endpoint_info.get_path_by_data(data),
+            params=endpoint_info.get_query_data_by_data(data),
+            json=endpoint_info.get_body_data_by_data(data),
+            **kwargs,
+        )
+
+    @overload
+    async def _send_request(self: AsyncClientMixin, request: Request) -> Response: ...
+    @overload
+    def _send_request(self: SyncClientMixin, request: Request) -> Response: ...
+    @abstractmethod
+    def _send_request(self, request: Request) -> Response:
+        pass
+
+    @staticmethod
+    def _parse_response(
+        *,
+        response: Response,
+        endpoint_info: ApiEndpointInfo,
+    ) -> ReturnType | dict | Response | str | bytes:
+        response.raise_for_status()
+        if endpoint_info.json_path is None:
+            if endpoint_info.return_type is str:
+                return response.text
+            if endpoint_info.return_type is bytes:
+                return response.content
+            return response
+
+        data = response.json()
+        for key in endpoint_info.json_path:
+            data = data[key]
+        if endpoint_info.return_type is not EMPTY:
+            return convert_data_to_type(data, endpoint_info.return_type)
+        return data
+
+    @overload
+    async def _handle_api_call(
+        self: AsyncClientMixin, endpoint_info: ApiEndpointInfo, data: dict
+    ) -> ReturnType | dict | Response: ...
+    @overload
+    def _handle_api_call(
+        self: SyncClientMixin, endpoint_info: ApiEndpointInfo, data: dict
+    ) -> ReturnType | dict | Response: ...
+    @abstractmethod
+    def _handle_api_call(self, endpoint_info: ApiEndpointInfo, data: dict) -> ReturnType | dict | Response: ...

contree_sdk/_internals/lib/helpers.py

@@ -0,0 +1,18 @@
+from cattrs.preconf.json import make_converter
+
+from contree_sdk._internals.lib.types import ReturnType
+
+
+_converter = make_converter()
+
+
+def convert_data_to_type(data: dict | int | str | list, return_type: type[ReturnType]) -> ReturnType:
+    return _converter.structure(data, return_type)
+
+
+def args_kwargs_to_kwargs(all_params: list[str], args: tuple, kwargs: dict) -> dict:
+    kwargs = kwargs.copy()
+
+    for param, arg in zip(all_params, args, strict=False):
+        kwargs[param] = arg
+    return kwargs

contree_sdk/_internals/lib/mixins.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from httpx import AsyncClient, Client, Request, Response
+
+from contree_sdk._internals.lib.types import ApiEndpointInfo, ReturnType
+
+
+if TYPE_CHECKING:
+    from contree_sdk._internals.lib.client_base import ClientBase
+
+
+class SyncClientMixin:
+    _client_class: type[Client] = Client
+    _client: Client
+
+    def _send_request(self, request: Request) -> Response:
+        return self._client.send(request, follow_redirects=True)
+
+    def _handle_api_call(self: ClientBase, endpoint_info: ApiEndpointInfo, data: dict) -> ReturnType | dict | Response:
+        request = self._build_request(endpoint_info=endpoint_info, data=data)
+        resp = self._send_request(request)
+        return self._parse_response(response=resp, endpoint_info=endpoint_info)
+
+
+class AsyncClientMixin:
+    _client_class: type[AsyncClient] = AsyncClient
+    _client: AsyncClient
+
+    async def _send_request(self, request: Request) -> Response:
+        resp = await self._client.send(request, follow_redirects=True, stream=True)
+        try:
+            await resp.aread()
+        except BaseException as e:
+            e.response = resp
+            await resp.aclose()
+            raise
+        else:
+            return resp
+
+    async def _handle_api_call(
+        self: ClientBase, endpoint_info: ApiEndpointInfo, data: dict
+    ) -> ReturnType | dict | Response:
+        request = self._build_request(endpoint_info=endpoint_info, data=data)
+
+        resp = await self._send_request(request)
+        return self._parse_response(response=resp, endpoint_info=endpoint_info)

contree_sdk/_internals/lib/types.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from string import Formatter
+from typing import IO, Annotated, Any, TypeVar, get_args, get_origin
+
+import cattrs
+from aiofiles.threadpool.binary import AsyncBufferedReader
+
+
+class _Empty:
+    pass
+
+
+EMPTY = _Empty()
+ReturnType = TypeVar("ReturnType")
+_formatter = Formatter()
+
+
+class Body:
+    pass
+
+
+class OctetFile:
+    pass
+
+
+@dataclass(kw_only=True, frozen=True)
+class ApiEndpointInfo:
+    # api info
+    method: str
+    path: str
+
+    # params info
+    all_params: list[str]
+    path_params: list[str]
+    query_params: list[str]
+    body_params: list[str]
+    file_params: list[str]
+
+    # how to parse
+    json_path: list | None
+    func: Callable[..., Any]
+    return_type: ReturnType | _Empty
+
+    def get_path_by_data(self, data: dict):
+        return self.path.format(**data)
+
+    def get_query_data_by_data(self, data: dict):
+        return {name: str(to_dict(data[name])) for name in self.query_params if name in data}
+
+    def get_body_data_by_data(self, data: dict):
+        if not self.body_params:
+            return None
+        res = {name: to_dict(data[name]) for name in self.body_params if name in data}
+        if len(self.body_params) == 1:
+            return res[self.body_params[0]]
+        return res
+
+    def get_file_upload_kwargs(self, data: dict) -> dict:
+        if not self.file_params:
+            return {}
+        if len(self.file_params) == 1:
+            return {
+                "headers": {
+                    "Content-Type": "application/octet-stream",
+                },
+                "content": data[self.file_params[0]],
+            }
+        return {"files": {name: (None, data[name], "application/octet-stream") for name in self.file_params}}
+
+    @classmethod
+    def from_func(
+        cls,
+        *,
+        method: str,
+        path: str,
+        json_path: list[str] | None,
+        func: Callable[..., Any],
+    ) -> ApiEndpointInfo:
+        parsed_path_params = {name for _, name, *_ in _formatter.parse(path) if name is not None}
+
+        all_params: list[str] = []
+        path_params: list[str] = []
+        query_params: list[str] = []
+        body_params: list[str] = []
+        file_params: list[str] = []
+
+        sig = inspect.signature(func)
+        for name, param in sig.parameters.items():
+            if name == "self":
+                continue
+            all_params.append(name)
+
+            is_body, is_file = cls._extract_flags(param)
+
+            if is_body:
+                body_params.append(name)
+            elif is_file:
+                file_params.append(name)
+            elif name in parsed_path_params:
+                path_params.append(name)
+            else:
+                query_params.append(name)
+
+        return cls(
+            method=method,
+            path=path,
+            all_params=all_params,
+            path_params=path_params,
+            query_params=query_params,
+            body_params=body_params,
+            file_params=file_params,
+            json_path=json_path,
+            func=func,
+            return_type=func.__annotations__.get("return", EMPTY),
+        )
+
+    @staticmethod
+    def _extract_flags(param: inspect.Parameter) -> tuple[bool, bool]:
+        ann = param.annotation
+        if get_origin(ann) is not Annotated:
+            return False, False
+
+        _, *meta = get_args(ann)
+
+        is_body = any(isinstance(m, type) and issubclass(m, Body) for m in meta)
+        is_file = any(isinstance(m, type) and issubclass(m, OctetFile) for m in meta)
+        return is_body, is_file
+
+
+def to_dict(data: Any) -> Any:
+    return cattrs.unstructure(data)
+
+
+FileContent = IO[bytes] | bytes | str | AsyncBufferedReader

contree_sdk/_internals/models/file.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class FileItemModel:
+    size: int
+    path: str
+    uid: int
+    gid: int
+    mode: int
+    mtime: int
+    nlink: int
+    symlink_to: str
+    is_dir: bool
+    is_regular: bool
+    is_socket: bool
+    is_fifo: bool
+    is_symlink: bool
+    owner: str
+    group: str

contree_sdk/_internals/models/image.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+
+ImageTag = str
+
+
+@dataclass
+class ImageSize:
+    logical: int
+    physical: int
+
+
+@dataclass(kw_only=True)
+class ContreeImageModel:
+    uuid: str
+    tag: str | None = None
+    created_at: datetime | None = None
+
+
+@dataclass(kw_only=True)
+class InspectImageResponse:
+    uuid: str
+    source: str | None = None
+    tag: str | None = None
+    created_at: int
+    size: ImageSize

contree_sdk/_internals/models/image_import.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class RegistryCredentials:
+    username: str
+    password: str
+
+
+@dataclass
+class PublicRegistryInfo:
+    url: str
+
+
+@dataclass
+class PrivateRegistryInfo(PublicRegistryInfo):
+    credentials: RegistryCredentials
+
+
+@dataclass
+class ImageImportRequest:
+    registry: PublicRegistryInfo | PrivateRegistryInfo
+    tag: str | None = None
+    timeout: int = 300