fix adding shapes and annotations inside batch_update()

Inside batch_update() property edits are deferred, but appending to a
compound array property still swaps in the new child objects, so the
freshly added shapes have no properties to read back yet. add_vline()
and friends then fail with "unsupported operand type(s) for +=:
'NoneType' and 'str'" while appending " domain" to the axis reference,
and a second add_shape()/add_annotation() in the same batch copies the
first one as an empty object.

Layout objects are structural additions like traces, and add_traces()
already applies those immediately regardless of batch mode. Do the same
here: add the objects and fix up their axis references with batch mode
switched off, so only regular property edits stay batched.

Closes #4742

Author: Belagum

CHANGELOG.md

@@ -4,6 +4,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Fixed
+- Fix `add_vline`, `add_hline`, `add_vrect` and `add_hrect` raising a `TypeError` inside `batch_update()`, and `add_shape`/`add_annotation` losing previously added objects there [[#4742](https://github.com/plotly/plotly.py/issues/4742)]
 
 ## [7.1.0] - 2026-09-15
 

plotly/basedatatypes.py

@@ -1627,7 +1627,8 @@ def _add_domain(ax_letter, new_axref):
             xref, yref = map(lambda t: _add_domain(*t), zip(["x", "y"], [xref, yref]))
             new_obj.update(xref=xref, yref=yref)
 
-        self.layout[prop_plural] += (new_obj,)
+        with self._batch_mode_disabled():
+            self.layout[prop_plural] += (new_obj,)
         # The 'new_obj.xref' and 'new_obj.yref' parameters need to be reset otherwise it
         # will appear as if user supplied yref params when looping through subplots and
         # will force annotation to be on the axis of the last drawn annotation
@@ -3077,6 +3078,24 @@ def batch_update(self):
                 self._batch_layout_edits.clear()
                 self._batch_trace_edits.clear()
 
+    @contextmanager
+    def _batch_mode_disabled(self):
+        """
+        Temporarily leave batch mode.
+
+        Adding layout objects (shapes, annotations, images, selections)
+        rebuilds the whole compound array property and, for the axis
+        spanning shapes, reads the new objects back. Neither works while
+        `batch_update()` is deferring property edits, so like `add_traces()`
+        these structural changes are applied immediately.
+        """
+        in_batch_mode = self._in_batch_mode
+        self._in_batch_mode = False
+        try:
+            yield
+        finally:
+            self._in_batch_mode = in_batch_mode
+
     def _build_update_params_from_batch(self):
         """
         Convert `_batch_trace_edits` and `_batch_layout_edits` into the
@@ -4003,52 +4022,53 @@ def _process_multiple_axis_spanning_shapes(
         augmented_annotation = shapeannotation.axis_spanning_shape_annotation(
             annotation, shape_type, shape_args, annotation_kwargs
         )
-        self.add_shape(
-            row=row,
-            col=col,
-            exclude_empty_subplots=exclude_empty_subplots,
-            **_combine_dicts([shape_args, shape_kwargs]),
-        )
-        if augmented_annotation is not None:
-            self.add_annotation(
-                augmented_annotation,
+        with self._batch_mode_disabled():
+            self.add_shape(
                 row=row,
                 col=col,
                 exclude_empty_subplots=exclude_empty_subplots,
-                yref=shape_kwargs.get("yref", "y"),
+                **_combine_dicts([shape_args, shape_kwargs]),
             )
-        # update xref and yref for the new shapes and annotations
-        for layout_obj, n_layout_objs_before in zip(
-            ["shapes", "annotations"], [n_shapes_before, n_annotations_before]
-        ):
-            n_layout_objs_after = len(self.layout[layout_obj])
-            if (n_layout_objs_after > n_layout_objs_before) and (
-                row is None and col is None
+            if augmented_annotation is not None:
+                self.add_annotation(
+                    augmented_annotation,
+                    row=row,
+                    col=col,
+                    exclude_empty_subplots=exclude_empty_subplots,
+                    yref=shape_kwargs.get("yref", "y"),
+                )
+            # update xref and yref for the new shapes and annotations
+            for layout_obj, n_layout_objs_before in zip(
+                ["shapes", "annotations"], [n_shapes_before, n_annotations_before]
             ):
-                # this was called intending to add to a single plot (and
-                # self.add_{layout_obj} succeeded)
-                # however, in the case of a single plot, xref and yref MAY not be
-                # specified, IF they are not specified we specify them here so the following routines can work
-                # (they need to append " domain" to xref or yref). If they are specified, we leave them alone.
-                if self.layout[layout_obj][-1].xref is None:
-                    self.layout[layout_obj][-1].update(xref="x")
-                if self.layout[layout_obj][-1].yref is None:
-                    self.layout[layout_obj][-1].update(yref="y")
-            new_layout_objs = tuple(
-                filter(
-                    lambda x: x is not None,
-                    [
-                        self._make_axis_spanning_layout_object(
-                            direction,
-                            self.layout[layout_obj][n],
-                        )
-                        for n in range(n_layout_objs_before, n_layout_objs_after)
-                    ],
+                n_layout_objs_after = len(self.layout[layout_obj])
+                if (n_layout_objs_after > n_layout_objs_before) and (
+                    row is None and col is None
+                ):
+                    # this was called intending to add to a single plot (and
+                    # self.add_{layout_obj} succeeded)
+                    # however, in the case of a single plot, xref and yref MAY not be
+                    # specified, IF they are not specified we specify them here so the following routines can work
+                    # (they need to append " domain" to xref or yref). If they are specified, we leave them alone.
+                    if self.layout[layout_obj][-1].xref is None:
+                        self.layout[layout_obj][-1].update(xref="x")
+                    if self.layout[layout_obj][-1].yref is None:
+                        self.layout[layout_obj][-1].update(yref="y")
+                new_layout_objs = tuple(
+                    filter(
+                        lambda x: x is not None,
+                        [
+                            self._make_axis_spanning_layout_object(
+                                direction,
+                                self.layout[layout_obj][n],
+                            )
+                            for n in range(n_layout_objs_before, n_layout_objs_after)
+                        ],
+                    )
+                )
+                self.layout[layout_obj] = (
+                    self.layout[layout_obj][:n_layout_objs_before] + new_layout_objs
                 )
-            )
-            self.layout[layout_obj] = (
-                self.layout[layout_obj][:n_layout_objs_before] + new_layout_objs
-            )
 
     def add_vline(
         self,

tests/test_core/test_figure_messages/test_plotly_update.py

@@ -57,6 +57,32 @@ def test_batch_update(self):
             trace_indexes=[0, 1],
         )
 
+    def test_add_layout_objects_in_batch_update(self):
+        self.figure._send_relayout_msg = MagicMock()
+
+        with self.figure.batch_update():
+            self.figure.add_shape(type="line", x0=0, x1=1, y0=0, y1=1)
+            self.figure.add_shape(type="rect", x0=1, x1=2, y0=1, y1=2)
+            self.figure.add_annotation(text="a", x=0, y=0)
+            self.figure.layout.xaxis.range = [10, 20]
+
+            # Like traces, layout objects are added right away
+            self.assertEqual(
+                [s.type for s in self.figure.layout.shapes], ["line", "rect"]
+            )
+            self.assertEqual(self.figure.layout.annotations[0].text, "a")
+            self.assertEqual(self.figure._send_relayout_msg.call_count, 3)
+
+            # while property assignments still wait for the context to exit
+            self.assertEqual(self.figure.layout.xaxis.range, (-1, 4))
+
+        self.assertEqual(self.figure.layout.xaxis.range, (10, 20))
+        self.figure._send_update_msg.assert_called_once()
+        self.assertEqual(
+            self.figure._send_update_msg.call_args.kwargs["relayout_data"],
+            {"xaxis.range": [10, 20]},
+        )
+
     def test_plotly_update(self):
         self.figure.plotly_update(
             restyle_data={

tests/test_optional/test_autoshapes/test_axis_span_shapes.py

@@ -473,3 +473,35 @@ def _check_figure_shapes_custom_sized(test_input, expected, fig):
 )
 def test_custom_sized_subplots(test_input, expected, custom_sized_subplots):
     _check_figure_shapes_custom_sized(test_input, expected, custom_sized_subplots)
+
+
+@pytest.mark.parametrize(
+    "f,kwargs",
+    [
+        (go.Figure.add_vline, dict(x=20)),
+        (go.Figure.add_hline, dict(y=6, annotation_text="six")),
+        (go.Figure.add_vrect, dict(x0=20, x1=30, annotation_text="twenties")),
+        (go.Figure.add_hrect, dict(y0=6, y1=8)),
+    ],
+)
+@pytest.mark.parametrize(
+    "fixture_name,row_col",
+    [
+        ("non_subplot_fig_fixture", dict()),
+        ("subplot_fig_fixture", dict(row=2, col=2)),
+        ("subplot_fig_fixture", dict(row="all", col="all")),
+    ],
+)
+def test_add_axis_spanning_shape_in_batch_update(
+    request, f, kwargs, fixture_name, row_col
+):
+    fig = request.getfixturevalue(fixture_name)
+    fig_batch = go.Figure(fig)
+
+    f(fig, **kwargs, **row_col)
+    with fig_batch.batch_update():
+        f(fig_batch, **kwargs, **row_col)
+
+    assert len(fig.layout.shapes) > 0
+    assert fig_batch.layout.shapes == fig.layout.shapes
+    assert fig_batch.layout.annotations == fig.layout.annotations