Skip to content

Commit fe9479a

Browse files
committed
Rename _ArtistPropertiesSubstitution.update() to register()
While it's internally a dict.update. The logical process is a registration to make the names publically available. Also, remove the possibility to pass a dict. Passing kwargs is enough and we can simplify the API to only one type of usage.
1 parent 8f855a6 commit fe9479a

File tree

15 files changed

+49
-32
lines changed

15 files changed

+49
-32
lines changed

lib/matplotlib/_docstring.py

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -85,24 +85,39 @@ def __missing__(self, key):
8585

8686
class _ArtistPropertiesSubstitution:
8787
"""
88-
A `.Substitution` with two additional features:
89-
90-
- Substitutions of the form ``%(classname:kwdoc)s`` (ending with the
91-
literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the
92-
given *classname*, and are substituted with the `.kwdoc` of that class.
93-
- Decorating a class triggers substitution both on the class docstring and
94-
on the class' ``__init__`` docstring (which is a commonly required
95-
pattern for Artist subclasses).
88+
A class to substitute formatted placeholders in docstrings.
89+
90+
This is realized in a single instance ``_docstring.interpd``.
91+
92+
Use `~._ArtistPropertiesSubstition.register` to define placeholders and
93+
their substitution, e.g. ``_docstring.interpd.register(name="some value")``.
94+
95+
Use this as a decorator to apply the substitution::
96+
97+
@_docstring.interpd
98+
def some_func():
99+
'''Replace %(name)s.'''
100+
101+
Decorating a class triggers substitution both on the class docstring and
102+
on the class' ``__init__`` docstring (which is a commonly required
103+
pattern for Artist subclasses).
104+
105+
Substitutions of the form ``%(classname:kwdoc)s`` (ending with the
106+
literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the
107+
given *classname*, and are substituted with the `.kwdoc` of that class.
96108
"""
97109

98110
def __init__(self):
99111
self.params = _ArtistKwdocLoader()
100112

101-
def update(self, *args, **kwargs):
113+
def register(self, **kwargs):
102114
"""
103-
Update ``self.params`` (which must be a dict) with the supplied args.
115+
Register substitutions.
116+
117+
``_docstring.interpd.register(name="some value")`` makes "name" available
118+
as a named parameter that will be replaced by "some value".
104119
"""
105-
self.params.update(*args, **kwargs)
120+
self.params.update(**kwargs)
106121

107122
def __call__(self, obj):
108123
if obj.__doc__:

lib/matplotlib/_docstring.pyi

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ class _ArtistKwdocLoader(dict[str, str]):
2323

2424
class _ArtistPropertiesSubstitution:
2525
def __init__(self) -> None: ...
26-
def update(self, *args, **kwargs) -> None:
26+
def register(self, **kwargs) -> None: ...
2727
def __call__(self, obj: _T) -> _T: ...
2828

2929

lib/matplotlib/_enums.py

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -181,5 +181,7 @@ def demo():
181181
+ ", ".join([f"'{cs.name}'" for cs in CapStyle]) \
182182
+ "}"
183183

184-
_docstring.interpd.update({'JoinStyle': JoinStyle.input_description,
185-
'CapStyle': CapStyle.input_description})
184+
_docstring.interpd.register(
185+
JoinStyle=JoinStyle.input_description,
186+
CapStyle=CapStyle.input_description,
187+
)

lib/matplotlib/axes/_secondary_axes.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -319,4 +319,4 @@ def set_color(self, color):
319319
**kwargs : `~matplotlib.axes.Axes` properties.
320320
Other miscellaneous Axes parameters.
321321
'''
322-
_docstring.interpd.update(_secax_docstring=_secax_docstring)
322+
_docstring.interpd.register(_secax_docstring=_secax_docstring)

lib/matplotlib/cm.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -651,7 +651,7 @@ def _format_cursor_data_override(self, data):
651651

652652

653653
# The docstrings here must be generic enough to apply to all relevant methods.
654-
mpl._docstring.interpd.update(
654+
mpl._docstring.interpd.register(
655655
cmap_doc="""\
656656
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
657657
The Colormap instance or registered colormap name used to map scalar data

lib/matplotlib/colorbar.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626

2727
_log = logging.getLogger(__name__)
2828

29-
_docstring.interpd.update(
29+
_docstring.interpd.register(
3030
_make_axes_kw_doc="""
3131
location : None or {'left', 'right', 'top', 'bottom'}
3232
The location, relative to the parent Axes, where the colorbar Axes

lib/matplotlib/contour.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -536,7 +536,7 @@ def _find_closest_point_on_path(xys, p):
536536
return (d2s[imin], projs[imin], (imin, imin+1))
537537

538538

539-
_docstring.interpd.update(contour_set_attributes=r"""
539+
_docstring.interpd.register(contour_set_attributes=r"""
540540
Attributes
541541
----------
542542
ax : `~matplotlib.axes.Axes`
@@ -1445,7 +1445,7 @@ def _initialize_x_y(self, z):
14451445
return np.meshgrid(x, y)
14461446

14471447

1448-
_docstring.interpd.update(contour_doc="""
1448+
_docstring.interpd.register(contour_doc="""
14491449
`.contour` and `.contourf` draw contour lines and filled contours,
14501450
respectively. Except as noted, function signatures and return values
14511451
are the same for both versions.

lib/matplotlib/legend.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -305,7 +305,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
305305
_loc_doc_base.format(parent='axes', default=':rc:`legend.loc`',
306306
best=_loc_doc_best, outside='') +
307307
_legend_kw_doc_base)
308-
_docstring.interpd.update(_legend_kw_axes=_legend_kw_axes_st)
308+
_docstring.interpd.register(_legend_kw_axes=_legend_kw_axes_st)
309309

310310
_outside_doc = """
311311
If a figure is using the constrained layout manager, the string codes
@@ -323,20 +323,20 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
323323
_loc_doc_base.format(parent='figure', default="'upper right'",
324324
best='', outside=_outside_doc) +
325325
_legend_kw_doc_base)
326-
_docstring.interpd.update(_legend_kw_figure=_legend_kw_figure_st)
326+
_docstring.interpd.register(_legend_kw_figure=_legend_kw_figure_st)
327327

328328
_legend_kw_both_st = (
329329
_loc_doc_base.format(parent='axes/figure',
330330
default=":rc:`legend.loc` for Axes, 'upper right' for Figure",
331331
best=_loc_doc_best, outside=_outside_doc) +
332332
_legend_kw_doc_base)
333-
_docstring.interpd.update(_legend_kw_doc=_legend_kw_both_st)
333+
_docstring.interpd.register(_legend_kw_doc=_legend_kw_both_st)
334334

335335
_legend_kw_set_loc_st = (
336336
_loc_doc_base.format(parent='axes/figure',
337337
default=":rc:`legend.loc` for Axes, 'upper right' for Figure",
338338
best=_loc_doc_best, outside=_outside_doc))
339-
_docstring.interpd.update(_legend_kw_set_loc_doc=_legend_kw_set_loc_st)
339+
_docstring.interpd.register(_legend_kw_set_loc_doc=_legend_kw_set_loc_st)
340340

341341

342342
class Legend(Artist):

lib/matplotlib/mlab.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -400,7 +400,7 @@ def _single_spectrum_helper(
400400

401401

402402
# Split out these keyword docs so that they can be used elsewhere
403-
_docstring.interpd.update(
403+
_docstring.interpd.register(
404404
Spectral="""\
405405
Fs : float, default: 2
406406
The sampling frequency (samples per time unit). It is used to calculate

lib/matplotlib/patches.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1552,7 +1552,7 @@ def _make_verts(self):
15521552
]
15531553

15541554

1555-
_docstring.interpd.update(
1555+
_docstring.interpd.register(
15561556
FancyArrow="\n".join(
15571557
(inspect.getdoc(FancyArrow.__init__) or "").splitlines()[2:]))
15581558

@@ -2290,7 +2290,7 @@ def __init_subclass__(cls):
22902290
# - %(BoxStyle:table_and_accepts)s
22912291
# - %(ConnectionStyle:table_and_accepts)s
22922292
# - %(ArrowStyle:table_and_accepts)s
2293-
_docstring.interpd.update({
2293+
_docstring.interpd.register(**{
22942294
f"{cls.__name__}:table": cls.pprint_styles(),
22952295
f"{cls.__name__}:table_and_accepts": (
22962296
cls.pprint_styles()

lib/matplotlib/projections/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,4 +123,4 @@ def get_projection_class(projection=None):
123123

124124

125125
get_projection_names = projection_registry.get_projection_names
126-
_docstring.interpd.update(projection_names=get_projection_names())
126+
_docstring.interpd.register(projection_names=get_projection_names())

lib/matplotlib/quiver.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,7 @@
230230
of the head in forward direction so that the arrow head looks broken.
231231
""" % _docstring.interpd.params
232232

233-
_docstring.interpd.update(quiver_doc=_quiver_doc)
233+
_docstring.interpd.register(quiver_doc=_quiver_doc)
234234

235235

236236
class QuiverKey(martist.Artist):
@@ -865,7 +865,7 @@ def _h_arrows(self, length):
865865
%(PolyCollection:kwdoc)s
866866
""" % _docstring.interpd.params
867867

868-
_docstring.interpd.update(barbs_doc=_barbs_doc)
868+
_docstring.interpd.register(barbs_doc=_barbs_doc)
869869

870870

871871
class Barbs(mcollections.PolyCollection):

lib/matplotlib/scale.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -750,7 +750,7 @@ def _get_scale_docs():
750750
return "\n".join(docs)
751751

752752

753-
_docstring.interpd.update(
753+
_docstring.interpd.register(
754754
scale_type='{%s}' % ', '.join([repr(x) for x in get_scale_names()]),
755755
scale_docs=_get_scale_docs().rstrip(),
756756
)

lib/matplotlib/text.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2030,4 +2030,4 @@ def get_tightbbox(self, renderer=None):
20302030
return super().get_tightbbox(renderer)
20312031

20322032

2033-
_docstring.interpd.update(Annotation=Annotation.__init__.__doc__)
2033+
_docstring.interpd.register(Annotation=Annotation.__init__.__doc__)

lib/matplotlib/tri/_tricontour.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ def _contour_args(self, args, kwargs):
7979
return (tri, z)
8080

8181

82-
_docstring.interpd.update(_tricontour_doc="""
82+
_docstring.interpd.register(_tricontour_doc="""
8383
Draw contour %%(type)s on an unstructured triangular grid.
8484
8585
Call signatures::

0 commit comments

Comments
 (0)