Title: Overlapping overloads false positive with ParamSpec shenanigans · Issue #21171 · python/mypy · GitHub
Open Graph Title: Overlapping overloads false positive with ParamSpec shenanigans · Issue #21171 · python/mypy
X Title: Overlapping overloads false positive with ParamSpec shenanigans · Issue #21171 · python/mypy
Description: Bug Report Abstract mypy incorrectly flags overloads of functions with certain signatures related to ParamSpec shenangians that do not overlap with previous overloads as being narrower than the previous overloads and thus impossible to m...
Open Graph Description: Bug Report Abstract mypy incorrectly flags overloads of functions with certain signatures related to ParamSpec shenangians that do not overlap with previous overloads as being narrower than the pre...
X Description: Bug Report Abstract mypy incorrectly flags overloads of functions with certain signatures related to ParamSpec shenangians that do not overlap with previous overloads as being narrower than the pre...
Opengraph URL: https://github.com/python/mypy/issues/21171
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Overlapping overloads false positive with ParamSpec shenanigans","articleBody":"**Bug Report**\n\n**Abstract**\nmypy incorrectly flags overloads of functions with certain signatures related to ParamSpec shenangians that do not overlap with previous overloads as being narrower than the previous overloads and thus impossible to match.\n\n**Background**\nThere is a notable limitation of ParamSpec that makes it difficult to annotate functions operating on a function and its parameters, as well as some keyword arguments (optional or required). Currently, the best workaround is to use Any to annotate the variadic args and kwargs, but that still loses some typing information. See the below snippet from the python docs.\n\n````markdown\n[Concatenating Keyword Parameters](https://peps.python.org/pep-0612/#concatenating-keyword-parameters)\nIn principle the idea of concatenation as a means to modify a finite number of positional parameters could be expanded to include keyword parameters.\n\n```python\ndef add_n(f: Callable[P, R]) -> Callable[Concatenate[(\"n\", int), P], R]:\n def inner(*args: P.args, n: int, **kwargs: P.kwargs) -> R:\n # use n\n return f(*args, **kwargs)\n return inner\n```\n\nHowever, the key distinction is that while prepending positional-only parameters to a valid callable type always yields another valid callable type, the same cannot be said for adding keyword-only parameters. As alluded to [above](https://peps.python.org/pep-0612/#above) , the issue is name collisions. The parameters `Concatenate[(\"n\", int), P]` are only valid when P itself does not already have a parameter named `n`.\n\n```python\ndef innocent_wrapper(f: Callable[P, R]) -> Callable[P, R]:\n def inner(*args: P.args, **kwargs: P.kwargs) -> R:\n added = add_n(f)\n return added(*args, n=1, **kwargs)\n return inner\n\n@innocent_wrapper\ndef problem(n: int) -> None:\n pass\n```\n\nCalling `problem(2)` works fine, but calling `problem(n=2)` leads to a `TypeError: problem() got multiple values for argument 'n'` from the call to added inside of innocent_wrapper.\n\nThis kind of situation could be avoided, and this kind of decorator could be typed if we could reify the constraint that a set of parameters not contain a certain name, with something like:\n\n```python\nP_without_n = ParamSpec(\"P_without_n\", banned_names=[\"n\"])\n\ndef add_n(\n f: Callable[P_without_n, R]\n) -> Callable[Concatenate[(\"n\", int), P_without_n], R]: ...\n```\n\nThe call to add_n inside of innocent_wrapper could then be rejected since the callable was not guaranteed not to already have a parameter named n.\n\nHowever, enforcing these constraints would require enough additional implementation work that we judged this extension to be out of scope of this PEP. Fortunately the design of ParamSpecs are such that we can return to this idea later if there is sufficient demand.\n````\n\nThis indicates that the below construct is unfortunately unsupported:\n\n```python\nclass PriorityPool:\n async def execute[T, **P](self, func: Callable[P, T], /, *args: P.args, priority: int = 0, **kwargs: P.kwargs) -> T: ...\n # type checker error!\n```\n\n**To Reproduce**\nmypy w/ default config on the following:\n\n```python\n# test.pyi\nfrom _collections_abc import Callable\nfrom typing import Any, overload\n@overload\ndef bar[T, **P](f: Callable[P, T], *a: P.args, **k: P.kwargs) -> T: ...\n@overload\ndef bar[T](f: Callable[..., T], *a: Any, baz: int, **k: Any) -> T: ...\n```\n\n**Expected Behavior**\nNo issues.\nThe first overload is for when `baz` is not passed, and the variadic `*a` and `**k` will eventually passed to `f`, so the ParamSpec dictates that only arguments accepted by the function `f` should be passed. The second overload is the case where `baz` is passed as a keyword argument, but due to the above limitation, it is not possible to annotate `*a: P.args` and `**k: P.kwargs`, so they are annotated as `Any`. The overloads are mutually exclusive.\n\n**Actual Behavior**\nmypy emits an error.\ntest.pyi:6: error: Overloaded function signature 2 will never be matched: signature 1's parameter type(s) are the same or broader [overload-cannot-match]\n\n**Your Environment**\n\n- Mypy version used: 1.19.1; compiled\n- Command used: `mypy test.pyi`\n- Mypy configuration options from `mypy.ini` (and other config files): None\n- Output of `python -vv`: Python 3.14.0 (tags/v3.14.0:ebf955d, Oct 7 2025, 10:15:03) [MSC v.1944 64 bit (AMD64)]\n","author":{"url":"https://github.com/jonathandung","@type":"Person","name":"jonathandung"},"datePublished":"2026-04-05T06:43:50Z","url":"https://github.com/python/mypy/issues/21171"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:0a712c46-6ba3-b0ed-a54c-47382a5d0256 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D4A8:1F3799:289F096:3538A06:6B0007C4 |
| html-safe-nonce | 842fc71266de4b8481cb741ed8d94c4b05bff7071e91ca532670616d8ad09efb |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJENEE4OjFGMzc5OToyODlGMDk2OjM1MzhBMDY6NkIwMDA3QzQiLCJ2aXNpdG9yX2lkIjoiNjg1MTEyMDA0NzUzNjk5ODM0MCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | d556bdd7d459b0bc000b30007ce283595cef0cb5a3ed7da856a283bb449ceb6d |
| hovercard-subject-tag | issue:4206757206 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/mypy/21171/issue_layout |
| twitter:image | https://opengraph.githubassets.com/b7c2a4b1054e83aac38ffb65750fc545a404a866fcafced19749d3b966209d5f/python/mypy/issues/21171 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/b7c2a4b1054e83aac38ffb65750fc545a404a866fcafced19749d3b966209d5f/python/mypy/issues/21171 |
| og:image:alt | Bug Report Abstract mypy incorrectly flags overloads of functions with certain signatures related to ParamSpec shenangians that do not overlap with previous overloads as being narrower than the pre... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | jonathandung |
| hostname | github.com |
| expected-hostname | github.com |
| None | 0a0d8686a27478df474dd7415776a7a080cde8838b3cd92ea7601187572e5729 |
| turbo-cache-control | no-preview |
| go-import | github.com/python/mypy git https://github.com/python/mypy.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 7053637 |
| octolytics-dimension-repository_nwo | python/mypy |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 7053637 |
| octolytics-dimension-repository_network_root_nwo | python/mypy |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 16a11879678aaf97e2a42c33ee70830aa084fa37 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width