antfly-sdk 0.0.2.dev2__py3-none-any.whl

antfly/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# JetBrains
+.idea/
+
+/coverage.xml
+/.coverage

antfly/README.md

@@ -0,0 +1,124 @@
+# antfly
+A client library for accessing Antfly Public API
+
+## Usage
+First, create a client:
+
+```python
+from client_generated import Client
+
+client = Client(base_url="https://api.example.com")
+```
+
+If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:
+
+```python
+from client_generated import AuthenticatedClient
+
+client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
+```
+
+Now call your endpoint and use your models:
+
+```python
+from client_generated.models import MyDataModel
+from client_generated.api.my_tag import get_my_data_model
+from client_generated.types import Response
+
+with client as client:
+    my_data: MyDataModel = get_my_data_model.sync(client=client)
+    # or if you need more info (e.g. status_code)
+    response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
+```
+
+Or do the same thing with an async version:
+
+```python
+from client_generated.models import MyDataModel
+from client_generated.api.my_tag import get_my_data_model
+from client_generated.types import Response
+
+async with client as client:
+    my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
+    response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
+```
+
+By default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken",
+    verify_ssl="/path/to/certificate_bundle.pem",
+)
+```
+
+You can also disable certificate validation altogether, but beware that **this is a security risk**.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken", 
+    verify_ssl=False
+)
+```
+
+Things to know:
+1. Every path/method combo becomes a Python module with four functions:
+    1. `sync`: Blocking request that returns parsed data (if successful) or `None`
+    1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
+    1. `asyncio`: Like `sync` but async instead of blocking
+    1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
+
+1. All path/query params, and bodies become method arguments.
+1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
+1. Any endpoint which did not have a tag will be in `client_generated.api.default`
+
+## Advanced customizations
+
+There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info. You can also customize the underlying `httpx.Client` or `httpx.AsyncClient` (depending on your use-case):
+
+```python
+from client_generated import Client
+
+def log_request(request):
+    print(f"Request event hook: {request.method} {request.url} - Waiting for response")
+
+def log_response(response):
+    request = response.request
+    print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")
+
+client = Client(
+    base_url="https://api.example.com",
+    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
+)
+
+# Or get the underlying httpx client to modify directly with client.get_httpx_client() or client.get_async_httpx_client()
+```
+
+You can even set the httpx client directly, but beware that this will override any existing settings (e.g., base_url):
+
+```python
+import httpx
+from client_generated import Client
+
+client = Client(
+    base_url="https://api.example.com",
+)
+# Note that base_url needs to be re-set, as would any shared cookies, headers, etc.
+client.set_httpx_client(httpx.Client(base_url="https://api.example.com", proxies="http://localhost:8030"))
+```
+
+## Building / publishing this package
+This project uses [Poetry](https://python-poetry.org/) to manage dependencies  and packaging.  Here are the basics:
+1. Update the metadata in pyproject.toml (e.g. authors, version)
+1. If you're using a private repository, configure it with Poetry
+    1. `poetry config repositories.<your-repository-name> <url-to-your-repository>`
+    1. `poetry config http-basic.<your-repository-name> <username> <password>`
+1. Publish the client with `poetry publish --build -r <your-repository-name>` or, if for public PyPI, just `poetry publish --build`
+
+If you want to install this client into another project without publishing it (e.g. for development) then:
+1. If that project **is using Poetry**, you can simply do `poetry add <path-to-this-client>` from that project
+1. If that project is not using Poetry:
+    1. Build a wheel with `poetry build -f wheel`
+    1. Install that wheel from the other project `pip install <path-to-wheel>`

antfly/__init__.py

@@ -0,0 +1,20 @@
+"""
+Antfly SDK - Python client for Antfly distributed key-value store and search engine.
+"""
+
+from .client import AntflyClient
+from .client_generated.models.embedding_type_1 import EmbeddingType1 as SparseEmbedding
+from .client_generated.models.embedding_type_3 import EmbeddingType3 as PackedSparseEmbedding
+from .exceptions import AntflyAuthError, AntflyConnectionError, AntflyException
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AntflyClient",
+    "AntflyException",
+    "AntflyConnectionError",
+    "AntflyAuthError",
+    "SparseEmbedding",
+    "PackedSparseEmbedding",
+    "__version__",
+]

antfly/client.py

@@ -0,0 +1,260 @@
+"""Main client interface for Antfly SDK."""
+
+import base64
+from typing import Any, Optional, cast
+from urllib.parse import quote
+
+from httpx import Timeout
+
+from antfly.client_generated import Client
+from antfly.client_generated.api.data_operations import (
+    batch_write as batch,
+)
+from antfly.client_generated.api.data_operations import (
+    lookup_key,
+)
+from antfly.client_generated.client import AuthenticatedClient
+from antfly.client_generated.models import (
+    BatchRequest,
+    BatchRequestInserts,
+    Error,
+)
+from antfly.client_generated.types import UNSET
+
+from .exceptions import AntflyException
+
+
+def normalize_base_url(base_url: str) -> str:
+    """Return the Antfly server root URL for local or CloudAF endpoints."""
+    trimmed = base_url.rstrip("/")
+    if trimmed.endswith("/db/v1"):
+        return trimmed[: -len("/db/v1")]
+    if trimmed.endswith("/auth/v1"):
+        return trimmed[: -len("/auth/v1")]
+    if trimmed.endswith("/ai/v1"):
+        return trimmed[: -len("/ai/v1")]
+    return trimmed
+
+
+class AntflyClient:
+    """High-level client for interacting with Antfly database."""
+
+    def __init__(
+        self,
+        base_url: str,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        api_key: Optional[tuple[str, str]] = None,
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize Antfly client.
+
+        Supports three authentication methods (mutually exclusive):
+        - Basic auth: provide ``username`` and ``password``
+        - API key: provide ``api_key`` as ``(key_id, key_secret)``
+        - Token: provide ``token``
+
+        Args:
+            base_url: Base URL of the Antfly server or CloudAF proxy
+            username: Username for basic authentication (optional)
+            password: Password for basic authentication (optional)
+            api_key: Tuple of (key_id, key_secret) for API key authentication (optional)
+            token: Token string for token authentication (optional)
+            timeout: Request timeout in seconds
+        """
+        self.base_url = normalize_base_url(base_url)
+
+        httpx_args: dict[str, Any] = {}
+
+        if api_key is not None:
+            key_id, key_secret = api_key
+            encoded = base64.b64encode(f"{key_id}:{key_secret}".encode()).decode()
+            self._client = AuthenticatedClient(
+                base_url=self.base_url,
+                token=encoded,
+                prefix="ApiKey",
+                timeout=Timeout(timeout),
+                httpx_args=httpx_args,
+            )
+        elif token is not None:
+            self._client = AuthenticatedClient(
+                base_url=self.base_url,
+                token=token,
+                prefix="Bearer",
+                timeout=Timeout(timeout),
+                httpx_args=httpx_args,
+            )
+        else:
+            if username and password:
+                httpx_args["auth"] = (username, password)
+
+            self._client = Client(
+                base_url=self.base_url,
+                timeout=Timeout(timeout),
+                httpx_args=httpx_args,
+            )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make an HTTP request using the underlying httpx client.
+
+        Args:
+            method: HTTP method
+            path: URL path (relative to base_url)
+            **kwargs: Additional arguments passed to httpx
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            AntflyException: If the request fails
+        """
+        response = self._client.get_httpx_client().request(method, path, **kwargs)
+        if response.status_code >= 400:
+            try:
+                error_body = response.json()
+                msg = error_body.get("error", response.text)
+            except Exception:
+                msg = response.text
+            raise AntflyException(f"Request failed ({response.status_code}): {msg}")
+        if response.status_code == 204:
+            return None
+        return response.json()
+
+    # Table operations
+
+    def create_table(
+        self,
+        name: str,
+        num_shards: Optional[int] = None,
+        indexes: Optional[dict[str, Any]] = None,
+        schema: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """
+        Create a new table.
+
+        Args:
+            name: Name of the table
+            num_shards: Number of shards for the table
+            indexes: Index configurations
+            schema: Table schema definition
+
+        Returns:
+            Created table object as a dictionary
+
+        Raises:
+            AntflyException: If table creation fails
+        """
+        body: dict[str, Any] = {}
+        if num_shards is not None:
+            body["num_shards"] = num_shards
+        if indexes is not None:
+            body["indexes"] = indexes
+        if schema is not None:
+            body["schema"] = schema
+
+        return self._request(
+            "POST",
+            f"/db/v1/tables/{quote(name, safe='')}",
+            json=body,
+        )
+
+    def list_tables(self) -> list[dict[str, Any]]:
+        """
+        List all tables.
+
+        Returns:
+            List of table status objects
+
+        Raises:
+            AntflyException: If listing tables fails
+        """
+        return self._request("GET", "/db/v1/tables")
+
+    def get_table(self, name: str) -> dict[str, Any]:
+        """
+        Get table details.
+
+        Args:
+            name: Name of the table
+
+        Returns:
+            Table status object as a dictionary
+
+        Raises:
+            AntflyException: If getting table fails
+        """
+        return self._request("GET", f"/db/v1/tables/{quote(name, safe='')}")
+
+    def drop_table(self, name: str) -> None:
+        """
+        Drop a table.
+
+        Args:
+            name: Name of the table to drop
+
+        Raises:
+            AntflyException: If dropping table fails
+        """
+        self._request("DELETE", f"/db/v1/tables/{quote(name, safe='')}")
+
+    def get(self, table: str, key: str) -> dict[str, Any]:
+        """
+        Get a single record by key.
+
+        Args:
+            table: Table name
+            key: Record key
+
+        Returns:
+            Record data
+
+        Raises:
+            AntflyException: If lookup fails
+        """
+        response = lookup_key.sync(
+            table_name=table,
+            key=key,
+            client=cast(AuthenticatedClient, self._client),
+        )
+
+        if isinstance(response, Error):
+            raise AntflyException(f"Failed to get key '{key}' from table '{table}': {response.error}")
+        if response is None:
+            raise AntflyException(f"Failed to get key '{key}' from table '{table}'")
+
+        return response.to_dict()
+
+    def batch(
+        self,
+        table: str,
+        inserts: Optional[dict[str, dict[str, Any]]] = None,
+        deletes: Optional[list[str]] = None,
+    ) -> None:
+        """
+        Perform batch operations on a table.
+
+        Args:
+            table: Table name
+            inserts: Dictionary of key-value pairs to insert
+            deletes: List of keys to delete
+
+        Raises:
+            AntflyException: If batch operation fails
+        """
+        request = BatchRequest(
+            inserts=cast(BatchRequestInserts, inserts) if inserts is not None else UNSET,
+            deletes=deletes or [],
+        )
+
+        response = batch.sync(
+            table_name=table,
+            client=cast(AuthenticatedClient, self._client),
+            body=request,
+        )
+
+        if isinstance(response, Error):
+            raise AntflyException(f"Batch operation failed for table '{table}': {response.error}")
+        if response is None:
+            raise AntflyException(f"Batch operation failed for table '{table}'")

antfly/client_generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Antfly Public API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

antfly/client_generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

antfly/client_generated/api/api_key/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

antfly/client_generated/api/api_key/create_api_key.py

@@ -0,0 +1,209 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.api_key_with_secret import ApiKeyWithSecret
+from ...models.create_api_key_request import CreateApiKeyRequest
+from ...models.error import Error
+from ...types import Response
+
+
+def _get_kwargs(
+    user_name: str,
+    *,
+    body: CreateApiKeyRequest,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/auth/v1/users/{user_name}/api-keys".format(
+            user_name=quote(str(user_name), safe=""),
+        ),
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> ApiKeyWithSecret | Error | None:
+    if response.status_code == 201:
+        response_201 = ApiKeyWithSecret.from_dict(response.json())
+
+        return response_201
+
+    if response.status_code == 400:
+        response_400 = Error.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 403:
+        response_403 = Error.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = Error.from_dict(response.json())
+
+        return response_404
+
+    if response.status_code == 500:
+        response_500 = Error.from_dict(response.json())
+
+        return response_500
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[ApiKeyWithSecret | Error]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    user_name: str,
+    *,
+    client: AuthenticatedClient,
+    body: CreateApiKeyRequest,
+) -> Response[ApiKeyWithSecret | Error]:
+    """Create a new API key
+
+     Creates a new API key for the specified user. The cleartext secret is returned only in this
+    response.
+
+    Args:
+        user_name (str):  Example: johndoe.
+        body (CreateApiKeyRequest): Request to create a new API key.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiKeyWithSecret | Error]
+    """
+
+    kwargs = _get_kwargs(
+        user_name=user_name,
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    user_name: str,
+    *,
+    client: AuthenticatedClient,
+    body: CreateApiKeyRequest,
+) -> ApiKeyWithSecret | Error | None:
+    """Create a new API key
+
+     Creates a new API key for the specified user. The cleartext secret is returned only in this
+    response.
+
+    Args:
+        user_name (str):  Example: johndoe.
+        body (CreateApiKeyRequest): Request to create a new API key.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiKeyWithSecret | Error
+    """
+
+    return sync_detailed(
+        user_name=user_name,
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    user_name: str,
+    *,
+    client: AuthenticatedClient,
+    body: CreateApiKeyRequest,
+) -> Response[ApiKeyWithSecret | Error]:
+    """Create a new API key
+
+     Creates a new API key for the specified user. The cleartext secret is returned only in this
+    response.
+
+    Args:
+        user_name (str):  Example: johndoe.
+        body (CreateApiKeyRequest): Request to create a new API key.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiKeyWithSecret | Error]
+    """
+
+    kwargs = _get_kwargs(
+        user_name=user_name,
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    user_name: str,
+    *,
+    client: AuthenticatedClient,
+    body: CreateApiKeyRequest,
+) -> ApiKeyWithSecret | Error | None:
+    """Create a new API key
+
+     Creates a new API key for the specified user. The cleartext secret is returned only in this
+    response.
+
+    Args:
+        user_name (str):  Example: johndoe.
+        body (CreateApiKeyRequest): Request to create a new API key.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiKeyWithSecret | Error
+    """
+
+    return (
+        await asyncio_detailed(
+            user_name=user_name,
+            client=client,
+            body=body,
+        )
+    ).parsed