[issue32501] Documentation for dir([object])
New submission from Vladislavs Burakovs <solomonchild@gmail.com>: 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 ---------- assignee: docs@python components: Documentation messages: 309544 nosy: Vladislavs Burakovs, docs@python priority: normal severity: normal status: open title: Documentation for dir([object]) type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
Eric V. Smith <eric@trueblade.com> added the comment: 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. ---------- nosy: +eric.smith _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
Matthew Cowles <mdcowles@users.sourceforge.net> added the comment: 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. ---------- nosy: +mdcowles _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
Matthew Cowles <mdcowles@users.sourceforge.net> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
Change by Ethan Furman <ethan@stoneleaf.us>: ---------- nosy: +ethan.furman _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________
participants (5)
-
Eric V. Smith -
Ethan Furman
-
Matthew Cowles
-
R. David Murray
-
Vladislavs Burakovs