Merge branch 'main' into docstring/order

Author: seisman

doc/contributing.md

@@ -488,10 +488,10 @@ integration systems will warn us and you can make a new commit with the formatte
 Even better, you can just write `/format` in the first line of any comment in a
 pull request to lint the code automatically.
 
-When wrapping a new alias, use an underscore to separate words bridged by vowels
-(aeiou), such as `no_skip` and `z_only`. Do not use an underscore to separate
-words bridged only by consonants, such as `distcalc`, and `crossprofile`. This
-convention is not applied by the code checking tools, but the PyGMT maintainers
+When introducing a new parameter name, use an underscore to separate words. This improves
+readability and aligns with the [PEP 8 style guide](https://peps.python.org/pep-0008/).
+For common shortcuts no underscore is needed, e.g., `surftype`, `outgrid`, or `timefmt`.
+This convention is not applied by the code checking tools, but the PyGMT maintainers
 will comment on any pull requests as needed.
 
 When working on a tutorial or a gallery plot, it is good practice to use code

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

pygmt/src/select.py

@@ -12,6 +12,7 @@
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
+    deprecate_parameter,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
@@ -22,14 +23,16 @@
 
 
 @fmt_docstring
+@deprecate_parameter("mask", "mask_values", "v0.18.0", remove_version="v0.20.0")
+@deprecate_parameter("gridmask", "mask_grid", "v0.18.0", remove_version="v0.20.0")
 @use_alias(
     A="area_thresh",
     C="dist2pt",
     F="polygon",
-    G="gridmask",
+    G="mask_grid",
     I="reverse",
     L="dist2line",
-    N="mask",
+    N="mask_values",
     Z="z_subregion",
     b="binary",
     d="nodata",
@@ -128,42 +131,40 @@ def select(
         <reference/file-formats.html#optional-segment-header-records>`
         *polygonfile*. For spherical polygons (lon, lat), make sure no
         consecutive points are separated by 180 degrees or more in longitude.
-    gridmask : str
+    mask_grid : str
         Pass all locations that are inside the valid data area of the grid
-        *gridmask*. Nodes that are outside are either NaN or zero.
+        *mask_grid*. Nodes that are outside are either NaN or zero.
     reverse : str
         [**cflrsz**].
         Reverse the sense of the test for each of the criteria specified:
 
         - **c** select records NOT inside any point's circle of influence.
         - **f** select records NOT inside any of the polygons.
         - **g** will pass records inside the cells with z equal zero of the
-          grid mask in ``gridmask``.
+          *mask_grid* in ``mask_grid``.
         - **l** select records NOT within the specified distance of any line.
         - **r** select records NOT inside the specified rectangular region.
-        - **s** select records NOT considered inside as specified by ``mask``
+        - **s** select records NOT considered inside as specified by ``mask_values``
           (and ``area_thresh``, ``resolution``).
         - **z** select records NOT within the range specified by
           ``z_subregion``.
     $projection
-    mask : str or list
-        Pass all records whose location is inside specified geographical
-        features. Specify if records should be skipped (s) or kept (k) using
-        1 of 2 formats:
+    mask_values : str or list
+        Pass all records whose location is inside specified geographical features.
+        Specify if records should be skipped (s) or kept (k) using 1 of 2 formats:
 
         - *wet/dry*.
         - *ocean/land/lake/island/pond*.
 
-        [Default is s/k/s/k/s (i.e., s/k), which passes all points on dry
-        land].
+        [Default is s/k/s/k/s (i.e., s/k), which passes all points on dry land].
     resolution
-        Ignored unless ``mask`` is set. Select the resolution of the coastline dataset
-        to use. The available resolutions from highest to lowest are: ``"full"``,
-        ``"high"``, ``"intermediate"``, ``"low"``, and ``"crude"``, which drops by 80%
-        between levels. Alternatively, choose ``"auto"`` to automatically select the
-        most suitable resolution given the chosen region. Note that because the
-        coastlines differ in details, a node in a mask file using one resolution is not
-        guaranteed to remain inside [or outside] when a different resolution is
+        Ignored unless ``mask_values`` is set. Select the resolution of the coastline
+        dataset to use. The available resolutions from highest to lowest are:
+        ``"full"``, ``"high"``, ``"intermediate"``, ``"low"``, and ``"crude"``, which
+        drops by 80% between levels. Alternatively, choose ``"auto"`` to automatically
+        select the most suitable resolution given the chosen region. Note that because
+        the coastlines differ in details, a node in a mask file using one resolution is
+        not guaranteed to remain inside [or outside] when a different resolution is
         selected. If ``None``, the low resolution is used by default.
     $region
     $verbose