Documenting builtin methods

[Joshua Landau]

On 11 July 2013 04:57, Ben Finney <ben+python at benfinney.id.au> wrote:
> Joshua Landau <joshua at landau.ws> writes:
>
>> I have this innocent and simple code:
>>
>> from collections import deque
>> exhaust_iter = deque(maxlen=0).extend
>> exhaust_iter.__doc__ = "Exhaust an iterator efficiently without
>> caching any of its yielded values."
>>
>> Obviously it does not work.
>
> Right. It raises a SyntaxError because you've got a simple string
> literal that isn't closed before the end of the line.

Is removing one newline such a big deal to you really?

>> Is there a way to get it to work simply
>
> What behaviour would you expect from that? We can't guess what you mean
> by “get it to work” unless we know what you're expecting and how the
> observed behaviour is different.

Obviously I want to set .__doc__. What else could you possibly glean
from me trying to set .__doc__? Are you that far away from an
interpreter that you can't see that it doesn't work?

> A good way to do this would be to show some actual code that
> demonstrates the surprising behaviour

That's what I did.

> (you may need to post using a
> service that doesn't munge your text), along with the traceback if any.

I imagine you could've run it yourself, seeing as it's a small,
reproducible test sample.

> Then, show a session that behaves the way you'd expect it to behave, and
> we can explain either how to achieve that or why it can't.

You know, I'd like it to not crash. And do what it would normally do
if it didn't crash.


I'm not sure why you've given this response, as my question was fairly
explanatory given that you spend the 10 seconds to run the code if you
couldn't see the crash by eye. It's a whole lot shorter than the time
you spent on the comment. There are a lot of people who post beasts of
code to this list that isn't remotely runnable and with cryptic
cropped errors that you have no obvious way of getting a duplicate of.
I did not do that.

For convenience, and because despite my tone of surprise I hold no
grudge or disdain, here is the relevant part of the traceback:
AttributeError: attribute '__doc__' of 'builtin_function_or_method'
objects is not writable

If you're still unhappy about the text-wrapping:
from collections import deque
exhaust_iter = deque(maxlen=0).extend
exhaust_iter.__doc__ = "Exhaust an iterator efficiently"