list(),tuple() should not place at "Built-in functions" in documentation

[Inside]

As telling in the subject,because "list" and "tuple" aren't functions,they are types.Is that right?

 

[Steven D'Aprano]

As telling in the subject,because "list" and "tuple" aren't functions,they
are types.Is that right?

Yes they are types. But they can still be used as functions. Does it matter?

 

[rantingrick]

As telling in the subject,because "list" and "tuple" aren't functions,they are types.Is that right?

You wanna see some warts in the docs. Okay, try to use the search box
to find list, dict, or tuple and see what happens...

http://docs.python.org/

Search: [ list ]

PyFloat_ClearFreeList (cfunction, in Floating Point Objects)
PyInt_ClearFreeList (cfunction, in Plain Integer Objects)
PyListObject (ctype, in List Objects)
PyList_Append (cfunction, in List Objects)
PyList_AsTuple (cfunction, in List Objects)
PyList_Check (cfunction, in List Objects)
PyList_CheckExact (cfunction, in List Objects)
PyList_GET_ITEM (cfunction, in List Objects)
PyList_GET_SIZE (cfunction, in List Objects)
PyList_GetItem (cfunction, in List Objects)
PyList_GetSlice (cfunction, in List Objects)
PyList_Insert (cfunction, in List Objects)
PyList_New (cfunction, in List Objects)
PyList_Reverse (cfunction, in List Objects)
PyList_SET_ITEM (cfunction, in List Objects)
PyList_SetItem (cfunction, in List Objects)
PyList_SetSlice (cfunction, in List Objects)
PyList_Size (cfunction, in List Objects)
PyList_Sort (cfunction, in List Objects)
PyList_Type (cvar, in List Objects)
PyMethod_ClearFreeList (cfunction, in Method Objects)

[ snip: mile long list with no LIST info to be found! ]

Hey don't get me wrong, the python docs are great; as long as you know
where to find what you're looking for.

 

[Corey Richardson]

Excerpts from rantingrick's message of Thu Jul 14 21:36:15 -0400 2011:

As telling in the subject,because "list" and "tuple" aren't functions,they are types.Is that right?

You wanna see some warts in the docs. Okay, try to use the search box
to find list, dict, or tuple and see what happens...

http://docs.python.org/

Search: [ list ]

PyMethod_ClearFreeList (cfunction, in Method Objects)

[ snip: mile long list with no LIST info to be found! ]

Hey don't get me wrong, the python docs are great; as long as you know
where to find what you're looking for.

I agree, having the stuff from the C API docs appear in the search isn't
very useful. Perhaps the search should be redesigned with stuff like that
in mind? (Or maybe the search is more advanced than I use it). They aren't
exactly warts, it's useful information, but in the common case they probably
aren't desired (I always use Google to search around the python docs).

Not to mention that the search is slooowwww. It's plenty fast on my local
download, but I haven't actually looked at the search to see what it does
and how.
--
Corey Richardson
"Those who deny freedom to others, deserve it not for themselves"
-- Abraham Lincoln

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)

iQEcBAEBCAAGBQJOH5+JAAoJEAFAbo/KNFvph6MH/123dtVlaqpszJN4LG1LviEh
V5GgBI8MkqPK+yZ7DAcXcRPKxrBXR2lES0lcF/4jf+DT4ZXEoM2FM04ahskeNtf2
EgTMow/tw6gdRZw6QrDsmJyySesFoagRiA896oSaYrGzbe4KjYeptX+XPQCs4zdL
AYaR5w2dVNhs49gHWqJ8aeVHkAc35SSRcIfHkLgrz67O783UgsJppEQQUXshGzLt
GRyqtemszFGdXorm+1PVf37s4cmfI+neD6/kz9IKxcoBjt564LpphQ9EYWhZaClj
RzhPJb1TzTAnpaIEZepKtL9gHFiIuvYTyFfyiYsJ5lc0hUtwz9bvMQUqj70t2sk=
=DDLx
-----END PGP SIGNATURE-----

 

[Terry Reedy]

At one time (before 2.2), they were functions and not classes.

As a newcomer to the documentation I looked fruitlessly in the table of
contents for a section that would contain the built-in types. “Built-in
functions†was eliminated for the reason the OP states.

I think it matters. (But I haven't proposed a documentation patch for it.)

I once proposed, I believe on the tracker, that 'built-in functions' be
expanded to 'built-in function and classes'. That was rejected on the
basis that people would then expect the full class documentation that is
in the 'built-in types' section (which could now be called the
built-isssn classes section.

A more exact title would be 'built-in callables', but that would be even
less helpful to newcomers. Callables are functions in the generic sense.

In any case, the new index makes it easy to see what is in that chapter.

 

[Chris Angelico]

Yes they are types. But they can still be used as functions. Does it matter?

Python is duck-typed, even in its documentation. If Python describes
something as a function, it means it can be used in place of func in
here:

result = func(arg1, arg2, arg3)

It might be something created with def (a "classic" function). It
might be something created with lambda. It might be an object with a
__call__ method. It might be a type.
def __call__(self):
return lambda: print("asdf")
asdf

How many functions are defined here?

Chris Angelico

 

[Stefan Behnel]

Terry Reedy, 15.07.2011 05:00:

At one time (before 2.2), they were functions and not classes.

They are still functions in the sense that you can call them (with or
without arguments) and get a result back. The exact distinction can be
considered an implementation detail in most contexts.

There are even extreme cases that render the distinction completely
useless. Think of type(), for example. In its exceedingly most common use
case, it does *not* create a type, even if it's a call to a type
constructor. Something similar applies to a no-args call to tuple(), which
does not create a new object in CPython, but only returns a new reference
to a singleton.

Types in Python are allowed to do these things, so it's not always
meaningful to distinguish between typeX() being a call to a type or a function.

I once proposed, I believe on the tracker, that 'built-in functions' be
expanded to 'built-in function and classes'. That was rejected on the basis
that people would then expect the full class documentation that is in the
'built-in types' section (which could now be called the built-isssn classes
section.

A more exact title would be 'built-in callables', but that would be even
less helpful to newcomers. Callables are functions in the generic sense.

I think "function" is about the best "expected" and "newcomer-friendly"
name one can give to a "callable", especially in the context of a
duck-typed, protocol-oriented language like Python. The section title in
question describes perfectly its contents.

It's a different question if a separate section like "here's a list of
reference to the descriptions of types that Python provides in its
builtins" is required. But I think we have that already.

In any case, the new index makes it easy to see what is in that chapter.

Agreed.

Stefan

 

[Raymond Hettinger]

As telling in the subject,because "list" and "tuple" aren't functions,they are types.Is that right?

list() and tuple() are in the right place in the documentation because
they would be harder to find if listed elsewhere. Tools like str(),
int(), list(), tuple() etc tend to be used like functions, so the
current location in the docs is where they have been for years.

A simple fact of documentation that is that tools don't always fall
cleanly into distinct categories. Accordingly, the Library Reference
includes str,int,list,tuple, etc in both Section 2 for builtin
functions and Section 5 for builtin types.

'nuff said,


Raymond

 

[Terry Reedy]

They are not instances of a class whose definition name includes the
word 'Function'. They *are* things that can be called with the call
operator () (because they have __call__ methods) and that, when called,
map input objects to output objects. That is the mathematical notion of
a function. It is also one thing that makes classes different from
modules, which cannot be called. Classes *also* have other behaviors
that functions do not, but that does not make them non-functions. Doing
things besides programming Python does not make one not a Python programmer.

list() and tuple() are in the right place in the documentation
because they would be harder to find if listed elsewhere. Tools
like str(), int(), list(), tuple() etc tend to be used like
functions, so the current location in the docs is where they have
been for years.

The location of anything (that is not missing from the index, which is a
bug) is easily discovered using the index.

A simple fact of documentation that is that tools don't always fall
cleanly into distinct categories.

This is more like a fact of life above the atomic level. As the number
of things classified grows, most classifications tend to become
controversial.

Accordingly, the Library Reference
includes str,int,list,tuple, etc in both Section 2 for
builtin functions and Section 5 for builtin types.

Chapter 5 is mostly about the behavior of built-in class instances. For
some classes, like range, instances only come from class calls and the
behavior of instances is intimately tied to the constructor arguments.
Having the constructor described in C.5 might be useful. For others,
like int, instances come from many sources and the behavior of instances
only depends on the resulting value and not the source. Ints can come
from literals, computation, and int calls with int, other number, or
string objects. The allowed argument issues for int calls are quite
separate from using int, so it really belongs in C.2.

I agree that it is best to list all named built-in classes in C.2 with
appropriates links to C.5 (and v.v.). There is a current tracker issue
to add the few links that are missing from C.2 to C.5.

 

[Stefan Behnel]

Terry Reedy, 19.07.2011 18:31:

Chapter 5 is mostly about the behavior of built-in class instances. For
some classes, like range, instances only come from class calls and the
behavior of instances is intimately tied to the constructor arguments.
Having the constructor described in C.5 might be useful.

I strongly disagree. To me, range() being implemented as a class or
function is a clear implementation detail that is of no importance to
virtually all use cases. It's only ever used as a function that returns a
list (in Py2) or something iterable (in Py3). Whether that "iterable" is of
type "range" or not is irrelevant. Even in Py2, it could return a subtype
of list, and would still fulfil its interface.

So, IMO, it makes no sense to have range() described in the builtin types
section. It would rather be confusing. It's perfectly correct and
sufficient to describe it in the builtin functions section.

Remember that Python is duck-typed. It makes no difference if you call a
function that returns a new instance of a type, or the type itself to
return an instance of itself (or something completely different, if it
wants to).

The distinction between types and functions is blurred in Python, and
that's a good thing. Just look at the itertools module. Some of the
"functions" are implemented as functions, some are implemented as types,
and some are functions that delegate to a type. But they all have the same
interface, which makes them easy to understand as a whole and which keeps
the implementation details out of the way.

Stefan

 

[Terry Reedy]

Terry Reedy, 19.07.2011 18:31:

I strongly disagree.

Wow. Strongly disagreeing with a mild statement like 'might be useful'
is really strong. But let me explain (using slice rather than range).
Three of the four non-special attributes of the slice objects produced
by the slice() function are the three arguments of the function. (The
fourth is an obscure method.) So the function and its result object are
closely tied together, and unusually so. Hence it *might* be useful to
discuss that particular pair together, especially since both are used
rarely and always together. This is a rather minimal concession to the OP.

But the overall thrust and conclusion of both that post of mine and the
previous one is that 'function' in 'built-in functions' is best
understood generically as including objects of type 'type' as well as
objects of 'builtin_function_or_method' (and any other built-in callable
if there happen to be any). So the rest of your post is strong agreement
with what I have said since the beginning of the thread.

What one needs to know about range is that it produces a non-iterator
re-iterable virtual sequence object that supports a basic subset of the
sequence operations. The function belongs in the function chapter and
the sequence object in the sequence section of the classes chapter.

The OP's point makes more sense in the context of other languages that
make an artificial distinction between functions and constructors and
require that the latter be preceded by keyword new. I prefer Python's
uniformity.