Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #91219 > unrolled thread

Documentaion of dunder methods

Back to article view | Back to comp.lang.python

Contents

  Documentaion of dunder methods Steven D'Aprano <steve@pearwood.info> - 2015-05-26 12:17 +1000
    Re: Documentaion of dunder methods Rustom Mody <rustompmody@gmail.com> - 2015-05-25 19:36 -0700
    Re: Documentaion of dunder methods Steven D'Aprano <steve@pearwood.info> - 2015-05-26 13:17 +1000
      Re: Documentaion of dunder methods Rustom Mody <rustompmody@gmail.com> - 2015-05-25 20:30 -0700
        Re: Documentaion of dunder methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2015-05-26 08:24 +0100
    Re: Documentaion of dunder methods Ian Kelly <ian.g.kelly@gmail.com> - 2015-05-25 22:34 -0600
      Re: Documentaion of dunder methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-05-26 17:12 +1000

#91219 — Documentaion of dunder methods

PEP 8 states that developers should never invent their own dunder methods:

    __double_leading_and_trailing_underscore__ : 
        "magic" objects or attributes that live in user-controlled
        namespaces. E.g. __init__ , __import__ or __file__ . Never 
        invent such names; only use them as documented. 

https://www.python.org/dev/peps/pep-0008/#naming-conventions


In other words, dunder methods are reserved for use by the core developers
for the use of the Python interpreter.

Apart from PEP 8, is this documented anywhere in the official documentation?
If so, I have been unable to find it.



-- 
Steven

[toc] | [next] | [standalone]

#91221

On Tuesday, May 26, 2015 at 7:47:41 AM UTC+5:30, Steven D'Aprano wrote:
> PEP 8 states that developers should never invent their own dunder methods:
> 
>     __double_leading_and_trailing_underscore__ : 
>         "magic" objects or attributes that live in user-controlled
>         namespaces. E.g. __init__ , __import__ or __file__ . Never 
>         invent such names; only use them as documented. 
> 
> https://www.python.org/dev/peps/pep-0008/#naming-conventions
> 
> 
> In other words, dunder methods are reserved for use by the core developers
> for the use of the Python interpreter.
> 
> Apart from PEP 8, is this documented anywhere in the official documentation?
> If so, I have been unable to find it.

Thanks for bringing this up.
dunder methods are a super-powerful and very pythonesque feature rendered 
somewhat useless by bad documentation.
Also I happen to disagree with (the literal rendering of your:

> In other words, dunder methods are reserved for use by the core developers
> for the use of the Python interpreter.

Of course defining YOUR OWN dunder method, disregarding the intended protocol
for that dunder method's usage, should not be done.
However if you interpret your statement as "Just dont go near them" it seems
like they are some kind of best-avoided leaky-abstraction of the (C)python 
implementation. And I guess you dont really want to assert that!!

What I'd like to see in the docs is something that 'zips' the operator table 
with the corresponding dunder method.  Something like:
| + | __add__ __radd__ |
| []| __getitem__ |
etc

Yeah I realize the most critical dunders dont 'have' an associated operator --
__init__.  But even there I'd put something like
|Class constructor¹| __init__

¹ Yeah I know about the 'initializer-vs-constructor' debates. Not really taking
a side on that one

[toc] | [prev] | [next] | [standalone]

#91224

On Tue, 26 May 2015 12:17 pm, Steven D'Aprano wrote:

> In other words, dunder methods are reserved for use by the core developers
> for the use of the Python interpreter.

Er, that's easy to misinterpret. Let me try rewording:

You should not invent new dunder methods.

And if possible, you should not call such dunder methods directly. Instead,
use the official protocol (e.g. next(x), not x.__next__()) whenever
possible. The operator module contains many helpers for that.

But of course you may *write* dunder methods.


-- 
Steven

[toc] | [prev] | [next] | [standalone]

#91225

On Tuesday, May 26, 2015 at 8:48:11 AM UTC+5:30, Steven D'Aprano wrote:
> On Tue, 26 May 2015 12:17 pm, Steven D'Aprano wrote:
> 
> > In other words, dunder methods are reserved for use by the core developers
> > for the use of the Python interpreter.
> 
> Er, that's easy to misinterpret. Let me try rewording:
> 
> You should not invent new dunder methods.
> 
> And if possible, you should not call such dunder methods directly. Instead,
> use the official protocol (e.g. next(x), not x.__next__()) whenever
> possible. The operator module contains many helpers for that.
> 
> But of course you may *write* dunder methods.

I guess you and I know what we want to convey and to proscribe.
However the above doesn't pass muster as documentation
The most glaring lack in the docs is some reification of the acceptable 
'protocols'.
Yeah people like to wax about duck-typing but that translates into semi-formal
protocols and they are just not documented 

[toc] | [prev] | [next] | [standalone]

#91237

On 26/05/2015 04:30, Rustom Mody wrote:
> On Tuesday, May 26, 2015 at 8:48:11 AM UTC+5:30, Steven D'Aprano wrote:
>> On Tue, 26 May 2015 12:17 pm, Steven D'Aprano wrote:
>>
>>> In other words, dunder methods are reserved for use by the core developers
>>> for the use of the Python interpreter.
>>
>> Er, that's easy to misinterpret. Let me try rewording:
>>
>> You should not invent new dunder methods.
>>
>> And if possible, you should not call such dunder methods directly. Instead,
>> use the official protocol (e.g. next(x), not x.__next__()) whenever
>> possible. The operator module contains many helpers for that.
>>
>> But of course you may *write* dunder methods.
>
> I guess you and I know what we want to convey and to proscribe.
> However the above doesn't pass muster as documentation
> The most glaring lack in the docs is some reification of the acceptable
> 'protocols'.
> Yeah people like to wax about duck-typing but that translates into semi-formal
> protocols and they are just not documented
>

All you need do is raise an issue on the bug tracker with an attached patch.

-- 
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence

[toc] | [prev] | [next] | [standalone]

#91227

On Mon, May 25, 2015 at 8:17 PM, Steven D'Aprano <steve@pearwood.info> wrote:
> PEP 8 states that developers should never invent their own dunder methods:
>
>     __double_leading_and_trailing_underscore__ :
>         "magic" objects or attributes that live in user-controlled
>         namespaces. E.g. __init__ , __import__ or __file__ . Never
>         invent such names; only use them as documented.
>
> https://www.python.org/dev/peps/pep-0008/#naming-conventions
>
>
> In other words, dunder methods are reserved for use by the core developers
> for the use of the Python interpreter.
>
> Apart from PEP 8, is this documented anywhere in the official documentation?
> If so, I have been unable to find it.

https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers

[toc] | [prev] | [next] | [standalone]

#91236

On Tuesday 26 May 2015 14:34, Ian Kelly wrote:

>> Apart from PEP 8, is this documented anywhere in the official
>> documentation? If so, I have been unable to find it.
> 
> https://docs.python.org/3/reference/lexical_analysis.html#reserved-
classes-of-identifiers


That's the bunny!

Thanks for that.


-- 
Steve

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web