Merge pull request #18346 from timhoffm/plot_date

Soft-deprecate Axes.plot_date()

doc/api/next_api_changes/deprecations/18346-TH.rst

@@ -0,0 +1,9 @@
+``plot_date``
+~~~~~~~~~~~~~
+The use of `~.Axes.plot_date` is discouraged. This method exists for historic
+reasons and may be deprecated in the future.
+
+- ``datetime``-like data should directly be plotted using `~.Axes.plot`.
+- If you need to plot plain numeric data as :ref:`date-format` or
+  need to set a timezone, call ``ax.xaxis.axis_date`` / ``ax.yaxis.axis_date``
+  before `~.Axes.plot`. See `.Axis.axis_date`.

examples/ticks_and_spines/date_demo_convert.py

@@ -17,7 +17,7 @@
 y = np.arange(len(dates))
 
 fig, ax = plt.subplots()
-ax.plot_date(dates, y ** 2)
+ax.plot(dates, y**2, 'o')
 
 # this is superfluous, since the autoscaler should get it right, but
 # use date2num and num2date to convert between dates and floats if

examples/ticks_and_spines/date_demo_rrule.py

@@ -35,7 +35,7 @@
 
 
 fig, ax = plt.subplots()
-plt.plot_date(dates, s)
+plt.plot(dates, s, 'o')
 ax.xaxis.set_major_locator(loc)
 ax.xaxis.set_major_formatter(formatter)
 ax.xaxis.set_tick_params(rotation=30, labelsize=10)

lib/matplotlib/axes/_axes.py

@@ -1616,6 +1616,18 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
         """
         Plot co-ercing the axis to treat floats as dates.
 
+        .. admonition:: Discouraged
+
+            This method exists for historic reasons and will be deprecated in
+            the future.
+
+            - ``datetime``-like data should directly be plotted using
+              `~.Axes.plot`.
+            -  If you need to plot plain numeric data as :ref:`date-format` or
+               need to set a timezone, call ``ax.xaxis.axis_date`` /
+               ``ax.yaxis.axis_date`` before `~.Axes.plot`. See
+               `.Axis.axis_date`.
+
         Similar to `.plot`, this plots *y* vs. *x* as lines or markers.
         However, the axis labels are formatted as dates depending on *xdate*
         and *ydate*.  Note that `.plot` will work with `datetime` and

lib/matplotlib/dates.py

@@ -85,7 +85,7 @@
 All the Matplotlib date converters, tickers and formatters are timezone aware.
 If no explicit timezone is provided, :rc:`timezone` is assumed.  If you want to
 use a custom time zone, pass a `datetime.tzinfo` instance with the tz keyword
-argument to `num2date`, `~.Axes.plot_date`, and any custom date tickers or
+argument to `num2date`, `.Axis.axis_date`, and any custom date tickers or
 locators you create.
 
 A wide range of specific and general purpose date tick locators and