Figure.histogram: Deprecate parameter barwidth to bar_width (Will be removed in v0.20.0) (#4279)

Author: yvonnefroehlich

examples/tutorials/advanced/cartesian_histograms.py

@@ -320,7 +320,7 @@
 # Grouped bars
 # ------------
 #
-# By setting the ``barwidth`` parameter in respect to the values passed to the
+# By setting the ``bar_width`` parameter in respect to the values passed to the
 # ``series`` parameter histograms with grouped bars can be created.
 #
 # Limitations of histograms with grouped bars are:
@@ -347,7 +347,7 @@
     # of the bin width
     # Offset ("+o") the bars to align each bar with the left limit of the corresponding
     # bin
-    barwidth=f"{binwidth / 2}+o-{binwidth / 4}",
+    bar_width=f"{binwidth / 2}+o-{binwidth / 4}",
     label="data01",
 )
 
@@ -358,7 +358,7 @@
     fill="orange",
     pen="1p,darkgray,solid",
     histtype=0,
-    barwidth=f"{binwidth / 2}+o{binwidth / 4}",
+    bar_width=f"{binwidth / 2}+o{binwidth / 4}",
     label="data02",
 )
 

pygmt/src/histogram.py

@@ -8,15 +8,22 @@
 from pygmt._typing import PathLike, TableLike
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import (
+    build_arg_list,
+    deprecate_parameter,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
 
 
 @fmt_docstring
+@deprecate_parameter("barwidth", "bar_width", "v0.18.0", remove_version="v0.20.0")
 @use_alias(
     A="horizontal",
     C="cmap",
     D="annotate",
-    E="barwidth",
+    E="bar_width",
     F="center",
     G="fill",
     L="extreme",
@@ -84,7 +91,7 @@ def histogram(
         annotation font; use **+o** to change the offset between bar and
         label [Default is ``"6p"``]; use **+r** to rotate the labels from
         horizontal to vertical.
-    barwidth : float or str
+    bar_width : float or str
         *width*\ [**+o**\ *offset*].
         Use an alternative histogram bar width than the default set via
         ``series``, and optionally shift all bars by an *offset*. Here