Merge pull request #464 from palewire/main

feat: implement method chaining for create, update, and publish

Author: palewire

.clinerules

@@ -1149,6 +1149,104 @@ Comprehensive tests for these operations are in `tests/functional/test_base_char
 - Tests cover successful operations, error cases, and custom access tokens
 - Test functions: `test_base_chart_delete_success`, `test_base_chart_delete_no_chart_id`, `test_base_chart_duplicate_success`, `test_base_chart_duplicate_invalid_response`, `test_base_chart_fork_success`, `test_get_display_urls_success`, `test_get_display_urls_no_chart_id`, `test_get_display_urls_custom_token`, `test_get_iframe_code_success`, `test_get_iframe_code_responsive`, `test_get_iframe_code_no_chart_id`, `test_get_iframe_code_custom_token`, `test_get_editor_url_success`, `test_get_editor_url_no_chart_id`, `test_get_png_url_success`, `test_get_png_url_no_chart_id`, etc.
 
+### Method Chaining Pattern (v2.0.0+)
+
+**BREAKING CHANGE**: Starting in version 2.0.0, the `create()`, `update()`, and `publish()` methods in BaseChart return `self` instead of their previous return types, enabling method chaining (fluent interface pattern).
+
+**Return Type Changes:**
+- `create()`: Changed from `str` (chart_id) to `"BaseChart"` (self)
+- `update()`: Changed from `str` (chart_id) to `"BaseChart"` (self)
+- `publish()`: Changed from `bool` to `"BaseChart"` (self), now raises exception on failure instead of returning False
+
+**Key Features:**
+- All three methods now return the chart instance (`self`) for method chaining
+- Methods can be chained together: `chart.create().update().publish()`
+- The `chart_id` is still set internally and accessible via `chart.chart_id`
+- `publish()` now raises an exception on failure instead of returning False
+
+**Migration Guide:**
+
+*Before (v1.x):*
+```python
+from datawrapper.charts import LineChart
+
+chart = LineChart(title="Temperature Data")
+chart_id = chart.create()  # Returns chart_id string
+print(f"Created chart: {chart_id}")
+
+chart.title = "Updated Temperature Data"
+chart_id = chart.update()  # Returns chart_id string
+
+success = chart.publish()  # Returns bool
+if success:
+    print("Published successfully")
+```
+
+*After (v2.0.0+):*
+```python
+from datawrapper.charts import LineChart
+
+# Method chaining approach
+chart = LineChart(title="Temperature Data").create().publish()
+print(f"Created chart: {chart.chart_id}")
+
+# Or step-by-step with chaining
+chart = LineChart(title="Temperature Data")
+chart.create().update().publish()
+
+# publish() now raises exception on failure
+try:
+    chart.publish()
+except Exception as e:
+    print(f"Publish failed: {e}")
+```
+
+**Benefits:**
+- More concise code with method chaining
+- Better developer experience with fluent interface
+- Consistent with modern Python API design patterns
+- Enables complex workflows in fewer lines of code
+
+**Example Workflows:**
+
+```python
+from datawrapper.charts import LineChart, Line
+
+# Create, configure, and publish in one chain
+chart = (
+    LineChart(title="Sales Trends")
+    .create()
+    .publish()
+)
+
+# Create, update multiple times, then publish
+chart = LineChart(title="Initial Title")
+chart.create()
+chart.title = "Updated Title"
+chart.update()
+chart.description = "Added description"
+chart.update().publish()
+
+# Duplicate and immediately publish
+original = LineChart.get(chart_id="abc123")
+duplicate = original.duplicate().publish()
+
+# Fork and update in one chain
+fork = original.fork()
+fork.title = "Forked Chart"
+fork.update().publish()
+```
+
+**Testing:**
+Comprehensive tests for method chaining are in `tests/functional/test_base_chart_operations.py`:
+- Tests verify that methods return the chart instance (self) for chaining
+- Tests verify identity checks (`result is chart`)
+- Tests cover full chaining workflows: `create().update().publish()`
+- All tests use fully mocked API calls (no API token required)
+
+**Documentation:**
+See `docs/user-guide/chart-operations.md` for complete migration guide and examples.
+
 ## Testing Patterns
 
 ### Mocking API Calls

datawrapper/charts/base.py

@@ -615,7 +615,7 @@ def get(cls, chart_id: str, access_token: str | None = None) -> "BaseChart":
 
     def create(
         self, access_token: str | None = None, folder_id: int | None = None
-    ) -> str:
+    ) -> "BaseChart":
         """Create a new chart via the Datawrapper API.
 
         Args:
@@ -624,7 +624,7 @@ def create(
             folder_id: Optional folder ID to create the chart in.
 
         Returns:
-            The chart ID of the created chart.
+            Self, to enable method chaining. The chart ID is stored in self.chart_id.
 
         Raises:
             ValueError: If no access token is available or API returns invalid response.
@@ -655,19 +655,19 @@ def create(
         if not chart_id or not isinstance(chart_id, str):
             raise ValueError(f"Invalid chart ID received from API: {chart_id}")
 
-        # Store and return the chart ID
+        # Store the chart ID and return self for chaining
         self.chart_id = chart_id
-        return self.chart_id
+        return self
 
-    def update(self, access_token: str | None = None) -> str:
+    def update(self, access_token: str | None = None) -> "BaseChart":
         """Update an existing chart via the Datawrapper API.
 
         Args:
             access_token: Optional Datawrapper API access token.
                          If not provided, will use DATAWRAPPER_ACCESS_TOKEN environment variable.
 
         Returns:
-            The chart ID of the updated chart.
+            Self, to enable method chaining.
 
         Raises:
             ValueError: If no chart_id is set or no access token is available.
@@ -695,25 +695,25 @@ def update(self, access_token: str | None = None) -> str:
             metadata=metadata["metadata"],
         )
 
-        # Return the chart ID
-        return self.chart_id
+        # Return self for chaining
+        return self
 
     def publish(
         self,
         access_token: str | None = None,
-    ) -> bool:
+    ) -> "BaseChart":
         """Publish the chart via the Datawrapper API.
 
         Args:
             access_token: Optional Datawrapper API access token.
                          If not provided, will use DATAWRAPPER_ACCESS_TOKEN environment variable.
 
         Returns:
-            True if the chart was published successfully, False otherwise.
+            Self, to enable method chaining.
 
         Raises:
             ValueError: If no chart_id is set or no access token is available.
-            Exception: If the API request fails.
+            Exception: If the API request fails or publishing fails.
         """
         if not self.chart_id:
             raise ValueError(
@@ -726,8 +726,12 @@ def publish(
         # Call the publish_chart method from the client
         result = client.publish_chart(chart_id=self.chart_id)
 
-        # Return a boolean indicating success
-        return True if result else False
+        # Raise an exception if publishing failed
+        if not result:
+            raise Exception(f"Failed to publish chart {self.chart_id}")
+
+        # Return self for chaining
+        return self
 
     def export(
         self,

docs/user-guide/chart-operations.md

@@ -1,6 +1,6 @@
 # Working with chart objects
 
-This guide tours the key operations available on all of our object-oriented chart types.
+This guide tours the key operations available on all charts based on our object-oriented classes.
 
 ## Creating a new chart
 
@@ -16,20 +16,20 @@ data = pd.DataFrame(
     }
 )
 
-# Create a chart
+# Configure the chart object
 chart = dw.BarChart(
     title="Most Popular Programming Languages 2024",
     data=data,
     value_label_format=dw.NumberFormat.ONE_DECIMAL,
 )
 
-# Create it in Datawrapper
-chart_id = chart.create()
+# Create it by sending to Datawrapper
+chart.create()
 ```
 
 ## Getting an existing chart
 
-You can retrieve an existing chart by using `get_chart` with the chart ID:
+You can retrieve an existing chart with the ID, which is found in its URL.
 
 ```python
 # Retrieve an existing chart
@@ -42,8 +42,6 @@ print(existing_chart.chart_id)
 
 ## Updating an existing chart
 
-After creating or retrieving a chart, you can modify its properties and update it:
-
 ```python
 # Modify the chart properties
 chart.title = "Programming Language Popularity - Updated"
@@ -58,7 +56,7 @@ new_data = pd.DataFrame(
 )
 chart.data = new_data
 
-# Push the changes to Datawrapper
+# This will send the updates to Datawrapper
 chart.update()
 ```
 
@@ -68,12 +66,13 @@ Once your chart is ready, publish it to make it publicly accessible:
 
 ```python
 chart.publish()
+
+# Chain with other operations
+chart.create().publish()
 ```
 
 ## Exporting a chart
 
-Export your chart as an SVG, PNG, or PDF file:
-
 ```python
 # Export as PNG (default)
 chart.export(filepath="chart.png")
@@ -87,14 +86,9 @@ chart.export(
 )
 ```
 
-The export method supports various other options for customizing the output format and dimensions.
-
 ## Duplicating a chart
 
-Create an editable copy of your chart:
-
 ```python
-# Create a duplicate
 duplicate_chart = chart.duplicate()
 
 # The duplicate is a new chart with a different ID
@@ -108,16 +102,19 @@ duplicate_chart.update()
 
 ## Deleting a chart
 
-Remove a chart from Datawrapper:
-
 ```python
-# Delete the chart
 success = chart.delete()
 
 if success:
     print("Chart deleted successfully")
-    # The chart_id is now None
-    print(f"Chart ID: {chart.chart_id}")
+```
+
+## Getting editor URL
+
+Get the Datawrapper URL to continue editing your chart:
+
+```python
+chart.get_editor_url()
 ```
 
 ## Getting iframe code
@@ -127,35 +124,17 @@ Get the HTML iframe embed code for your chart:
 ```python
 # Get standard iframe code
 iframe_code = chart.get_iframe_code()
-print(iframe_code)
 
 # Get responsive iframe code
 responsive_iframe = chart.get_iframe_code(responsive=True)
-print(responsive_iframe)
-```
-
-The iframe code can be directly embedded in HTML pages. The `responsive=True` option generates code that automatically adjusts to container width.
-
-## Getting editor URL
-
-Get the Datawrapper URL to continue editing your chart:
-
-```python
-# Get the editor URL
-chart.get_editor_url()
 ```
 
 ## Getting png URL
 
 Get the fallback image URL for use in noscript tags:
 
 ```python
-# Get the PNG URL
 png_url = chart.get_png_url()
-print(f"PNG fallback: {png_url}")
 
-# Use in HTML noscript tags
 html = f'<noscript><img src="{png_url}" alt="Chart" /></noscript>'
 ```
-
-This provides a static image fallback for environments where JavaScript is disabled. It's also a handy way to get a direct link to the chart image for other uses.

docs/user-guide/quickstart.md

@@ -57,8 +57,7 @@ chart = dw.BarChart(
 )
 
 # Create the chart on Datawrapper (uses DATAWRAPPER_ACCESS_TOKEN environment variable)
-chart_id = chart.create()
-print(f"Chart created! ID: {chart_id}")
+chart.create()
 
 # You could also provide the token at runtime
 # chart_id = chart.create(access_token="your_token_here")
@@ -85,7 +84,7 @@ for category in ["Sales", "Revenue", "Profit"]:
     chart = dw.BarChart(
         title=f"{category} by Region", data=get_data_for_category(category)
     )
-    chart_id = chart.create()
+    chart.create()
 ```
 
 Happy charting! 📊

tests/functional/test_api_end_to_end.py

@@ -123,7 +123,8 @@ def test_create_sample_bar_chart_with_datawrapper():
 
     # Create the chart via Datawrapper API
     print("🚀 Creating chart via Datawrapper API...")
-    chart_id = chart.create()
+    chart.create()
+    chart_id = chart.chart_id
 
     print(f"✅ Chart created successfully with ID: {chart_id}")
 
@@ -199,7 +200,8 @@ def test_create_simple_bar_chart_with_api():
 
     # Create via API
     print("🚀 Creating chart via API...")
-    chart_id = chart.create()
+    chart.create()
+    chart_id = chart.chart_id
 
     print(f"✅ Chart created with ID: {chart_id}")
 
@@ -341,7 +343,8 @@ def test_create_happiness_scores_bar_chart_with_datawrapper():
 
     # Create the chart via Datawrapper API
     print("🚀 Creating chart via Datawrapper API...")
-    chart_id = chart.create()
+    chart.create()
+    chart_id = chart.chart_id
 
     print(f"✅ Chart created successfully with ID: {chart_id}")