Bug report

Here's how it looks right now:

Link: https://docs.python.org/dev/library/copy.html

But, there's no such thing as copy.__replace__.

There are several options:

1. Do not document this as a method (however, it is)
2. Document it as object.__replace__, but object does not have this method - it can be very confusing
3. Add some protocol, like typing.SupportsReplace and document SupportsReplace.__replace__

I personally think that typing.SupportsReplace is very useful on its own, because:

• we will use it in typeshed for typing copy.replace
• it can be used in other places by end users
• it matches exactly what __replace__ is: a protocol

So, it can something like:

class SupportsReplace(Protocol):
    def __replace__(self, /, **kwargs: Any) -> Self: ...

We cannot really type **kwargs here. See https://discuss.python.org/t/generalize-replace-function/28511/20 But, we can later apply mypy plugin similar to one we use for dataclasses.replace: https://github.com/python/mypy/blob/4b66fa9de07828621fee1d53abd533f3903e570a/mypy/plugins/dataclasses.py#L390-L402

I would like to work on docs / implementation changes after we discuss all the things and come to an agreement :)

CC @serhiy-storchaka @AlexWaygood

Linked PRs

• gh-109961: Docs: Fix incorrect rendering of __replace__ in copy.rst #109968
• gh-109961: Use proper module for copy method docs #110027
• [3.12] gh-109961: Docs: Fix incorrect rendering of __replace__ in copy.rst (GH-109968) #130909