Clarify multiple function names in the tutorial

[xfq]

BPO	28681
Nosy	@rhettinger, @terryjreedy, @stevendaprano, @bitdancer, @xfq, @vedgar, @DimitrisJim, @miss-islington, @nanjekyejoannah
PRs	bpo-28681: Clarify multiple function names in the tutorial #21340 [3.9] bpo-28681: Clarify multiple function names in the tutorial (GH-21340) #21343 [3.8] bpo-28681: Clarify multiple function names in the tutorial (GH-21340) #21344
Files	renaming.patch: 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 = None
closed_at = <Date 2020-07-06.09:40:20.297>
created_at = <Date 2016-11-13.03:36:36.819>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Clarify multiple function names in the tutorial'
updated_at = <Date 2020-07-06.09:40:20.296>
user = 'https://github.com/xfq'

bugs.python.org fields:

activity = <Date 2020-07-06.09:40:20.296>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-07-06.09:40:20.297>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2016-11-13.03:36:36.819>
creator = 'xfq'
dependencies = []
files = ['45468']
hgrepos = []
issue_num = 28681
keywords = ['patch']
message_count = 12.0
messages = ['280683', '280686', '280687', '280688', '280691', '280705', '281154', '281199', '373057', '373060', '373064', '373065']
nosy_count = 10.0
nosy_names = ['rhettinger', 'terry.reedy', 'steven.daprano', 'r.david.murray', 'docs@python', 'xfq', 'veky', 'Jim Fasarakis-Hilliard', 'miss-islington', 'nanjekyejoannah']
pr_nums = ['21340', '21343', '21344']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28681'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[xfq]

In https://hg.python.org/cpython/file/6fbb7c9d77c6/Doc/tutorial/controlflow.rst#l295 :

A function definition introduces the function name in the
current symbol table. The value of the function name has a
type that is recognized by the interpreter as a user-defined
function. This value can be assigned to another name which
can then also be used as a function. This serves as a general
renaming mechanism

Maybe "aliasing" is a better term than "renaming" here, since the original function name can still be used after the "renaming".

[rhettinger]

+1 "Aliasing" is more accurate.

[stevendaprano]

I disagree that "aliasing" is more accurate.

We have a perfectly good name for symbols in Python: "name". A value (and that includes functions) can have multiple names. It seems to me that if we're to start distinguishing between names and aliases, then aliases have to be different from names. And the way I understand "alias" is that it is another symbol for a variable, not another symbol for the same value.

We wouldn't say that

    x = 1
    y = x

makes y an alias for x. y just happens to be a second name for the same value that x currently has. There's no guarantee that they will stay the same. Substitute a function object for the int 1, and you have the situation being discussed in the tutorial.

I would expect that aliases should not be effected by rebinding:

    x = 1
    y = alias(x)  # if such a thing existed
    x = 2
    assert y == 2

Obviously there's nothing in Python like that! This doesn't match Python's name binding model at all.

I think that talking about a "general aliasing" mechanism is exactly wrong. I think that the tutorial should emphasis the reality that functions are just ordinary values, like ints and floats and dicts and lists, and not try to indicate that there is something special or different about names bound to functions:

    def f(): ...
    g = f

is no different from the x = y example earlier.

[rhettinger]

To me, this is renaming:

     def f(x): pass
     f.__name__ = g

And this is aliasing:

     g = f

[stevendaprano]

And this is aliasing:
g = f

Is it only aliasing if you know that f is a function? I don't mean that
as a rhetorical question -- I'm asking if we're comfortable with the
idea of saying that g is an alias when f is (say) a float.

[bitdancer]

I would rewrite that paragraph as follows:

A function definition associates the function name with
the function object in the current symbol table. The
interpreter recognizes the object pointed to by that
name as a user-defined function. Other names can also
point to that same function object and can then also
be used as a function.

You will note that I've dropped the mention of renaming entirely, since the function does know it's __name__, and introducing that topic at this point in the tutorial would be confusing and unnecessary. (NB: one could also say "referenced" and "reference" rather than "pointed to" and "point to"; I'm not sure which is more in line with the rest of the tutorial).

[terryjreedy]

It took me a moment to realize that 'value of the function name' meant 'the function object associated with the name'. I think David's rewrite is a substantial improvement. I would just change the end 'can be used as a function' to 'can be used to access the function.'

'Renaming' is wrong to me because it implies invalidation of the previous name. 'Alternate name' is more accurate.

I agree that 'alias' is better, but also that it is a bit problematical*. 'Alias' is distinct from 'legal name'. The closest analogy to 'legal name' is 'definition name' (.__name__ attribute). But definition names are distinct from bound names, only some objects have definition names, and when they do, they can be renamed if and only if the object is coded in Python.

I don't understand the relevance of the middle sentence
"The interpreter recognizes the object pointed to by that
name as a user-defined function."
All objects can be given multiple names. In this context, the difference between C and Python coded names is whether the .__name__ attribute can be rebound, and that attribute is not part of the discussion here. The paragraph introduces this code example, which has nothing to do with .__name__.

   >>> fib
   <function fib at 10042ed0>
   >>> f = fib
   >>> f(100)
   0 1 1 2 3 5 8 13 21 34 55 89

(* Steven, I would say that both 'x' and 'y' in your example are aliases for the int 1. But I understand the other viewpoint.)

[vedgar]

Obligatory link: https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/ :-P
Yes, Python objects are simpler than people, but still not completely trivial. The core issue is "who does the calling".

Even one's native language might subtly (in Orwell sense) alter what they mean the name is. English question "What is your name?" is usually translated into Croatian (and some other Slavic languages) as "Kako se zoveš?", literally "how do you call yourself". In some other languages, it's "how should I call you". I think you agree those are three different concepts. And I think most disagreements between people in these discussions stem from those cultural differences. (Even people who consider English their native language might still have cultural differences, since English is spoken so widely.)

In Python, the most important distinction is "name as own identity"(1) vs "name as handle for calling"(2). Of course, we all know that each of these concepts have disadvantages, and as such, cannot serve completely. name(1) is not something all objects have (but e.g. functions and classes do), while name(2) is external to the object - each of existing namespaces might or might not have a way (or three, or infinitely many) to refer to it. And all those ways are not considered to be known to the object itself.

Since this concrete example speaks about names of functions defined with a def statement, those concepts coincide, and that's why some people have thought it speaks about name(1) and some others have thought it speaks about name(2). If we want to be completely honest, we should clarify that "name" is used in two ways, and that later text speaks only about name(2). But it might be too much for beginners. In that case, we should probably avoid mention name(1) sense until much later, and speak only of names as "name(2)".

[terryjreedy]

Vedran, thank you for the interesting cultural and linguistic perspective. In Spanish, "Como te llamas?" (familiar) "Como se llama?" (formal) literally translate as "What do you call yourself?" (want me to call you?). (I believe the latter could also be translated as "What are you called?", which you note is slightly different. I also know that addressing people by name is a more involved -- and dangerous-- subject in Japan than in America.

I think that David's rewrite is clear enough with the little change I suggested at the end, and have approved Joannah's PR with one little addition. Even if not perfect, it is definitely better than the current text.