From 1cd3b20a0eb7281427eb22f33d7323ba173a50bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Senanur=20=C3=87etin?= Date: Fri, 16 Oct 2026 21:21:14 +0300 Subject: [PATCH 1/2] docs: clarify figure factory return types (#5396) --- plotly/figure_factory/_quiver.py | 5 +++- plotly/figure_factory/_streamline.py | 5 +++- .../test_return_type_docs.py | 28 +++++++++++++++++++ 3 files changed, 36 insertions(+), 2 deletions(-) create mode 100644 tests/test_optional/test_figure_factory/test_return_type_docs.py diff --git a/plotly/figure_factory/_quiver.py b/plotly/figure_factory/_quiver.py index fa182222881..f3803345604 100644 --- a/plotly/figure_factory/_quiver.py +++ b/plotly/figure_factory/_quiver.py @@ -27,7 +27,10 @@ def create_quiver( for more information on valid kwargs call help(plotly.graph_objs.Scatter) - :rtype (dict): returns a representation of quiver figure. + Returns + ------- + plotly.graph_objects.Figure + A Plotly figure containing the quiver arrows. Example 1: Trivial Quiver diff --git a/plotly/figure_factory/_streamline.py b/plotly/figure_factory/_streamline.py index 55b74c3e7b7..a8fb59947de 100644 --- a/plotly/figure_factory/_streamline.py +++ b/plotly/figure_factory/_streamline.py @@ -55,7 +55,10 @@ def create_streamline( for more information on valid kwargs call help(plotly.graph_objs.Scatter) - :rtype (dict): returns a representation of streamline figure. + Returns + ------- + plotly.graph_objects.Figure + A Plotly figure containing the streamlines and arrows. Example 1: Plot simple streamline and increase arrow size diff --git a/tests/test_optional/test_figure_factory/test_return_type_docs.py b/tests/test_optional/test_figure_factory/test_return_type_docs.py new file mode 100644 index 00000000000..7ffc17d0d28 --- /dev/null +++ b/tests/test_optional/test_figure_factory/test_return_type_docs.py @@ -0,0 +1,28 @@ +"""Figure-factory return type documentation regression checks.""" + +import inspect + +import pytest + +import plotly.figure_factory as ff +from plotly.graph_objects import Figure + + +@pytest.mark.parametrize( + "factory, kwargs", + [ + (ff.create_quiver, {"x": [0], "y": [0], "u": [1], "v": [1]}), + ( + ff.create_streamline, + { + "x": [0, 1, 2], + "y": [0, 1, 2], + "u": [[1, 1, 1], [1, 1, 1], [1, 1, 1]], + "v": [[1, 1, 1], [1, 1, 1], [1, 1, 1]], + }, + ), + ], +) +def test_factory_return_docs_match_runtime(factory, kwargs): + assert "Returns\n-------\nplotly.graph_objects.Figure" in inspect.getdoc(factory) + assert isinstance(factory(**kwargs), Figure) From 0b3cf5e8dcb23a9a98bdfdac3dc0be64d60c9eca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Senanur=20=C3=87etin?= Date: Tue, 20 Oct 2026 02:39:17 +0300 Subject: [PATCH 2/2] docs: use Sphinx rtype for figure factories and drop docstring-only tests --- plotly/figure_factory/_quiver.py | 7 ++--- plotly/figure_factory/_streamline.py | 7 ++--- .../test_return_type_docs.py | 28 ------------------- 3 files changed, 4 insertions(+), 38 deletions(-) delete mode 100644 tests/test_optional/test_figure_factory/test_return_type_docs.py diff --git a/plotly/figure_factory/_quiver.py b/plotly/figure_factory/_quiver.py index f3803345604..a72df5ba10b 100644 --- a/plotly/figure_factory/_quiver.py +++ b/plotly/figure_factory/_quiver.py @@ -9,7 +9,7 @@ def create_quiver( x, y, u, v, scale=0.1, arrow_scale=0.3, angle=math.pi / 9, scaleratio=None, **kwargs ): """ - Returns data for a quiver plot. + Returns a figure for a quiver plot. :param (list|ndarray) x: x coordinates of the arrow locations :param (list|ndarray) y: y coordinates of the arrow locations @@ -27,10 +27,7 @@ def create_quiver( for more information on valid kwargs call help(plotly.graph_objs.Scatter) - Returns - ------- - plotly.graph_objects.Figure - A Plotly figure containing the quiver arrows. + :rtype (plotly.graph_objects.Figure): returns a representation of quiver figure. Example 1: Trivial Quiver diff --git a/plotly/figure_factory/_streamline.py b/plotly/figure_factory/_streamline.py index a8fb59947de..537665cc28f 100644 --- a/plotly/figure_factory/_streamline.py +++ b/plotly/figure_factory/_streamline.py @@ -38,7 +38,7 @@ def create_streamline( x, y, u, v, density=1, angle=math.pi / 9, arrow_scale=0.09, **kwargs ): """ - Returns data for a streamline plot. + Returns a figure for a streamline plot. :param (list|ndarray) x: 1 dimensional, evenly spaced list or array :param (list|ndarray) y: 1 dimensional, evenly spaced list or array @@ -55,10 +55,7 @@ def create_streamline( for more information on valid kwargs call help(plotly.graph_objs.Scatter) - Returns - ------- - plotly.graph_objects.Figure - A Plotly figure containing the streamlines and arrows. + :rtype (plotly.graph_objects.Figure): returns a representation of streamline figure. Example 1: Plot simple streamline and increase arrow size diff --git a/tests/test_optional/test_figure_factory/test_return_type_docs.py b/tests/test_optional/test_figure_factory/test_return_type_docs.py deleted file mode 100644 index 7ffc17d0d28..00000000000 --- a/tests/test_optional/test_figure_factory/test_return_type_docs.py +++ /dev/null @@ -1,28 +0,0 @@ -"""Figure-factory return type documentation regression checks.""" - -import inspect - -import pytest - -import plotly.figure_factory as ff -from plotly.graph_objects import Figure - - -@pytest.mark.parametrize( - "factory, kwargs", - [ - (ff.create_quiver, {"x": [0], "y": [0], "u": [1], "v": [1]}), - ( - ff.create_streamline, - { - "x": [0, 1, 2], - "y": [0, 1, 2], - "u": [[1, 1, 1], [1, 1, 1], [1, 1, 1]], - "v": [[1, 1, 1], [1, 1, 1], [1, 1, 1]], - }, - ), - ], -) -def test_factory_return_docs_match_runtime(factory, kwargs): - assert "Returns\n-------\nplotly.graph_objects.Figure" in inspect.getdoc(factory) - assert isinstance(factory(**kwargs), Figure)