keboola-query-service 0.1.0__tar.gz

keboola_query_service-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+
+# MISC
+.env

keboola_query_service-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: keboola-query-service
+Version: 0.1.0
+Summary: Python SDK for Keboola Query Service API
+Project-URL: Homepage, https://github.com/keboola/query-service-python-sdk
+Project-URL: Documentation, https://developers.keboola.com/
+Project-URL: Repository, https://github.com/keboola/query-service-python-sdk
+Project-URL: Issues, https://github.com/keboola/query-service-python-sdk/issues
+Author-email: Keboola <support@keboola.com>
+License-Expression: MIT
+Keywords: bigquery,data,keboola,query,snowflake,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.22.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Keboola Query Service Python SDK
+
+Python client for [Keboola Query Service API](https://query.keboola.com/api/v1/documentation).
+
+## Installation
+
+```bash
+pip install keboola-query-service
+```
+
+## Quick Start
+
+```python
+from keboola_query_service import Client
+
+# Initialize client
+client = Client(
+    base_url="https://query.keboola.com",
+    token="your-storage-api-token"
+)
+
+# Execute a query and wait for results
+results = client.execute_query(
+    branch_id="123",
+    workspace_id="456",
+    statements=["SELECT * FROM my_table LIMIT 10"]
+)
+
+# Access results
+for row in results[0].data:
+    print(row)
+```
+
+## Features
+
+- **Sync and async support** - Both synchronous and async (asyncio) APIs
+- **Automatic retries** - Configurable retry logic for transient failures
+- **Job polling** - Built-in exponential backoff for waiting on job completion
+- **Streaming** - NDJSON streaming for large result sets
+- **Type hints** - Full type annotations for IDE support
+
+## Usage
+
+### Basic Query Execution
+
+```python
+from keboola_query_service import Client
+
+with Client(base_url="https://query.keboola.com", token="...") as client:
+    # Execute query and wait for results
+    results = client.execute_query(
+        branch_id="123",
+        workspace_id="456",
+        statements=[
+            "SELECT * FROM orders WHERE date > '2024-01-01'",
+            "SELECT COUNT(*) FROM customers"
+        ],
+        transactional=True  # Execute in a transaction
+    )
+
+    # Results is a list - one QueryResult per statement
+    orders_result = results[0]
+    count_result = results[1]
+
+    print(f"Columns: {[c.name for c in orders_result.columns]}")
+    print(f"Rows: {len(orders_result.data)}")
+```
+
+### Async Usage
+
+```python
+import asyncio
+from keboola_query_service import Client
+
+async def main():
+    async with Client(base_url="...", token="...") as client:
+        results = await client.execute_query_async(
+            branch_id="123",
+            workspace_id="456",
+            statements=["SELECT 1"]
+        )
+        print(results[0].data)
+
+asyncio.run(main())
+```
+
+### Low-Level API
+
+For more control, use the low-level methods:
+
+```python
+# Submit job without waiting
+job_id = client.submit_job(
+    branch_id="123",
+    workspace_id="456",
+    statements=["SELECT * FROM large_table"]
+)
+
+# Check status
+status = client.get_job_status(job_id)
+print(f"Status: {status.status}")  # created, enqueued, processing, completed, failed
+
+# Wait for completion
+final_status = client.wait_for_job(job_id, max_wait_time=300)
+
+# Get results for specific statement
+result = client.get_job_results(job_id, final_status.statements[0].id)
+```
+
+### Streaming Large Results
+
+```python
+# Stream results as NDJSON for large datasets
+for row in client.stream_results(job_id, statement_id):
+    process_row(row)
+```
+
+### Error Handling
+
+```python
+from keboola_query_service import (
+    Client,
+    AuthenticationError,
+    ValidationError,
+    JobError,
+    TimeoutError,
+)
+
+try:
+    results = client.execute_query(...)
+except AuthenticationError:
+    print("Invalid token")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except JobError as e:
+    print(f"Query failed: {e.message}")
+    for stmt in e.failed_statements:
+        print(f"  Statement {stmt['id']}: {stmt['error']}")
+except TimeoutError as e:
+    print(f"Job {e.job_id} timed out")
+```
+
+### Query History
+
+```python
+history = client.get_query_history(
+    branch_id="123",
+    workspace_id="456",
+    page_size=100
+)
+
+for stmt in history.statements:
+    print(f"{stmt.query_job_id}: {stmt.query[:50]}... ({stmt.status})")
+```
+
+## Configuration
+
+```python
+client = Client(
+    base_url="https://query.keboola.com",
+    token="your-token",
+    timeout=120.0,           # Request timeout (seconds)
+    connect_timeout=10.0,    # Connection timeout (seconds)
+    max_retries=3,           # Max retry attempts
+    user_agent="my-app/1.0", # Custom user agent
+)
+```
+
+## API Reference
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `execute_query()` | Submit query, wait for completion, return results |
+| `submit_job()` | Submit query job without waiting |
+| `get_job_status()` | Get current job status |
+| `get_job_results()` | Get results for a statement |
+| `wait_for_job()` | Wait for job to complete |
+| `cancel_job()` | Cancel a running job |
+| `get_query_history()` | Get query history for workspace |
+| `stream_results()` | Stream results as NDJSON |
+
+All methods have async variants with `_async` suffix.
+
+### Models
+
+- `JobStatus` - Job status with statements
+- `QueryResult` - Query results with columns and data
+- `Statement` - Individual SQL statement info
+- `Column` - Column metadata
+- `JobState` - Enum: created, enqueued, processing, completed, failed, canceled
+- `StatementState` - Enum: waiting, processing, completed, failed, canceled, notExecuted
+
+## License
+
+MIT

keboola_query_service-0.1.0/README.md

@@ -0,0 +1,197 @@
+# Keboola Query Service Python SDK
+
+Python client for [Keboola Query Service API](https://query.keboola.com/api/v1/documentation).
+
+## Installation
+
+```bash
+pip install keboola-query-service
+```
+
+## Quick Start
+
+```python
+from keboola_query_service import Client
+
+# Initialize client
+client = Client(
+    base_url="https://query.keboola.com",
+    token="your-storage-api-token"
+)
+
+# Execute a query and wait for results
+results = client.execute_query(
+    branch_id="123",
+    workspace_id="456",
+    statements=["SELECT * FROM my_table LIMIT 10"]
+)
+
+# Access results
+for row in results[0].data:
+    print(row)
+```
+
+## Features
+
+- **Sync and async support** - Both synchronous and async (asyncio) APIs
+- **Automatic retries** - Configurable retry logic for transient failures
+- **Job polling** - Built-in exponential backoff for waiting on job completion
+- **Streaming** - NDJSON streaming for large result sets
+- **Type hints** - Full type annotations for IDE support
+
+## Usage
+
+### Basic Query Execution
+
+```python
+from keboola_query_service import Client
+
+with Client(base_url="https://query.keboola.com", token="...") as client:
+    # Execute query and wait for results
+    results = client.execute_query(
+        branch_id="123",
+        workspace_id="456",
+        statements=[
+            "SELECT * FROM orders WHERE date > '2024-01-01'",
+            "SELECT COUNT(*) FROM customers"
+        ],
+        transactional=True  # Execute in a transaction
+    )
+
+    # Results is a list - one QueryResult per statement
+    orders_result = results[0]
+    count_result = results[1]
+
+    print(f"Columns: {[c.name for c in orders_result.columns]}")
+    print(f"Rows: {len(orders_result.data)}")
+```
+
+### Async Usage
+
+```python
+import asyncio
+from keboola_query_service import Client
+
+async def main():
+    async with Client(base_url="...", token="...") as client:
+        results = await client.execute_query_async(
+            branch_id="123",
+            workspace_id="456",
+            statements=["SELECT 1"]
+        )
+        print(results[0].data)
+
+asyncio.run(main())
+```
+
+### Low-Level API
+
+For more control, use the low-level methods:
+
+```python
+# Submit job without waiting
+job_id = client.submit_job(
+    branch_id="123",
+    workspace_id="456",
+    statements=["SELECT * FROM large_table"]
+)
+
+# Check status
+status = client.get_job_status(job_id)
+print(f"Status: {status.status}")  # created, enqueued, processing, completed, failed
+
+# Wait for completion
+final_status = client.wait_for_job(job_id, max_wait_time=300)
+
+# Get results for specific statement
+result = client.get_job_results(job_id, final_status.statements[0].id)
+```
+
+### Streaming Large Results
+
+```python
+# Stream results as NDJSON for large datasets
+for row in client.stream_results(job_id, statement_id):
+    process_row(row)
+```
+
+### Error Handling
+
+```python
+from keboola_query_service import (
+    Client,
+    AuthenticationError,
+    ValidationError,
+    JobError,
+    TimeoutError,
+)
+
+try:
+    results = client.execute_query(...)
+except AuthenticationError:
+    print("Invalid token")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except JobError as e:
+    print(f"Query failed: {e.message}")
+    for stmt in e.failed_statements:
+        print(f"  Statement {stmt['id']}: {stmt['error']}")
+except TimeoutError as e:
+    print(f"Job {e.job_id} timed out")
+```
+
+### Query History
+
+```python
+history = client.get_query_history(
+    branch_id="123",
+    workspace_id="456",
+    page_size=100
+)
+
+for stmt in history.statements:
+    print(f"{stmt.query_job_id}: {stmt.query[:50]}... ({stmt.status})")
+```
+
+## Configuration
+
+```python
+client = Client(
+    base_url="https://query.keboola.com",
+    token="your-token",
+    timeout=120.0,           # Request timeout (seconds)
+    connect_timeout=10.0,    # Connection timeout (seconds)
+    max_retries=3,           # Max retry attempts
+    user_agent="my-app/1.0", # Custom user agent
+)
+```
+
+## API Reference
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `execute_query()` | Submit query, wait for completion, return results |
+| `submit_job()` | Submit query job without waiting |
+| `get_job_status()` | Get current job status |
+| `get_job_results()` | Get results for a statement |
+| `wait_for_job()` | Wait for job to complete |
+| `cancel_job()` | Cancel a running job |
+| `get_query_history()` | Get query history for workspace |
+| `stream_results()` | Stream results as NDJSON |
+
+All methods have async variants with `_async` suffix.
+
+### Models
+
+- `JobStatus` - Job status with statements
+- `QueryResult` - Query results with columns and data
+- `Statement` - Individual SQL statement info
+- `Column` - Column metadata
+- `JobState` - Enum: created, enqueued, processing, completed, failed, canceled
+- `StatementState` - Enum: waiting, processing, completed, failed, canceled, notExecuted
+
+## License
+
+MIT

keboola_query_service-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "keboola-query-service"
+version = "0.1.0"
+description = "Python SDK for Keboola Query Service API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Keboola", email = "support@keboola.com" }
+]
+keywords = ["keboola", "query", "sql", "data", "snowflake", "bigquery"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-httpx>=0.22.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/keboola/query-service-python-sdk"
+Documentation = "https://developers.keboola.com/"
+Repository = "https://github.com/keboola/query-service-python-sdk"
+Issues = "https://github.com/keboola/query-service-python-sdk/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/keboola_query_service"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

keboola_query_service-0.1.0/src/keboola_query_service/__init__.py

@@ -0,0 +1,38 @@
+"""Keboola Query Service Python SDK."""
+
+from ._version import __version__
+from .client import Client
+from .models import (
+    ActorType,
+    JobState,
+    StatementState,
+    Column,
+    Statement,
+    JobStatus,
+    QueryResult,
+    QueryHistory,
+)
+from .exceptions import (
+    QueryServiceError,
+    AuthenticationError,
+    ValidationError,
+    JobError,
+    JobTimeoutError,
+)
+
+__all__ = [
+    "Client",
+    "ActorType",
+    "JobState",
+    "StatementState",
+    "Column",
+    "Statement",
+    "JobStatus",
+    "QueryResult",
+    "QueryHistory",
+    "QueryServiceError",
+    "AuthenticationError",
+    "ValidationError",
+    "JobError",
+    "JobTimeoutError",
+]

keboola_query_service-0.1.0/src/keboola_query_service/_version.py

@@ -0,0 +1,3 @@
+"""Version information for Keboola Query Service SDK."""
+
+__version__ = "0.1.0"