Suggestion: link from UserList docs to the collections classes list of methods
Hi! My exposure to Python is sporadic so I am functionally a complete newbie here, and maybe this is just really obvious to more experienced people, but I couldn't find a thing I wanted in the UserList documentation, and "an experienced programmer who doesn't know this language is confused by the documentation" feels like a thing potentially worth reporting. I started here: https://docs.python.org/3/library/collections.html#collections.UserList
In addition to supporting the methods and operations of mutable sequences, UserList instances provide the following attribute:
As a naive user, I don't know what are the "methods and operations of mutable sequences", or where to look for them. So when I was contemplating subclassing UserList and attempting to wrap its methods, I found that I did not know what those methods would be, or how to find those methods. A helpful user with more experience pointed me to: https://docs.python.org/3/library/collections.abc.html#collections-abstract-... And from this I have concluded that, if I wanted to override behavior such that my wrapped list would intercept every list operation, I would need to define: __getitem__, __setitem__, __delitem__, __len__, insert And... I think that's it? I think if I understand correctly, the "mixin methods" such as __iadd__ would be defined in terms of these. I think. But I think it would be better if, as a naive user encountering the UserList documentation, I could figure this out without asking other people. Possible enhancements: 1. UserList actually provides the list directly inline. 2. The "methods and operations of mutable sequences" could be or also provide a link directly to that list of methods and operations. -s
Hello, Thank you for the report. I've added it to Python's bug tracker here so volunteers can find it more easily: https://github.com/python/cpython/issues/110383 On 12/29/23 17:40, Seebs wrote:
Hi! My exposure to Python is sporadic so I am functionally a complete newbie here, and maybe this is just really obvious to more experienced people, but I couldn't find a thing I wanted in the UserList documentation, and "an experienced programmer who doesn't know this language is confused by the documentation" feels like a thing potentially worth reporting.
I started here:
https://docs.python.org/3/library/collections.html#collections.UserList
In addition to supporting the methods and operations of mutable sequences, UserList instances provide the following attribute: As a naive user, I don't know what are the "methods and operations of mutable sequences", or where to look for them. So when I was contemplating subclassing UserList and attempting to wrap its methods, I found that I did not know what those methods would be, or how to find those methods.
A helpful user with more experience pointed me to:
https://docs.python.org/3/library/collections.abc.html#collections-abstract-...
And from this I have concluded that, if I wanted to override behavior such that my wrapped list would intercept every list operation, I would need to define: __getitem__, __setitem__, __delitem__, __len__, insert
And... I think that's it? I think if I understand correctly, the "mixin methods" such as __iadd__ would be defined in terms of these. I think.
But I think it would be better if, as a naive user encountering the UserList documentation, I could figure this out without asking other people.
Possible enhancements: 1. UserList actually provides the list directly inline. 2. The "methods and operations of mutable sequences" could be or also provide a link directly to that list of methods and operations.
-s _______________________________________________ docs mailing list -- docs@python.org To unsubscribe send an email to docs-leave@python.org https://mail.python.org/mailman3/lists/docs.python.org/ Member address: encukou@gmail.com
Hi! Thank you for bringing this up. I feel like the documentation of MutableSequence [1] in collections.abc reference could be enhanced (the section of it is called "Collections Abstract Base Classes – Detailed Descriptions "). And then linked from UserList documentation. Would you be willing to open a PR? Maciek [1] https://docs.python.org/3/library/collections.abc.html#collections.abc.Mutab... śr., 24 sty 2024 o 18:33 Seebs <seebs@seebs.net> napisał(a):
Hi! My exposure to Python is sporadic so I am functionally a complete newbie here, and maybe this is just really obvious to more experienced people, but I couldn't find a thing I wanted in the UserList documentation, and "an experienced programmer who doesn't know this language is confused by the documentation" feels like a thing potentially worth reporting.
I started here:
https://docs.python.org/3/library/collections.html#collections.UserList
In addition to supporting the methods and operations of mutable sequences, UserList instances provide the following attribute:
As a naive user, I don't know what are the "methods and operations of mutable sequences", or where to look for them. So when I was contemplating subclassing UserList and attempting to wrap its methods, I found that I did not know what those methods would be, or how to find those methods.
A helpful user with more experience pointed me to:
https://docs.python.org/3/library/collections.abc.html#collections-abstract-...
And from this I have concluded that, if I wanted to override behavior such that my wrapped list would intercept every list operation, I would need to define: __getitem__, __setitem__, __delitem__, __len__, insert
And... I think that's it? I think if I understand correctly, the "mixin methods" such as __iadd__ would be defined in terms of these. I think.
But I think it would be better if, as a naive user encountering the UserList documentation, I could figure this out without asking other people.
Possible enhancements: 1. UserList actually provides the list directly inline. 2. The "methods and operations of mutable sequences" could be or also provide a link directly to that list of methods and operations.
-s _______________________________________________ docs mailing list -- docs@python.org To unsubscribe send an email to docs-leave@python.org https://mail.python.org/mailman3/lists/docs.python.org/ Member address: maciej.olko@gmail.com
participants (3)
-
Maciek Olko -
Petr Viktorin -
Seebs