altertable-lakehouse 0.2.0__tar.gz

altertable_lakehouse-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Altertable
+
+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.

altertable_lakehouse-0.2.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: altertable-lakehouse
+Version: 0.2.0
+Summary: Official Python SDK for Altertable Lakehouse API
+License-File: LICENSE
+Author: Altertable
+Author-email: hello@altertable.ai
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: dataclasses-json (>=0.6.7,<0.7.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Altertable Lakehouse Python SDK
+
+Official Python SDK for the Altertable Lakehouse API.
+
+## Installation
+
+```bash
+pip install altertable-lakehouse
+```
+
+## Usage
+
+### Initialization
+
+```python
+from altertable_lakehouse import Client
+
+client = Client(username="your_username", password="your_password")
+```
+
+### Querying
+
+```python
+from altertable_lakehouse.models import QueryRequest
+
+# Stream rows (good for large datasets)
+req = QueryRequest(statement="SELECT * FROM my_table")
+metadata, row_iterator = client.query(req)
+for row in row_iterator:
+    print(row)
+
+# Accumulate all rows in memory
+result = client.query_all(req)
+print(result.rows)
+```
+
+### Append
+
+```python
+res = client.append(catalog="my_cat", schema="my_schema", table="my_table", data={"col1": "val1"})
+print(res.ok)
+```
+
+### Upload
+
+```python
+from altertable_lakehouse.models import UploadFormat, UploadMode
+
+with open("data.csv", "rb") as f:
+    client.upload(
+        catalog="my_cat", 
+        schema="my_schema", 
+        table="my_table", 
+        format=UploadFormat.CSV, 
+        mode=UploadMode.APPEND, 
+        content=f.read()
+    )
+```
+
+### Validate Query
+
+```python
+res = client.validate("SELECT * FROM non_existent")
+print(res.valid)
+print(res.connections_errors)
+```
+
+### Query Log & Cancellation
+
+```python
+# Get query status
+log_res = client.get_query("query_uuid_here")
+print(log_res.progress)
+
+# Cancel a query
+cancel_res = client.cancel_query("query_uuid_here", "session_id_here")
+print(cancel_res.cancelled)
+```
+

altertable_lakehouse-0.2.0/README.md

@@ -0,0 +1,78 @@
+# Altertable Lakehouse Python SDK
+
+Official Python SDK for the Altertable Lakehouse API.
+
+## Installation
+
+```bash
+pip install altertable-lakehouse
+```
+
+## Usage
+
+### Initialization
+
+```python
+from altertable_lakehouse import Client
+
+client = Client(username="your_username", password="your_password")
+```
+
+### Querying
+
+```python
+from altertable_lakehouse.models import QueryRequest
+
+# Stream rows (good for large datasets)
+req = QueryRequest(statement="SELECT * FROM my_table")
+metadata, row_iterator = client.query(req)
+for row in row_iterator:
+    print(row)
+
+# Accumulate all rows in memory
+result = client.query_all(req)
+print(result.rows)
+```
+
+### Append
+
+```python
+res = client.append(catalog="my_cat", schema="my_schema", table="my_table", data={"col1": "val1"})
+print(res.ok)
+```
+
+### Upload
+
+```python
+from altertable_lakehouse.models import UploadFormat, UploadMode
+
+with open("data.csv", "rb") as f:
+    client.upload(
+        catalog="my_cat", 
+        schema="my_schema", 
+        table="my_table", 
+        format=UploadFormat.CSV, 
+        mode=UploadMode.APPEND, 
+        content=f.read()
+    )
+```
+
+### Validate Query
+
+```python
+res = client.validate("SELECT * FROM non_existent")
+print(res.valid)
+print(res.connections_errors)
+```
+
+### Query Log & Cancellation
+
+```python
+# Get query status
+log_res = client.get_query("query_uuid_here")
+print(log_res.progress)
+
+# Cancel a query
+cancel_res = client.cancel_query("query_uuid_here", "session_id_here")
+print(cancel_res.cancelled)
+```

altertable_lakehouse-0.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "altertable-lakehouse"
+version = "0.2.0"
+description = "Official Python SDK for Altertable Lakehouse API"
+authors = ["Altertable <hello@altertable.ai>"]
+readme = "README.md"
+packages = [{include = "altertable_lakehouse", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+httpx = "^0.28.1"
+dataclasses-json = "^0.6.7"
+pydantic = "^2.12.5"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+ruff = "^0.3.0"
+mypy = "^1.8.0"
+testcontainers = "<4.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

altertable_lakehouse-0.2.0/src/altertable_lakehouse/__init__.py

@@ -0,0 +1,5 @@
+from .client import Client
+from . import models
+from . import errors
+
+__all__ = ["Client", "models", "errors"]

altertable_lakehouse-0.2.0/src/altertable_lakehouse/client.py

@@ -0,0 +1,186 @@
+import os
+import json
+import base64
+import httpx
+from typing import Any, Dict, Iterator, Optional, Union, Tuple, NoReturn
+from .models import (
+    AppendRequestSingle, AppendRequestBatch, AppendResponse,
+    QueryRequest, QueryLogResponse, CancelQueryResponse,
+    ValidateResponse, UploadFormat, UploadMode,
+    QueryMetadata, QueryResult
+)
+from .errors import (
+    AuthError, BadRequestError, NetworkError, TimeoutError,
+    ParseError, ApiError, ConfigurationError,
+    AltertableLakehouseError
+)
+
+class Client:
+    def __init__(
+        self,
+        base_url: str = "https://api.altertable.ai",
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+        user_agent_suffix: Optional[str] = None
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        
+        auth_token = None
+        if token:
+            auth_token = token
+        elif username and password:
+            auth_token = base64.b64encode(f"{username}:{password}".encode()).decode()
+        elif "ALTERTABLE_BASIC_AUTH_TOKEN" in os.environ:
+            auth_token = os.environ["ALTERTABLE_BASIC_AUTH_TOKEN"]
+        elif "ALTERTABLE_USERNAME" in os.environ and "ALTERTABLE_PASSWORD" in os.environ:
+            u = os.environ["ALTERTABLE_USERNAME"]
+            p = os.environ["ALTERTABLE_PASSWORD"]
+            auth_token = base64.b64encode(f"{u}:{p}".encode()).decode()
+        
+        if not auth_token:
+            raise ConfigurationError("No credentials provided.")
+            
+        ua = "altertable-lakehouse-python/0.1.0"
+        if user_agent_suffix:
+            ua += f" {user_agent_suffix}"
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers={
+                "Authorization": f"Basic {auth_token}",
+                "User-Agent": ua
+            }
+        )
+
+    def _handle_error(self, e: Exception) -> NoReturn:
+        if isinstance(e, httpx.TimeoutException):
+            raise TimeoutError("Request timed out", e)
+        if isinstance(e, httpx.RequestError):
+            raise NetworkError(f"Network error: {str(e)}", e)
+        raise AltertableLakehouseError(f"Unexpected error: {str(e)}", e)
+
+    def _check_response(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        if response.status_code == 401:
+            raise AuthError("Unauthorized", response.status_code)
+        if response.status_code == 400:
+            raise BadRequestError(response.text, response.status_code)
+        raise ApiError(response.text, response.status_code)
+
+    def append(self, catalog: str, schema: str, table: str, data: Union[AppendRequestSingle, AppendRequestBatch]) -> AppendResponse:
+        try:
+            payload = data.model_dump() if hasattr(data, "model_dump") else data
+            res = self._client.post(
+                "/append",
+                params={"catalog": catalog, "schema": schema, "table": table},
+                json=payload
+            )
+            self._check_response(res)
+            return AppendResponse(**res.json())
+        except httpx.RequestError as e:
+            self._handle_error(e)
+
+    def upload(self, catalog: str, schema: str, table: str, format: UploadFormat, mode: UploadMode, content: bytes, primary_key: Optional[str] = None) -> None:
+        params = {
+            "catalog": catalog,
+            "schema": schema,
+            "table": table,
+            "format": format.value,
+            "mode": mode.value
+        }
+        if primary_key:
+            params["primary_key"] = primary_key
+        try:
+            res = self._client.post(
+                "/upload",
+                params=params,
+                content=content,
+                headers={"Content-Type": "application/octet-stream"}
+            )
+            self._check_response(res)
+        except httpx.RequestError as e:
+            self._handle_error(e)
+
+    def get_query(self, query_id: str) -> QueryLogResponse:
+        try:
+            res = self._client.get(f"/query/{query_id}")
+            self._check_response(res)
+            return QueryLogResponse(**res.json())
+        except httpx.RequestError as e:
+            self._handle_error(e)
+
+    def cancel_query(self, query_id: str, session_id: str) -> CancelQueryResponse:
+        try:
+            res = self._client.delete(f"/query/{query_id}", params={"session_id": session_id})
+            self._check_response(res)
+            return CancelQueryResponse(**res.json())
+        except httpx.RequestError as e:
+            self._handle_error(e)
+
+    def validate(self, statement: str) -> ValidateResponse:
+        try:
+            res = self._client.post("/validate", json={"statement": statement})
+            self._check_response(res)
+            return ValidateResponse(**res.json())
+        except httpx.RequestError as e:
+            self._handle_error(e)
+
+    def query(self, request: QueryRequest) -> Tuple[QueryMetadata, Iterator[Dict[str, Any]]]:
+        payload = request.model_dump(exclude_none=True)
+        try:
+            req = self._client.build_request(
+                "POST", 
+                "/query", 
+                json=payload,
+                headers={"Accept": "application/x-ndjson"}
+            )
+            res = self._client.send(req, stream=True)
+            self._check_response(res)
+            
+            def parse_stream() -> Iterator[Dict[str, Any]]:
+                line_index = 0
+                for line in res.iter_lines():
+                    if not line.strip():
+                        continue
+                    try:
+                        yield json.loads(line)
+                    except json.JSONDecodeError as exc:
+                        raise ParseError("Failed to parse NDJSON line", line_index, line) from exc
+                    line_index += 1
+            
+            iterator = parse_stream()
+            metadata = QueryMetadata()
+            
+            first = next(iterator, None)
+            if first and "metadata" in first:
+                metadata.stats = first.get("metadata", {})
+                second = next(iterator, None)
+                if second and "columns" in second:
+                    metadata.columns = second.get("columns", [])
+                else:
+                    def row_generator1(first_row: Any, iter_obj: Iterator[Any]) -> Iterator[Any]:
+                        if first_row:
+                            yield first_row
+                        yield from iter_obj
+                    return metadata, row_generator1(second, iterator)
+            else:
+                def row_generator2(first_row: Any, iter_obj: Iterator[Any]) -> Iterator[Any]:
+                    if first_row:
+                        yield first_row
+                    yield from iter_obj
+                return metadata, row_generator2(first, iterator)
+
+            return metadata, iterator
+
+        except httpx.RequestError as e:
+            self._handle_error(e)
+
+    def query_all(self, request: QueryRequest) -> QueryResult:
+        metadata, iterator = self.query(request)
+        rows = list(iterator)
+        return QueryResult(metadata=metadata, rows=rows)

altertable_lakehouse-0.2.0/src/altertable_lakehouse/errors.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+class AltertableLakehouseError(Exception):
+    def __init__(self, message: str, cause: Optional[Exception] = None):
+        super().__init__(message)
+        self.cause = cause
+
+class NetworkError(AltertableLakehouseError): 
+    pass
+
+class TimeoutError(AltertableLakehouseError): 
+    pass
+
+class SerializationError(AltertableLakehouseError): 
+    pass
+
+class ParseError(AltertableLakehouseError):
+    def __init__(self, message: str, line_index: int, raw_content: str):
+        super().__init__(f"{message} at line {line_index}: {raw_content}")
+        self.line_index = line_index
+        self.raw_content = raw_content
+
+class ApiError(AltertableLakehouseError):
+    def __init__(self, message: str, status_code: int):
+        super().__init__(f"{status_code}: {message}")
+        self.status_code = status_code
+
+class AuthError(ApiError): 
+    pass
+
+class BadRequestError(ApiError): 
+    pass
+
+class ConfigurationError(AltertableLakehouseError): 
+    pass

altertable_lakehouse-0.2.0/src/altertable_lakehouse/models.py

@@ -0,0 +1,78 @@
+from typing import Any, Dict, List, Optional, Literal, Union
+from enum import Enum
+from pydantic import BaseModel, Field
+
+class ComputeSize(str, Enum):
+    S = "S"
+    M = "M"
+    L = "L"
+
+class UploadFormat(str, Enum):
+    CSV = "csv"
+    JSON = "json"
+    PARQUET = "parquet"
+
+class UploadMode(str, Enum):
+    CREATE = "create"
+    APPEND = "append"
+    UPSERT = "upsert"
+    OVERWRITE = "overwrite"
+
+AppendRequestSingle = Dict[str, Any]
+AppendRequestBatch = List[Dict[str, Any]]
+AppendRequest = Union[AppendRequestSingle, AppendRequestBatch]
+
+class AppendResponse(BaseModel):
+    ok: bool
+    error_code: Optional[Literal["invalid-data"]] = None
+
+class QueryRequest(BaseModel):
+    statement: str
+    catalog: Optional[str] = None
+    schema_: Optional[str] = Field(default=None, alias="schema")
+    session_id: Optional[str] = None
+    compute_size: Optional[ComputeSize] = None
+    sanitize: Optional[bool] = None
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+    timezone: Optional[str] = None
+    ephemeral: Optional[bool] = None
+    visible: Optional[bool] = None
+    requested_by: Optional[str] = None
+    query_id: Optional[str] = None
+
+class QueryLogResponse(BaseModel):
+    uuid: str
+    start_time: str
+    end_time: str
+    duration_ms: int
+    query: str
+    session_id: Optional[str] = None
+    client_interface: str
+    error: Optional[str] = None
+    stats: Dict[str, Any]
+    progress: int
+    visible: bool
+    requested_by: str
+    user_agent: str
+
+class CancelQueryResponse(BaseModel):
+    cancelled: bool
+    message: str
+
+class ValidateRequest(BaseModel):
+    statement: str
+
+class ValidateResponse(BaseModel):
+    valid: bool
+    statement: str
+    connections_errors: Any
+    error: Optional[str] = None
+
+class QueryMetadata(BaseModel):
+    columns: List[Dict[str, Any]] = Field(default_factory=list)
+    stats: Dict[str, Any] = Field(default_factory=dict)
+
+class QueryResult(BaseModel):
+    metadata: QueryMetadata
+    rows: List[Any]