polydata-client 0.1.0__py3-none-any.whl

polydata/__init__.py

@@ -0,0 +1,4 @@
+from .client import PolydataClient
+from .common import create_or_update_ticker, create_or_update_view
+
+__version__ = "0.1.0"

polydata/client.py

@@ -0,0 +1,666 @@
+from pathlib import Path
+from typing import Dict
+
+import pandas as pd
+import requests
+
+
+class PolydataClient:
+    """Client for interacting with the Polydata API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.polydata.co/v1",
+        timeout: int = 3600,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.timeout = timeout  # Default 60 minutes (3600 seconds)
+        self.session = requests.Session()
+        self.session.headers.update(
+            {"Authorization": "Bearer {}".format(api_key)}
+        )
+
+    def _handle_response(
+        self,
+        response: requests.Response,
+        success_message: str = None,
+        error_context: str = "Request",
+    ) -> Dict:
+        """
+        Handle API response with standardized error handling.
+
+        Args:
+            response: The response object from requests
+            success_message: Optional message to print on success
+            error_context: Context for error message (e.g., "Create ticker")
+
+        Returns:
+            Dict: Response JSON if successful
+
+        Raises:
+            Exception: If request fails (status != 200)
+        """
+        if response.status_code == 200:
+            if success_message:
+                print(success_message)
+            return response.json() if response.text else {}
+        else:
+            raise Exception(
+                f"{error_context} failed with status "
+                f"{response.status_code}: {response.text}"
+            )
+
+    def test_connection(self) -> Dict:
+        """
+        Test the API connection and authentication.
+
+        Returns:
+          Dict: Response from the API with user info.
+
+        Raises:
+          Exception: If connection fails or API key is invalid
+        """
+        response = self.session.get(f"{self.base_url}/auth/test-auth")
+        self._handle_response(
+            response,
+            success_message="✅ API key connection works.",
+            error_context="Connection test",
+        )
+        return True
+
+    def upload_data_source(
+        self,
+        file_path: str,
+        hub_schema: str,
+        table_name: str,
+        schema_path: str,
+        type: str,
+        ignore_superset_validation: bool = False,
+        explicitly_delete_view: bool = False,
+        force_cascade: bool = False,
+    ) -> Dict:
+        """
+        Upload, replace, or append data to a data source.
+
+        Args:
+          file_path: Path to the CSV file
+          hub_schema: The hub schema name (e.g. fight_matrix)
+          table_name: Name for the table
+          schema_path: Path to the JSON schema file
+          type: Operation type - "create", "replace", or "append"
+          ignore_superset_validation: If True, skip superset validation
+            (only applies to replace operations)
+          explicitly_delete_view: If True, delete view before replacing
+            (only applies to replace operations)
+          force_cascade: If True, use CASCADE when dropping columns
+            (only applies to replace operations)
+
+        Returns:
+          Dict: Response from the API
+
+        Raises:
+          Exception: If upload fails or invalid type specified
+        """
+
+        # Validate type parameter
+        valid_types = ["create", "replace", "append"]
+        if type not in valid_types:
+            raise ValueError(
+                f"Invalid type '{type}'. Must be one of: {valid_types}"
+            )
+
+        with open(schema_path, "r") as f:
+            table_schema = f.read()
+
+        form_data = {
+            "hub_schema": hub_schema,
+            "table_name": table_name,
+            "table_schema": table_schema,
+        }
+
+        # Only add these params for replace operations
+        if type == "replace":
+            form_data.update(
+                {
+                    "ignore_superset_validation": str(
+                        ignore_superset_validation
+                    ).lower(),
+                    "explicitly_delete_view": str(
+                        explicitly_delete_view
+                    ).lower(),
+                    "force_cascade": str(force_cascade).lower(),
+                }
+            )
+
+        # Map type to endpoint
+        endpoint_map = {
+            "create": "/data/workflows/create-data-source-from-file",
+            "replace": "/data/workflows/replace-data-source-from-file",
+            "append": "/data/workflows/append-data-source-from-file",
+        }
+
+        endpoint = endpoint_map[type]
+        action = type.capitalize()
+
+        file_path = Path(file_path)
+        with open(file_path, "rb") as f:
+            files = {"file": (file_path.name, f, "text/csv")}
+            response = self.session.post(
+                f"{self.base_url}{endpoint}",
+                data=form_data,
+                files=files,
+                timeout=self.timeout,
+            )
+
+        return self._handle_response(response, error_context=action)
+
+    def create_data_app(
+        self,
+        hub_schema: str,
+        data_app_name: str,
+        data_app_title: str,
+        data_app_description: str,
+    ) -> bool:
+        """
+        Create a data app using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          data_app_name: Name for the data app
+          data_app_title: Title for the data app
+          data_app_description: Description of the data app
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {
+            "hub_schema": hub_schema,
+            "data_app_name": data_app_name,
+            "data_app_title": data_app_title,
+            "data_app_description": data_app_description,
+        }
+
+        response = self.session.post(
+            f"{self.base_url}/apps/workflows/initialize-data-app",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Created data app: {data_app_name}",
+            error_context=f"Create data app {data_app_name}",
+        )
+        return True
+
+    def update_data_app_page(self, app_config: dict) -> bool:
+        """
+        Update data app page configuration using the API endpoint.
+
+        Args:
+          app_config: Dictionary containing the app configuration
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        response = self.session.patch(
+            f"{self.base_url}/apps/pages/update-data-app-page",
+            json=app_config,
+        )
+        app_name = app_config.get("data_app_name", "unknown")
+        self._handle_response(
+            response,
+            success_message=f"✓ Updated page config for: {app_name}",
+            error_context="Update page config",
+        )
+        return True
+
+    def create_data_view(
+        self, hub_schema: str, view_name: str, view_query: str
+    ) -> bool:
+        """
+        Create a data view using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          view_name: Name for the view
+          view_query: SQL query for the view
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {"view_query": view_query}
+        response = self.session.post(
+            f"{self.base_url}/data/views/{hub_schema}/{view_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Created data view: {view_name}",
+            error_context=f"Create view {view_name}",
+        )
+        return True
+
+    def update_data_view(
+        self, hub_schema: str, view_name: str, view_query: str
+    ) -> bool:
+        """
+        Update an existing data view using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          view_name: Name of the view to update
+          view_query: New SQL query for the view
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {"view_query": view_query}
+        response = self.session.patch(
+            f"{self.base_url}/data/views/{hub_schema}/{view_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Updated data view: {view_name}",
+            error_context=f"Update view {view_name}",
+        )
+        return True
+
+    def get_data_view(
+        self, hub_schema: str, view_name: str, include_data: bool = True
+    ) -> pd.DataFrame:
+        """
+        Get data from an existing data view and return as a pandas DataFrame.
+
+        Args:
+          hub_schema: The hub schema name
+          view_name: Name of the view to retrieve
+          include_data: Whether to include the actual data (default: True)
+
+        Returns:
+          pd.DataFrame: DataFrame containing the view data
+
+        Raises:
+          Exception: If retrieval fails
+        """
+        response = self.session.get(
+            f"{self.base_url}/data/views/{hub_schema}/{view_name}",
+            params={"include_data": include_data},
+        )
+        response_data = self._handle_response(
+            response, error_context=f"Get view {view_name}"
+        )
+        view_data = response_data.get("data", {}).get("data", [])
+        df = pd.DataFrame(view_data)
+        print(f"✓ Retrieved data view: {view_name} ({len(df)} rows)")
+        return df
+
+    def list_data_views(self, hub_schema: str) -> pd.DataFrame:
+        """
+        List all data views for a specific hub and return as a pandas DataFrame.
+
+        Args:
+          hub_schema: The hub schema name
+
+        Returns:
+          pd.DataFrame: DataFrame containing view metadata (hub_view_id, hub_id, created_by, view_name, view_query)
+
+        Raises:
+          Exception: If retrieval fails
+        """  # noqa: E501
+        response = self.session.get(f"{self.base_url}/data/views/{hub_schema}")
+        response_data = self._handle_response(
+            response, error_context=f"List views for hub {hub_schema}"
+        )
+        views_list = response_data.get("data", [])
+        df = pd.DataFrame(views_list)
+        print(f"✓ Retrieved {len(df)} data views for hub: {hub_schema}")
+        return df
+
+    def list_data_apps(self, hub_schema: str) -> pd.DataFrame:
+        """
+        List all data apps for a specific hub and return as a pandas DataFrame.
+
+        Args:
+          hub_schema: The hub schema name
+
+        Returns:
+          pd.DataFrame: DataFrame containing data app metadata
+
+        Raises:
+          Exception: If retrieval fails
+        """
+        response = self.session.get(
+            f"{self.base_url}/apps/dataapps/{hub_schema}"
+        )
+        response_data = self._handle_response(
+            response, error_context=f"List apps for hub {hub_schema}"
+        )
+        apps_list = response_data.get("data", [])
+        df = pd.DataFrame(apps_list)
+        print(f"✓ Retrieved {len(df)} data apps for hub: {hub_schema}")
+        return df
+
+    def update_component(
+        self, hub_schema: str, component_name: str, component_config: dict
+    ) -> bool:
+        """
+        Update an existing component using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          component_name: Name of the component to update
+          component_config: Component configuration dict
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        import json
+
+        payload = {"component_config": json.dumps(component_config)}
+
+        response = self.session.patch(
+            f"{self.base_url}/apps/components/{hub_schema}/{component_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Updated component: {component_name}",
+            error_context=f"Update component {component_name}",
+        )
+        return True
+
+    def create_widget(
+        self, hub_schema: str, widget_name: str, widget_config: dict
+    ) -> bool:
+        """
+        Create a new widget using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          widget_name: Name for the widget
+          widget_config: Widget configuration dict
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        import json
+
+        payload = {"widget_config": json.dumps(widget_config)}
+
+        response = self.session.post(
+            f"{self.base_url}/apps/widgets/{hub_schema}/{widget_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Created widget: {widget_name}",
+            error_context=f"Create widget {widget_name}",
+        )
+        return True
+
+    def update_widget(
+        self, hub_schema: str, widget_name: str, widget_config: dict
+    ) -> bool:
+        """
+        Update an existing widget using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          widget_name: Name of the widget to update
+          widget_config: Widget configuration dict
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        import json
+
+        payload = {"widget_config": json.dumps(widget_config)}
+
+        response = self.session.patch(
+            f"{self.base_url}/apps/widgets/{hub_schema}/{widget_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Updated widget: {widget_name}",
+            error_context=f"Update widget {widget_name}",
+        )
+        return True
+
+    def create_ticker(
+        self,
+        hub_schema: str,
+        ticker_name: str,
+        ticker_config: dict,
+        is_ticker_on_homepage: bool = False,
+        is_ticker_on_hub_homepage: bool = False,
+        data_app_name: str = None,
+        last_updated_table_name: str = None,
+    ) -> bool:
+        """
+        Create a new ticker using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          ticker_name: Name for the ticker
+          ticker_config: Ticker configuration dict (required)
+          is_ticker_on_homepage: Whether to show ticker on homepage
+            (default: False)
+          is_ticker_on_hub_homepage: Whether to show ticker on hub homepage
+            (default: False)
+          data_app_name: Name of the associated data app (optional)
+          last_updated_table_name: Name of the table to check for last
+            update (optional)
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {
+            "ticker_config": ticker_config,
+            "is_ticker_on_homepage": is_ticker_on_homepage,
+            "is_ticker_on_hub_homepage": is_ticker_on_hub_homepage,
+        }
+
+        if data_app_name is not None:
+            payload["data_app_name"] = data_app_name
+        if last_updated_table_name is not None:
+            payload["last_updated_table_name"] = last_updated_table_name
+
+        response = self.session.post(
+            f"{self.base_url}/apps/tickers/{hub_schema}/{ticker_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Created ticker: {ticker_name}",
+            error_context=f"Create ticker {ticker_name}",
+        )
+        return True
+
+    def update_ticker(
+        self,
+        hub_schema: str,
+        ticker_name: str,
+        ticker_config: dict = None,
+        is_ticker_on_homepage: bool = None,
+        is_ticker_on_hub_homepage: bool = None,
+        data_app_name: str = None,
+        last_updated_table_name: str = None,
+    ) -> bool:
+        """
+        Update an existing ticker using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          ticker_name: Name of the ticker to update
+          ticker_config: Ticker configuration dict (optional)
+          is_ticker_on_homepage: Whether to show ticker on homepage
+            (optional)
+          is_ticker_on_hub_homepage: Whether to show ticker on hub homepage
+            (optional)
+          data_app_name: Name of the associated data app (optional)
+          last_updated_table_name: Name of the table to check for last
+            update (optional)
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {}
+
+        if ticker_config is not None:
+            payload["ticker_config"] = ticker_config
+        if is_ticker_on_homepage is not None:
+            payload["is_ticker_on_homepage"] = is_ticker_on_homepage
+        if is_ticker_on_hub_homepage is not None:
+            payload["is_ticker_on_hub_homepage"] = is_ticker_on_hub_homepage
+        if data_app_name is not None:
+            payload["data_app_name"] = data_app_name
+        if last_updated_table_name is not None:
+            payload["last_updated_table_name"] = last_updated_table_name
+
+        response = self.session.patch(
+            f"{self.base_url}/apps/tickers/{hub_schema}/{ticker_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Updated ticker: {ticker_name}",
+            error_context=f"Update ticker {ticker_name}",
+        )
+        return True
+
+    def list_tickers(self, hub_schema: str) -> pd.DataFrame:
+        """
+        List all tickers for a specific hub and return as a pandas DataFrame.
+
+        Args:
+          hub_schema: The hub schema name
+
+        Returns:
+          pd.DataFrame: DataFrame containing ticker metadata
+
+        Raises:
+          Exception: If retrieval fails
+        """
+        response = self.session.get(
+            f"{self.base_url}/apps/tickers/{hub_schema}"
+        )
+        response_data = self._handle_response(
+            response, error_context=f"List tickers for hub {hub_schema}"
+        )
+        tickers_list = response_data.get("data", [])
+        df = pd.DataFrame(tickers_list)
+        print(f"✓ Retrieved {len(df)} tickers for hub: {hub_schema}")
+        return df
+
+    def create_endpoint(
+        self,
+        hub_schema: str,
+        hub_view_id: int,
+        hub_endpoint_name: str,
+        subscription_plan_type_name: str = "enterprise",
+        params_config: dict = None,
+    ) -> bool:
+        """
+        Create a new hub endpoint using the API.
+
+        Args:
+          hub_schema: The hub schema name
+          hub_view_id: ID of the hub view to expose as an endpoint
+          hub_endpoint_name: Name for the endpoint
+          subscription_plan_type_name: Subscription plan type required
+            (default: "enterprise")
+          params_config: Optional configuration for query parameters and
+            allowed columns
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {
+            "hub_view_id": hub_view_id,
+            "hub_endpoint_name": hub_endpoint_name,
+            "subscription_plan_type_name": subscription_plan_type_name,
+        }
+
+        if params_config is not None:
+            payload["params_config"] = params_config
+
+        response = self.session.post(
+            f"{self.base_url}/endpoints/{hub_schema}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Created endpoint: {hub_endpoint_name}",
+            error_context=f"Create endpoint {hub_endpoint_name}",
+        )
+        return True
+
+    def update_endpoint(
+        self,
+        hub_schema: str,
+        hub_endpoint_name: str,
+        hub_view_id: int = None,
+        subscription_plan_type_name: str = None,
+        params_config: dict = None,
+        is_active: bool = None,
+    ) -> bool:
+        """
+        Update an existing hub endpoint using the API.
+
+        Args:
+          hub_schema: The hub schema name
+          hub_endpoint_name: Name of the endpoint to update
+          hub_view_id: New hub view ID (optional)
+          subscription_plan_type_name: New subscription plan type (optional)
+          params_config: New configuration for query parameters (optional)
+          is_active: Whether the endpoint is active (optional)
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        payload = {}
+
+        if hub_view_id is not None:
+            payload["hub_view_id"] = hub_view_id
+        if subscription_plan_type_name is not None:
+            payload["subscription_plan_type_name"] = subscription_plan_type_name
+        if params_config is not None:
+            payload["params_config"] = params_config
+        if is_active is not None:
+            payload["is_active"] = is_active
+
+        response = self.session.patch(
+            f"{self.base_url}/endpoints/{hub_schema}/{hub_endpoint_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Updated endpoint: {hub_endpoint_name}",
+            error_context=f"Update endpoint {hub_endpoint_name}",
+        )
+        return True
+
+    def list_endpoints(self, hub_schema: str) -> pd.DataFrame:
+        """
+        List all endpoints for a specific hub and return as a pandas DataFrame.
+
+        Args:
+          hub_schema: The hub schema name
+
+        Returns:
+          pd.DataFrame: DataFrame containing endpoint metadata including
+            params_config
+
+        Raises:
+          Exception: If retrieval fails
+        """
+        response = self.session.get(f"{self.base_url}/endpoints/{hub_schema}")
+        response_data = self._handle_response(
+            response, error_context=f"List endpoints for hub {hub_schema}"
+        )
+        endpoints_list = response_data.get("data", [])
+        df = pd.DataFrame(endpoints_list)
+        print(f"✓ Retrieved {len(df)} endpoints for hub: {hub_schema}")
+        return df

polydata/common.py

@@ -0,0 +1,320 @@
+"""
+Common utility functions for Polydata client usage.
+"""
+
+import os
+import tempfile
+import time
+from typing import Dict
+
+import pandas as pd
+
+
+def hub_view_exists(view_name: str, hub_views_df: pd.DataFrame) -> bool:
+    """
+    Check if a view exists in the hub.
+
+    Args:
+        view_name: Full view name (schema.view_name format)
+        hub_views_df: DataFrame from client.list_data_views()
+
+    Returns:
+        True if the view exists, False otherwise
+    """
+    return view_name in hub_views_df["view_name"].values
+
+
+def create_or_update_view(
+    client,
+    hub_schema: str,
+    view_name: str,
+    view_query: str,
+    hub_views_df: pd.DataFrame,
+):
+    """
+    Create or update a data view based on whether it exists.
+
+    This function checks if a view already exists and calls either
+    client.create_data_view() or client.update_data_view() accordingly.
+
+    Args:
+        client: PolydataClient instance
+        hub_schema: Schema name
+        view_name: View name (without schema prefix)
+        view_query: SQL query for the view
+        hub_views_df: DataFrame from client.list_data_views(hub_schema=hub_schema)
+
+    Example:
+        ```python
+        from polydata import PolydataClient
+        from polydata.common import create_or_update_view
+
+        client = PolydataClient(api_key="...", base_url="...")
+        hub_views_df = client.list_data_views(hub_schema="my_schema")
+
+        create_or_update_view(
+            client=client,
+            hub_schema="my_schema",
+            view_name="my_view",
+            view_query="SELECT * FROM my_table",
+            hub_views_df=hub_views_df,
+        )
+        ```
+    """
+    full_view_name = f"{hub_schema}.{view_name}"
+
+    if hub_view_exists(full_view_name, hub_views_df):
+        client.update_data_view(
+            hub_schema=hub_schema,
+            view_name=view_name,
+            view_query=view_query,
+        )
+    else:
+        client.create_data_view(
+            hub_schema=hub_schema,
+            view_name=view_name,
+            view_query=view_query,
+        )
+
+
+def ticker_exists(ticker_name: str, hub_tickers_df: pd.DataFrame) -> bool:
+    """
+    Check if a ticker exists in the hub.
+
+    Args:
+        ticker_name: Ticker name to check
+        hub_tickers_df: DataFrame from client.list_tickers()
+
+    Returns:
+        True if the ticker exists, False otherwise
+    """
+    if hub_tickers_df.empty:
+        return False
+    return ticker_name in hub_tickers_df["ticker_name"].values
+
+
+def create_or_update_ticker(
+    client,
+    hub_schema: str,
+    ticker_name: str,
+    ticker_config: dict,
+    hub_tickers_df: pd.DataFrame,
+    is_ticker_on_homepage: bool = False,
+    is_ticker_on_hub_homepage: bool = False,
+    data_app_name: str = None,
+    last_updated_table_name: str = None,
+):
+    """
+    Create or update a ticker based on whether it exists.
+
+    This function checks if a ticker already exists and calls either
+    client.create_ticker() or client.update_ticker() accordingly.
+
+    Args:
+        client: PolydataClient instance
+        hub_schema: Schema name
+        ticker_name: Ticker name
+        ticker_config: Ticker configuration dict
+        hub_tickers_df: DataFrame from client.list_tickers()
+        is_ticker_on_homepage: Whether to show ticker on homepage
+        is_ticker_on_hub_homepage: Whether to show ticker on hub homepage
+        data_app_name: Name of the associated data app (optional)
+        last_updated_table_name: Name of the table to check for last update
+
+    Example:
+        ```python
+        from polydata import PolydataClient, create_or_update_ticker
+
+        client = PolydataClient(api_key="...", base_url="...")
+        hub_tickers_df = client.list_tickers(hub_schema="my_schema")
+
+        create_or_update_ticker(
+            client=client,
+            hub_schema="my_schema",
+            ticker_name="my_ticker",
+            ticker_config={...},
+            hub_tickers_df=hub_tickers_df,
+            is_ticker_on_homepage=True,
+            data_app_name="My App",
+        )
+        ```
+    """
+    if ticker_exists(ticker_name, hub_tickers_df):
+        client.update_ticker(
+            hub_schema=hub_schema,
+            ticker_name=ticker_name,
+            ticker_config=ticker_config,
+            is_ticker_on_homepage=is_ticker_on_homepage,
+            is_ticker_on_hub_homepage=is_ticker_on_hub_homepage,
+            data_app_name=data_app_name,
+            last_updated_table_name=last_updated_table_name,
+        )
+    else:
+        client.create_ticker(
+            hub_schema=hub_schema,
+            ticker_name=ticker_name,
+            ticker_config=ticker_config,
+            is_ticker_on_homepage=is_ticker_on_homepage,
+            is_ticker_on_hub_homepage=is_ticker_on_hub_homepage,
+            data_app_name=data_app_name,
+            last_updated_table_name=last_updated_table_name,
+        )
+
+
+def upload_large_csv_in_batches(
+    client,
+    file_path: str,
+    hub_schema: str,
+    table_name: str,
+    schema_path: str,
+    chunk_size: int = 10000,
+    delay_between_chunks: int = 5,
+    ignore_superset_validation: bool = False,
+    explicitly_delete_view: bool = False,
+    force_cascade: bool = False,
+) -> Dict:
+    """
+    Upload a large CSV file in batches to avoid memory issues.
+
+    This function splits a large CSV into smaller chunks and uploads them
+    sequentially. The first chunk uses type="replace" to clear/create the
+    table, and subsequent chunks use type="append" to add more rows.
+
+    This is useful when uploading files that would exceed API memory limits
+    (typically > 50-100MB depending on server configuration).
+
+    Args:
+        client: PolydataClient instance
+        file_path: Path to the large CSV file
+        hub_schema: The hub schema name (e.g. fight_matrix)
+        table_name: Name for the table
+        schema_path: Path to the JSON schema file
+        chunk_size: Number of rows per chunk (default: 10,000)
+        delay_between_chunks: Seconds to wait between chunk uploads to allow
+          server garbage collection (default: 5). Increase for memory-constrained
+          servers. Set to 0 to disable delays.
+        ignore_superset_validation: If True, skip superset validation
+          (only applies to first/replace operation)
+        explicitly_delete_view: If True, delete view before replacing
+          (only applies to first/replace operation)
+        force_cascade: If True, use CASCADE when dropping columns
+          (only applies to first/replace operation)
+
+    Returns:
+        Dict: Summary of upload results
+
+    Example:
+        ```python
+        from polydata import PolydataClient
+        from polydata.common import upload_large_csv_in_batches
+
+        client = PolydataClient(api_key="...", base_url="...")
+
+        upload_large_csv_in_batches(
+            client=client,
+            file_path="/path/to/large_file.csv",
+            hub_schema="my_schema",
+            table_name="my_table",
+            schema_path="/path/to/schema.json",
+            chunk_size=10000
+        )
+        ```
+    """
+    print(f"\n📦 Starting batched upload of: {file_path}")
+    print(f"   Chunk size: {chunk_size:,} rows")
+
+    # Read CSV as raw lines to preserve exact formatting
+    with open(file_path, "r") as f:
+        lines = f.readlines()
+
+    header = lines[0]
+    data_lines = lines[1:]
+    total_rows = len(data_lines)
+    num_chunks = (total_rows + chunk_size - 1) // chunk_size
+
+    print(f"   Total rows: {total_rows:,}")
+    print(f"   Number of chunks: {num_chunks}")
+
+    # Create temporary directory for chunk files
+    temp_dir = tempfile.mkdtemp(prefix="polydata_chunks_")
+    print(f"   Temporary directory: {temp_dir}")
+
+    try:
+        for chunk_num in range(num_chunks):
+            start_row = chunk_num * chunk_size
+            end_row = min(start_row + chunk_size, total_rows)
+            chunk_lines = data_lines[start_row:end_row]
+
+            # Create temporary chunk file
+            chunk_filename = f"chunk_{chunk_num:04d}.csv"
+            chunk_path = os.path.join(temp_dir, chunk_filename)
+
+            # Write chunk preserving exact CSV format
+            with open(chunk_path, "w") as f:
+                f.write(header)
+                f.writelines(chunk_lines)
+
+            chunk_size_mb = os.path.getsize(chunk_path) / (1024 * 1024)
+            chunk_row_count = len(chunk_lines)
+
+            print(
+                f"\n   📤 Uploading chunk {chunk_num + 1}/{num_chunks} "
+                f"(rows {start_row:,}-{end_row:,}, "
+                f"{chunk_row_count:,} rows, {chunk_size_mb:.2f} MB)"
+            )
+
+            # First chunk: replace, rest: append
+            if chunk_num == 0:
+                client.upload_data_source(
+                    file_path=chunk_path,
+                    hub_schema=hub_schema,
+                    table_name=table_name,
+                    schema_path=schema_path,
+                    type="replace",
+                    ignore_superset_validation=ignore_superset_validation,
+                    explicitly_delete_view=explicitly_delete_view,
+                    force_cascade=force_cascade,
+                )
+            else:
+                client.upload_data_source(
+                    file_path=chunk_path,
+                    hub_schema=hub_schema,
+                    table_name=table_name,
+                    schema_path=schema_path,
+                    type="append",
+                )
+
+            print(f"      ✓ Chunk {chunk_num + 1} uploaded successfully")
+
+            # Clean up chunk file after upload
+            os.remove(chunk_path)
+
+            # Add delay between chunks to allow server garbage collection
+            # (skip delay after last chunk)
+            if delay_between_chunks > 0 and chunk_num < num_chunks - 1:
+                print(
+                    f"      ⏳ Waiting {delay_between_chunks}s for server "
+                    f"garbage collection..."
+                )
+                time.sleep(delay_between_chunks)
+
+    finally:
+        # Clean up temporary directory
+        try:
+            os.rmdir(temp_dir)
+            print("\n   🧹 Cleaned up temporary directory")
+        except OSError:
+            print(
+                f"\n   ⚠️  Could not remove temp directory: {temp_dir} "
+                f"(may contain files)"
+            )
+
+    print(
+        f"\n   ✅ Batched upload complete: {total_rows:,} total rows uploaded"
+    )
+
+    return {
+        "total_rows": total_rows,
+        "num_chunks": num_chunks,
+        "chunk_size": chunk_size,
+    }

polydata_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: polydata-client
+Version: 0.1.0
+Summary: Official Python client for Polydata API
+Author-email: Polydata <support@polydata.co>
+Maintainer-email: Polydata <support@polydata.co>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://polydata.co
+Project-URL: Documentation, https://docs.polydata.co/
+Keywords: polydata,api,client,data,data-apps,data-viz
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pandas>=1.5.0
+Dynamic: license-file
+
+# Polydata Python Client
+
+Official Python client for the [Polydata](https://polydata.co) API.
+
+## Installation
+
+```bash
+pip install polydata-client
+```
+
+## Quick Start
+
+```python
+from polydata import PolydataClient
+
+# Initialize client with your API key
+client = PolydataClient(api_key="pd_sk_your_api_key_here")
+
+# Test connection
+client.test_connection()
+
+# Get data from a view
+df = client.get_data_view(
+    hub_schema="my_hub",
+    view_name="my_view"
+)
+```
+
+## Authentication
+
+Get your API key from your Polydata dashboard. You can pass it directly or set it as an environment variable:
+
+```bash
+export POLYDATA_API_KEY="pd_sk_your_api_key_here"
+```
+
+```python
+import os
+from polydata import PolydataClient
+
+client = PolydataClient(api_key=os.getenv("POLYDATA_API_KEY"))
+```
+
+## Core Features
+
+### Get Data
+
+Retrieve data from a view as a pandas DataFrame:
+
+```python
+df = client.get_data_view(
+    hub_schema="my_hub",
+    view_name="my_view"
+)
+```
+
+### Upload Data
+
+Upload CSV data to create or update tables:
+
+```python
+client.upload_data_source(
+    file_path="data.csv",
+    hub_schema="my_hub",
+    table_name="my_table",
+    schema_path="schema.json",
+    type="create"  # or "replace" or "append"
+)
+```
+
+### Manage Views
+
+```python
+# List all views
+views = client.list_data_views(hub_schema="my_hub")
+```
+
+## Additional Features
+
+The client also supports:
+
+- Data apps, pages, components, and widgets
+- Tickers for real-time displays
+- Custom API endpoints
+- Batch uploads for large files
+
+## Requirements
+
+- Python >= 3.8
+- requests >= 2.31.0
+- pandas >= 1.5.0
+
+## Links
+
+- [Homepage](https://polydata.co)
+- [Documentation](https://docs.polydata.co)
+
+## License
+
+Apache License 2.0

polydata_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+polydata/__init__.py,sha256=BEtkb0BKMCWA9G7M6wsq6zyzK376BOJ_JJRM1eds8Ck,125
+polydata/client.py,sha256=c-sh3X812jXcXYjHrEm8vfyTuAfoKPr7Bb_xR3Ihb1Q,21802
+polydata/common.py,sha256=KG5UgLjc61E4SXRexgTwrTO-zI6B-Zwb1IofcGG9l_A,10526
+polydata_client-0.1.0.dist-info/licenses/LICENSE,sha256=RPfqTzAnWfAG4rjiQ4dnSvLSumVXV35vnchUMmiySpw,10497
+polydata_client-0.1.0.dist-info/licenses/NOTICE,sha256=CQcX8EeU0TGCgxJykn5uQIiHq8tNfUqx1FONK3zj8LM,131
+polydata_client-0.1.0.dist-info/METADATA,sha256=PgGV1P68W0Y1KyMR6MZYPb-ZMc0XxqjwavodJYZyI1Q,2821
+polydata_client-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+polydata_client-0.1.0.dist-info/top_level.txt,sha256=Ocz6UylAMpuNxakKZdMihF8mlzzKaYXPMtI128RhTyw,9
+polydata_client-0.1.0.dist-info/RECORD,,

polydata_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polydata_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                    http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source files, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Support. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright 2026 Polydata, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

polydata_client-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,4 @@
+Polydata Python Client
+Copyright 2026 Polydata, Inc.
+
+This product includes software developed at Polydata (https://polydata.co/).

polydata_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+polydata