Is the term attribute used uncanonically?

[funkyfuture]

if i understand the sections module correctly, i have the impression that the term attribute is used uncanonically with regards to Python's oop terminology. in that jargon, a property is a data object or descriptor that is bound to a class or instance, while a method is a callable that is bound to a class. an attribute is a union of both.

unless i'm missing something, the term property should be used where attribute is used atm in the sections module.

[kalekundert]

You're right that I'm not using "attribute" correctly, but don't think "property" would be correct either. Just so we're on the same page, this is how I'm using the terms:

• Property: a data descriptor, specifically one created the @property decorator.
• Method: a callable bound to a class.
• Attribute: not one of the above (and also not a inner class)

I have a more narrow view of what "property" means, which is why I don't think it's a good term for "non-method/non-class attribute". Unfortunately, there doesn't seem to be an official definition of "property", but I think my definition is more consistent with general usage and with the way it's used in the stdlib documentation, e.g. inspect, new-style class, and property. It's also the case that a property can be a method, just like an attribute can.

Maybe "data member" would be a more accurate term for a non-method/non-class attribute, but it feels to unpythonic to me (I associate the term more with statically-typed languages like C++).

After thinking about this for a bit, I'm inclined to stick with the terminology I have. It's not strictly correct, but I haven't been able to come up with an alternative I like better. I also think that it fits with the colloquial use of the term "attribute", although maybe that's just my perception.

On a related note, right now autoclasstoc groups descriptors in with methods, but I'm thinking now that that might have been a mistake. After all, descriptors have the same interface as attributes, so it would make more sense for them to be grouped together.

[funkyfuture]

i see your point regarding property.

i'd still object that your use of attribute is uncommonly narrow. also mind the builtins getattr, hasattr, setattr and AttributeError. and i find it misleading regarding sections.is_attribute and the contributed sections that rely on it.

On a related note, right now autoclasstoc groups descriptors in with methods, but I'm thinking now that that might have been a mistake. After all, descriptors have the same interface as attributes, so it would make more sense for them to be grouped together.

yep, that's exactly the question that got me started with this question. in docs i'd always separate callables and "data members" due to their distinct usage and purposes. at least for me, it is helpful when grasping an api that's new to me.

[kalekundert]

I looked around a little more, and I now think that "data attribute" is the most correct term, based on its usage in the stdlib docs here. I also found that autodoc uses .. attribute:: and :attr: to cross-reference data attributes, and there may be some value in staying consistent with that.

I think what I'll do is rename "attribute" to "data attribute" everywhere in sections.py and in the docs, with the exception that I'll keep the "public-attr/private-attr" section keys the same. This removes most of the ambiguity, and keeps the usage of "attr" in *.rst files consistent with autodoc.

[funkyfuture]

that is much clearer. i wouldn't consider anything from Sphinx as an authority when it comes to naming things though.