René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[MNT]: Type hints for the data keyword argument","articleBody":"### Summary\n\nThe `data` keyword argument presents a tricky edge case for typing that is currently not ideal.\r\n\r\n#25632 Provides the first step, untyped but present in the type stubs (so `stubtest` will check them at least.\n\n### Proposed fix\n\n## The OO api type hints: overloads\r\n\r\nThe most properly the type hint would look something like:\r\n\r\n```python\r\n    @overload\r\n    def hlines(\r\n        self,\r\n        y: float | ArrayLike,\r\n        xmin: float | ArrayLike,\r\n        xmax: float | ArrayLike,\r\n        colors: Sequence[ColorType] | None = ...,\r\n        linestyles: LineStyleType = ...,\r\n        label: str = ...,\r\n        *,\r\n        data: None =...,\r\n        **kwargs\r\n    ) -\u003e LineCollection: ...\r\n    @overload\r\n    def hlines(\r\n        self,\r\n        y: float | ArrayLike | str,\r\n        xmin: float | ArrayLike | str,\r\n        xmax: float | ArrayLike | str,\r\n        colors: Sequence[ColorType] | None | str = ...,\r\n        linestyles: LineStyleType = ...,\r\n        label: str = ...,\r\n        *,\r\n        data: Mapping[str, ArrayLike],\r\n        **kwargs\r\n    ) -\u003e LineCollection: ...\r\n```\r\n\r\nThat is to say:\r\n\r\nAn overloaded call where one call has `data` of type `None`, and the other has `data` with type `Mapping[str, ArrayLike]` (and also appends `str` to the valid types for affected parameters)\r\n\r\nNote that technically `str` does pass as `ArrayLike`, as that is a broad union which includes scalars (and `str` specifically), but communicating explicitly that `str` is expected for the case where data is not None is a bit better.\r\n\r\nIf `**kwargs` is not included, the first overload could simply omit `data` all together, making it a required keyword arg.\r\n\r\n## The problem: pyplot\r\n\r\nCurrent pyplot generation code (tools/boilerplate.py) _only_ looks at the _first_ signature of overloads.\r\nThis currently only affects a small number of methods that are in the autogenerated portion of pyplot and have overloads in their definitions (e.g. Axes.legend), which simply don't get the full type hints in pyplot. \r\n\r\nCurrently, none of the affected methods result in a type hint being added which is not correct, just type hints being omitted (and thus to mypy are `Any`) and so not deriving the value of having type hints for that small number of methods\r\n\r\nThe above overload for `data` would not be the same, as it would either get `None` OR `Mapping[...]`, not the union. In the latter case, this would be a problem as the default would not match the hint. In the former, it would fail if you tried to use the arg. If no `**kwargs` and data is simply omitted, it would simply be as it already was where pyplot gets no type hint for `data`, but it does appear in the signature.\r\n\r\nThe pyplot generation code may need to be be more comprehensive and explicitly handle the case of overloads. This is certainly possible, but not easy.\r\n\r\n## Considerations for inline type hints\r\n\r\nSince `data` does not appear in the actual signature this is mildly complicated for if we ever do want to move towards inline type hints. Such a move is not in the current plans, but worth writing down why this is a complicating factor.\r\n\r\nIf we use overloads, I think it may actually just wash away, so maybe not as complicated as otherwise.\r\n\r\n[PEP 612](https://peps.python.org/pep-0612/) addresses allowing static typing of decorators which modify signatures by adding _positional_ arguments, but [explicitly excludes](https://peps.python.org/pep-0612/#concatenating-keyword-parameters) the case of adding a _keyword-only_ arg, as is the case for the `_preprocess_data`. So statically using the decorator to transparently modify the signature for the type checker is not possible.","author":{"url":"https://github.com/ksunden","@type":"Person","name":"ksunden"},"datePublished":"2023-04-05T22:07:52.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/25634/matplotlib/issues/25634"}