Repository navigation
Incorrect rendering of __replace__ method in copy docs: consider adding copy.SupportsReplace? #109961
Description
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:
- Do not document this as a method (however, it is)
- Document it as
object.__replace__, butobjectdoes not have this method - it can be very confusing - Add some protocol, like
typing.SupportsReplaceand documentSupportsReplace.__replace__
I personally think that typing.SupportsReplace is very useful on its own, because:
- we will use it in
typeshedfor typingcopy.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
Activity
[-]Incorrect rendering of `__replace__` method in `copy` docs[/-][+]Incorrect rendering of `__replace__` method in `copy` docs: consider adding `typing.SupportsReplace`?[/+]AA-Turner commentedon Sep 27, 2023
We should document this in the datamodel, similar to
__buffer__, which is also only applicable in certain cases.A
AlexWaygood commentedon Sep 27, 2023
I like the idea of
SupportsReplace. I think it should be added to thecopymodule, though, nottyping, similar to howPathLikeis in theosmodule andAbstractContextManageris incontextlib.We can take the same approach we do with
os.PathLikeandcontextlib.AbstractContextManagerin order to avoid importingtypingin those modules: have it be anabc.ABCat runtime, but special-case it intypingso that it behaves like a protocol (and pretend in typeshed that it is a protocol). That gives us the best of both worlds.sobolevn commentedon Sep 27, 2023
Yes, I agree with
copymodule. This way it would be also more convenient for users:AA-Turner commentedon Sep 27, 2023
Minor, but perhaps consider
Replaceable? That's more in line with the collections ABCs.A
[-]Incorrect rendering of `__replace__` method in `copy` docs: consider adding `typing.SupportsReplace`?[/-][+]Incorrect rendering of `__replace__` method in `copy` docs: consider adding `copy.SupportsReplace`?[/+]AlexWaygood commentedon Sep 27, 2023
I think I prefer Nikita's name, which is inline with the
Supports*naming convention in the typing module --SupportsInt,SupportsFloat, etc. "Replaceable" feels like you're making some comment about the fungibility of the object in question, which isn't necessarily true ;)AA-Turner commentedon Sep 27, 2023
Fair enough -- the suggestion was in large part as currently it is only the
typingmodule which uses theSupportsDunderconvention. Outwithtyping, the following usages appear:typing.Protocolsubclasses. All of the following are 'complex' protocols with multiple attributes, save for_Readable, which only defines theread()method.importlib.metadata.{PackageMetadata,SimplePath}importlib.resources.abc.Traversablewsgiref.types.{StartResponse,InputStream,ErrorStream,_Readable,FileWrapper}abc.ABCsubclasses orabc.ABCMetasubclasses. Contrary to my earlier note, it seems only 6 of thecollections.abctypes are named-ble. However, these 6 form a plurality of the 'single method' types (rounding out the set areBuffer,Container,Sized,PathLike, and variousnumbertypes.collections.abc.{Awaitable,AsyncIterable,Hashable,Iterable,Reversible,Callable }collections.abc.{AsyncGenerator,AsyncIterator,Buffer,ByteString,Collection,Container,Coroutine,Generator,ItemsView,Iterator,KeysView,Mapping,MappingView,MutableMapping,MutableSequence,MutableSet,Sequence,Set,Sized,ValuesView}contextlib.{AbstractContextManager,AbstractAsyncContextManager}importlib.resources.simple.SimpleReadermultiprocessing.reduction.AbstractReducernumbers.Number(& by extension the whole numeric tower)os.PathLikeselectors.BaseSelectorSo it seems consistency is not quite here! I think I sympathise most with your fungability argument, given that this replaces data within the object, not the object itself--though for immutable types the object will be replaced!
A
AlexWaygood commentedon Sep 27, 2023
Yes: objects with the
__replace__method may be fungible, but aren't necessarily fungible :)serhiy-storchaka commentedon Sep 27, 2023
Thank you for catching this @sobolevn.
I think adding
object.would be enough. There are no SupportCopy, SupportDeepCopy or SupportPickle. While currentlycopy.replace()only supports classes with__replace__method, in future it may support other objects. For example it could support pure Python classes without__new__and__init__methods, or some pickleable classes. For now it requires the__replace__method, but after it became widely used we can analyze patterns of its use and make defining trivial__replace__methods unneeded.AlexWaygood commentedon Sep 27, 2023
Ah, if that's the intention, then adding
SupportsReplacewould indeed be a bad idea.pythongh-109961: Fix incorrect rendering of `__replace__` in `library…
gh-109961: Docs: Fix incorrect rendering of `__replace__` in `copy.rs…
pythongh-109961: Use proper `module` for `copy` method docs
pythongh-109961: Docs: Fix incorrect rendering of `__replace__` in `c…
gh-109961: Use proper `module` for `copy` method docs (#110027)
serhiy-storchaka commentedon Oct 7, 2023
Can it be closed already?
pythongh-109961: Docs: Fix incorrect rendering of `__replace__` in `c…
pythongh-109961: Use proper `module` for `copy` method docs (python#1…
[3.12] pythongh-109961: Docs: Fix incorrect rendering of `__replace__…
[3.12] gh-109961: Docs: Fix incorrect rendering of `__replace__` in `…