8000 Reorder kwonly kwargs in Colorbar & related docs. by anntzer · Pull Request #29652 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Reorder kwonly kwargs in Colorbar & related docs. #29652

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 22, 2025
Merged

Reorder kwonly kwargs in Colorbar & related docs. #29652

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 33 additions & 38 deletions lib/matplotlib/colorbar.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,15 +226,26 @@ class Colorbar:
mappable : `.ScalarMappable`
The mappable whose colormap and norm will be used.

To show the under- and over- value colors, the mappable's norm should
be specified as ::
To show the colors versus index instead of on a 0-1 scale, set the
mappable's norm to ``colors.NoNorm()``.

norm = colors.Normalize(clip=False)
alpha : float
The colorbar transparency between 0 (transparent) and 1 (opaque).

location : None or {'left', 'right', 'top', 'bottom'}
Set the colorbar's *orientation* and *ticklocation*. Colorbars on
the left and right are vertical, colorbars at the top and bottom
are horizontal. The *ticklocation* is the same as *location*, so if
*location* is 'top', the ticks are on the top. *orientation* and/or
*ticklocation* can be provided as well and overrides the value set by
*location*, but there will be an error for incompatible combinations.

To show the colors versus index instead of on a 0-1 scale, use::
.. versionadded:: 3.7

norm=colors.NoNorm()
%(_colormap_kw_doc)s

Other Parameters
----------------
Comment on lines +247 to +248
Copy link
Member
@timhoffm timhoffm Feb 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like numpydoc is placing the Attributes section between Parameters and Other Parameters, which I find quite confusing.

grafik

I propose not use Other Parameters then here.

Edit: This is an intentional change in numpydoc 1.8 (numpy/numpydoc#571), though I'm not clear whether this effect was considered.

We can work around this by moving the parameters to the __init__ docstring, because that seems to be appended below the class docstring, see e.g. https://matplotlib.org/devdocs/api/widgets_api.html#matplotlib.widgets.Button. In a quick check, this seems to be a pattern we generally use.

cmap : `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
The colormap 8000 to use. This parameter is ignored, unless *mappable* is
None.
Expand All @@ -243,9 +254,6 @@ class Colorbar:
The normalization to use. This parameter is ignored, unless *mappable*
is None.

alpha : float
The colorbar transparency between 0 (transparent) and 1 (opaque).

orientation : None or {'vertical', 'horizontal'}
If None, use the value determined by *location*. If both
*orientation* and *location* are None then defaults to 'vertical'.
Expand All @@ -257,40 +265,27 @@ class Colorbar:
*location*, so a colorbar to the left will have ticks to the left. If
*location* is None, the ticks will be at the bottom for a horizontal
colorbar and at the right for a vertical.

%(_colormap_kw_doc)s

location : None or {'left', 'right', 'top', 'bottom'}
Set the *orientation* and *ticklocation* of the colorbar using a
single argument. Colorbars on the left and right are vertical,
colorbars at the top and bottom are horizontal. The *ticklocation* is
the same as *location*, so if *location* is 'top', the ticks are on
the top. *orientation* and/or *ticklocation* can be provided as well
and overrides the value set by *location*, but there will be an error
for incompatible combinations.

.. versionadded:: 3.7
"""

n_rasterize = 50 # rasterize solids if number of colors >= n_rasterize

def __init__(self, ax, mappable=None, *, cmap=None,
norm=None,
alpha=None,
values=None,
boundaries=None,
orientation=None,
ticklocation='auto',
extend=None,
spacing='uniform', # uniform or proportional
ticks=None,
format=None,
drawedges=False,
extendfrac=None,
extendrect=False,
label='',
location=None,
):
def __init__(
self, ax, mappable=None, *,
alpha=None,
location=None,
extend=None,
extendfrac=None,
extendrect=False,
ticks=None,
format=None,
values=None,
boundaries=None,
spacing='uniform',
drawedges=False,
label='',
cmap=None, norm=None, # redundant with *mappable*
orientation=None, ticklocation='auto', # redundant with *location*
):

if mappable is None:
mappable = cm.ScalarMappable(norm=norm, cmap=cmap)
Expand Down
Loading
0