Skip to content

Commit 791347b

Browse files
timhoffmtimhoffm
authored
Merge pull request #26051 from ksunden/typing_devdoc
Type hinting developer docs
2 parents 0747d1e + acb4923 commit 791347b

File tree

6 files changed

+47
-15
lines changed

6 files changed

+47
-15
lines changed

‎ci/mypy-stubtest-allowlist.txt

-12
Original file line numberDiff line numberDiff line change
@@ -54,26 +54,14 @@ matplotlib.cm.register_cmap
5454
matplotlib.cm.unregister_cmap
5555
matplotlib.collections.PolyCollection.span_where
5656
matplotlib.gridspec.GridSpecBase.get_grid_positions
57-
matplotlib.widgets.Lasso.__init__
58-
matplotlib.widgets.PolygonSelector.__init__
59-
matplotlib.widgets.Slider.__init__
60-
matplotlib.widgets.RangeSlider.__init__
61-
matplotlib.widgets.TextBox.__init__
62-
matplotlib.widgets.Cursor.__init__
63-
matplotlib.widgets.SpanSelector.__init__
64-
matplotlib.widgets.ToolLineHandles.__init__
65-
matplotlib.widgets.ToolHandles.__init__
66-
matplotlib.widgets.LassoSelector.__init__
6757
matplotlib.widgets.MultiCursor.needclear
6858

6959
# 3.8 deprecations
70-
matplotlib.axes._base._AxesBase.get_tightbbox
7160
matplotlib.cbook.get_sample_data
7261
matplotlib.contour.ContourSet.allkinds
7362
matplotlib.contour.ContourSet.allsegs
7463
matplotlib.contour.ContourSet.tcolors
7564
matplotlib.contour.ContourSet.tlinewidths
76-
matplotlib.figure.FigureBase.get_tightbbox
7765
matplotlib.ticker.LogLocator.__init__
7866
matplotlib.ticker.LogLocator.set_params
7967

‎doc/devel/coding_guide.rst

+2
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,8 @@ will run on all supported platforms and versions of Python.
350350

351351
- If *Linting* fails, you have a code style issue, which will be listed
352352
as annotations on the pull request's diff.
353+
- If *Mypy* or *Stubtest* fails, you have inconsistency in type hints, which
354+
will be listed as annotations in the diff.
353355
- If a GitHub Actions or AppVeyor run fails, search the log for ``FAILURES``.
354356
The subsequent section will contain information on the failed tests.
355357
- If CircleCI fails, likely you have some reStructuredText style issue in

‎doc/devel/contribute.rst

+33
Original file line numberDiff line numberDiff line change
@@ -345,6 +345,8 @@ Introducing
345345
- Use ``_api.warn_deprecated()`` for general deprecation warnings
346346
- Use the decorator ``@_api.deprecated`` to deprecate classes, functions,
347347
methods, or properties
348+
- Use ``@_api.deprecate_privatize_attribute`` to annotate deprecation of
349+
attributes while keeping the internal private version.
348350
- To warn on changes of the function signature, use the decorators
349351
``@_api.delete_parameter``, ``@_api.rename_parameter``, and
350352
``@_api.make_keyword_only``
@@ -354,6 +356,23 @@ Introducing
354356

355357
You can use standard rst cross references in *alternative*.
356358

359+
3. Make appropriate changes to the type hints in the associated ``.pyi`` file.
360+
The general guideline is to match runtime reported behavior.
361+
362+
- Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
363+
are generally kept during the expiry period, and thus no changes are needed on
364+
introduction.
365+
- Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
366+
report the *new* (post deprecation) signature at runtime, and thus *should* be
367+
updated on introduction.
368+
- Items decorated with ``@_api.delete_parameter`` should include a default value hint
369+
for the deleted parameter, even if it did not previously have one (e.g.
370+
``param: <type> = ...``). Even so, the decorator changes the default value to a
371+
sentinel value which should not be included in the type stub. Thus, Mypy Stubtest
372+
needs to be informed of the inconsistency by placing the method into
373+
:file:`ci/mypy-stubtest-allowlist.txt` under a heading indicating the deprecation
374+
version number.
375+
357376
Expiring
358377
~~~~~~~~
359378

@@ -365,6 +384,19 @@ Expiring
365384
information. For the content, you can usually copy the deprecation notice
366385
and adapt it slightly.
367386
2. Change the code functionality and remove any related deprecation warnings.
387+
3. Make appropriate changes to the type hints in the associated ``.pyi`` file.
388+
389+
- Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
390+
are to be removed on expiry.
391+
- Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
392+
will have been updated at introduction, and require no change now.
393+
- Items decorated with ``@_api.delete_parameter`` will need to be updated to the
394+
final signature, in the same way as the ``.py`` file signature is updated.
395+
The entry in :file:`ci/mypy-stubtest-allowlist.txt` should be removed.
396+
- Any other entries in :file:`ci/mypy-stubtest-allowlist.txt` under a version's
397+
deprecations should be double checked, as only ``delete_parameter`` should normally
398+
require that mechanism for deprecation. For removed items that were not in the stub
399+
file, only deleting from the allowlist is required.
368400

369401
Adding new API
370402
--------------
@@ -391,6 +423,7 @@ New modules and files: installation
391423
* If you have added new files or directories, or reorganized existing
392424
ones, make sure the new files are included in the match patterns in
393425
in *package_data* in :file:`setupext.py`.
426+
* New modules *may* be typed inline or using parallel stub file like existing modules.
394427

395428
C/C++ extensions
396429
----------------

‎lib/matplotlib/axes/_base.pyi

+1-1
Original file line numberDiff line numberDiff line change
@@ -367,9 +367,9 @@ class _AxesBase(martist.Artist):
367367
def get_tightbbox(
368368
self,
369369
renderer: RendererBase | None = ...,
370+
*,
370371
call_axes_locator: bool = ...,
371372
bbox_extra_artists: Sequence[Artist] | None = ...,
372-
*,
373373
for_layout_only: bool = ...
374374
) -> Bbox | None: ...
375375
def twinx(self) -> _AxesBase: ...

‎lib/matplotlib/figure.pyi

+1
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ class FigureBase(Artist):
223223
def get_tightbbox(
224224
self,
225225
renderer: RendererBase | None = ...,
226+
*,
226227
bbox_extra_artists: Iterable[Artist] | None = ...,
227228
) -> Bbox: ...
228229

‎lib/matplotlib/widgets.pyi

+10-2
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ class Slider(SliderBase):
9696
label: str,
9797
valmin: float,
9898
valmax: float,
99+
*,
99100
valinit: float = ...,
100101
valfmt: str | None = ...,
101102
closedmin: bool = ...,
@@ -105,7 +106,6 @@ class Slider(SliderBase):
105106
dragging: bool = ...,
106107
valstep: float | ArrayLike | None = ...,
107108
orientation: Literal["horizontal", "vertical"] = ...,
108-
*,
109109
initcolor: ColorType = ...,
110110
track_color: ColorType = ...,
111111
handle_style: dict[str, Any] | None = ...,
@@ -127,6 +127,7 @@ class RangeSlider(SliderBase):
127127
label: str,
128128
valmin: float,
129129
valmax: float,
130+
*,
130131
valinit: tuple[float, float] | None = ...,
131132
valfmt: str | None = ...,
132133
closedmin: bool = ...,
@@ -181,6 +182,7 @@ class TextBox(AxesWidget):
181182
ax: Axes,
182183
label: str,
183184
initial: str = ...,
185+
*,
184186
color: ColorType = ...,
185187
hovercolor: ColorType = ...,
186188
label_pad: float = ...,
@@ -236,6 +238,7 @@ class Cursor(AxesWidget):
236238
def __init__(
237239
self,
238240
ax: Axes,
241+
*,
239242
horizOn: bool = ...,
240243
vertOn: bool = ...,
241244
useblit: bool = ...,
@@ -317,6 +320,7 @@ class SpanSelector(_SelectorWidget):
317320
ax: Axes,
318321
onselect: Callable[[float, float], Any],
319322
direction: Literal["horizontal", "vertical"],
323+
*,
320324
minspan: float = ...,
321325
useblit: bool = ...,
322326
props: dict[str, Any] | None = ...,
@@ -348,6 +352,7 @@ class ToolLineHandles:
348352
ax: Axes,
349353
positions: ArrayLike,
350354
direction: Literal["horizontal", "vertical"],
355+
*,
351356
line_props: dict[str, Any] | None = ...,
352357
useblit: bool = ...,
353358
) -> None: ...
@@ -370,6 +375,7 @@ class ToolHandles:
370375
ax: Axes,
371376
x: ArrayLike,
372377
y: ArrayLike,
378+
*,
373379
marker: str = ...,
374380
marker_props: dict[str, Any] | None = ...,
375381
useblit: bool = ...,
@@ -436,6 +442,7 @@ class LassoSelector(_SelectorWidget):
436442
self,
437443
ax: Axes,
438444
onselect: Callable[[list[tuple[float, float]]], Any],
445+
*,
439446
useblit: bool = ...,
440447
props: dict[str, Any] | None = ...,
441448
button: MouseButton | Collection[MouseButton] | None = ...,
@@ -447,11 +454,11 @@ class PolygonSelector(_SelectorWidget):
447454
self,
448455
ax: Axes,
449456
onselect: Callable[[ArrayLike, ArrayLike], Any],
457+
*,
450458
useblit: bool = ...,
451459
props: dict[str, Any] | None = ...,
452460
handle_props: dict[str, Any] | None = ...,
453461
grab_range: float = ...,
454-
*,
455462
draw_bounding_box: bool = ...,
456463
box_handle_props: dict[str, Any] | None = ...,
457464
box_props: dict[str, Any] | None = ...
@@ -473,6 +480,7 @@ class Lasso(AxesWidget):
473480
ax: Axes,
474481
xy: tuple[float, float],
475482
callback: Callable[[list[tuple[float, float]]], Any],
483+
*,
476484
useblit: bool = ...,
477485
) -> None: ...
478486
def onrelease(self, event: Event) -> None: ...

0 commit comments

Comments
 (0)