definite-sdk 0.1.3__tar.gz → 0.1.8__tar.gz

definite_sdk-0.1.8/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.3
+Name: definite-sdk
+Version: 0.1.8
+Summary: Definite SDK for Python
+License: MIT
+Author: Definite
+Author-email: hello@definite.app
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+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
+Provides-Extra: dlt
+Requires-Dist: dlt (>=1.0,<2.0) ; extra == "dlt"
+Requires-Dist: duckdb (>=1.0,<2.0) ; extra == "dlt"
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Definite SDK
+
+A Python client for interacting with the Definite API, providing a convenient interface for key-value store operations, SQL query execution, secrets management, and DLT (Data Load Tool) integration with state persistence.
+
+## Installation
+
+**pip:**
+```bash
+pip install definite-sdk
+
+# For dlt support
+pip install "definite-sdk[dlt]"
+```
+
+**poetry:**
+```bash
+poetry add definite-sdk
+
+# For dlt support
+poetry add "definite-sdk[dlt]"
+```
+
+## Quick Start
+
+```python
+from definite_sdk import DefiniteClient
+
+# Initialize the client
+client = DefiniteClient("YOUR_API_KEY")
+```
+
+## Features
+
+- **Key-Value Store**: Persistent storage with version control and transactional commits
+- **SQL Query Execution**: Execute SQL queries against your connected database integrations
+- **Cube Query Execution**: Execute Cube queries for advanced analytics and data modeling
+- **Secret Management**: Secure storage and retrieval of application secrets
+- **Integration Store**: Read-only access to integration configurations
+- **dlt Integration**: Run dlt pipelines with automatic state persistence to Definite
+- **DuckDB Support**: Automatic discovery and connection to team's DuckDB integrations
+
+## Basic Usage
+
+### 🗄️ Key-Value Store
+
+Store and retrieve key-value pairs that can be accessed by custom Python scripts hosted on Definite.
+
+```python
+# Initialize or retrieve an existing key-value store
+store = client.get_kv_store('test_store')
+# Or use the alias method
+store = client.kv_store('test_store')
+
+# Add or update key-value pairs
+store['replication_key'] = 'created_at'
+store['replication_state'] = '2024-05-20'
+store["key1"] = "value1"
+store["key2"] = {"nested": "data"}
+
+# Commit changes
+store.commit()
+
+# Retrieve values
+print(store['replication_key'])  # 'created_at'
+value = store["key1"]
+```
+
+### 🗃️ SQL Query Execution
+
+Execute SQL queries against your connected database integrations.
+
+```python
+# Initialize the SQL client
+sql_client = client.get_sql_client()
+
+# Execute a SQL query
+result = sql_client.execute("SELECT * FROM users LIMIT 10")
+print(result)
+
+# Execute a SQL query with a specific integration
+result = sql_client.execute(
+    "SELECT COUNT(*) FROM orders WHERE status = 'completed'",
+    integration_id="my_database_integration"
+)
+print(result)
+```
+
+### 📊 Cube Query Execution
+
+Execute Cube queries for advanced analytics and data modeling.
+
+```python
+# Prepare a Cube query
+cube_query = {
+    "dimensions": [],
+    "measures": ["sales.total_amount"],
+    "timeDimensions": [{
+        "dimension": "sales.date", 
+        "granularity": "month"
+    }],
+    "limit": 1000
+}
+
+# Execute the Cube query
+result = sql_client.execute_cube_query(
+    cube_query, 
+    integration_id="my_cube_integration"
+)
+print(result)
+```
+
+### 🔒 Secret Store
+
+Securely store and retrieve secrets for your integrations.
+
+```python
+# Initialize the secret store
+secret_store = client.get_secret_store()
+# Or use the alias method
+secret_store = client.secret_store()
+
+# Set a secret
+secret_store.set_secret("database_password", "my_secure_password")
+
+# Get a secret
+password = secret_store.get_secret("database_password")
+
+# List all secrets
+secrets = list(secret_store.list_secrets())
+```
+
+### 🔗 Integration Management
+
+Manage your data integrations and connections.
+
+```python
+# Initialize the integration store
+integration_store = client.get_integration_store()
+# Or use the alias method
+integration_store = client.integration_store()
+
+# List all integrations
+integrations = list(integration_store.list_integrations())
+
+# Get a specific integration
+integration = integration_store.get_integration("my_integration")
+```
+
+### dlt Integration
+
+```python
+from definite_sdk.dlt import DefiniteDLTPipeline
+import dlt
+
+# Create an incremental resource
+@dlt.resource(primary_key="id", write_disposition="merge")
+def orders(cursor=dlt.sources.incremental("created_at")):
+    # Your data loading logic here
+    pass
+
+# Create and run pipeline
+pipeline = DefiniteDLTPipeline("orders_sync")
+pipeline.run(orders())
+
+# State is automatically persisted to Definite
+last_cursor = pipeline.get_state("orders")
+```
+
+### DuckDB Integration Discovery
+
+```python
+from definite_sdk.dlt import get_duckdb_connection
+
+# Automatically discovers DuckDB integration using DEFINITE_API_KEY env var
+result = get_duckdb_connection()
+if result:
+    integration_id, connection = result
+    # Use the DuckDB connection
+    connection.execute("SELECT * FROM my_table")
+```
+
+**Note**: DuckDB integration discovery is currently limited as the API only exposes source integrations, not destination integrations. This functionality is provided for future compatibility.
+
+### State Management
+
+```python
+# Set custom state
+pipeline.set_state("custom_key", "custom_value")
+
+# Get all state
+all_state = pipeline.get_state()
+
+# Resume from previous state
+pipeline.resume_from_state()
+
+# Reset state
+pipeline.reset_state()
+```
+
+## Authentication
+
+To use the Definite SDK, you'll need an API key. You can find and copy your API key from the bottom left user menu in your Definite workspace.
+
+For SQL queries, you'll also need your integration ID, which can be found in your integration's page URL.
+
+## Environment Variables
+
+- `DEFINITE_API_KEY`: Your Definite API key (auto-injected in Definite runtime)
+- `DEF_API_KEY`: Alternative environment variable for API key
+
+## Error Handling
+
+The SDK uses standard HTTP status codes and raises `requests.HTTPError` for API errors:
+
+```python
+import requests
+
+try:
+    result = sql_client.execute("SELECT * FROM invalid_table")
+except requests.HTTPError as e:
+    print(f"API Error: {e}")
+```
+
+## Testing
+
+```bash
+# Run all tests
+DEF_API_KEY=your_api_key poetry run pytest
+
+# Run specific test file
+DEF_API_KEY=your_api_key poetry run pytest tests/test_dlt.py
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Documentation
+
+For more detailed documentation, visit: https://docs.definite.app/
+
+## Support
+
+If you encounter any issues or have questions, please reach out to hello@definite.app
+

definite_sdk-0.1.8/README.md

@@ -0,0 +1,248 @@
+# Definite SDK
+
+A Python client for interacting with the Definite API, providing a convenient interface for key-value store operations, SQL query execution, secrets management, and DLT (Data Load Tool) integration with state persistence.
+
+## Installation
+
+**pip:**
+```bash
+pip install definite-sdk
+
+# For dlt support
+pip install "definite-sdk[dlt]"
+```
+
+**poetry:**
+```bash
+poetry add definite-sdk
+
+# For dlt support
+poetry add "definite-sdk[dlt]"
+```
+
+## Quick Start
+
+```python
+from definite_sdk import DefiniteClient
+
+# Initialize the client
+client = DefiniteClient("YOUR_API_KEY")
+```
+
+## Features
+
+- **Key-Value Store**: Persistent storage with version control and transactional commits
+- **SQL Query Execution**: Execute SQL queries against your connected database integrations
+- **Cube Query Execution**: Execute Cube queries for advanced analytics and data modeling
+- **Secret Management**: Secure storage and retrieval of application secrets
+- **Integration Store**: Read-only access to integration configurations
+- **dlt Integration**: Run dlt pipelines with automatic state persistence to Definite
+- **DuckDB Support**: Automatic discovery and connection to team's DuckDB integrations
+
+## Basic Usage
+
+### 🗄️ Key-Value Store
+
+Store and retrieve key-value pairs that can be accessed by custom Python scripts hosted on Definite.
+
+```python
+# Initialize or retrieve an existing key-value store
+store = client.get_kv_store('test_store')
+# Or use the alias method
+store = client.kv_store('test_store')
+
+# Add or update key-value pairs
+store['replication_key'] = 'created_at'
+store['replication_state'] = '2024-05-20'
+store["key1"] = "value1"
+store["key2"] = {"nested": "data"}
+
+# Commit changes
+store.commit()
+
+# Retrieve values
+print(store['replication_key'])  # 'created_at'
+value = store["key1"]
+```
+
+### 🗃️ SQL Query Execution
+
+Execute SQL queries against your connected database integrations.
+
+```python
+# Initialize the SQL client
+sql_client = client.get_sql_client()
+
+# Execute a SQL query
+result = sql_client.execute("SELECT * FROM users LIMIT 10")
+print(result)
+
+# Execute a SQL query with a specific integration
+result = sql_client.execute(
+    "SELECT COUNT(*) FROM orders WHERE status = 'completed'",
+    integration_id="my_database_integration"
+)
+print(result)
+```
+
+### 📊 Cube Query Execution
+
+Execute Cube queries for advanced analytics and data modeling.
+
+```python
+# Prepare a Cube query
+cube_query = {
+    "dimensions": [],
+    "measures": ["sales.total_amount"],
+    "timeDimensions": [{
+        "dimension": "sales.date", 
+        "granularity": "month"
+    }],
+    "limit": 1000
+}
+
+# Execute the Cube query
+result = sql_client.execute_cube_query(
+    cube_query, 
+    integration_id="my_cube_integration"
+)
+print(result)
+```
+
+### 🔒 Secret Store
+
+Securely store and retrieve secrets for your integrations.
+
+```python
+# Initialize the secret store
+secret_store = client.get_secret_store()
+# Or use the alias method
+secret_store = client.secret_store()
+
+# Set a secret
+secret_store.set_secret("database_password", "my_secure_password")
+
+# Get a secret
+password = secret_store.get_secret("database_password")
+
+# List all secrets
+secrets = list(secret_store.list_secrets())
+```
+
+### 🔗 Integration Management
+
+Manage your data integrations and connections.
+
+```python
+# Initialize the integration store
+integration_store = client.get_integration_store()
+# Or use the alias method
+integration_store = client.integration_store()
+
+# List all integrations
+integrations = list(integration_store.list_integrations())
+
+# Get a specific integration
+integration = integration_store.get_integration("my_integration")
+```
+
+### dlt Integration
+
+```python
+from definite_sdk.dlt import DefiniteDLTPipeline
+import dlt
+
+# Create an incremental resource
+@dlt.resource(primary_key="id", write_disposition="merge")
+def orders(cursor=dlt.sources.incremental("created_at")):
+    # Your data loading logic here
+    pass
+
+# Create and run pipeline
+pipeline = DefiniteDLTPipeline("orders_sync")
+pipeline.run(orders())
+
+# State is automatically persisted to Definite
+last_cursor = pipeline.get_state("orders")
+```
+
+### DuckDB Integration Discovery
+
+```python
+from definite_sdk.dlt import get_duckdb_connection
+
+# Automatically discovers DuckDB integration using DEFINITE_API_KEY env var
+result = get_duckdb_connection()
+if result:
+    integration_id, connection = result
+    # Use the DuckDB connection
+    connection.execute("SELECT * FROM my_table")
+```
+
+**Note**: DuckDB integration discovery is currently limited as the API only exposes source integrations, not destination integrations. This functionality is provided for future compatibility.
+
+### State Management
+
+```python
+# Set custom state
+pipeline.set_state("custom_key", "custom_value")
+
+# Get all state
+all_state = pipeline.get_state()
+
+# Resume from previous state
+pipeline.resume_from_state()
+
+# Reset state
+pipeline.reset_state()
+```
+
+## Authentication
+
+To use the Definite SDK, you'll need an API key. You can find and copy your API key from the bottom left user menu in your Definite workspace.
+
+For SQL queries, you'll also need your integration ID, which can be found in your integration's page URL.
+
+## Environment Variables
+
+- `DEFINITE_API_KEY`: Your Definite API key (auto-injected in Definite runtime)
+- `DEF_API_KEY`: Alternative environment variable for API key
+
+## Error Handling
+
+The SDK uses standard HTTP status codes and raises `requests.HTTPError` for API errors:
+
+```python
+import requests
+
+try:
+    result = sql_client.execute("SELECT * FROM invalid_table")
+except requests.HTTPError as e:
+    print(f"API Error: {e}")
+```
+
+## Testing
+
+```bash
+# Run all tests
+DEF_API_KEY=your_api_key poetry run pytest
+
+# Run specific test file
+DEF_API_KEY=your_api_key poetry run pytest tests/test_dlt.py
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Documentation
+
+For more detailed documentation, visit: https://docs.definite.app/
+
+## Support
+
+If you encounter any issues or have questions, please reach out to hello@definite.app

definite_sdk-0.1.8/definite_sdk/__init__.py

@@ -0,0 +1,20 @@
+"""
+Definite SDK for Python
+
+A Python library for interacting with the Definite API and tools.
+"""
+
+from definite_sdk.client import DefiniteClient
+from definite_sdk.integration import DefiniteIntegrationStore
+from definite_sdk.secret import DefiniteSecretStore
+from definite_sdk.sql import DefiniteSqlClient
+from definite_sdk.store import DefiniteKVStore
+
+__version__ = "0.1.8"
+__all__ = [
+    "DefiniteClient",
+    "DefiniteIntegrationStore",
+    "DefiniteSecretStore",
+    "DefiniteSqlClient",
+    "DefiniteKVStore",
+]

definite_sdk-0.1.8/definite_sdk/client.py

@@ -0,0 +1,79 @@
+import os
+from typing import Optional
+
+from definite_sdk.integration import DefiniteIntegrationStore
+from definite_sdk.secret import DefiniteSecretStore
+from definite_sdk.sql import DefiniteSqlClient
+from definite_sdk.store import DefiniteKVStore
+
+API_URL = "https://api.definite.app"
+
+
+class DefiniteClient:
+    """Client for interacting with the Definite API."""
+
+    def __init__(self, api_key: Optional[str] = None, api_url: str = API_URL):
+        """Creates a definite client with the provided API key.
+
+        Args:
+            api_key: API key for authentication. If not provided, will look for
+                    DEFINITE_API_KEY or DEF_API_KEY environment variables.
+            api_url: Base URL for the Definite API.
+
+        See: https://docs.definite.app/definite-api for how to obtain an API key.
+        """
+        if api_key is None:
+            api_key = os.getenv("DEFINITE_API_KEY") or os.getenv("DEF_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "API key must be provided or set in DEFINITE_API_KEY "
+                    "or DEF_API_KEY environment variable"
+                )
+
+        self.api_key = api_key
+        self.api_url = api_url
+
+    def get_kv_store(self, name: str) -> DefiniteKVStore:
+        """Initializes a key-value store with the provided name.
+
+        See DefiniteKVStore for more how to interact with the store.
+        """
+
+        return DefiniteKVStore(name, self.api_key, self.api_url)
+
+    def get_secret_store(self) -> DefiniteSecretStore:
+        """Initializes the secret store.
+
+        See DefiniteSecretStore for more how to interact with the store.
+        """
+
+        return DefiniteSecretStore(self.api_key, self.api_url)
+
+    def get_integration_store(self) -> DefiniteIntegrationStore:
+        """Initializes the integration store.
+
+        See DefiniteIntegrationStore for more how to interact with the store.
+        """
+
+        return DefiniteIntegrationStore(self.api_key, self.api_url)
+
+    def get_sql_client(self) -> DefiniteSqlClient:
+        """Initializes the SQL client for executing SQL queries.
+
+        See DefiniteSqlClient for more how to execute SQL queries.
+        """
+
+        return DefiniteSqlClient(self.api_key, self.api_url)
+
+    # Alias methods for consistency
+    def kv_store(self, name: str) -> DefiniteKVStore:
+        """Alias for get_kv_store."""
+        return self.get_kv_store(name)
+
+    def secret_store(self) -> DefiniteSecretStore:
+        """Alias for get_secret_store."""
+        return self.get_secret_store()
+
+    def integration_store(self) -> DefiniteIntegrationStore:
+        """Alias for get_integration_store."""
+        return self.get_integration_store()

definite_sdk-0.1.8/definite_sdk/dlt.py

@@ -0,0 +1,237 @@
+"""DLT (Data Load Tool) integration for Definite SDK."""
+
+import os
+import json
+from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import dlt
+    from dlt.common import Destination
+    from dlt.pipeline import Pipeline
+else:
+    try:
+        import dlt
+        from dlt.common import Destination
+        from dlt.pipeline import Pipeline
+    except ImportError:
+        dlt = None  # type: ignore
+        Destination = None  # type: ignore
+        Pipeline = None  # type: ignore
+
+from .client import DefiniteClient
+
+
+class DefiniteDLTPipeline:
+    """Wrapper for DLT pipelines with Definite state management."""
+
+    def __init__(
+        self,
+        name: str,
+        dataset_name: Optional[str] = None,
+        destination: Optional["Destination"] = None,
+        **kwargs: Any,
+    ):
+        """Initialize a DLT pipeline with Definite integration.
+
+        Args:
+            name: Pipeline name
+            dataset_name: Dataset name for the destination
+            destination: DLT destination (defaults to duckdb)
+            **kwargs: Additional arguments passed to dlt.pipeline()
+        """
+        if dlt is None:
+            raise ImportError(
+                "dlt package not installed. Install with: pip install definite-sdk[dlt]"
+            )
+
+        self.name = name
+        self._client = DefiniteClient()
+        self._state_store = self._client.kv_store(f"dlt_state_{name}")
+
+        # Default to DuckDB if no destination specified
+        if destination is None:
+            destination = "duckdb"
+
+        # Use dataset_name or default to pipeline name
+        if dataset_name is None:
+            dataset_name = name
+
+        # Create the underlying DLT pipeline
+        self._pipeline = dlt.pipeline(
+            pipeline_name=name,
+            destination=destination,
+            dataset_name=dataset_name,
+            **kwargs,
+        )
+
+    @property
+    def pipeline(self) -> "Pipeline":
+        """Get the underlying DLT pipeline."""
+        return self._pipeline
+
+    @property
+    def state(self) -> Dict[str, Any]:
+        """Get the current pipeline state."""
+        return dict(self._pipeline.state)
+
+    def run(
+        self,
+        data: Any,
+        *,
+        table_name: Optional[str] = None,
+        write_disposition: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Run the pipeline with the given data.
+
+        Args:
+            data: Data to load (resource, source, or iterator)
+            table_name: Name of the table to load data into
+            write_disposition: How to write data (append, replace, merge)
+            **kwargs: Additional arguments passed to pipeline.run()
+
+        Returns:
+            Load info from the pipeline run
+        """
+        # Run the pipeline
+        load_info = self._pipeline.run(
+            data, table_name=table_name, write_disposition=write_disposition, **kwargs
+        )
+
+        # Persist state to Definite after successful run
+        self._persist_state()
+
+        return load_info
+
+    def _persist_state(self) -> None:
+        """Persist current pipeline state to Definite."""
+        state = self._pipeline.state
+        if state:
+            # Store each state key separately for easier access
+            for key, value in state.items():
+                # Serialize value to JSON string
+                self._state_store[key] = json.dumps(value)
+            self._state_store.commit()
+
+    def get_state(self, key: Optional[str] = None) -> Any:
+        """Retrieve state from Definite store.
+
+        Args:
+            key: Specific state key to retrieve. If None, returns all state.
+
+        Returns:
+            State value or entire state dict
+        """
+        if key is not None:
+            value = self._state_store.get(key, None)
+            return json.loads(value) if value else None
+
+        # Return all state as dict
+        return {k: json.loads(self._state_store[k]) for k in self._state_store}
+
+    def set_state(self, key: str, value: Any) -> None:
+        """Set a state value.
+
+        Args:
+            key: State key
+            value: State value
+        """
+        self._pipeline.state[key] = value
+        # Also persist to Definite immediately
+        self._state_store[key] = json.dumps(value)
+        self._state_store.commit()
+
+    def resume_from_state(self) -> None:
+        """Resume pipeline from previously stored state."""
+        # Load state from Definite
+        stored_state: Dict[str, Any] = {
+            k: json.loads(self._state_store[k]) for k in self._state_store
+        }
+
+        # Apply state to pipeline
+        for key, value in stored_state.items():
+            self._pipeline.state[key] = value
+
+    def reset_state(self) -> None:
+        """Reset pipeline state."""
+        # Clear pipeline state
+        self._pipeline.state.clear()
+
+        # Clear Definite state
+        keys_to_delete = list(self._state_store)
+        for key in keys_to_delete:
+            del self._state_store[key]
+        self._state_store.commit()
+
+
+class DLTStateAdapter:
+    """Adapter for DLT state management conforming to Definite patterns."""
+
+    def __init__(self, pipeline_name: str):
+        """Initialize state adapter.
+
+        Args:
+            pipeline_name: Name of the DLT pipeline
+        """
+        self.pipeline_name = pipeline_name
+        self._client = DefiniteClient()
+        self._store = self._client.kv_store(f"dlt_state_{pipeline_name}")
+
+    def save_state(self, state: Dict[str, Any]) -> None:
+        """Save pipeline state.
+
+        Args:
+            state: State dictionary to save
+        """
+        for key, value in state.items():
+            self._store[key] = json.dumps(value)
+        self._store.commit()
+
+    def load_state(self) -> Dict[str, Any]:
+        """Load pipeline state.
+
+        Returns:
+            State dictionary
+        """
+        return {k: json.loads(self._store[k]) for k in self._store}
+
+    def clear_state(self) -> None:
+        """Clear all state."""
+        keys_to_delete = list(self._store)
+        for key in keys_to_delete:
+            del self._store[key]
+        self._store.commit()
+
+
+def get_duckdb_connection() -> Optional[Tuple[str, Any]]:
+    """Get DuckDB connection from Definite integration.
+
+    Uses the DEFINITE_API_KEY environment variable to authenticate and
+    lookup the team's DuckDB integration.
+
+    Returns:
+        Optional[Tuple[str, Any]]: Tuple of (integration_id, connection) if found,
+                                   None if no DuckDB integration or API key.
+    """
+    api_key = os.getenv("DEFINITE_API_KEY")
+    if not api_key:
+        return None
+
+    try:
+        import duckdb
+    except ImportError:
+        raise ImportError(
+            "duckdb package not installed. Install with: pip install duckdb"
+        )
+
+    client = DefiniteClient(api_key=api_key)
+    integration_store = client.integration_store()
+
+    result = integration_store.lookup_duckdb_integration()
+    if result:
+        integration_id, connection_uri = result
+        # Create DuckDB connection
+        connection = duckdb.connect(connection_uri)
+        return (integration_id, connection)
+
+    return None

definite_sdk-0.1.8/definite_sdk/integration.py

@@ -0,0 +1,99 @@
+from typing import Iterator, Optional, Tuple
+
+import requests
+
+INTEGRATION_ENDPOINT = "/v1/api/integration"
+
+
+class DefiniteIntegrationStore:
+    """
+    Read only access to the integration store on Definite.
+
+    Initialization:
+    >>> client = DefiniteSdkClient("MY_API_KEY")
+    >>> integration_store = client.get_integration_store()
+
+    Accessing values:
+    >>> integration_store.list_integrations()
+    >>> integration_store.get_integration("name")
+    """
+
+    def __init__(self, api_key: str, api_url: str):
+        """
+        Initializes the DefiniteSecretStore
+
+        Args:
+            api_key (str): The API key for authorization.
+        """
+        self._api_key = api_key
+        self._integration_store_url = api_url + INTEGRATION_ENDPOINT
+
+    def list_integrations(self) -> Iterator[dict]:
+        """
+        Lists all integrations in the store.
+
+        Returns:
+            Iterator[str]: An iterator of integrations.
+        """
+        response = requests.get(
+            self._integration_store_url,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return iter(response.json())
+
+    def get_integration(self, name: str) -> dict:
+        """
+        Retrieves an integration by name.
+
+        Args:
+            name (str): The name of the integration.
+
+        Returns:
+            str: The value of the integration.
+        """
+        response = requests.get(
+            self._integration_store_url + f"/{name}",
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return dict(response.json())
+
+    def lookup_duckdb_integration(self) -> Optional[Tuple[str, str]]:
+        """
+        Look up the team's DuckDB integration.
+        
+        Note: Currently, the API only returns extractor (source) integrations.
+        Destination integrations like DuckDB are not yet exposed through this endpoint.
+        This method is provided for future compatibility when the API is updated.
+
+        Returns:
+            Optional[Tuple[str, str]]: Tuple of (integration_id, connection_uri)
+                if found, None if no DuckDB integration exists.
+        """
+        try:
+            response = requests.get(
+                self._integration_store_url,
+                headers={"Authorization": "Bearer " + self._api_key},
+            )
+            response.raise_for_status()
+            integrations = response.json()
+        except:
+            return None
+
+        # Check for DuckDB in the integrations
+        # Note: Currently this will not find DuckDB as it's a destination integration
+        for integration in integrations:
+            integration_type = integration.get("integration_type", "").lower()
+            if integration_type == "duckdb" and integration.get("active", True):
+                integration_id = integration.get("id")
+                # Connection URI might be in config or connection_string field
+                connection_uri = (
+                    integration.get("connection_string")
+                    or integration.get("config", {}).get("database_path")
+                    or integration.get("config", {}).get("connection_string")
+                )
+                if integration_id and connection_uri:
+                    return (integration_id, connection_uri)
+
+        return None

definite_sdk-0.1.8/definite_sdk/secret.py

@@ -0,0 +1,94 @@
+from typing import Iterator
+
+import requests
+
+SECRET_STORE_ENDPOINT = "/v1/api/secret"
+
+
+class DefiniteSecretStore:
+    """
+    A secret store hosted by Definite.
+
+    Initialization:
+    >>> client = DefiniteSdkClient("MY_API_KEY")
+    >>> secret_store = client.get_secret_store()
+
+    Accessing values:
+    >>> secret_store.list_secrets()
+    >>> secret_store.get_secret("key")
+
+    Setting values:
+    >>> secret_store.set_secret("key", "value")
+
+    To permanently delete a secret:
+    >>> secret_store.delete_secret("key")
+    """
+
+    def __init__(self, api_key: str, api_url: str):
+        """
+        Initializes the DefiniteSecretStore
+
+        Args:
+            api_key (str): The API key for authorization.
+        """
+        self._api_key = api_key
+        self._secret_store_url = api_url + SECRET_STORE_ENDPOINT
+
+    def list_secrets(self) -> Iterator[str]:
+        """
+        Lists all secrets in the store.
+
+        Returns:
+            Iterator[str]: An iterator of secret keys.
+        """
+        response = requests.get(
+            self._secret_store_url,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return iter(response.json()["secrets"])
+
+    def get_secret(self, key: str) -> str:
+        """
+        Retrieves the value of a secret.
+
+        Args:
+            key (str): The key of the secret.
+
+        Returns:
+            str: The value of the secret.
+        """
+        response = requests.get(
+            self._secret_store_url + f"/{key}",
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return str(response.json()["value"])
+
+    def set_secret(self, key: str, value: str):
+        """
+        Sets the value of a secret.
+
+        Args:
+            key (str): The key of the secret.
+            value (str): The value of the secret.
+        """
+        response = requests.post(
+            self._secret_store_url + f"/{key}",
+            json={"value": value},
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+
+    def delete_secret(self, key: str):
+        """
+        Deletes a secret.
+
+        Args:
+            key (str): The key of the secret.
+        """
+        response = requests.delete(
+            self._secret_store_url + f"/{key}",
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()

definite_sdk-0.1.8/definite_sdk/sql.py

@@ -0,0 +1,126 @@
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+SQL_ENDPOINT = "/v1/query"
+
+
+class DefiniteSqlClient:
+    """
+    A SQL client for executing SQL queries via the Definite API.
+
+    Initialization:
+    >>> client = DefiniteClient("MY_API_KEY")
+    >>> sql_client = client.get_sql_client()
+
+    Executing SQL queries:
+    >>> result = sql_client.execute("SELECT * FROM my_table LIMIT 10")
+    >>> print(result)
+
+    Executing SQL queries with integration ID:
+    >>> result = sql_client.execute(
+    ...     "SELECT * FROM my_table LIMIT 10",
+    ...     integration_id="my_integration_id"
+    ... )
+    >>> print(result)
+
+    Executing Cube queries:
+    >>> cube_query = {
+    ...     "dimensions": [],
+    ...     "measures": ["sales.total_amount"],
+    ...     "timeDimensions": [{"dimension": "sales.date", "granularity": "month"}],
+    ...     "limit": 1000
+    ... }
+    >>> result = sql_client.execute_cube_query(cube_query, integration_id="my_cube_integration")
+    >>> print(result)
+    """
+
+    def __init__(self, api_key: str, api_url: str):
+        """
+        Initializes the DefiniteSqlClient.
+
+        Args:
+            api_key (str): The API key for authorization.
+            api_url (str): The base URL for the Definite API.
+        """
+        self._api_key = api_key
+        self._sql_url = api_url + SQL_ENDPOINT
+
+    def execute(
+        self, 
+        sql: str, 
+        integration_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Executes a SQL query against a database integration.
+
+        Args:
+            sql (str): The SQL query to execute.
+            integration_id (Optional[str]): The integration ID to query against.
+                If not provided, the default integration will be used.
+
+        Returns:
+            Dict[str, Any]: The query result as returned by the API.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+
+        Example:
+            >>> result = sql_client.execute("SELECT COUNT(*) FROM users")
+            >>> print(result)
+        """
+        payload = {"sql": sql}
+        if integration_id:
+            payload["integration_id"] = integration_id
+
+        response = requests.post(
+            self._sql_url,
+            json=payload,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def execute_cube_query(
+        self, 
+        cube_query: Dict[str, Any], 
+        integration_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Executes a Cube query against a Cube integration.
+
+        Args:
+            cube_query (Dict[str, Any]): The Cube query in JSON format.
+            integration_id (Optional[str]): The Cube integration ID to query against.
+                If not provided, the default integration will be used.
+
+        Returns:
+            Dict[str, Any]: The query result as returned by the API.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+
+        Example:
+            >>> cube_query = {
+            ...     "dimensions": [],
+            ...     "measures": ["sales.total_amount"],
+            ...     "timeDimensions": [{
+            ...         "dimension": "sales.date",
+            ...         "granularity": "month"
+            ...     }],
+            ...     "limit": 1000
+            ... }
+            >>> result = sql_client.execute_cube_query(cube_query, "my_cube_integration")
+            >>> print(result)
+        """
+        payload = {"cube_query": cube_query}
+        if integration_id:
+            payload["integration_id"] = integration_id
+
+        response = requests.post(
+            self._sql_url,
+            json=payload,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return response.json()

{definite_sdk-0.1.3 → definite_sdk-0.1.8}/definite_sdk/store.py

@@ -1,4 +1,4 @@
-from typing import Iterator
+from typing import Iterator, Union, Optional
 
 import requests
 
@@ -109,7 +109,7 @@ class DefiniteKVStore:
         self._data = {}
         self._version_id = None
 
-    def __getitem__(self, key: str) -> str | None:
+    def __getitem__(self, key: str) -> Optional[str]:
         """
         Gets the value for a given key.
 
@@ -190,3 +190,19 @@ class DefiniteKVStore:
             print(store)
         """
         return repr(self._data)
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Gets the value for a given key with a default.
+
+        Args:
+            key (str): The key to retrieve the value for.
+            default: The default value to return if key doesn't exist.
+
+        Returns:
+            The value associated with the key, or default if the key does not exist.
+
+        Example:
+            value = store.get("key1", "default_value")
+        """
+        return self._data.get(key, default)

{definite_sdk-0.1.3 → definite_sdk-0.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "definite-sdk"
-version = "0.1.3"
+version = "0.1.8"
 description = "Definite SDK for Python"
 authors = ["Definite <hello@definite.app>"]
 license = "MIT"
@@ -9,6 +9,11 @@ readme = "README.md"
 [tool.poetry.dependencies]
 python = "^3.9"
 requests = "^2.31.0"
+dlt = {version = "^1.0", optional = true}
+duckdb = {version = "^1.0", optional = true}
+
+[tool.poetry.extras]
+dlt = ["dlt", "duckdb"]
 
 
 [tool.poetry.group.dev.dependencies]

definite_sdk-0.1.3/PKG-INFO

@@ -1,21 +0,0 @@
-Metadata-Version: 2.1
-Name: definite-sdk
-Version: 0.1.3
-Summary: Definite SDK for Python
-License: MIT
-Author: Definite
-Author-email: hello@definite.app
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-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
-Requires-Dist: requests (>=2.31.0,<3.0.0)
-Description-Content-Type: text/markdown
-
-# Definite SDK
-
-A Python client for interacting with the Definite API, providing a convenient interface for key-value store operations.
-

definite_sdk-0.1.3/README.md

@@ -1,3 +0,0 @@
-# Definite SDK
-
-A Python client for interacting with the Definite API, providing a convenient interface for key-value store operations.

definite_sdk-0.1.3/definite_sdk/client.py

@@ -1,23 +0,0 @@
-from definite_sdk.store import DefiniteKVStore
-
-API_URL = "https://api.definite.app"
-
-
-class DefiniteClient:
-    """Client for interacting with the Definite API."""
-
-    def __init__(self, api_key: str, api_url: str = API_URL):
-        """Creates a definite client with the provided API key.
-
-        See: https://docs.definite.app/definite-api for how to obtain an API key.
-        """
-        self.api_key = api_key
-        self.api_url = api_url
-
-    def get_kv_store(self, name: str) -> DefiniteKVStore:
-        """Initializes a key-value store with the provided name.
-
-        See DefiniteKVStore for more how to interact with the store.
-        """
-
-        return DefiniteKVStore(name, self.api_key, self.api_url)