polydata-client 0.1.1__tar.gz → 0.1.3__tar.gz

polydata_client-0.1.3/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to the Polydata Python client will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.3] - 2026-10-13
+
+### Added
+
+- `update_data_view()` adds `update_method`: `"create_or_replace"` (default) keeps views that read from the updated view, while `"drop_and_create"` allows column changes.
+- `create_component()`, `list_components()` and `list_widgets()`.
+- `create_or_update_component()` and `create_or_update_widget()`, so the same script can create components and widgets on a brand-new hub or update them on an existing one.
+
+### Changed
+
+- `create_or_update_view()` replaces `allow_delete_then_create` with `update_method` (`"create_or_replace"` default, or `"drop_and_create"` when a query changes the view's columns). It no longer guesses from a failed update. With `"drop_and_create"`, `dependent_views` are recreated even if the update fails, and the view keeps its history.
+
+### Removed
+
+- `upload_data_source()` and `upload_large_csv_in_batches()` no longer accept `force_cascade`. A table replace no longer deletes the views that depend on it; if one is in the way, the replace fails with a clear error. To rebuild dependent views, use `create_or_update_view()` with `dependent_views`.
+
+## [0.1.2] - 2026-07-23
+
+### Added
+
+- `create_or_update_view()` adds `allow_delete_then_create` option, which helps creators who change their column names.
+- `create_or_update_view()` also adds `dependent_views` which are dropped and rebuilt around the recreate.
+
+## [0.1.1] - 2026-01-27
+
+### Added
+
+- Added utilities to manage and update the cache
+  - `client.get_cache_stats()` Gets the Redis cache statistics.
+  - `client.clear_hub_cache()` Clears all cached data app pages for a Hub.
+
+## [0.1.0] - 2026-01-16
+
+### Added
+
+- Initial release of Polydata Python client
+- Support for data source uploads (create, replace, append)
+- Data view management (create, update, get, list)
+- Data app creation and page updates
+- Component and widget management
+- Ticker creation and updates
+- Custom endpoint creation and management
+- Helper utilities for create-or-update patterns
+- Batch upload support for large CSV files
+- Comprehensive error handling
+- API connection testing

{polydata_client-0.1.1 → polydata_client-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polydata-client
-Version: 0.1.1
+Version: 0.1.3
 Summary: Official Python client for Polydata API
 Author-email: Polydata <support@polydata.co>
 Maintainer-email: Polydata <support@polydata.co>

polydata_client-0.1.3/polydata/__init__.py

@@ -0,0 +1,10 @@
+from .client import PolydataClient
+from .common import (
+    create_or_update_component,
+    create_or_update_endpoint,
+    create_or_update_ticker,
+    create_or_update_view,
+    create_or_update_widget,
+)
+
+__version__ = "0.1.0"

{polydata_client-0.1.1 → polydata_client-0.1.3}/polydata/client.py

@@ -79,7 +79,6 @@ class PolydataClient:
         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.
@@ -94,8 +93,6 @@ class PolydataClient:
             (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
@@ -130,7 +127,6 @@ class PolydataClient:
                     "explicitly_delete_view": str(
                         explicitly_delete_view
                     ).lower(),
-                    "force_cascade": str(force_cascade).lower(),
                 }
             )
 
@@ -241,7 +237,11 @@ class PolydataClient:
         return True
 
     def update_data_view(
-        self, hub_schema: str, view_name: str, view_query: str
+        self,
+        hub_schema: str,
+        view_name: str,
+        view_query: str,
+        update_method: str = "create_or_replace",
     ) -> bool:
         """
         Update an existing data view using the API endpoint.
@@ -250,11 +250,14 @@ class PolydataClient:
           hub_schema: The hub schema name
           view_name: Name of the view to update
           view_query: New SQL query for the view
+          update_method: "create_or_replace" (default) keeps views that read
+            from this one, but can't change its columns. "drop_and_create"
+            can change columns, but fails if other views read from this one.
 
         Returns:
           bool: True if successful, False otherwise
         """
-        payload = {"view_query": view_query}
+        payload = {"view_query": view_query, "update_method": update_method}
         response = self.session.patch(
             f"{self.base_url}/data/views/{hub_schema}/{view_name}",
             json=payload,
@@ -266,6 +269,30 @@ class PolydataClient:
         )
         return True
 
+    def delete_data_view(self, hub_schema: str, view_name: str) -> bool:
+        """
+        Delete an existing data view using the API endpoint.
+
+        Drops both the physical Postgres view and its hub_views metadata
+        record.
+
+        Args:
+          hub_schema: The hub schema name
+          view_name: Name of the view to delete
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        response = self.session.delete(
+            f"{self.base_url}/data/views/{hub_schema}/{view_name}",
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Deleted data view: {view_name}",
+            error_context=f"Delete view {view_name}",
+        )
+        return True
+
     def get_data_view(
         self, hub_schema: str, view_name: str, include_data: bool = True
     ) -> pd.DataFrame:
@@ -370,6 +397,48 @@ class PolydataClient:
         )
         return True
 
+    def create_component(
+        self, hub_schema: str, component_name: str, component_config: dict
+    ) -> bool:
+        """
+        Create a new component using the API endpoint.
+
+        Args:
+          hub_schema: The hub schema name
+          component_name: Name for the component
+          component_config: Component configuration dict
+
+        Returns:
+          bool: True if successful, False otherwise
+        """
+        # Unlike update_component, the create endpoint takes the config as a
+        # dict rather than a JSON string.
+        payload = {"component_config": component_config}
+
+        response = self.session.post(
+            f"{self.base_url}/apps/components/{hub_schema}/{component_name}",
+            json=payload,
+        )
+        self._handle_response(
+            response,
+            success_message=f"✓ Created component: {component_name}",
+            error_context=f"Create component {component_name}",
+        )
+        return True
+
+    def list_components(self, hub_schema: str) -> pd.DataFrame:
+        """List a hub's components as a DataFrame (one row per component)."""
+        response = self.session.get(
+            f"{self.base_url}/apps/components/{hub_schema}"
+        )
+        response_data = self._handle_response(
+            response, error_context=f"List components for hub {hub_schema}"
+        )
+        components_list = response_data.get("data", [])
+        df = pd.DataFrame(components_list)
+        print(f"✓ Retrieved {len(df)} components for hub: {hub_schema}")
+        return df
+
     def create_widget(
         self, hub_schema: str, widget_name: str, widget_config: dict
     ) -> bool:
@@ -428,6 +497,19 @@ class PolydataClient:
         )
         return True
 
+    def list_widgets(self, hub_schema: str) -> pd.DataFrame:
+        """List a hub's widgets as a DataFrame (one row per widget)."""
+        response = self.session.get(
+            f"{self.base_url}/apps/widgets/{hub_schema}"
+        )
+        response_data = self._handle_response(
+            response, error_context=f"List widgets for hub {hub_schema}"
+        )
+        widgets_list = response_data.get("data", [])
+        df = pd.DataFrame(widgets_list)
+        print(f"✓ Retrieved {len(df)} widgets for hub: {hub_schema}")
+        return df
+
     def create_ticker(
         self,
         hub_schema: str,
@@ -719,4 +801,4 @@ class PolydataClient:
             f"  - Cleared {deleted} cached pages out of {cached} that were cached ({total} total pages)"
         )
 
-        return True
+        return True

{polydata_client-0.1.1 → polydata_client-0.1.3}/polydata/common.py

@@ -30,6 +30,8 @@ def create_or_update_view(
     view_name: str,
     view_query: str,
     hub_views_df: pd.DataFrame,
+    update_method: str = "create_or_replace",
+    dependent_views: dict | None = None,
 ):
     """
     Create or update a data view based on whether it exists.
@@ -43,6 +45,18 @@ def create_or_update_view(
         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)
+        update_method: How an existing view is updated.
+            - "create_or_replace" (default): keeps views that read from this
+              one, but can't rename, reorder or remove columns.
+            - "drop_and_create": use when the query changes the view's
+              columns. Views that read from this one block the drop, so list
+              them in dependent_views.
+        dependent_views: Mapping of {view_name: view_query} for views that read
+            from this view. Only used with "drop_and_create": they are deleted
+            before the update and recreated after it (in reverse order), even
+            if the update fails. Every view needs a query (a ValueError is
+            raised before anything is deleted otherwise), and each query must
+            be valid against the NEW definition of this view.
 
     Example:
         ```python
@@ -63,18 +77,65 @@ def create_or_update_view(
     """
     full_view_name = f"{hub_schema}.{view_name}"
 
-    if hub_view_exists(full_view_name, hub_views_df):
-        client.update_data_view(
+    if not hub_view_exists(full_view_name, hub_views_df):
+        client.create_data_view(
             hub_schema=hub_schema,
             view_name=view_name,
             view_query=view_query,
         )
-    else:
-        client.create_data_view(
+        return
+
+    valid_update_methods = ["create_or_replace", "drop_and_create"]
+    if update_method not in valid_update_methods:
+        raise ValueError(
+            f"Invalid update_method '{update_method}'. "
+            f"Must be one of: {valid_update_methods}"
+        )
+
+    if update_method == "create_or_replace":
+        client.update_data_view(
             hub_schema=hub_schema,
             view_name=view_name,
             view_query=view_query,
         )
+    else:
+        # Views that read from this one block its (non-CASCADE) drop, so they
+        # are deleted first and recreated afterwards, even if the update fails.
+        dependent_views = dependent_views or {}
+        missing_queries = [
+            dependent_name
+            for dependent_name, dependent_query in dependent_views.items()
+            if not dependent_query or not dependent_query.strip()
+        ]
+        if missing_queries:
+            raise ValueError(
+                f"dependent_views {missing_queries} have no view_query, so "
+                "they couldn't be recreated after the update."
+            )
+
+        for dependent_name in dependent_views:
+            if hub_view_exists(f"{hub_schema}.{dependent_name}", hub_views_df):
+                client.delete_data_view(
+                    hub_schema=hub_schema,
+                    view_name=dependent_name,
+                )
+
+        try:
+            client.update_data_view(
+                hub_schema=hub_schema,
+                view_name=view_name,
+                view_query=view_query,
+                update_method="drop_and_create",
+            )
+        finally:
+            for dependent_name, dependent_query in reversed(
+                list(dependent_views.items())
+            ):
+                client.create_data_view(
+                    hub_schema=hub_schema,
+                    view_name=dependent_name,
+                    view_query=dependent_query,
+                )
 
 
 def ticker_exists(ticker_name: str, hub_tickers_df: pd.DataFrame) -> bool:
@@ -161,6 +222,150 @@ def create_or_update_ticker(
         )
 
 
+def endpoint_exists(endpoint_name: str, hub_endpoints_df: pd.DataFrame) -> bool:
+    """
+    Check if an endpoint exists in the hub.
+
+    Args:
+        endpoint_name: Endpoint name to check
+        hub_endpoints_df: DataFrame from client.list_endpoints()
+
+    Returns:
+        True if the endpoint exists, False otherwise
+    """
+    if hub_endpoints_df.empty:
+        return False
+    return endpoint_name in hub_endpoints_df["hub_endpoint_name"].values
+
+
+def create_or_update_endpoint(
+    client,
+    hub_schema: str,
+    endpoint_name: str,
+    view_name: str,
+    params_config: dict,
+    hub_views_df: pd.DataFrame,
+    hub_endpoints_df: pd.DataFrame,
+    subscription_plan_type_name: str = "enterprise",
+):
+    """
+    Create or update an endpoint based on whether it exists.
+
+    Mirrors create_or_update_view: checks hub_endpoints_df and calls either
+    client.update_endpoint() or client.create_endpoint() (resolving the backing
+    view's id from hub_views_df) accordingly.
+
+    Args:
+        client: PolydataClient instance
+        hub_schema: Schema name
+        endpoint_name: Human-readable endpoint name
+        view_name: Backing view name (without schema prefix)
+        params_config: Endpoint params config (allowed_params/allowed_columns)
+        hub_views_df: DataFrame from client.list_data_views()
+        hub_endpoints_df: DataFrame from client.list_endpoints()
+        subscription_plan_type_name: Plan required when creating the endpoint
+            (default: "enterprise"); ignored on update
+
+    Example:
+        ```python
+        from polydata import PolydataClient
+        from polydata.common import create_or_update_endpoint
+
+        client = PolydataClient(api_key="...", base_url="...")
+        hub_views_df = client.list_data_views(hub_schema="my_schema")
+        hub_endpoints_df = client.list_endpoints(hub_schema="my_schema")
+
+        create_or_update_endpoint(
+            client=client,
+            hub_schema="my_schema",
+            endpoint_name="Available Leagues",
+            view_name="available_leagues",
+            params_config={...},
+            hub_views_df=hub_views_df,
+            hub_endpoints_df=hub_endpoints_df,
+        )
+        ```
+    """
+    if endpoint_exists(endpoint_name, hub_endpoints_df):
+        client.update_endpoint(
+            hub_schema=hub_schema,
+            hub_endpoint_name=endpoint_name,
+            params_config=params_config,
+        )
+    else:
+        full_view_name = f"{hub_schema}.{view_name}"
+        matching = hub_views_df[hub_views_df["view_name"] == full_view_name]
+        if matching.empty:
+            raise ValueError(f"Could not find view {full_view_name}")
+        client.create_endpoint(
+            hub_schema=hub_schema,
+            hub_view_id=int(matching.iloc[0]["hub_view_id"]),
+            hub_endpoint_name=endpoint_name,
+            subscription_plan_type_name=subscription_plan_type_name,
+            params_config=params_config,
+        )
+
+
+def component_exists(
+    component_name: str, hub_components_df: pd.DataFrame
+) -> bool:
+    """Check if a component exists, given client.list_components() output."""
+    if hub_components_df.empty:
+        return False
+    return component_name in hub_components_df["component_name"].values
+
+
+def create_or_update_component(
+    client,
+    hub_schema: str,
+    component_name: str,
+    component_config: dict,
+    hub_components_df: pd.DataFrame,
+):
+    """Create the component, or update it if it already exists."""
+    if component_exists(component_name, hub_components_df):
+        client.update_component(
+            hub_schema=hub_schema,
+            component_name=component_name,
+            component_config=component_config,
+        )
+    else:
+        client.create_component(
+            hub_schema=hub_schema,
+            component_name=component_name,
+            component_config=component_config,
+        )
+
+
+def widget_exists(widget_name: str, hub_widgets_df: pd.DataFrame) -> bool:
+    """Check if a widget exists, given client.list_widgets() output."""
+    if hub_widgets_df.empty:
+        return False
+    return widget_name in hub_widgets_df["widget_name"].values
+
+
+def create_or_update_widget(
+    client,
+    hub_schema: str,
+    widget_name: str,
+    widget_config: dict,
+    hub_widgets_df: pd.DataFrame,
+):
+    """Create the widget, or update it if it already exists."""
+    if widget_exists(widget_name, hub_widgets_df):
+        client.update_widget(
+            hub_schema=hub_schema,
+            widget_name=widget_name,
+            widget_config=widget_config,
+        )
+    else:
+        client.create_widget(
+            hub_schema=hub_schema,
+            widget_name=widget_name,
+            widget_config=widget_config,
+        )
+
+
 def upload_large_csv_in_batches(
     client,
     file_path: str,
@@ -171,7 +376,6 @@ def upload_large_csv_in_batches(
     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.
@@ -197,8 +401,6 @@ def upload_large_csv_in_batches(
           (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
@@ -273,7 +475,6 @@ def upload_large_csv_in_batches(
                     type="replace",
                     ignore_superset_validation=ignore_superset_validation,
                     explicitly_delete_view=explicitly_delete_view,
-                    force_cascade=force_cascade,
                 )
             else:
                 client.upload_data_source(
@@ -299,7 +500,6 @@ def upload_large_csv_in_batches(
                 time.sleep(delay_between_chunks)
 
     finally:
-        # Clean up temporary directory
         try:
             os.rmdir(temp_dir)
             print("\n   🧹 Cleaned up temporary directory")

{polydata_client-0.1.1 → polydata_client-0.1.3}/polydata_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polydata-client
-Version: 0.1.1
+Version: 0.1.3
 Summary: Official Python client for Polydata API
 Author-email: Polydata <support@polydata.co>
 Maintainer-email: Polydata <support@polydata.co>

{polydata_client-0.1.1 → polydata_client-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polydata-client"
-version = "0.1.1"
+version = "0.1.3"
 description = "Official Python client for Polydata API"
 readme = "README.md"
 requires-python = ">=3.8"

polydata_client-0.1.1/CHANGELOG.md

@@ -1,31 +0,0 @@
-# Changelog
-
-All notable changes to the Polydata Python client will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.1.1] - 2026-01-27
-
-### Added
-
-- Added utilities to manage and update the cache
-  - `client.get_cache_stats()` Gets the Redis cache statistics.
-  - `client.clear_hub_cache()` Clears all cached data app pages for a Hub.
-
-
-## [0.1.0] - 2026-01-16
-
-### Added
-
-- Initial release of Polydata Python client
-- Support for data source uploads (create, replace, append)
-- Data view management (create, update, get, list)
-- Data app creation and page updates
-- Component and widget management
-- Ticker creation and updates
-- Custom endpoint creation and management
-- Helper utilities for create-or-update patterns
-- Batch upload support for large CSV files
-- Comprehensive error handling
-- API connection testing

polydata_client-0.1.1/polydata/__init__.py

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