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

{polydata_client-0.1.2 → polydata_client-0.1.3}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to the Polydata Python client will be documented in this fil
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polydata-client
-Version: 0.1.2
+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.2 → polydata_client-0.1.3}/polydata/__init__.py

@@ -1,8 +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.2 → 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,
@@ -394,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:
@@ -452,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,

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

@@ -30,7 +30,7 @@ def create_or_update_view(
     view_name: str,
     view_query: str,
     hub_views_df: pd.DataFrame,
-    allow_delete_then_create: bool = False,
+    update_method: str = "create_or_replace",
     dependent_views: dict | None = None,
 ):
     """
@@ -45,20 +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)
-        allow_delete_then_create: If True and an in-place update fails, fall back
-            to deleting and recreating the view. The update uses CREATE OR
-            REPLACE VIEW, which cannot rename or reorder existing columns; enable
-            this when a query change alters the view's column set. Off by default
-            because delete-then-create is more destructive. When False, an update
-            failure propagates unchanged.
-        dependent_views: Mapping of {view_name: view_query} for views that
-            depend on this view and would block its DROP. Only consulted on the
-            delete-then-create fallback: dependents are deleted first (in the
-            given order) so the main view can be dropped without CASCADE, then
-            recreated from the provided queries (in reverse order) once the
-            main view is rebuilt. Pass each dependent's current query if it is
-            unchanged — but note it must still be valid against the NEW main
-            view definition.
+        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
@@ -87,43 +85,57 @@ def create_or_update_view(
         )
         return
 
-    try:
+    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,
         )
-    except Exception:
-        if not allow_delete_then_create:
-            raise
-        # In-place update failed (e.g. the query renames/reorders columns,
-        # which CREATE OR REPLACE VIEW forbids). Rebuild from scratch:
-        # dependents are knocked out first so the plain (non-CASCADE) DROP of
-        # the main view succeeds, then restored once it is rebuilt.
+    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,
                 )
-        client.delete_data_view(
-            hub_schema=hub_schema,
-            view_name=view_name,
-        )
-        client.create_data_view(
-            hub_schema=hub_schema,
-            view_name=view_name,
-            view_query=view_query,
-        )
-        for dependent_name, dependent_query in reversed(
-            list(dependent_views.items())
-        ):
-            client.create_data_view(
+
+        try:
+            client.update_data_view(
                 hub_schema=hub_schema,
-                view_name=dependent_name,
-                view_query=dependent_query,
+                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:
@@ -294,6 +306,66 @@ def create_or_update_endpoint(
         )
 
 
+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,
@@ -304,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.
@@ -330,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
@@ -406,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(

{polydata_client-0.1.2 → 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.2
+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.2 → polydata_client-0.1.3}/pyproject.toml

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