classification
Title: Documentation for dir([object])
Type: enhancement Stage:
Components: Documentation Versions: Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Vladislavs Burakovs, docs@python, eric.smith, ethan.furman, mdcowles, r.david.murray
Priority: normal Keywords:

Created on 2018-01-06 08:54 by Vladislavs Burakovs, last changed 2020-12-24 19:53 by ethan.furman.

Messages (6)
msg309544 - (view) Author: Vladislavs Burakovs (Vladislavs Burakovs) Date: 2018-01-06 08:54
Documentation page [1]  says "If the object has a method named __dir__(), this method will be called and must return the list of attributes.". 

It seems that on Python 3.6 it only works if the *class* has a method named __dir__. Should the documentation be changed?

Microsoft Windows [Version 10.0.16299.192]
(c) 2017 Microsoft Corporation. All rights reserved.

D:\Users\wlad>python
Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> class C: pass
...
>>> x = C()
>>> import types
>>> x.__dir__ = types.MethodType(lambda _:[], x)
>>> dir(x)
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__']
>>> C.__dir__ = types.MethodType(lambda _:[], x)
>>> dir(x)
[]

[1] https://docs.python.org/3/library/functions.html
msg309550 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2018-01-06 15:16
This is a general property of dunder methods in python3, and I think we have chosen not to change the wording when this has come up in other contexts.  I'm not sure, though.
msg309552 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-01-06 16:03
It's described here: https://docs.python.org/3/reference/datamodel.html#special-lookup

Maybe we should have a glossary entry for "special method lookup", and somehow link mentions like __dir__ to it?

This is slightly different from https://docs.python.org/3/reference/datamodel.html#specialnames, which already has a glossary entry.

On the other hand, unless you already understand the problem, it's going to be difficult to search for it.
msg309576 - (view) Author: Matthew Cowles (mdcowles) Date: 2018-01-06 20:21
If David is right and people have previously decided not to change wording like this, can someone explain why? As it stands, the meaning is clear and incorrect.
msg309596 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2018-01-07 02:22
I'm not sure, but the discussion I remember was that it would require changes to an awful lot of places in the docs that would make the docs harder to read.  It is very seldom in normal Python coding that an object has a method that it does *not* get from its class, and by the time you get to the level where you are adding methods to instances it is likely you know about dunder methods only being looked up on classes.  Usually you learn about it the first time you try to put a dunder method on an instance, and you scratch your head for a while, and then you find out...but complicating the docs to mention this at every turn would be...excessive, I think.  But again, I'm not 100% sure I'm remembering the outcome of that conversation, and I can't remember where it took place (it was an issue in this tracker, but I don't know which one.)
msg309608 - (view) Author: Matthew Cowles (mdcowles) Date: 2018-01-07 05:38
My thanks to David for the clarification. I don't find the logic he describes (but does not necessarily subscribe to!) persuasive in this case. In my opinion, "Let's be incorrect for the sake of simplicity," is not the way to document a programming language in the language's official library documentation.

I think that saying, "If the object (technically the class) has a method named..." would add very little burden to people who don't care about the difference.
History
Date User Action Args
2020-12-24 19:53:07ethan.furmansetnosy: + ethan.furman
2018-01-07 05:38:37mdcowlessetmessages: + msg309608
2018-01-07 02:22:32r.david.murraysetmessages: + msg309596
2018-01-06 20:21:31mdcowlessetnosy: + mdcowles
messages: + msg309576
2018-01-06 16:03:44eric.smithsetnosy: + eric.smith
messages: + msg309552
2018-01-06 15:16:27r.david.murraysetnosy: + r.david.murray
messages: + msg309550
2018-01-06 08:54:03Vladislavs Burakovscreate