Title: `copy.replace` rejects a union whose members each have a field the others lack (since #14819) · Issue #16582 · python/typeshed · GitHub
Open Graph Title: `copy.replace` rejects a union whose members each have a field the others lack (since #14819) · Issue #16582 · python/typeshed
X Title: `copy.replace` rejects a union whose members each have a field the others lack (since #14819) · Issue #16582 · python/typeshed
Description: WarningLLM Disclosure This post was authored by claude-opus-5-5 on behalf of @JPHutchins. While working out JPHutchins/salix#359 (a dataclass_transform library whose replace stub has the same ParamSpec-protocol shape as copy.replace), JP...
Open Graph Description: WarningLLM Disclosure This post was authored by claude-opus-5-5 on behalf of @JPHutchins. While working out JPHutchins/salix#359 (a dataclass_transform library whose replace stub has the same Param...
X Description: WarningLLM Disclosure This post was authored by claude-opus-5-5 on behalf of @JPHutchins. While working out JPHutchins/salix#359 (a dataclass_transform library whose replace stub has the same Param...
Opengraph URL: https://github.com/python/typeshed/issues/16582
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"`copy.replace` rejects a union whose members each have a field the others lack (since #14819)","articleBody":"> [!WARNING]\n> **LLM Disclosure**\n>\n> This post was authored by claude-opus-5-5 on behalf of @JPHutchins. While working out JPHutchins/salix#359 (a `dataclass_transform` library whose `replace` stub has the same ParamSpec-protocol shape as `copy.replace`), JP asked me to report the upstream causes with evidence.\n\n**Since #14819 typed `copy.replace` through `_SupportsReplace[_P, _RT_co]`, a union argument is rejected whenever each member has a field the others lack, such as `Circle | Square` sharing `name`.**\n- **ty 0.0.90**, which bundles #14819, rejects `copy.replace(shape, name=\"renamed\")` today. **mypy 2.4.0**, which also bundles it, rejects the call and returns `object`.\n- **pyright 1.1.414** (released 2026-09-09) rejects it against main's signature; its bundled typeshed predates #14819.\n- **Unions that still pass:** identical fields (`Left | Right`), or one member's fields containing the other's.\n- **The call is fine at runtime.**\n\n**Proposed fix:** a second overload that no argument can match. Checkers then apply the spec's argument type expansion and check each union member on its own, and changes stay typed. Measured on all three: `rename` passes and `wrong` is still refused. mypy still returns `object` for `bump`, its join, linked below.\n\n```python\nimport copy\nfrom dataclasses import dataclass\n\n\n@dataclass(frozen=True)\nclass Circle:\n name: str\n radius: float\n\n\n@dataclass(frozen=True)\nclass Square:\n name: str\n side: float\n\n\n@dataclass(frozen=True)\nclass Left:\n x: int\n\n\n@dataclass(frozen=True)\nclass Right:\n x: int\n\n\ndef rename(shape: Circle | Square) -> Circle | Square:\n return copy.replace(shape, name=\"renamed\")\n\n\ndef bump(value: Left | Right) -> Left | Right:\n return copy.replace(value, x=1)\n\n\ndef wrong(shape: Circle | Square) -> Circle | Square:\n return copy.replace(shape, name=1)\n```\n\n| at a 3.14 target | `rename` | `bump` | `wrong` |\n|---|---|---|---|\n| ty 0.0.63, bundled, before #14819 | ok | ok | not checked |\n| ty 0.0.90, bundled, with #14819 | **rejected** | ok | refused |\n| pyright 1.1.414, bundled, before #14819 | ok | ok | not checked |\n| pyright 1.1.414, main's signature | **rejected** | ok | refused |\n| mypy 2.4.0, bundled, with #14819 | **rejected, `object`** | **`object`** | refused |\n| all three, main's signature plus the overload below | ok | mypy: **`object`**; pyright and ty: ok | refused |\n\n\u003cdetails>\u003csummary>Exact output\u003c/summary>\n\nty 0.0.90 (bundled `copy.replace`):\n```\nrepro.py:28:25: error[invalid-argument-type] Argument to function `replace` is incorrect: Expected `_SupportsReplace[((*, name: str = ..., radius: float = ...)) | ((*, name: str = ..., side: float = ...)), Circle | Square]`, found `Circle | Square`\n```\npyright 1.1.414, against main's signature (its bundled typeshed is 289e5d3, from 2026-06-24, so I put main's `_SupportsReplace` and `replace` in a local stub):\n```\nrepro_tsmain.py:28:25 - error: Argument of type \"Circle | Square\" cannot be assigned to parameter \"obj\" of type \"_SupportsReplace[_P@replace, _RT_co@replace]\" in function \"replace\"\n```\nmypy 2.4.0 (bundled):\n```\nrepro.py:28: error: Incompatible return value type (got \"object\", expected \"Circle | Square\") [return-value]\nrepro.py:28: error: Argument 1 to \"replace\" has incompatible type \"Circle | Square\"; expected \"_SupportsReplace[[DefaultNamedArg(str, 'name'), DefaultNamedArg(float, 'radius')], object]\" [arg-type]\nrepro.py:32: error: Incompatible return value type (got \"object\", expected \"Left | Right\") [return-value]\n```\nAt run time on CPython 3.14.8, `rename(Square(\"s\", 1.0))` returns `Square(name='renamed', side=1.0)` and `bump(Right(0))` returns `Right(x=1)`.\n\n\u003c/details>\n\n\u003cdetails>\u003csummary>The proposed overloads, and why they work\u003c/summary>\n\n```python\n@final\n@type_check_only\nclass _Unreplaceable: ...\n\n@overload\ndef replace(obj: _SupportsReplace[_P, _RT_co], /, *_: _P.args, **changes: _P.kwargs) -> _RT_co: ...\n@overload\ndef replace(obj: _Unreplaceable, /, **changes: object) -> Never: ...\n```\n\n- mypy only splits the union once the whole union fails the first overload. `Left | Right` matches it as a whole through the join, so `bump` stays `object`.\n- On sentinel choice: with `obj: Never` as the second overload's parameter, mypy reports `overload-cannot-match` on this stub. A `@final` class no argument is an instance of avoids that.\n\nFrom the typing spec's [overload call evaluation, step 3](https://typing.python.org/en/latest/spec/overload.html#step-3):\n\n> If step 2 produces errors for all overloads, perform \"argument type expansion\". Union types can be expanded into their constituent subtypes.\n\n> If all argument lists evaluate successfully, combine their respective return types by union to determine the final return type for the call, and stop.\n\npyright's maintainer has explained why a ParamSpec can't bind a union of signatures, and has pointed to overloads for other ParamSpec-and-union shapes. Neither thread is about `copy.replace`:\n- [pyright#4760](https://github.com/microsoft/pyright/issues/4760): “A `ParamSpec` cannot take on multiple signatures. There's no way to \"widen\" a signature to include multiple signatures.” and “Perhaps an overload would satisfy your use case?”\n- [pyright#11152](https://github.com/microsoft/pyright/issues/11152): \"The correct way to annotate this function is with an overload.\"\n\n\u003c/details>\n\n\u003cdetails>\u003csummary>Related\u003c/summary>\n\n- #14819 (ParamSpec `copy.replace`, merged 2026-09-02) and #14786 (the covariant protocol).\n- #15973, and the open PR #15997 (written against the pre-#14819 signature): a bound TypeVar or `Self` argument widened to its bound. Not addressed by the overloads above.\n- mypy's join:\n - python/mypy#21672: the same widening in mypy;\n - python/mypy#8601: a protocol solved from a union gives `object`;\n - python/mypy#13493: union math on non-overloaded calls.\n- JPHutchins/salix#359, the downstream report: the same shape in a `dataclass_transform` stub.\n\n\u003c/details>\n","author":{"url":"https://github.com/JPHutchins","@type":"Person","name":"JPHutchins"},"datePublished":"2026-10-21T01:43:36Z","url":"https://github.com/python/typeshed/issues/16582"}
| 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:9e96ea6f-4845-738b-80ca-d7ff23505ccf |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B7F0:3E4AC7:2D0D9FB:3D6057F:6B005982 |
| html-safe-nonce | 08b5ac846bb7485fc4c26bf56e324b1d245a567abd7449c7ca86533c535e22f7 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCN0YwOjNFNEFDNzoyRDBEOUZCOjNENjA1N0Y6NkIwMDU5ODIiLCJ2aXNpdG9yX2lkIjoiODUxODQ2NzE3MTIxMzQwMDQ1MCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 7325aa1ae8cfc63d86e49bdaae7b54cd085453bfc3c2c22a98e2ddfdf491f078 |
| hovercard-subject-tag | issue:5952750787 |
| 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/typeshed/16582/issue_layout |
| twitter:image | https://opengraph.githubassets.com/e97c38ca6a209093e9e5300e15f6f9562e6aaad41501f3ecee9a166452ef79a5/python/typeshed/issues/16582 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/e97c38ca6a209093e9e5300e15f6f9562e6aaad41501f3ecee9a166452ef79a5/python/typeshed/issues/16582 |
| og:image:alt | WarningLLM Disclosure This post was authored by claude-opus-5-5 on behalf of @JPHutchins. While working out JPHutchins/salix#359 (a dataclass_transform library whose replace stub has the same Param... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | JPHutchins |
| hostname | github.com |
| expected-hostname | github.com |
| None | 29be975efff6507a5d135de9c7d634cf7ff8f0c55222a64386ab3202209aaf73 |
| turbo-cache-control | no-preview |
| go-import | github.com/python/typeshed git https://github.com/python/typeshed.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 31696383 |
| octolytics-dimension-repository_nwo | python/typeshed |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 31696383 |
| octolytics-dimension-repository_network_root_nwo | python/typeshed |
| 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 | eacd927ba6112e3b01ba99c762bd699a4a4f5df7 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width