vikingdb-python-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

{vikingdb_python_sdk-0.1.0 → vikingdb_python_sdk-0.1.2}/PKG-INFO

@@ -1,16 +1,14 @@
 Metadata-Version: 2.4
 Name: vikingdb-python-sdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: vikingdb Python SDK
-License: Apache-2.0
+License-Expression: Apache-2.0
 Project-URL: Documentation, https://github.com/volcengine/volc-vikingdb-python-sdk/README.md
 Project-URL: Source, https://github.com/volcengine/volc-vikingdb-python-sdk
 Keywords: vikingdb,vector,bytedance,volcengine,sdk
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -44,7 +42,7 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 Clone the repository and install the SDK in editable mode:
 
 ```bash
-pip install -e .
+uv add vikingdb-python-sdk
 ```
 
 > **Dependencies:** The SDK relies on `requests`, `pydantic>=2.5`, and the Volcano Engine base SDK (`volcengine`) for request signing.
@@ -54,34 +52,24 @@ pip install -e .
 #### Vector Database
 
 ```python
+import os
 from vikingdb import IAM
-from vikingdb.vector import UpsertDataRequest, VikingVector
+from vikingdb.vector import SearchByRandomRequest, VikingVector
 
-auth = IAM(ak="<AK>", sk="<SK>")
+auth = IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]) 
 client = VikingVector(
-    host="api.vector.bytedance.com",
-    region="cn-beijing",
+    host=os.environ["VIKINGDB_HOST"],
+    region=os.environ["VIKINGDB_REGION"],
     auth=auth,
     scheme="https",
     timeout=30,
 )
-
-collection = client.collection(collection_name="demo_collection")
-index = client.index(collection_name="demo_collection", index_name="demo_index")
-embedding = client.embedding()
-
-# Upsert documents into a collection
-upsert_request = UpsertDataRequest(
-    data=[
-        {"title": "Demo Chapter", "paragraph": 1, "score": 42.0, "text": "hello vikingdb"},
-    ]
+index = client.index(
+    collection_name=os.environ["VIKINGDB_COLLECTION"],
+    index_name=os.environ["VIKINGDB_INDEX"],
 )
-response = collection.upsert(upsert_request)
-print("request_id:", response.request_id, "result:", response.result)
-
-# Run a quick search
-search_response = index.search_by_random({"limit": 1})
-print("search hits:", len(search_response.result.data) if search_response.result else 0)
+resp = index.search_by_random(SearchByRandomRequest(limit=1))
+print(f"request_id={resp.request_id} hits={len(resp.result.data or [])}")
 ```
 
 #### Memory Management
@@ -128,15 +116,17 @@ print("search results:", result)
 
 ### Example Guides
 
-#### Vector Examples (Pytest)
+#### Vector Examples
 
-The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`E1`–`E5`). Each test connects to a live VikingDB environment and exercises a specific workflow.
+The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`1`–`6`). Each test connects to a live VikingDB environment and exercises a specific workflow.
 
 1. Set the required environment variables (or create a `.env` file in the project root):
 
    ```
    VIKINGDB_AK=your-access-key
    VIKINGDB_SK=your-secret-key
+   VIKINGDB_COLLECTION=demo_collection
+   VIKINGDB_INDEX=demo_index
    # Optional:
    # VIKINGDB_PROJECT=project-name
    # VIKINGDB_RESOURCE_ID=resource-id
@@ -152,13 +142,13 @@ The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`
 2. Install pytest (if not already available):
 
    ```bash
-   pip install pytest
+   uv add --dev pytest
    ```
 
 3. Execute the guides:
 
    ```bash
-   pytest examples/vector -k guide
+   uv run pytest examples/vector -k scenario
    ```
 
 Each scenario writes temporary documents using unique session tags and cleans them up afterwards.
@@ -223,9 +213,9 @@ vikingdb/
 
 examples/
 ├── vector/              # Vector integration guides (pytest)
-│   ├── E1_connectivity_test.py
-│   ├── E2_collection_lifecycle_test.py
-│   ├── E3_*_test.py     # Search and indexing examples
+│   ├── 1_connectivity_test.py
+│   ├── 2_collection_lifecycle_test.py
+│   ├── 3_*_test.py     # Search and indexing examples
 │   └── ...
 └── memory/              # Memory usage examples
     ├── 01_init_client_and_collection.py

{vikingdb_python_sdk-0.1.0 → vikingdb_python_sdk-0.1.2}/README.md

@@ -14,7 +14,7 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 Clone the repository and install the SDK in editable mode:
 
 ```bash
-pip install -e .
+uv add vikingdb-python-sdk
 ```
 
 > **Dependencies:** The SDK relies on `requests`, `pydantic>=2.5`, and the Volcano Engine base SDK (`volcengine`) for request signing.
@@ -24,34 +24,24 @@ pip install -e .
 #### Vector Database
 
 ```python
+import os
 from vikingdb import IAM
-from vikingdb.vector import UpsertDataRequest, VikingVector
+from vikingdb.vector import SearchByRandomRequest, VikingVector
 
-auth = IAM(ak="<AK>", sk="<SK>")
+auth = IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]) 
 client = VikingVector(
-    host="api.vector.bytedance.com",
-    region="cn-beijing",
+    host=os.environ["VIKINGDB_HOST"],
+    region=os.environ["VIKINGDB_REGION"],
     auth=auth,
     scheme="https",
     timeout=30,
 )
-
-collection = client.collection(collection_name="demo_collection")
-index = client.index(collection_name="demo_collection", index_name="demo_index")
-embedding = client.embedding()
-
-# Upsert documents into a collection
-upsert_request = UpsertDataRequest(
-    data=[
-        {"title": "Demo Chapter", "paragraph": 1, "score": 42.0, "text": "hello vikingdb"},
-    ]
+index = client.index(
+    collection_name=os.environ["VIKINGDB_COLLECTION"],
+    index_name=os.environ["VIKINGDB_INDEX"],
 )
-response = collection.upsert(upsert_request)
-print("request_id:", response.request_id, "result:", response.result)
-
-# Run a quick search
-search_response = index.search_by_random({"limit": 1})
-print("search hits:", len(search_response.result.data) if search_response.result else 0)
+resp = index.search_by_random(SearchByRandomRequest(limit=1))
+print(f"request_id={resp.request_id} hits={len(resp.result.data or [])}")
 ```
 
 #### Memory Management
@@ -98,15 +88,17 @@ print("search results:", result)
 
 ### Example Guides
 
-#### Vector Examples (Pytest)
+#### Vector Examples
 
-The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`E1`–`E5`). Each test connects to a live VikingDB environment and exercises a specific workflow.
+The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`1`–`6`). Each test connects to a live VikingDB environment and exercises a specific workflow.
 
 1. Set the required environment variables (or create a `.env` file in the project root):
 
    ```
    VIKINGDB_AK=your-access-key
    VIKINGDB_SK=your-secret-key
+   VIKINGDB_COLLECTION=demo_collection
+   VIKINGDB_INDEX=demo_index
    # Optional:
    # VIKINGDB_PROJECT=project-name
    # VIKINGDB_RESOURCE_ID=resource-id
@@ -122,13 +114,13 @@ The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`
 2. Install pytest (if not already available):
 
    ```bash
-   pip install pytest
+   uv add --dev pytest
    ```
 
 3. Execute the guides:
 
    ```bash
-   pytest examples/vector -k guide
+   uv run pytest examples/vector -k scenario
    ```
 
 Each scenario writes temporary documents using unique session tags and cleans them up afterwards.
@@ -193,9 +185,9 @@ vikingdb/
 
 examples/
 ├── vector/              # Vector integration guides (pytest)
-│   ├── E1_connectivity_test.py
-│   ├── E2_collection_lifecycle_test.py
-│   ├── E3_*_test.py     # Search and indexing examples
+│   ├── 1_connectivity_test.py
+│   ├── 2_collection_lifecycle_test.py
+│   ├── 3_*_test.py     # Search and indexing examples
 │   └── ...
 └── memory/              # Memory usage examples
     ├── 01_init_client_and_collection.py

{vikingdb_python_sdk-0.1.0 → vikingdb_python_sdk-0.1.2}/pyproject.toml

@@ -8,14 +8,12 @@ dynamic = ["version"]
 description = "vikingdb Python SDK"
 readme = "README.md"
 requires-python = ">=3.8"
-license = {text = "Apache-2.0"}
+license = "Apache-2.0"
 keywords = ["vikingdb", "vector", "bytedance", "volcengine", "sdk"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
@@ -46,4 +44,5 @@ version = {attr = "vikingdb.version.__version__"}
 [dependency-groups]
 dev = [
     "pytest>=7.4.4",
+    "ruff>=0.14.3",
 ]

{vikingdb_python_sdk-0.1.0 → vikingdb_python_sdk-0.1.2}/vikingdb/__init__.py

@@ -17,6 +17,7 @@ from .memory import (
     VikingMem,
     Collection,
 )
+from .version import __version__
 __all__ = [
     "IAM",
     "APIKey",
@@ -29,4 +30,5 @@ __all__ = [
     "memory",
     "VikingMem",
     "Collection",
+    "__version__",
 ]

{vikingdb_python_sdk-0.1.0 → vikingdb_python_sdk-0.1.2}/vikingdb/_client.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 from abc import ABC, abstractmethod
+from json import JSONDecodeError
 from typing import Any, Mapping, Optional
 
 import aiohttp
@@ -17,6 +18,13 @@ from volcengine.base.Request import Request
 from volcengine.base.Service import Service
 
 from .auth import Auth
+from .exceptions import (
+    DEFAULT_UNKNOWN_ERROR_CODE,
+    VikingAPIException,
+)
+
+
+_REQUEST_ID_HEADER = "X-Tt-Logid"
 
 
 class Client(Service, ABC):
@@ -73,7 +81,7 @@ class Client(Service, ABC):
     def prepare_request(self, api_info: ApiInfo, params: Optional[Mapping[str, Any]], doseq: int = 0):
         """Prepare a volcengine request without adding implicit headers."""
         request = Request()
-        request.set_shema(self.service_info.scheme)
+        request.set_schema(self.service_info.scheme)
         request.set_method(api_info.method)
         request.set_host(self.service_info.host)
         request.set_path(api_info.path)
@@ -113,6 +121,9 @@ class Client(Service, ABC):
         self.auth_provider.sign_request(request)
         url = request.build()
         
+        request_id_value = request.headers.get(_REQUEST_ID_HEADER)
+        request_id = str(request_id_value) if request_id_value else "unknown"
+        
         # Use custom timeout if provided, otherwise use default
         if timeout is not None:
             request_timeout = (timeout, timeout)
@@ -122,15 +133,49 @@ class Client(Service, ABC):
                 self.service_info.socket_timeout,
             )
         
-        response = self.session.post(
-            url,
-            headers=request.headers,
-            data=request.body,
-            timeout=request_timeout,
-        )
-        if response.status_code == 200:
+        try:
+            response = self.session.post(
+                url,
+                headers=request.headers,
+                data=request.body,
+                timeout=request_timeout,
+            )
+        except Exception as exc:
+            raise VikingAPIException(
+                    DEFAULT_UNKNOWN_ERROR_CODE,
+                    request_id=request_id,
+                    message=f"failed to run session.post {api}: {exc}",
+                ) from exc
+
+        payload_text_attr = getattr(response, "text", "")
+        payload_text = payload_text_attr if isinstance(payload_text_attr, str) else ""
+        payload_text = payload_text or ""
+
+        if response.status_code != 200:
+            error = VikingAPIException.from_response(
+                payload_text,
+                request_id=request_id,
+                status_code=response.status_code,
+            )
+            raise error
+
+        try:
             return response.json()
-        raise Exception(response.text.encode("utf-8"))
+        except (ValueError, JSONDecodeError) as exc:
+            raise VikingAPIException(
+                DEFAULT_UNKNOWN_ERROR_CODE,
+                request_id=request_id,
+                message=f"failed to decode JSON response for {api}: {exc}",
+                status_code=response.status_code,
+            ) from exc
+
+        except Exception as exc:  # pragma: no cover - defensive fallback
+            raise VikingAPIException(
+                DEFAULT_UNKNOWN_ERROR_CODE,
+                request_id=request_id,
+                message=f"unexpected error parsing response for {api}: {exc}",
+                status_code=response.status_code,
+            ) from exc
 
     async def async_json(
         self,
@@ -175,14 +220,36 @@ class Client(Service, ABC):
             )
         
         url = request.build()
-        async with aiohttp.request(
-            "POST",
-            url,
-            headers=request.headers,
-            data=request.body,
-            timeout=client_timeout,
-        ) as response:
-            payload = await response.text(encoding="utf-8")
-            if response.status == 200:
-                return json.loads(payload)
-            raise Exception(payload)
+        try:
+            async with aiohttp.request(
+                "POST",
+                url,
+                headers=request.headers,
+                data=request.body,
+                timeout=client_timeout,
+            ) as response:
+                request_id_value = response.headers.get(_REQUEST_ID_HEADER)
+                request_id = str(request_id_value) if request_id_value else "unknown"
+                payload = await response.text(encoding="utf-8")
+                if response.status != 200:
+                    error = VikingAPIException.from_response(
+                        payload,
+                        request_id=request_id,
+                        status_code=response.status,
+                    )
+                    raise error
+                try:
+                    return json.loads(payload)
+                except JSONDecodeError as exc:
+                    raise VikingAPIException(
+                        DEFAULT_UNKNOWN_ERROR_CODE,
+                        request_id=request_id,
+                        message=f"failed to decode JSON response for {api}: {exc}",
+                        status_code=response.status,
+                    ) from exc
+        except Exception as exc:
+            raise VikingAPIException(
+                    DEFAULT_UNKNOWN_ERROR_CODE,
+                    request_id=request_id,
+                    message=f"failed to run aiohttp {api}: {exc}",
+                ) from exc

vikingdb_python_sdk-0.1.2/vikingdb/exceptions.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Type, TypeVar, Union
+
+DEFAULT_UNKNOWN_ERROR_CODE: Union[int, str] = 1000028
+NETWORK_ERROR_CODE = 1001
+
+
+@dataclass
+class ParsedError:
+    code: Union[int, str]
+    request_id: str
+    message: Optional[str]
+    payload: Any
+    raw: Optional[str] = None
+
+
+def _normalize_code(value: Any, default: Union[int, str]) -> Union[int, str]:
+    if value is None:
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or default
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def parse_error_payload(payload: Any) -> ParsedError:
+    """
+    Parse a server error payload into a consistent structure.
+    
+    Supports both the legacy {"ResponseMetadata": {"Error": {...}}} format and the
+    newer flat {"code": ..., "request_id": ..., "message": ...} shape. When JSON
+    decoding fails, the raw text is preserved as the message.
+    """
+    code = DEFAULT_UNKNOWN_ERROR_CODE
+    request_id = "unknown"
+    message: Optional[str] = None
+    raw_text: Optional[str] = None
+    parsed_payload: Any = payload
+
+    if isinstance(payload, bytes):
+        raw_text = payload.decode("utf-8", errors="replace")
+    elif isinstance(payload, str):
+        raw_text = payload
+
+    if raw_text is not None:
+        try:
+            parsed_payload = json.loads(raw_text)
+        except json.JSONDecodeError:
+            message = raw_text.strip() or None
+            return ParsedError(code, request_id, message, raw_text, raw_text)
+
+    if isinstance(parsed_payload, Mapping):
+        metadata = parsed_payload.get("ResponseMetadata")
+        if isinstance(metadata, Mapping):
+            error = metadata.get("Error")
+            if isinstance(error, Mapping):
+                code_value = error.get("Code") if "Code" in error else error.get("code")
+                code = _normalize_code(code_value, code)
+                request_id = str(error.get("RequestId") or request_id)
+                if error.get("Message"):
+                    message = str(error["Message"])
+            if metadata.get("RequestId"):
+                request_id = str(metadata["RequestId"])
+        else:
+            code_value = parsed_payload.get("code")
+            if code_value is None and "Code" in parsed_payload:
+                code_value = parsed_payload.get("Code")
+            code = _normalize_code(code_value, code)
+            if parsed_payload.get("request_id"):
+                request_id = str(parsed_payload["request_id"])
+            if parsed_payload.get("message"):
+                message = str(parsed_payload["message"])
+    else:
+        if message is None and raw_text is None:
+            message = str(parsed_payload)
+
+    if raw_text is None and isinstance(parsed_payload, (dict, list)):
+        try:
+            raw_text = json.dumps(parsed_payload, ensure_ascii=False)
+        except Exception:
+            raw_text = None
+
+    return ParsedError(code, request_id, message, parsed_payload, raw_text)
+
+
+T_VikingException = TypeVar("T_VikingException", bound="VikingException")
+
+
+class VikingException(Exception):
+    """
+    Base exception for all Viking SDK errors.
+
+    Captures standard fields returned by the service for consistent error handling.
+    """
+
+    def __init__(
+        self,
+        code: Union[int, str],
+        request_id: str = "unknown",
+        message: Optional[str] = None,
+        *,
+        status_code: Optional[int] = None,
+    ) -> None:
+        self.code = code
+        self.request_id = request_id or "unknown"
+        self.status_code = status_code
+        self.message = message or f"request failed (code={self.code})"
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        status = f", http_status={self.status_code}" if self.status_code is not None else ""
+        return f"{self.message} (code={self.code}, request_id={self.request_id}{status})"
+
+    def promote(self, target_cls: Type[T_VikingException]) -> T_VikingException:
+        """
+        Promote this exception to a more specific subclass, reusing captured context.
+        """
+        if isinstance(self, target_cls):
+            return self  # type: ignore[return-value]
+        return target_cls(
+            self.code,
+            self.request_id,
+            self.message,
+            status_code=self.status_code,
+        )
+
+
+class VikingAPIException(VikingException):
+    """Raised when the remote API returns an error payload."""
+
+    @classmethod
+    def from_response(cls, payload: Any, *, request_id: Optional[str] = "unknown", status_code: Optional[int] = None) -> "VikingAPIException":
+        parsed = parse_error_payload(payload)
+        return cls(
+            parsed.code,
+            parsed.request_id or request_id,
+            parsed.message or "unknown api error",
+            status_code=status_code,
+        )
+
+
+def promote_exception(
+    exc: VikingException,
+    *,
+    exception_map: Optional[Mapping[int, Type[T_VikingException]]] = None,
+    default_cls: Type[T_VikingException],
+) -> T_VikingException:
+    """
+    Promote a VikingException to a service-specific subclass using the provided map.
+    """
+    target_cls = (exception_map or {}).get(exc.code, default_cls)
+    return exc.promote(target_cls)

{vikingdb_python_sdk-0.1.0 → vikingdb_python_sdk-0.1.2}/vikingdb/memory/client.py

@@ -6,12 +6,11 @@
 
 from __future__ import annotations
 
-import json
-
 from volcengine.ApiInfo import ApiInfo
 
 from .._client import Client
 from ..auth import Auth
+from ..exceptions import VikingException, promote_exception
 from .collection import Collection
 from .exceptions import EXCEPTION_MAP, VikingMemException
 from ..version import __version__
@@ -193,33 +192,12 @@ class VikingMem(Client):
         """
         try:
             res = self._json(api, params, body, headers=headers, timeout=timeout)
-        except Exception as e:
-            try:
-                err_msg = (
-                    e.args[0].decode("utf-8")
-                    if isinstance(e.args[0], bytes)
-                    else str(e.args[0])
-                )
-                res_json = json.loads(err_msg)
-            except:
-                raise VikingMemException(
-                    1000028, "missed", "json load res error, res:{}".format(str(e))
-                ) from None
-            if "ResponseMetadata" in res_json:
-                error = res_json["ResponseMetadata"].get("Error", {})
-                code = error.get("Code", 1000028)
-                request_id = error.get("RequestId", "unknown")
-                message = error.get("Message", None)
-                raise EXCEPTION_MAP.get(code, VikingMemException)(
-                    code, request_id, message
-                ) from None
-            else:
-                code = res_json.get("code", 1000028)
-                request_id = res_json.get("request_id", "unknown")
-                message = res_json.get("message", None)
-                raise VikingMemException(
-                    code, request_id, message
-                ) from None
+        except VikingException as exc:
+            raise promote_exception(
+                exc,
+                exception_map=EXCEPTION_MAP,
+                default_cls=VikingMemException,
+            ) from None
         if res is None:
             raise VikingMemException(
                 1000028,
@@ -241,33 +219,12 @@ class VikingMem(Client):
         """
         try:
             res = await self.async_json(api, params, body, headers=headers, timeout=timeout)
-        except Exception as e:
-            try:
-                err_msg = (
-                    e.args[0].decode("utf-8")
-                    if isinstance(e.args[0], bytes)
-                    else str(e.args[0])
-                )
-                res_json = json.loads(err_msg)
-            except:
-                raise VikingMemException(
-                    1000028, "missed", "json load res error, res:{}".format(str(e))
-                ) from None
-            if "ResponseMetadata" in res_json:
-                error = res_json["ResponseMetadata"].get("Error", {})
-                code = error.get("Code", 1000028)
-                request_id = error.get("RequestId", "unknown")
-                message = error.get("Message", None)
-                raise EXCEPTION_MAP.get(code, VikingMemException)(
-                    code, request_id, message
-                ) from None
-            else:
-                code = res_json.get("code", 1000028)
-                request_id = res_json.get("request_id", "unknown")
-                message = res_json.get("message", None)
-                raise VikingMemException(
-                    code, request_id, message
-                ) from None
+        except VikingException as exc:
+            raise promote_exception(
+                exc,
+                exception_map=EXCEPTION_MAP,
+                default_cls=VikingMemException,
+            ) from None
         if res is None:
             raise VikingMemException(
                 1000028,