Random Remarks in class documentation

[atsengg]

BPO	12634
Nosy	@rhettinger, @terryjreedy, @ezio-melotti, @merwok
PRs	bpo-12634: Clarify an awkward section of the tutorial #15406 [3.8] bpo-12634: Clarify an awkward section of the tutorial (GH-15406) #15409
Files	issue12634.patch issue12634-27.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-08-23.06:46:25.514>
created_at = <Date 2011-07-25.06:36:50.164>
labels = ['easy', '3.8', '3.9', 'docs']
title = 'Random Remarks in class documentation'
updated_at = <Date 2019-08-23.06:46:25.514>
user = 'https://bugs.python.org/atsengg'

bugs.python.org fields:

activity = <Date 2019-08-23.06:46:25.514>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-08-23.06:46:25.514>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2011-07-25.06:36:50.164>
creator = 'ats.engg'
dependencies = []
files = ['30134', '30135']
hgrepos = []
issue_num = 12634
keywords = ['patch', 'easy']
message_count = 12.0
messages = ['141073', '141074', '141078', '141089', '141103', '174672', '174753', '187691', '188444', '188445', '350252', '350254']
nosy_count = 9.0
nosy_names = ['rhettinger', 'terry.reedy', 'fossilet', 'ezio.melotti', 'eric.araujo', 'cvrebert', 'docs@python', 'ats.engg', 'Yogesh.Chaudhari']
pr_nums = ['15406', '15409']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue12634'
versions = ['Python 3.8', 'Python 3.9']

[atsengg]

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"

[rhettinger]

The proposed rewrite doesn't make any sense to me. Also "set through" is an reads awkwardly.

[ezio-melotti]

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 PEP-8). 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".

[merwok]

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.

[terryjreedy]

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."

[merwok]

+1 to something like Terry’s proposal.

[ezio-melotti]

See also bpo-16048.

[fossilet]

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.

[YogeshChaudhari]

Based on Teery's comments, this patch makes the changes to the random remarks section of the class documentation

[YogeshChaudhari]

Similar changes for 2.7 branch

[rhettinger]

New changeset 483ae0c by Raymond Hettinger in branch 'master':
bpo-12634: Clarify an awkward section of the tutorial (GH-15406)
483ae0c

[rhettinger]

New changeset f6a7f5b by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-12634: Clarify an awkward section of the tutorial (GH-15406) (GH-15409)
f6a7f5b