Plotly add_trace vs append_trace

Question

Is there any difference between add_trace and append_trace in Plotly? Is the latter a legacy of the former?

In the Plotly.py GitHub, there are 88 markdown + 21 Python instances of add_trace and 9 markdowbn + 7 Python instances of append_trace. The latter are mainly coming from doc and packages/python/plotly/plotly/figure_factory.

In the Plotly subplots documentation, there are 4 instances of append_trace while all other 52 instances are add_trace.

Here is an example extracted from there:

from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(rows=3, cols=1)

fig.append_trace(go.Scatter(
    x=[3, 4, 5],
    y=[1000, 1100, 1200],
), row=1, col=1)

fig.append_trace(go.Scatter(
    x=[2, 3, 4],
    y=[100, 110, 120],
), row=2, col=1)

fig.append_trace(go.Scatter(
    x=[0, 1, 2],
    y=[10, 11, 12]
), row=3, col=1)


fig.update_layout(height=600, width=600, title_text="Stacked Subplots")
fig.show()

I have tried replacing the append_trace instances in this code snippets to add_trace and did not observe any apparent differences.

Answer 1

I don't have the technical background to explain it to you, but the official reference has the following explanation

New traces can be added to a graph object figure using the add_trace() method. This method accepts a graph object trace (an instance of go.Scatter, go.Bar, etc.) and adds it to the figure. This allows you to start with an empty figure, and add traces to it sequentially. The append_trace() method does the same thing, although it does not return the figure.

Answer 2

The append_trace method is deprecated and will be removed in a future version.
Please use the add_trace method with the row and col parameters.

--

source code:

    def append_trace(self, trace, row, col):
        """
        Add a trace to the figure bound to axes at the specified row,
        col index.

        A row, col index grid is generated for figures created with
        plotly.tools.make_subplots, and can be viewed with the `print_grid`
        method

        Parameters
        ----------
        trace
            The data trace to be bound
        row: int
            Subplot row index (see Figure.print_grid)
        col: int
            Subplot column index (see Figure.print_grid)

        Examples
        --------

        >>> from plotly import tools
        >>> import plotly.graph_objs as go
        >>> # stack two subplots vertically
        >>> fig = tools.make_subplots(rows=2)

        This is the format of your plot grid:
        [ (1,1) x1,y1 ]
        [ (2,1) x2,y2 ]

        >>> fig.append_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1)
        >>> fig.append_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)
        """
        warnings.warn(
            """\
The append_trace method is deprecated and will be removed in a future version.
Please use the add_trace method with the row and col parameters.
""",
            DeprecationWarning,
        )

        self.add_trace(trace=trace, row=row, col=col)

plotly==5.18.0

.venv\Lib\site-packages\plotly\basedatatypes.py

though, I never see the warning pop up, idk why