An attribute is a variable that is looked up on another object using dot syntax: obj.attribute
. The way Python is designed, attribute lookups can do a variety of things, and that variety can sometimes lead to bugs if you don't really understand what is happening (this is what the documentation you linked to warns about).
The most basic issue is that an attribute lookup can find either a value stored in the object's instance dictionary, or it can find something from the object's class (or a base class, if there's inheritance going on). Methods are functions stored in the class, but you usually use them by looking them up on an instance (which "binds" the method, inserting the object as the first arguemnt when the method is called).
The exact sequence of what is checked when is a bit complicated (I described the full process in an answer to another question), but at the most basic level, instance attributes usually take precedence over class attribute.
If an instance attribute and a class attribute with the same name both exist, usually only the instance attribute will be accessible. This can be very confusing if it is unintended.
Consider the following code:
class Foo(object):
def __init__(self, lst):
self.lst = lst
def sum(self):
self.sum = sum(self.lst)
return self.sum
f = Foo([1,2,3])
print(f.sum())
print(f.sum())
At the bottom of this code, we make two identical calls. The first works just fine, but the second will raise an exception.
This is because the first time we look up f.sum
we find a method in the Foo
class. We can call the method with no problems. The trouble comes from the fact that the sum
method assigns the result of its calculation (the sum of the elements in self.lst
) to an instance attribute also named sum
. This hides the sum
method from view.
When second f.sum()
call looks up f.sum
, it finds the instance attribute, containing the integer 6
, rather than the expected method. An integer is not callable, so we get an exception.
The solution, of course, is not to use the same name for the method and attribute. The code above is a pretty trivial example. The bugs caused by this sort of thing in more complex code can be much more difficult to figure out.
If you're writing code that adds attributes to objects you don't know much about, you should be careful to avoid common names. If you're writing a mixin class, consider using two leading underscores in the attribute names to trigger Python's name mangling, which is designed for exactly this sort of situation.
Addendum: It's also possible that the distinction the documentation is trying to make is between data and non-data descriptors. Methods are the most common kind of non-data descriptor, so it might make a degree of sense to call them "method attributes" (especially in contrast to "data attributes" which would be the corresponding name for data descriptors), though I'm not aware of that language being used more widely. The important difference between the two kinds of descriptors is that data descriptors (like property
) get processed before the instance dictionary is checked for an ordinary instance variable. As discussed above, non-data descriptors like methods get processed only after the instance dictionary is checked, so they can be shadowed by data stored on the instance.