classification
Title: Random Remarks in class documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Yogesh.Chaudhari, ats.engg, cvrebert, docs@python, eric.araujo, ezio.melotti, fossilet, rhettinger, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2011-07-25 06:36 by ats.engg, last changed 2019-08-23 06:46 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
issue12634.patch Yogesh.Chaudhari, 2013-05-05 14:07 review
issue12634-27.patch Yogesh.Chaudhari, 2013-05-05 14:08 review
Pull Requests
URL Status Linked Edit
PR 15406 merged rhettinger, 2019-08-22 23:36
PR 15409 merged miss-islington, 2019-08-23 06:27
Messages (12)
msg141073 - (view) Author: Ashutosh Swain (ats.engg) Date: 2011-07-25 06:36
URL: http://docs.python.org/tutorial/classes.html
section: 9.4 Random Remarks 

The first sentense is bit confusing:
"Data attributes override method attributes with the same name"

Is it possible to change the sentense something like this:
"Data attributes set through instance override method attributes with the same name"
msg141074 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-07-25 07:16
The proposed rewrite doesn't make any sense to me.  Also "set through" is an reads awkwardly.
msg141078 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-07-25 09:24
Indeed that paragraph is not really clear.  I had to read it till the end ("verbs for methods and nouns for data attributes") to figure out what it was talking about.  Even then it's still not clear what it's trying to say.
I *think* it means that if you have a class Foo with a method bar, and you do Foo.bar = 'data', the method will be overridden (so you won't be able to do Foo.bar for the 'data' and Foo.bar() for the method), but the opposite is also true.
Moreover I find both the suggestions for avoiding conflicts (capitalizing method names and/or using an underscore) wrong (both against PEP8).  Also it never happened to me to have an attribute with the same name of a method, and I think in general it's not a common case (becase, as the paragraph says, methods are verbs and attributes nouns).

The whole thing could be rewritten to just say that an attribute name always refers to a single object, either to a method or to some "data".
msg141089 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-25 12:02
I have the same reading as Ezio, and the same opinion that it’s unclear and unhelpful.  +1 to saying that there is only one namespace for data attributes and methods.
msg141103 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-25 17:10
That sentence is wrong to imply that there is anything special about data versus method attributes with respect to overriding -- or that attributes are special when it comes to names in a single namespace. What I think the paragraph should say, if not just deleted, is something like.

"Instance attributes hide class attributes. Instance data names are often intended to override class data names. But instance data names masking methods names is likely a mistake. This can be avoided by using verbs for method names and nouns for data names."
msg174672 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-03 19:03
+1 to something like Terry’s proposal.
msg174753 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-04 04:37
See also #16048.
msg187691 - (view) Author: Yongzhi Pan (fossilet) * Date: 2013-04-24 09:09
It may be worth to noting that when creating property attribute using the property decorator, we may tend to name the method using nouns, like here:
http://docs.python.org/2/library/functions.html#property

This is when I once overided data attribute with method.
msg188444 - (view) Author: Yogesh Chaudhari (Yogesh.Chaudhari) * Date: 2013-05-05 14:07
Based on Teery's comments, this patch makes the changes to the random remarks section of the class documentation
msg188445 - (view) Author: Yogesh Chaudhari (Yogesh.Chaudhari) * Date: 2013-05-05 14:08
Similar changes for 2.7 branch
msg350252 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-23 06:27
New changeset 483ae0cf1dcf46f8b71c4bf32419dd138e908553 by Raymond Hettinger in branch 'master':
bpo-12634: Clarify an awkward section of the tutorial (GH-15406)
https://github.com/python/cpython/commit/483ae0cf1dcf46f8b71c4bf32419dd138e908553
msg350254 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-23 06:45
New changeset f6a7f5bc50f4267cfb7fe0c4ea16d5359c009cbd by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-12634: Clarify an awkward section of the tutorial (GH-15406) (GH-15409)
https://github.com/python/cpython/commit/f6a7f5bc50f4267cfb7fe0c4ea16d5359c009cbd
History
Date User Action Args
2019-08-23 06:46:25rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-08-23 06:45:59rhettingersetmessages: + msg350254
2019-08-23 06:27:25rhettingersetmessages: + msg350252
2019-08-23 06:27:17miss-islingtonsetpull_requests: + pull_request15114
2019-08-22 23:37:13rhettingersetversions: + Python 3.8, Python 3.9, - Python 2.7, Python 3.2, Python 3.3, Python 3.4
2019-08-22 23:36:26rhettingersetstage: needs patch -> patch review
pull_requests: + pull_request15111
2013-05-12 23:24:59Yogesh.Chaudharisethgrepos: - hgrepo188
2013-05-05 14:08:28Yogesh.Chaudharisetfiles: + issue12634-27.patch
hgrepos: + hgrepo188
messages: + msg188445
2013-05-05 14:07:06Yogesh.Chaudharisetfiles: + issue12634.patch

nosy: + Yogesh.Chaudhari
messages: + msg188444

keywords: + patch
2013-04-24 09:09:26fossiletsetmessages: + msg187691
2012-11-04 07:41:00fossiletsetnosy: + fossilet
2012-11-04 05:05:18cvrebertsetnosy: + cvrebert
2012-11-04 04:37:12ezio.melottisetmessages: + msg174753
2012-11-04 04:36:41ezio.melottilinkissue16048 superseder
2012-11-03 19:03:24eric.araujosetversions: + Python 3.4
messages: + msg174672

keywords: + easy
type: enhancement ->
stage: needs patch
2011-07-25 17:10:36terry.reedysetmessages: + msg141103
2011-07-25 12:02:14eric.araujosetmessages: + msg141089
2011-07-25 09:24:02ezio.melottisetnosy: + terry.reedy, eric.araujo, ezio.melotti

messages: + msg141078
versions: + Python 3.2, Python 3.3
2011-07-25 07:16:30rhettingersetassignee: docs@python -> rhettinger

messages: + msg141074
nosy: + rhettinger
2011-07-25 06:36:50ats.enggcreate