Classes tutorial: confusing explanation of non-instance methods

[deuberger]

Documentation

From https://docs.python.org/3/tutorial/classes.html#instance-objects:

The other kind of instance attribute reference is a method. A method is a function that “belongs to” an object. (In Python, the term method is not unique to class instances: other object types can have methods as well. For example, list objects have methods called append, insert, remove, sort, and so on. However, in the following discussion, we’ll use the term method exclusively to mean methods of class instance objects, unless explicitly stated otherwise.)

From the user's perspective, a list is a class in Python 3. It may be implemented under the hood using some special construct, but in all the documentation and to the user, it is still a class. So an a list object is a class instance for all intents and purposes even if it's really not under the hood.

I suggest reworking this paragraph to clarify whatever it's trying to communicate or deleting it except the first 2 sentences.

A potential reworked version is below, but I'm not sure it wouldn't still be confusing to someone new.

The other kind of instance attribute reference is a method. A method is a function that “belongs to” an object. (Note that technically, there are different types of methods in python - see https://docs.python.org/3/library/stdtypes.html#methods for more details. However, in the following discussion, we’ll use the term method exclusively to mean methods of class instance objects, unless explicitly stated otherwise.)

Note that part of the confusion might be because the tutorial doesn't really explain about bound methods. Note that the following section 9.3.4 mentions a method being "bound" without the terminology ever being explained.

Is the distinction between built-in and instance methods even necessary at this point especially in higher level docs like the tutorial?

Linked PRs

• gh-119016: Remove outdated sentences from the "classes" tutorial #119130
• [3.13] gh-119016: Remove outdated sentences from the "classes" tutorial (GH-119130) #119925
• [3.12] gh-119016: Remove outdated sentences from the "classes" tutorial (GH-119130) #119926

[eendebakpt]

Maybe the confusion is due to the interpretation of "list object". If I read the documentation it seems like "list object" refers to the builtin list, but not to the instantiation of a list. For example:

x=[]
list.append(x, 2) # here append is a method of the list object. but list is not a class instance
print(x)
x.append(3) # here append is a method of the list instance "x"
print(x)

The documentation is then confusing because there is only one list. So perhaps

For example, list objects have methods called append, insert ...

should be rewritten to

For example, the builtin list object has methods called append, insert ...

Making the distinction between instance methods and non-instance methods is relevant for the part that describes method objects, in particular the part In general, methods work as follows. When ... is only valid for method objects (e.g. on in instance, and not on a class)

[deuberger]

Thanks @eendebakpt.

I've dug deeper into this and actually I think the root issue is that A method is a function that “belongs to” an object. is confusing and not actually true for Python. If this were true, then all functions would be methods because all functions belong to a module or a class which are both also objects. A closer reading of https://docs.python.org/3/reference/datamodel.html and https://docs.python.org/3/library/types.html suggests that there are really only two types of methods in Python: instance methods and built-in methods. Both behave the same from the user perspective, but are implemented differently. Also, the former is of type types.MethodType whereas the latter is of types.BuiltinMethodType (which is in alias for types.BuiltinFunctionType).
From the second link regarding built-in methods:

This is really a different disguise of a built-in function, this time containing an object passed to the C function as an implicit extra argument. An example of a built-in method is alist.append(), assuming alist is a list object. In this case, the special read-only attribute self is set to the object denoted by alist. (The attribute has the same semantics as it does with other instance methods.)

So in Python, "method" refers to instance attribute used to call the associated function on the instance whether the type is user-defined or built-in. The implementation differs slightly and aspects of these differences are visible to the user so the docs in question only address "instance methods" meaning functions belonging to an instance of a user-defined class (meaning defined in Python rather than C).

Note that class methods are a actually a special case of instance methods. Static methods may be implemented similarly (in pure python), but the docs seem to indicate they are in CPython and in any case to the user it looks like they are a regular unbounded function. Additional details at https://docs.python.org/3/howto/descriptor.html#kinds-of-methods.

So I propose the following:

The other kind of instance attribute reference is a method. In the following discussion, we’ll use the term method exclusively to mean methods of class instance objects, unless explicitly stated otherwise. (In other words, we are not referring to built-in methods such as alist.append where alist is a list object.)

[AlexWaygood]

My analysis of the original intention of this paragraph is slightly different. I don't think it was intended to point out the difference between user-defined methods and methods of builtin types. See my comment at #119130 (comment).

[AlexWaygood]

Thanks for the report @deuberger! We've removed the confusing sentences from the docs in the main branch, and I've scheduled automerge on the backport PRs.