Plotly add_trace vs append_trace

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.

Solution

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.