Cleanup and document _plot_args()

timhoffm · timhoffm · commit 1eb540adee37 · 2021-01-11T22:45:50.000+01:00
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -403,12 +403,50 @@ def _makefill(self, x, y, kw, kwargs):
         return seg, kwargs
 
     def _plot_args(self, tup, kwargs, return_kwargs=False):
+        """
+        Process the arguments of ``plot([x], y, [fmt], **kwargs)`` calls.
+
+        This processes a single set of ([x], y, [fmt]) parameters; i.e. for
+        ``plot(x, y, x2, y2)`` it will be called twice. Once for (x, y) and
+        once for (x2, y2).
+
+        x and y may be 2D and thus can still represent multiple datasets.
+
+        For multiple datasets, if the keyword argument *label* is a list, this
+        will unpack the list and assign the individual labels to the datasets.
+
+        Parameters
+        ----------
+        tup : tuple
+            A tuple of the positional parameters. This can be one of
+
+            - (y,)
+            - (x, y)
+            - (y, fmt)
+            - (x, y, fmt)
+
+        kwargs : dict
+            The keyword arguments passed to ``plot()``.
+
+        return_kwargs : bool
+            If true, return the effective keyword arguments after label
+            unpacking.
+
+        Returns
+        -------
+        result
+            If *return_kwargs* is false, a list of Artists representing the
+            dataset(s).
+            If *return_kwargs* is true, a list of (Artist, effective_kwargs)
+            representing the dataset(s). See *return_kwargs*.
+        """
         if len(tup) > 1 and isinstance(tup[-1], str):
-            linestyle, marker, color = _process_plot_format(tup[-1])
-            tup = tup[:-1]
+            *xy, fmt = tup
+            linestyle, marker, color = _process_plot_format(fmt)
         elif len(tup) == 3:
             raise ValueError('third arg must be a format string')
         else:
+            xy = tup
             linestyle, marker, color = None, None, None
 
         # Don't allow any None value; these would be up-converted to one
@@ -417,16 +455,16 @@ def _plot_args(self, tup, kwargs, return_kwargs=False):
             raise ValueError("x, y, and format string must not be None")
 
         kw = {}
-        for k, v in zip(('linestyle', 'marker', 'color'),
-                        (linestyle, marker, color)):
+        for prop_name, v in zip(('linestyle', 'marker', 'color'),
+                                (linestyle, marker, color)):
             if v is not None:
-                kw[k] = v
+                kw[prop_name] = v
 
-        if len(tup) == 2:
-            x = _check_1d(tup[0])
-            y = _check_1d(tup[-1])
+        if len(xy) == 2:
+            x = _check_1d(xy[0])
+            y = _check_1d(xy[1])
         else:
-            x, y = index_of(tup[-1])
+            x, y = index_of(xy[-1])
 
         if self.axes.xaxis is not None:
             self.axes.xaxis.update_units(x)
