kc-sdk-python 0.1.0__tar.gz

kc_sdk_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kvindo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kc_sdk_python-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: kc-sdk-python
+Version: 0.1.0
+Summary: Python SDK / client for the Kvindo Cloud API
+Author: Kvindo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kvindo/kc-sdk-python
+Project-URL: Repository, https://github.com/Kvindo/kc-sdk-python
+Keywords: kvindo,cloud,sdk,client,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: marshmallow-dataclass
+Requires-Dist: py-ulid
+Dynamic: license-file
+
+# kc-sdk-python
+
+Python SDK / client for the **Kvindo Cloud API**.
+
+A thin, typed client over the REST API: one resource client per resource type
+(VMs, volumes, load balancers, kubernetes, S3, VPCs, …), all sharing the same
+create / read / update / delete / list contract.
+
+## Install
+
+```sh
+pip install kc-sdk-python
+```
+
+Dependencies: `requests`, `marshmallow-dataclass`, `py-ulid`.
+
+## Usage
+
+```python
+from kc_api import KcClient
+
+client = KcClient("YOUR_API_TOKEN")  # api_url defaults to https://cloud-api.kvindo.ru
+
+# List (label-filtered, paginated)
+resp = client.vms.get_by_labels({"env": "prod"}, max_page_size=50)
+for vm in resp.resources:
+    print(vm["metadata"]["name"])
+
+# Read one
+vm = client.vms.read("01H...")
+print(vm.resource)
+
+# Create / update (async) then wait for it to reconcile
+created = client.vms.create_or_update({
+    "metadata": {"name": "my-vm", "folderId": "01H..."},
+    "spec": {"offerId": "g3-1c2-100", "state": "running", ...},
+})
+status = client.vms.wait_request_satisfied(created.requestId, timeout_seconds=300)
+assert status.succeeded
+
+# Delete (optionally block until reconciled)
+client.vms.delete("01H...", wait=True)
+```
+
+Create / update / delete are **asynchronous**: they return a `requestId`; poll
+`read_request(requestId)` or use `wait_request_satisfied(...)`. Every response
+object carries `errorMessage` / `errorCode` (a typed `KcApi*ErrorCode`) which are
+`None` on success.
+
+### Available resources
+
+`KcClient` exposes one `KcResourceClient` per type, e.g. `client.vms`,
+`client.volumes`, `client.s3_buckets`, `client.kubernetes`,
+`client.load_balancers`, `client.vpcs`, `client.postgresql_standalones`,
+`client.folders`, `client.transactions`, … (the surface mirrors the official
+Kvindo Cloud API).
+
+## License
+
+MIT

kc_sdk_python-0.1.0/README.md

@@ -0,0 +1,60 @@
+# kc-sdk-python
+
+Python SDK / client for the **Kvindo Cloud API**.
+
+A thin, typed client over the REST API: one resource client per resource type
+(VMs, volumes, load balancers, kubernetes, S3, VPCs, …), all sharing the same
+create / read / update / delete / list contract.
+
+## Install
+
+```sh
+pip install kc-sdk-python
+```
+
+Dependencies: `requests`, `marshmallow-dataclass`, `py-ulid`.
+
+## Usage
+
+```python
+from kc_api import KcClient
+
+client = KcClient("YOUR_API_TOKEN")  # api_url defaults to https://cloud-api.kvindo.ru
+
+# List (label-filtered, paginated)
+resp = client.vms.get_by_labels({"env": "prod"}, max_page_size=50)
+for vm in resp.resources:
+    print(vm["metadata"]["name"])
+
+# Read one
+vm = client.vms.read("01H...")
+print(vm.resource)
+
+# Create / update (async) then wait for it to reconcile
+created = client.vms.create_or_update({
+    "metadata": {"name": "my-vm", "folderId": "01H..."},
+    "spec": {"offerId": "g3-1c2-100", "state": "running", ...},
+})
+status = client.vms.wait_request_satisfied(created.requestId, timeout_seconds=300)
+assert status.succeeded
+
+# Delete (optionally block until reconciled)
+client.vms.delete("01H...", wait=True)
+```
+
+Create / update / delete are **asynchronous**: they return a `requestId`; poll
+`read_request(requestId)` or use `wait_request_satisfied(...)`. Every response
+object carries `errorMessage` / `errorCode` (a typed `KcApi*ErrorCode`) which are
+`None` on success.
+
+### Available resources
+
+`KcClient` exposes one `KcResourceClient` per type, e.g. `client.vms`,
+`client.volumes`, `client.s3_buckets`, `client.kubernetes`,
+`client.load_balancers`, `client.vpcs`, `client.postgresql_standalones`,
+`client.folders`, `client.transactions`, … (the surface mirrors the official
+Kvindo Cloud API).
+
+## License
+
+MIT

kc_sdk_python-0.1.0/kc_api.py

@@ -0,0 +1,774 @@
+"""Python client (SDK) for the Kvindo Cloud API.
+
+`KcClient` exposes one `KcResourceClient` per resource type (vms, volumes,
+load balancers, kubernetes, s3, …). Every resource speaks the same REST
+contract under `/api/v1/<resource-type>`:
+
+    PUT    /api/v1/<type>              create or update (idempotent on metadata.id)
+    GET    /api/v1/<type>/<id>         read one
+    DELETE /api/v1/<type>/<id>         delete one
+    GET    /api/v1/<type>/get-by-labels   list (label-filtered, paginated)
+    GET    /api/v1/<type>/request/<reqId> poll an async change-request's status
+
+Create/update/delete are **asynchronous**: they return a `requestId`
+immediately; the actual provisioning is done by server-side reconcilers. Poll
+`read_request(requestId)` (or use `wait_request_satisfied`) until it succeeds.
+
+The resource surface mirrors the maintained C# client
+`KvindoCloud.Api/KvindoCloudClient.cs`, which is the source of truth.
+
+Dependencies: requests, marshmallow-dataclass, py-ulid.
+"""
+
+import time
+import logging
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+from urllib.parse import urlencode
+from enum import Enum
+
+# https://stackoverflow.com/questions/15476983/deserialize-a-json-string-to-an-object-in-python
+from marshmallow_dataclass import dataclass
+from typing import List, Optional
+from dataclasses import field
+from ulid import ULID
+
+# Why a module logger here instead of importing one: this file is published as a
+# standalone SDK, so it must not depend on the internal kc_common module (which
+# pulls in python-json-logger and a pre-configured logger). Callers configure
+# logging as they see fit; by default this logger is silent.
+logger = logging.getLogger(__name__)
+
+
+# Vendored from kc_common (create_http_client_with_retries / create_url_with_query_params)
+# so the SDK carries no local-module dependency — its only third-party deps are
+# requests, marshmallow-dataclass and py-ulid.
+def create_http_client_with_retries(
+    retry_statuses=[500, 502, 503, 504, 520, 521],
+    verify_ssl: bool = False,
+) -> requests.Session:
+    """Build a `requests.Session` that retries idempotent failures with backoff.
+
+    Args:
+        retry_statuses: HTTP status codes that should be retried. 5xx are
+            server-side; 520 = web server returned an unknown error;
+            521 = origin down (Cloudflare-specific).
+        verify_ssl: enable/disable TLS certificate verification. Defaults to
+            False because internal/dev endpoints use self-signed certs; pass
+            True against public prod.
+
+    Returns:
+        A configured `requests.Session` (reuse it for connection pooling).
+    """
+    session = requests.Session()
+    session.verify = verify_ssl
+    # total=5 attempts; backoff_factor=1 -> delays 0.5, 1, 2, 4, 8 ... seconds.
+    retries = Retry(total=5, backoff_factor=1, status_forcelist=retry_statuses)
+    adapter = HTTPAdapter(max_retries=retries)
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    return session
+
+
+def create_url_with_query_params(base_url: str, query_params: dict) -> str:
+    """Append a query string to `base_url`, URL-encoding keys and values.
+
+    A dict-valued param is flattened to repeated `key[subkey]=value` pairs
+    (used for the `labels` filter). `None` values are dropped entirely.
+
+    Args:
+        base_url: URL without a query string.
+        query_params: flat dict; values may be scalars or a one-level dict.
+
+    Returns:
+        The full URL including the `?...` query string.
+    """
+    # Drop params whose value is None (e.g. an unset enumeratorId).
+    params = {k: v for k, v in query_params.items() if v is not None}
+
+    url = base_url + "?"
+
+    # TODO: Add recursive traverse
+    for p in params:
+        if isinstance(params[p], dict):
+            # Flatten one nesting level: labels={"env":"dev"} -> labels[env]=dev
+            for p2 in params[p]:
+                url = f"{url}{'' if url.endswith('?') else '&'}{urlencode({f'{p}[{p2}]': params[p][p2]})}"
+        else:
+            url = f"{url}{'' if url.endswith('?') else '&'}{urlencode({p: params[p]})}"
+
+    return url
+
+
+# ── Error codes ───────────────────────────────────────────────────────────────
+# Error-code enums mirror the C# enums in KvindoCloud.Api/Models/*ErrorCode.cs.
+# The API serializes them as the PascalCase member NAME (each C# enum carries
+# [JsonConverter(typeof(JsonStringEnumConverter))]), and marshmallow loads Enum
+# fields by name, so the member names below must match the C# names exactly.
+# Why each value is the name string (not the HTTP status code it used to be):
+# duplicate values make Python collapse members into aliases of the first one
+# with that value (e.g. every 422 became an alias of NotFound), so "MissingIdField"
+# on the wire silently loaded as NotFound. Unique values keep every code distinct.
+#
+# Note: the """docstrings""" after each member/field are attribute docstrings —
+# editors (Pylance/PyCharm) surface them on hover, unlike `#` comments.
+
+
+class KcApiGenericErrorCode(Enum):
+    """Generic top-level errors not specific to one operation."""
+
+    Unauthorized = "Unauthorized"
+    """Token missing/invalid or lacks the required permission."""
+    BadData = "BadData"
+    """Request was malformed (bad JSON, wrong types, etc.)."""
+
+
+class KcApiModificationErrorCode(Enum):
+    """Errors returned by create / update / delete (PUT and DELETE)."""
+
+    NotFound = "NotFound"
+    """No resource with the given id."""
+    Unauthorized = "Unauthorized"
+    """Token lacks permission for this resource/action."""
+    MissingIdField = "MissingIdField"
+    """Body had no id (and none could be derived)."""
+    ResourceIsScheduling = "ResourceIsScheduling"
+    """A previous change request is still in flight; retry later."""
+    MissingNameField = "MissingNameField"
+    """Body had no name."""
+    Unknown = "Unknown"
+    """Unhandled server-side error (treat as a 5xx)."""
+    ResourceIsDeleteProtected = "ResourceIsDeleteProtected"
+    """deleteProtection=true; clear it before deleting."""
+    BadData = "BadData"
+    """Request was malformed."""
+
+
+@dataclass
+class KcResourceDeleteResponse(object):
+    """Response of `KcResourceClient.delete`."""
+
+    requestId: str = None
+    """Id of the async change request to poll; None on error."""
+    resourceId: str = None
+    """Id of the resource being deleted; None on error."""
+    errorMessage: str = None
+    """Human-readable error; None on success."""
+    errorCode: KcApiModificationErrorCode = None
+    """Machine-readable error; None on success."""
+
+
+@dataclass
+class KcResourceCreateResponse(object):
+    """Response of `KcResourceClient.create` / `create_or_update`."""
+
+    requestId: str = None
+    """Id of the async change request to poll; None on error."""
+    resourceId: str = None
+    """Id of the created/updated resource; None on error."""
+    errorMessage: str = None
+    """Human-readable error; None on success."""
+    errorCode: KcApiModificationErrorCode = None
+    """Machine-readable error; None on success."""
+
+
+@dataclass
+class KcResourceUpdateResponse(object):
+    """Response of `KcResourceClient.update`. Shape-identical to the create response."""
+
+    requestId: str = None
+    """Id of the async change request to poll; None on error."""
+    resourceId: str = None
+    """Id of the updated resource; None on error."""
+    errorMessage: str = None
+    """Human-readable error; None on success."""
+    errorCode: KcApiModificationErrorCode = None
+    """Machine-readable error; None on success."""
+
+
+class KcApiReadErrorCode(Enum):
+    """Errors returned by a single-resource read (`GET /api/v1/<type>/<id>`)."""
+
+    Unauthorized = "Unauthorized"
+    """Token lacks read permission."""
+    NotFound = "NotFound"
+    """No resource with the given id."""
+    ResourceIsScheduling = "ResourceIsScheduling"
+    """Resource exists but its first change request hasn't completed."""
+    Unknown = "Unknown"
+    """Unhandled server-side error."""
+    BadData = "BadData"
+    """Malformed request (e.g. invalid id)."""
+
+
+@dataclass
+class KcResourceReadResponse(object):
+    """Response of `KcResourceClient.read`."""
+
+    resource: dict = None
+    """The resource as a raw dict; None if errorMessage is set."""
+    errorMessage: str = None
+    """Human-readable error; None on success."""
+    errorCode: KcApiReadErrorCode = None
+    """Machine-readable error; set iff errorMessage is set."""
+
+
+class KcApiReadRequestErrorCode(Enum):
+    """Errors returned when polling an async change-request's status."""
+
+    Unauthorized = "Unauthorized"
+    """Token lacks permission."""
+    NotFound = "NotFound"
+    """No change request with the given requestId."""
+    Unknown = "Unknown"
+    """Unhandled server-side error."""
+    BadData = "BadData"
+    """Malformed request."""
+    UnableToReconcile = "UnableToReconcile"
+    """The reconciler failed to apply the change (terminal failure)."""
+
+
+@dataclass
+class KcResourceReadRequestResponse(object):
+    """Status of an async create/update/delete request (`GET .../request/<id>`)."""
+
+    succeeded: bool
+    """True once the reconciler has finished applying the change."""
+    scheduledResourceId: str
+    """Id of the resource the request targets."""
+    errorMessage: str = None
+    """Set if the request failed; None while pending or on success."""
+    errorCode: KcApiReadRequestErrorCode = None
+    """Machine-readable failure code; None while pending or on success."""
+
+
+class KcApiGetByLabelsErrorCode(Enum):
+    """Errors returned by label-filtered list (`GET .../get-by-labels`)."""
+
+    Unauthorized = "Unauthorized"
+    """Token lacks list permission."""
+    PageSizeTooBig = "PageSizeTooBig"
+    """maxPageSize exceeded the server limit (max 100)."""
+    EnumeratorNotFound = "EnumeratorNotFound"
+    """The pagination enumeratorId expired or is unknown."""
+    Unknown = "Unknown"
+    """Unhandled server-side error."""
+    BadData = "BadData"
+    """Malformed request."""
+
+
+@dataclass
+class KcResourceGetByLabelsPagination(object):
+    """Pagination cursor returned by get-by-labels; pass it back to fetch the next page."""
+
+    enumeratorId: str = None
+    """Opaque cursor; feed to the next get_by_labels call as enumerator_id."""
+
+
+@dataclass
+class KcResourceGetByLabelsResponse(object):
+    """Response of `KcResourceClient.get_by_labels` (one page of results)."""
+
+    # pagination and resources are null on error responses (errorMessage set), so
+    # they must be Optional or marshmallow rejects the payload before the caller
+    # can read errorMessage.
+    pagination: Optional[KcResourceGetByLabelsPagination] = None
+    """Cursor for the next page; None on error."""
+    resources: Optional[List[dict]] = field(default_factory=list)
+    """This page's resources as raw dicts; None on error."""
+    errorMessage: str = None
+    """Human-readable error; None on success."""
+    errorCode: KcApiGetByLabelsErrorCode = None
+    """Machine-readable error; None on success."""
+
+
+# HTTP statuses the API uses to carry a structured (deserializable) body. Anything
+# outside this set is an unexpected transport/server failure and is raised instead.
+_HANDLED_STATUS_CODES = [200, 400, 401, 403, 422]
+
+
+class KcResourceClient:
+    """Client for a single resource type of the Kvindo Cloud API.
+
+    One instance is bound to one resource type (e.g. "vm", "s3-bucket") and
+    reused for all calls against it. Obtain instances via `KcClient`, e.g.
+    `KcClient(token).vms`.
+
+    See https://cloud-api.kvindo.ru/swagger/index.html for the full contract.
+    """
+
+    def __init__(
+        self,
+        resource_type: str,
+        token: str,
+        api_url: str = "https://cloud-api.kvindo.ru",
+        log_extra: dict = None,
+    ):
+        """
+        Args:
+            resource_type: the kebab-case API path segment (e.g. "vm", "s3-bucket").
+            token: the bearer token; a leading "Bearer " prefix is stripped if present.
+            api_url: base URL of the Cloud API (no trailing slash).
+            log_extra: optional dict merged into every debug log record's `extra`.
+        """
+        self.__token = token.replace("Bearer ", "")
+        self.__resource_type = resource_type
+        self.__api_url = api_url
+        self.__log_extra = log_extra if log_extra is not None else {}
+
+    def __headers(self) -> dict:
+        """Standard auth + content-type headers for every request."""
+        return {
+            "accept": "*/*",
+            "Authorization": f"Bearer {self.__token}",
+            "Content-Type": "application/json-patch+json",
+        }
+
+    def delete(self, id: str, wait=False) -> KcResourceDeleteResponse:
+        """Delete a resource by id (asynchronous).
+
+        Args:
+            id: id of the resource to delete.
+            wait: if True, block (up to 300s) until the delete reconciles via
+                `wait_request_satisfied` before returning.
+
+        Returns:
+            KcResourceDeleteResponse with `requestId` to poll, or `errorMessage`/
+            `errorCode` set on a handled error.
+
+        Raises:
+            Exception: on an unexpected HTTP status (outside 200/400/401/403/422).
+        """
+        url = f"{self.__api_url}/api/v1/{self.__resource_type}/{id}"
+
+        response = create_http_client_with_retries().delete(url, headers=self.__headers())
+
+        logger.debug(
+            f"Got {response.status_code} status code while making request DELETE {url}\nResponse body: {response.text}",
+            extra=self.__log_extra,
+        )
+
+        if response.status_code in _HANDLED_STATUS_CODES:
+            result: KcResourceDeleteResponse = KcResourceDeleteResponse.Schema().load(
+                response.json()
+            )
+            if wait:
+                self.wait_request_satisfied(result.requestId, 300)
+            return result
+        else:
+            raise Exception(
+                f"Got {response.status_code} status code while making request DELETE {url}\nResponse body: {response.text}"
+            )
+
+    def read(self, id: str) -> KcResourceReadResponse:
+        """Read a single resource by id.
+
+        Args:
+            id: id of the resource to read.
+
+        Returns:
+            KcResourceReadResponse with `resource` (a raw dict) on success, or
+            `errorMessage`/`errorCode` set on a handled error.
+
+        Raises:
+            Exception: on an unexpected HTTP status.
+        """
+        url = f"{self.__api_url}/api/v1/{self.__resource_type}/{id}"
+
+        response = create_http_client_with_retries().get(url, headers=self.__headers())
+
+        logger.debug(
+            f"Got {response.status_code} status code while making request GET {url}\nResponse body: {response.text}",
+            extra=self.__log_extra,
+        )
+
+        if response.status_code in _HANDLED_STATUS_CODES:
+            return KcResourceReadResponse.Schema().load(response.json())
+        else:
+            raise Exception(
+                f"Got {response.status_code} status code while making request GET {url}\nResponse body: {response.text}"
+            )
+
+    def get_by_labels(
+        self, labels: dict = None, enumerator_id: str = None, max_page_size: int = 10
+    ) -> KcResourceGetByLabelsResponse:
+        """List resources of this type, filtered by labels and paginated.
+
+        Args:
+            labels: label filter as a dict; values may use `*` wildcards. Empty/None
+                matches all. Defaults to None (treated as no filter).
+            enumerator_id: pagination cursor from a previous call's
+                `pagination.enumeratorId`; None starts at the first page.
+            max_page_size: max resources per page. **Must not exceed 100** or the
+                API returns `PageSizeTooBig`.
+
+        Returns:
+            KcResourceGetByLabelsResponse: one page in `resources`, the next-page
+            cursor in `pagination`, or `errorMessage`/`errorCode` on a handled error.
+
+        Raises:
+            Exception: on an unexpected HTTP status.
+        """
+        url = f"{self.__api_url}/api/v1/{self.__resource_type}/get-by-labels"
+        params = {
+            "labels": labels if labels is not None else {},
+            "maxPageSize": max_page_size,
+            "enumeratorId": enumerator_id,
+        }
+
+        url = create_url_with_query_params(url, params)
+        response = create_http_client_with_retries().get(url, headers=self.__headers())
+
+        logger.debug(
+            f"Got {response.status_code} status code while making request GET {url}\nResponse body: {response.text}",
+            extra=self.__log_extra,
+        )
+
+        if response.status_code in _HANDLED_STATUS_CODES:
+            return KcResourceGetByLabelsResponse.Schema().load(response.json())
+        else:
+            raise Exception(
+                f"Got {response.status_code} status code while making request GET {url}\nResponse body: {response.text}"
+            )
+
+    def read_request(self, request_id: str) -> KcResourceReadRequestResponse:
+        """Read the current status of an async change request (one poll).
+
+        Args:
+            request_id: the `requestId` returned by create/update/delete.
+
+        Returns:
+            KcResourceReadRequestResponse: `succeeded` True once applied,
+            `errorMessage`/`errorCode` set if it failed, otherwise still pending.
+
+        Raises:
+            Exception: on an unexpected HTTP status.
+        """
+        url = f"{self.__api_url}/api/v1/{self.__resource_type}/request/{request_id}"
+
+        response = create_http_client_with_retries().get(url, headers=self.__headers())
+
+        logger.debug(
+            f"Got {response.status_code} status code while making request GET {url}\nResponse body: {response.text}",
+            extra=self.__log_extra,
+        )
+
+        if response.status_code in _HANDLED_STATUS_CODES:
+            return KcResourceReadRequestResponse.Schema().load(response.json())
+        else:
+            raise Exception(
+                f"Got {response.status_code} status code while making request GET {url}\nResponse body: {response.text}"
+            )
+
+    def wait_request_satisfied(
+        self, request_id: str, timeout_seconds: int
+    ) -> KcResourceReadRequestResponse:
+        """Poll a change request once per second until it finishes or times out.
+
+        Returns as soon as the request succeeds (`succeeded == True`) or fails
+        (both `errorMessage` and `errorCode` set). On timeout it returns the last
+        (still-pending) status rather than raising — inspect `succeeded` to tell
+        the cases apart.
+
+        Args:
+            request_id: the `requestId` to poll.
+            timeout_seconds: max number of 1-second polls before giving up.
+
+        Returns:
+            The final (or last-seen) KcResourceReadRequestResponse.
+        """
+        result = self.read_request(request_id)
+
+        i = 0
+        while result.succeeded == False and result.errorMessage == None:
+            i = i + 1
+            if i > timeout_seconds:
+                return result  # timed out while still pending
+
+            time.sleep(1)
+            result = self.read_request(request_id)
+
+            if result.succeeded == True:
+                return result  # applied successfully
+            if result.errorMessage != None and result.errorCode != None:
+                return result  # failed terminally
+
+        return result
+
+    def create_or_update(self, data: dict) -> KcResourceCreateResponse:
+        """Create a resource, or update it if one with the same id already exists.
+
+        Idempotent on the resource id: if no id is present in `data` (neither
+        `data["metadata"]["id"]` for the envelope shape nor top-level `data["id"]`
+        for the flat shape), a fresh ULID is generated and used, so re-sending the
+        same `data` object updates the same resource.
+
+        Args:
+            data: the resource body, either the kubectl-style envelope
+                ({"metadata": {...}, "spec": {...}}) or the flat shape. **Mutated
+                in place** to inject the generated id when absent.
+
+        Returns:
+            KcResourceCreateResponse with `requestId`/`resourceId`, or
+            `errorMessage`/`errorCode` on a handled error.
+
+        Raises:
+            Exception: on an unexpected HTTP status.
+        """
+        logger.debug(f"create_or_update({data})")
+
+        # Inject a ULID id when absent so the call is idempotent and the caller can
+        # poll the returned requestId. Two body shapes are supported:
+        if "metadata" in data:
+            # Envelope shape: id lives under metadata.
+            if "id" not in data["metadata"] or not data["metadata"]["id"]:
+                data["metadata"]["id"] = str(ULID())
+        elif "id" not in data or not data["id"]:
+            # Flat shape: id at the top level.
+            data["id"] = str(ULID())
+
+        url = f"{self.__api_url}/api/v1/{self.__resource_type}"
+
+        response = create_http_client_with_retries().put(url, json=data, headers=self.__headers())
+
+        logger.debug(
+            f"Got {response.status_code} status code while making request PUT {url}\nRequest body: {data}\nResponse body: {response.text}",
+            extra=self.__log_extra,
+        )
+
+        if response.status_code in _HANDLED_STATUS_CODES:
+            return KcResourceCreateResponse.Schema().load(response.json())
+        else:
+            raise Exception(
+                f"Got {response.status_code} status code while making request PUT {url}\nRequest body: {data}\nResponse body: {response.text}"
+            )
+
+    def create(self, data: dict) -> KcResourceCreateResponse:
+        """Left for compatibility! Use create_or_update instead.
+
+        Args:
+            data: see `create_or_update`.
+        """
+        return self.create_or_update(data)
+
+    def update(self, data: dict) -> KcResourceUpdateResponse:
+        """Left for compatibility! Use create_or_update instead.
+
+        Args:
+            data: see `create_or_update`.
+        """
+        return self.create_or_update(data)
+
+
+class KcClient:
+    """Top-level Kvindo Cloud API client.
+
+    Construct once with a token, then access a per-type `KcResourceClient` via the
+    attributes below (e.g. `KcClient(token).vms.get_by_labels(...)`).
+
+    See https://cloud-api.kvindo.ru/swagger/index.html. The resource surface
+    mirrors the maintained C# client KvindoCloud.Api/KvindoCloudClient.cs.
+    """
+
+    # Compute
+    vms: KcResourceClient
+    vm_on_off_maintenance_actions: KcResourceClient
+    vm_recurrent_command_maintenance_actions: KcResourceClient
+    volumes: KcResourceClient
+    volume_attachments: KcResourceClient
+    images: KcResourceClient
+    image_schedules: KcResourceClient
+    ssh_keys: KcResourceClient
+    ssh_private_keys: KcResourceClient
+    certificates: KcResourceClient
+
+    # Networking
+    floating_ips: KcResourceClient
+    vpcs: KcResourceClient
+    vpc_subnets: KcResourceClient
+    vpc_peerings: KcResourceClient
+    vpc_peering_peers: KcResourceClient
+    vpc_peering_external_peers: KcResourceClient
+    route_tables: KcResourceClient
+    route_table_attachments: KcResourceClient
+    route_table_routes: KcResourceClient
+    security_groups: KcResourceClient
+    nat_gateways: KcResourceClient
+
+    # Load balancer
+    load_balancers: KcResourceClient
+    load_balancer_http_listeners: KcResourceClient
+    load_balancer_http_listener_rules: KcResourceClient
+    load_balancer_https_listeners: KcResourceClient
+    load_balancer_https_listener_rules: KcResourceClient
+    load_balancer_tcp_listeners: KcResourceClient
+    load_balancer_tcp_listener_rules: KcResourceClient
+    load_balancer_udp_listeners: KcResourceClient
+    load_balancer_udp_listener_rules: KcResourceClient
+    load_balancer_tls_listeners: KcResourceClient
+    load_balancer_tls_listener_rules: KcResourceClient
+    load_balancer_target_groups: KcResourceClient
+    load_balancer_target_group_service_discovery_targets: KcResourceClient
+    load_balancer_target_group_static_targets: KcResourceClient
+
+    # S3
+    s3_buckets: KcResourceClient
+    s3_users: KcResourceClient
+    s3_user_access_policies: KcResourceClient
+
+    # Managed services
+    kubernetes: KcResourceClient
+    kubernetes_node_groups: KcResourceClient
+    kubernetes_users: KcResourceClient
+    kubernetes_user_roles: KcResourceClient
+    postgresqls: KcResourceClient
+    postgresql_standalones: KcResourceClient
+    postgresql_node_groups: KcResourceClient
+    postgresql_parameters_sets: KcResourceClient
+    etcd: KcResourceClient
+    etcd_node_group: KcResourceClient
+    open_vpns: KcResourceClient
+    open_vpn_users: KcResourceClient
+    open_vpn_user_settings: KcResourceClient
+    gitlabs: KcResourceClient
+    gitlab_runners: KcResourceClient
+    grafanas: KcResourceClient
+    victoria_metrics: KcResourceClient
+    ollamas: KcResourceClient
+
+    # IaM / org
+    folders: KcResourceClient
+    hosting_providers: KcResourceClient
+    access_policies: KcResourceClient
+    users: KcResourceClient
+    user_tokens: KcResourceClient
+    billing_accounts: KcResourceClient
+    quotas: KcResourceClient
+    quota_change_requests: KcResourceClient
+    support_plans: KcResourceClient
+    support_tickets: KcResourceClient
+    support_ticket_comments: KcResourceClient
+    support_ticket_comment_attachments: KcResourceClient
+    transactions: KcResourceClient
+
+    def __init__(
+        self,
+        token: str,
+        api_url: str = "https://cloud-api.kvindo.ru",
+        log_extra: dict = None,
+    ):
+        """
+        Args:
+            token: the bearer token; a leading "Bearer " prefix is stripped if present.
+            api_url: base URL of the Cloud API (no trailing slash).
+            log_extra: optional dict merged into every debug log record's `extra`;
+                propagated to every per-resource client.
+        """
+        self.__log_extra = log_extra if log_extra is not None else {}
+        self.__token = token.replace("Bearer ", "")
+        self.__api_url = api_url
+        # Cached response of get_transaction_collection_keys (lazy, fetched once).
+        self._transaction_collection_keys = None
+
+        def _r(resource_type: str) -> KcResourceClient:
+            """Build a per-type client sharing this client's token/url/log_extra."""
+            return KcResourceClient(resource_type, token, api_url, log_extra)
+
+        # Compute
+        self.vms = _r("vm")
+        self.vm_on_off_maintenance_actions = _r("vm-on-off-maintenance-action")
+        self.vm_recurrent_command_maintenance_actions = _r("vm-recurrent-command-maintenance-action")
+        self.volumes = _r("volume")
+        self.volume_attachments = _r("volume-attachment")
+        self.images = _r("image")
+        self.image_schedules = _r("image-schedule")
+        self.ssh_keys = _r("ssh-key")
+        self.ssh_private_keys = _r("ssh-private-key")
+        self.certificates = _r("certificate")
+
+        # Networking
+        self.floating_ips = _r("floating-ip")
+        self.vpcs = _r("vpc")
+        self.vpc_subnets = _r("vpc-subnet")
+        self.vpc_peerings = _r("vpc-peering")
+        self.vpc_peering_peers = _r("vpc-peering-peer")
+        self.vpc_peering_external_peers = _r("vpc-peering-external-peer")
+        self.route_tables = _r("route-table")
+        self.route_table_attachments = _r("route-table-attachment")
+        self.route_table_routes = _r("route-table-route")
+        self.security_groups = _r("security-group")
+        self.nat_gateways = _r("nat-gateway")
+
+        # Load balancer
+        self.load_balancers = _r("loadbalancer")
+        self.load_balancer_http_listeners = _r("loadbalancer-http-listener")
+        self.load_balancer_http_listener_rules = _r("loadbalancer-http-listener-rule")
+        self.load_balancer_https_listeners = _r("loadbalancer-https-listener")
+        self.load_balancer_https_listener_rules = _r("loadbalancer-https-listener-rule")
+        self.load_balancer_tcp_listeners = _r("loadbalancer-tcp-listener")
+        self.load_balancer_tcp_listener_rules = _r("loadbalancer-tcp-listener-rule")
+        self.load_balancer_udp_listeners = _r("loadbalancer-udp-listener")
+        self.load_balancer_udp_listener_rules = _r("loadbalancer-udp-listener-rule")
+        self.load_balancer_tls_listeners = _r("loadbalancer-tls-listener")
+        self.load_balancer_tls_listener_rules = _r("loadbalancer-tls-listener-rule")
+        self.load_balancer_target_groups = _r("loadbalancer-target-group")
+        self.load_balancer_target_group_service_discovery_targets = _r("loadbalancer-target-group-service-discovery-target")
+        self.load_balancer_target_group_static_targets = _r("loadbalancer-target-group-static-target")
+
+        # S3
+        self.s3_buckets = _r("s3-bucket")
+        self.s3_users = _r("s3-user")
+        self.s3_user_access_policies = _r("s3-user-access-policy")
+
+        # Managed services
+        self.kubernetes = _r("kubernetes")
+        self.kubernetes_node_groups = _r("kubernetes-node-group")
+        self.kubernetes_users = _r("kubernetes-user")
+        self.kubernetes_user_roles = _r("kubernetes-user-role")
+        self.postgresqls = _r("postgresql")
+        self.postgresql_standalones = _r("postgresql-standalone")
+        self.postgresql_node_groups = _r("postgresql-node-group")
+        self.postgresql_parameters_sets = _r("postgresql-parameters-set")
+        self.etcd = _r("etcd")
+        self.etcd_node_group = _r("etcd-node-group")
+        self.open_vpns = _r("open-vpn")
+        self.open_vpn_users = _r("open-vpn-user")
+        self.open_vpn_user_settings = _r("open-vpn-user-settings")
+        self.gitlabs = _r("gitlab")
+        self.gitlab_runners = _r("gitlab-runner")
+        self.grafanas = _r("grafana")
+        self.victoria_metrics = _r("victoria-metrics")
+        self.ollamas = _r("ollama")
+
+        # IaM / org
+        self.folders = _r("folder")
+        self.hosting_providers = _r("hosting-provider")
+        self.access_policies = _r("access-policy")
+        self.users = _r("user")
+        self.user_tokens = _r("user-token")
+        self.billing_accounts = _r("billing-account")
+        self.quotas = _r("quota")
+        self.quota_change_requests = _r("quota-change-request")
+        self.support_plans = _r("support-plan")
+        self.support_tickets = _r("support-ticket")
+        self.support_ticket_comments = _r("support-ticket-comment")
+        self.support_ticket_comment_attachments = _r("support-ticket-comment-attachment")
+        self.transactions = _r("transaction")
+
+    def get_transaction_collection_keys(self) -> list:
+        """Return the transaction-spec collection keys (the child-resource
+        collection names accepted inside an OrganizationTransaction).
+
+        Fetched once from `/api/v1/internal/transaction-spec` and cached on the
+        instance for subsequent calls.
+
+        Returns:
+            The raw list returned by the transaction-spec endpoint.
+        """
+        if self._transaction_collection_keys is None:
+            url = f"{self.__api_url}/api/v1/internal/transaction-spec"
+            headers = {"Authorization": f"Bearer {self.__token}"}
+            response = create_http_client_with_retries().get(url, headers=headers)
+            self._transaction_collection_keys = response.json()
+        return self._transaction_collection_keys

kc_sdk_python-0.1.0/kc_sdk_python.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: kc-sdk-python
+Version: 0.1.0
+Summary: Python SDK / client for the Kvindo Cloud API
+Author: Kvindo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kvindo/kc-sdk-python
+Project-URL: Repository, https://github.com/Kvindo/kc-sdk-python
+Keywords: kvindo,cloud,sdk,client,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: marshmallow-dataclass
+Requires-Dist: py-ulid
+Dynamic: license-file
+
+# kc-sdk-python
+
+Python SDK / client for the **Kvindo Cloud API**.
+
+A thin, typed client over the REST API: one resource client per resource type
+(VMs, volumes, load balancers, kubernetes, S3, VPCs, …), all sharing the same
+create / read / update / delete / list contract.
+
+## Install
+
+```sh
+pip install kc-sdk-python
+```
+
+Dependencies: `requests`, `marshmallow-dataclass`, `py-ulid`.
+
+## Usage
+
+```python
+from kc_api import KcClient
+
+client = KcClient("YOUR_API_TOKEN")  # api_url defaults to https://cloud-api.kvindo.ru
+
+# List (label-filtered, paginated)
+resp = client.vms.get_by_labels({"env": "prod"}, max_page_size=50)
+for vm in resp.resources:
+    print(vm["metadata"]["name"])
+
+# Read one
+vm = client.vms.read("01H...")
+print(vm.resource)
+
+# Create / update (async) then wait for it to reconcile
+created = client.vms.create_or_update({
+    "metadata": {"name": "my-vm", "folderId": "01H..."},
+    "spec": {"offerId": "g3-1c2-100", "state": "running", ...},
+})
+status = client.vms.wait_request_satisfied(created.requestId, timeout_seconds=300)
+assert status.succeeded
+
+# Delete (optionally block until reconciled)
+client.vms.delete("01H...", wait=True)
+```
+
+Create / update / delete are **asynchronous**: they return a `requestId`; poll
+`read_request(requestId)` or use `wait_request_satisfied(...)`. Every response
+object carries `errorMessage` / `errorCode` (a typed `KcApi*ErrorCode`) which are
+`None` on success.
+
+### Available resources
+
+`KcClient` exposes one `KcResourceClient` per type, e.g. `client.vms`,
+`client.volumes`, `client.s3_buckets`, `client.kubernetes`,
+`client.load_balancers`, `client.vpcs`, `client.postgresql_standalones`,
+`client.folders`, `client.transactions`, … (the surface mirrors the official
+Kvindo Cloud API).
+
+## License
+
+MIT

kc_sdk_python-0.1.0/kc_sdk_python.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+kc_api.py
+pyproject.toml
+kc_sdk_python.egg-info/PKG-INFO
+kc_sdk_python.egg-info/SOURCES.txt
+kc_sdk_python.egg-info/dependency_links.txt
+kc_sdk_python.egg-info/requires.txt
+kc_sdk_python.egg-info/top_level.txt

kc_sdk_python-0.1.0/kc_sdk_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kc_sdk_python-0.1.0/kc_sdk_python.egg-info/requires.txt

@@ -0,0 +1,3 @@
+requests
+marshmallow-dataclass
+py-ulid

kc_sdk_python-0.1.0/kc_sdk_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+kc_api

kc_sdk_python-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kc-sdk-python"
+version = "0.1.0"
+description = "Python SDK / client for the Kvindo Cloud API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kvindo" }]
+keywords = ["kvindo", "cloud", "sdk", "client", "api"]
+dependencies = [
+    "requests",
+    "marshmallow-dataclass",
+    "py-ulid",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://github.com/Kvindo/kc-sdk-python"
+Repository = "https://github.com/Kvindo/kc-sdk-python"
+
+[tool.setuptools]
+py-modules = ["kc_api"]

kc_sdk_python-0.1.0/setup.cfg

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