This PR is a first step toward refactoring the autoshape helpers to use the newlayout.shape.label API in Plotly.js, while keeping backward-compatible annotation behavior for now.

Scope

This PR updates:

• Figure.add_vline
• Figure.add_hline
• Figure.add_vrect
• Figure.add_hrect

Key changes:

1. Legacy → label shim

   • Introduce_coerce_shape_label_from_legacy_annotation_kwargs(kwargs) to translate a safe subset ofannotation_* kwargs into alabel dict:
     • annotation_text →label.text
     • annotation_font →label.font
     • annotation_textangle →label.textangle
   • The shim is called from each of the four helpers and isnon-destructive: it does not removeannotation_* from kwargs.
   • When anyannotation_* field is used, aFutureWarning is emitted to encourage migrating tolabel={...}.

2. Add shape.label for autoshapes

   In_process_multiple_axis_spanning_shapes, forshape_type in:

   • "vline"
   • "hline"
   • "vrect"
   • "hrect"

   we now:

   • Split kwargs intoshape_kwargs andlegacy_ann viashapeannotation.split_dict_by_key_prefix(..., "annotation_").
   • Build alabel_dict starting from any explicitlabel passed by the user and then merging in legacy fields if they are not present.
   • Attachlabel_dict to the new shape (shape_to_add["label"] = label_dict) before callingadd_shape(...).

3. Mapping annotation_position → label.textposition

   We partially mapannotation_position intolabel.textposition to keep intuitive placement:

   • Forlines:

     • vline:
       • "top" →"end"
       • "bottom" →"start"
       • "middle"/"center" →"middle"
     • hline:
       • "right" →"end"
       • "left" →"start"
       • "middle"/"center" →"middle"
     • A helper_normalize_legacy_line_position_to_textposition is used to validate legacy strings and to keep behavior predictable.

   • Forrectangles (vrect,hrect):

     • We strip"inside " /"outside " and map the remaining part to a valid rect textposition:
       • "top left","top center","top right", …
       • "middle left","middle center","middle right", …
       • "bottom left","bottom center","bottom right", …
     • Single-side positions like"top","bottom","left","right" are mapped to sensible defaults (e.g."top" →"top center").

4. Warnings for unsupported styling

   • annotation_bgcolor /annotation_bordercolor arenot supported onshape.label and are currently ignored with aFutureWarning suggesting use of label font/color or a background shape instead.

5. Backward compatibility (important)

   • The existing annotation path isstill active:
     • axis_spanning_shape_annotation(...) is still called.
     • add_annotation(...) is still called whenaugmented_annotation is notNone.
   • This means that:
     • existing user code that relies onlayout.annotations continues to work,
     • existing tests that assert on annotations continue to pass,
     • but shapes now also carry alabel, which will allow us to stop creating separate annotations in a later step.

Bug / motivation

This work is motivated by the issue where usingadd_vline withannotation_text on a datetime x-axis can raise aTypeError due to arithmetic on mixed types when positioning the annotation (see the discussion in#3065).

By moving towardshape.label:

• we can avoid doing arithmetic on the coordinate values just to place the label, and
• we get a more direct and robust representation of labels attached to shapes.

For now, we keep the annotation logic in place to avoid breaking existing behavior while we gather feedback.

Tests

Locally, I ran:

python -m pytest -q tests/test_optional/test_autoshapes/test_annotated_shapes.py## Code PR- [ x] I haveread through the [contributing notes](https://github.com/plotly/plotly.py/blob/main/CONTRIBUTING.md) and understand the structure of the package. In particular,if my PR modifies code of`plotly.graph_objects`, my modifications concern the code generator and*not* the generated files.- [ ] I have added tests or modified existing tests.- [ ] For a new feature, I have added documentation examples (please see the doc checklist as well).- [ ] I have added a CHANGELOG entryif changing anything substantial.- [ ] For a new feature or a changein behavior, I have updated the relevant docstringsin the code.