Merge pull request matplotlib#15124 from timhoffm/replace-parameter-lists

Replace parameter lists with square brackets

Author: anntzer

doc/devel/documenting_mpl.rst

@@ -514,12 +514,6 @@ rcParams can be referenced with the custom ``:rc:`` role:
 :literal:`:rc:\`foo\`` yields ``rcParams["foo"] = 'default'``, which is a link
 to the :file:`matplotlibrc` file description.
 
-Deprecated formatting conventions
----------------------------------
-Formerly, we have used square brackets for explicit parameter lists
-``['solid' | 'dashed' | 'dotted']``. With numpydoc we have switched to their
-standard using curly braces ``{'solid', 'dashed', 'dotted'}``.
-
 Setters and getters
 -------------------
 

examples/misc/set_and_get.py

@@ -18,7 +18,7 @@
 name of the property you want to set without a value::
 
   >>> plt.setp(line, 'linestyle')
-      linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]
+      linestyle: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
 
 If you want to see all the properties that can be set, and their
 possible values, you can do::

examples/specialty_plots/radar_chart.py

@@ -34,7 +34,7 @@ def radar_factory(num_vars, frame='circle'):
     ----------
     num_vars : int
         Number of variables for radar chart.
-    frame : {'circle' | 'polygon'}
+    frame : {'circle', 'polygon'}
         Shape of frame surrounding axes.
 
     """

lib/matplotlib/artist.py

@@ -1536,7 +1536,7 @@ def setp(obj, *args, **kwargs):
     the name of the property you want to set without a value::
 
       >>> setp(line, 'linestyle')
-          linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]
+          linestyle: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
 
     If you want to see all the properties that can be set, and their
     possible values, you can do::

lib/matplotlib/axes/_base.py

@@ -2777,8 +2777,8 @@ def ticklabel_format(self, *, axis='both', style='', scilimits=None,
           ==============   =========================================
           Keyword          Description
           ==============   =========================================
-          *axis*           [ 'x' | 'y' | 'both' ]
-          *style*          [ 'sci' (or 'scientific') | 'plain' ]
+          *axis*           {'x', 'y', 'both'}
+          *style*          {'sci' (or 'scientific'), 'plain'}
                            plain turns off scientific notation
           *scilimits*      (m, n), pair of integers; if *style*
                            is 'sci', scientific notation will
@@ -2787,11 +2787,11 @@ def ticklabel_format(self, *, axis='both', style='', scilimits=None,
                            Use (0, 0) to include all numbers.
                            Use (m, m) where m != 0 to fix the order
                            of magnitude to 10\ :sup:`m`.
-          *useOffset*      [ bool | offset ]; if True,
-                           the offset will be calculated as needed;
-                           if False, no offset will be used; if a
-                           numeric offset is specified, it will be
-                           used.
+          *useOffset*      bool or float
+                           If True, the offset will be calculated as
+                           needed; if False, no offset will be used;
+                           if a numeric offset is specified, it will
+                           be used.
           *useLocale*      If True, format the number according to
                            the current locale.  This affects things
                            such as the character used for the

lib/matplotlib/axis.py

@@ -2365,12 +2365,7 @@ def set_offset_position(self, position):
         position : {'left', 'right'}
         """
         x, y = self.offsetText.get_position()
-        if position == 'left':
-            x = 0
-        elif position == 'right':
-            x = 1
-        else:
-            raise ValueError("Position accepts only [ 'left' | 'right' ]")
+        x = cbook._check_getitem({'left': 0, 'right': 1}, position=position)
 
         self.offsetText.set_ha(position)
         self.offsetText.set_position((x, y))

lib/matplotlib/collections.py

@@ -1580,10 +1580,9 @@ def is_horizontal(self):
         return self._is_horizontal
 
     def get_orientation(self):
-        '''
-        get the orientation of the event line, may be:
-        [ 'horizontal' | 'vertical' ]
-        '''
+        """
+        Return the orientation of the event line ('horizontal' or 'vertical').
+        """
         return 'horizontal' if self.is_horizontal() else 'vertical'
 
     def switch_orientation(self):
@@ -1599,11 +1598,14 @@ def switch_orientation(self):
         self.stale = True
 
     def set_orientation(self, orientation=None):
-        '''
-        set the orientation of the event line
-        [ 'horizontal' | 'vertical' | None ]
-        defaults to 'horizontal' if not specified or None
-        '''
+        """
+        Set the orientation of the event line.
+
+        Parameters
+        ----------
+        orientation: {'horizontal', 'vertical'} or None
+            Defaults to 'horizontal' if not specified or None.
+        """
         if (orientation is None or orientation.lower() == 'none' or
                 orientation.lower() == 'horizontal'):
             is_horizontal = True

lib/matplotlib/colorbar.py

@@ -66,11 +66,11 @@
     ============  ====================================================
     Property      Description
     ============  ====================================================
-    *extend*      [ 'neither' | 'both' | 'min' | 'max' ]
+    *extend*      {'neither', 'both', 'min', 'max'}
                   If not 'neither', make pointed end(s) for out-of-
                   range values.  These are set for a given colormap
                   using the colormap set_under and set_over methods.
-    *extendfrac*  [ *None* | 'auto' | length | lengths ]
+    *extendfrac*  {*None*, 'auto', length, lengths}
                   If set to *None*, both the minimum and maximum
                   triangular colorbar extensions with have a length of
                   5% of the interior colorbar length (this is the
@@ -90,14 +90,14 @@
                   If *False* the minimum and maximum colorbar extensions
                   will be triangular (the default). If *True* the
                   extensions will be rectangular.
-    *spacing*     [ 'uniform' | 'proportional' ]
+    *spacing*     {'uniform', 'proportional'}
                   Uniform spacing gives each discrete color the same
                   space; proportional makes the space proportional to
                   the data interval.
-    *ticks*       [ None | list of ticks | Locator object ]
+    *ticks*       *None* or list of ticks or Locator
                   If None, ticks are determined automatically from the
                   input.
-    *format*      [ None | format string | Formatter object ]
+    *format*      None or str or Formatter
                   If None, the
                   :class:`~matplotlib.ticker.ScalarFormatter` is used.
                   If a format string is given, e.g., '%.3f', that is

lib/matplotlib/mlab.py

@@ -151,7 +151,7 @@ def detrend(x, key=None, axis=None):
     x : array or sequence
         Array or sequence containing the data.
 
-    key : [ 'default' | 'constant' | 'mean' | 'linear' | 'none'] or function
+    key : {'default', 'constant', 'mean', 'linear', 'none'} or function
         Specifies the detrend algorithm to use. 'default' is 'mean', which is
         the same as `detrend_mean`. 'constant' is the same. 'linear' is
         the same as `detrend_linear`. 'none' is the same as

lib/matplotlib/scale.py

@@ -772,6 +772,6 @@ def _get_scale_docs():
 
 
 docstring.interpd.update(
-    scale=' | '.join([repr(x) for x in get_scale_names()]),
+    scale_type='{%s}' % ', '.join([repr(x) for x in get_scale_names()]),
     scale_docs=_get_scale_docs().rstrip(),
     )