Update example and docstring to encourage the use of functools.partial

jeffreypaul15 · oscargus · commit 56192f1c27d1 · 2022-10-21T10:08:24.000+02:00
diff --git a/doc/api/animation_api.rst b/doc/api/animation_api.rst
@@ -113,6 +113,7 @@ artist at a global scope and let Python sort things out.  For example ::
    import numpy as np
    import matplotlib.pyplot as plt
    from matplotlib.animation import FuncAnimation
+   from functools import partial
 
    fig, ax = plt.subplots()
    xdata, ydata = [], []
@@ -133,8 +134,37 @@ artist at a global scope and let Python sort things out.  For example ::
                        init_func=init, blit=True)
    plt.show()
 
-The second method is to use `functools.partial` to 'bind' artists to
-function.  A third method is to use closures to build up the required
+The second method is to use `functools.partial` to pass arguments to the
+function. ::
+
+   import numpy as np
+   import matplotlib.pyplot as plt
+   from matplotlib.animation import FuncAnimation
+   from functools import partial
+
+   fig, ax = plt.subplots()
+   ln, = plt.plot([], [], 'ro')
+
+   def init():
+      ax.set_xlim(0, 2*np.pi)
+      ax.set_ylim(-1, 1)
+      return ln,
+
+   def update(frame, x, y):
+      x.append(frame)
+      y.append(np.sin(frame))
+      ln.set_data(xdata, ydata)
+      return ln,
+
+   xdata, ydata = [], []
+   ani = FuncAnimation(
+       fig, partial(update, x=xdata, y=ydata),
+       frames=np.linspace(0, 2 * np.pi, 128),
+       init_func=init, blit=True)
+
+   plt.show()
+
+A third method is to use closures to build up the required
 artists and functions.  A fourth method is to create a class.
 
 Examples
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -1564,7 +1564,8 @@ def init_func() -> iterable_of_artists
         value is unused if ``blit == False`` and may be omitted in that case.
 
     fargs : tuple or None, optional
-        Additional arguments to pass to each call to *func*.
+        Additional arguments to pass to each call to *func*. Note: the use of
+        `functools.partial` is preferred over *fargs*.
 
     save_count : int, default: 100
         Fallback for the number of values from *frames* to cache. This is
