Deprecate parameter orientation of bar() and barh()

timhoffm · timhoffm · commit 4c3cc9dd924d · 2020-05-04T15:48:13.000+02:00
diff --git a/doc/api/api_changes_3.3/deprecations.rst b/doc/api/api_changes_3.3/deprecations.rst
@@ -531,6 +531,11 @@ experimental and may change in the future.
 These are unused and can be easily reproduced by other date tools.
 `.get_epoch` will return Matplotlib's epoch.
 
+Passing ``orientation`` to ``bar()`` and ``barh()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This parameter is considered internal. Please use ``bar()`` for vertical bars
+and ``barh()`` for horizontal bars.
+
 ``axes_grid1.CbarAxes`` attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The ``cbid`` and ``locator`` attribute are deprecated.  Use
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2392,7 +2392,14 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
         error_kw.setdefault('ecolor', ecolor)
         error_kw.setdefault('capsize', capsize)
 
-        orientation = kwargs.pop('orientation', 'vertical')
+        if 'orientation' in kwargs:
+            orientation = kwargs['orientation']
+            cbook.warn_deprecated(
+                "3.3", message="passing 'orientation' to bar() is for "
+                               "internal use only. Please use barh() or bar() "
+                               "explicitly to define the orientation.")
+        else:
+            orientation = kwargs.pop('_orientation', 'vertical')
         cbook._check_in_list(['vertical', 'horizontal'],
                              orientation=orientation)
         log = kwargs.pop('log', False)
@@ -2630,9 +2637,17 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
         :doc:`/gallery/lines_bars_and_markers/horizontal_barchart_distribution`
         .
         """
-        kwargs.setdefault('orientation', 'horizontal')
+
+        if 'orientation' in kwargs:
+            orientation = kwargs['orientation']
+            cbook.warn_deprecated(
+                "3.3", message="passing 'orientation' to barh() is for "
+                               "internal use only. Please use bar() or barh() "
+                               "explicitly to define the orientation.")
+        else:
+            orientation = 'horizontal'
         patches = self.bar(x=left, height=height, width=width, bottom=y,
-                           align=align, **kwargs)
+                           align=align, _orientation=orientation, **kwargs)
         return patches
 
     @_preprocess_data()
