Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #9496 > unrolled thread

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

Back to article view | Back to comp.lang.python

Contents

  list(),tuple() should not place at "Built-in functions" in documentation Inside <fancheyujian@gmail.com> - 2011-07-14 18:21 -0700
    Re: list(),tuple() should not place at "Built-in functions" in documentation Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-07-15 11:32 +1000
      Re: list(),tuple() should not place at "Built-in functions" in documentation Ben Finney <ben+python@benfinney.id.au> - 2011-07-15 11:51 +1000
        Re: list(), tuple() should not place at "Built-in functions" in documentation Terry Reedy <tjreedy@udel.edu> - 2011-07-14 23:00 -0400
        Re: list(), tuple() should not place at "Built-in functions" in documentation Stefan Behnel <stefan_ml@behnel.de> - 2011-07-15 23:03 +0200
      Re: list(), tuple() should not place at "Built-in functions" in documentation Chris Angelico <rosuav@gmail.com> - 2011-07-15 16:24 +1000
    Re: list(),tuple() should not place at "Built-in functions" in documentation rantingrick <rantingrick@gmail.com> - 2011-07-14 18:36 -0700
      Re: list(), tuple() should not place at "Built-in functions" in documentation Corey Richardson <kb1pkl@aim.com> - 2011-07-14 22:01 -0400
    Re: list(),tuple() should not place at "Built-in functions" in documentation Raymond Hettinger <python@rcn.com> - 2011-07-18 23:52 -0700
      Re: list(), tuple() should not place at "Built-in functions" in documentation Terry Reedy <tjreedy@udel.edu> - 2011-07-19 12:31 -0400
      Re: list(), tuple() should not place at "Built-in functions" in documentation Stefan Behnel <stefan_ml@behnel.de> - 2011-07-20 08:21 +0200
      Re: list(), tuple() should not place at "Built-in functions" in documentation Terry Reedy <tjreedy@udel.edu> - 2011-07-20 16:53 -0400

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

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

[toc] | [next] | [standalone]

#9497

Inside wrote:

> 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?


-- 
Steven

[toc] | [prev] | [next] | [standalone]

#9499

Steven D'Aprano <steve+comp.lang.python@pearwood.info> writes:

> Inside wrote:
>
> > 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?

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.)

-- 
 \       “But Marge, what if we chose the wrong religion? Each week we |
  `\          just make God madder and madder.” —Homer, _The Simpsons_ |
_o__)                                                                  |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#9502 — Re: list(), tuple() should not place at "Built-in functions" in documentation

On 7/14/2011 9:51 PM, Ben Finney wrote:
> Steven D'Aprano<steve+comp.lang.python@pearwood.info>  writes:
>
>> Inside wrote:
>>
>>> As telling in the subject,because "list" and "tuple" aren't functions,they
>>> are types.Is that right?

At one time (before 2.2), they were functions and not classes.
>>
>> Yes they are types. But they can still be used as functions. Does it matter?
>
> 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.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#9568 — Re: list(), tuple() should not place at "Built-in functions" in documentation

Terry Reedy, 15.07.2011 05:00:
> On 7/14/2011 9:51 PM, Ben Finney wrote:
>> Steven D'Aprano writes:
>>
>>> Inside wrote:
>>>
>>>> As telling in the subject,because "list" and "tuple" aren't functions,they
>>>> are types.Is that right?
>
> 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.


>>> Yes they are types. But they can still be used as functions. Does it
>>> matter?
>>
>> 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.

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

[toc] | [prev] | [next] | [standalone]

#9509 — Re: list(), tuple() should not place at "Built-in functions" in documentation

On Fri, Jul 15, 2011 at 11:32 AM, Steven D'Aprano
<steve+comp.lang.python@pearwood.info> wrote:
> Inside wrote:
>
>> 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?

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.

>>> class foo:
	def __call__(self):
		return lambda: print("asdf")

>>> bar=foo()
>>> quux=bar()
>>> quux()
asdf

How many functions are defined here?

Chris Angelico

[toc] | [prev] | [next] | [standalone]

#9498

On Jul 14, 8:21 pm, Inside <fancheyuj...@gmail.com> wrote:
> 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.

[toc] | [prev] | [next] | [standalone]

#9500 — Re: list(), tuple() should not place at "Built-in functions" in documentation

[Multipart message — attachments visible in raw view] — view raw

Excerpts from rantingrick's message of Thu Jul 14 21:36:15 -0400 2011:
> On Jul 14, 8:21pm, Inside <fancheyuj...@gmail.com> wrote:
> > 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

[toc] | [prev] | [next] | [standalone]

#9860

On Jul 14, 6:21 pm, Inside <fancheyuj...@gmail.com> wrote:
> 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

[toc] | [prev] | [next] | [standalone]

#9886 — Re: list(), tuple() should not place at "Built-in functions" in documentation

On 7/19/2011 2:52 AM, Raymond Hettinger wrote:
> On Jul 14, 6:21 pm, Inside<fancheyuj...@gmail.com>  wrote:
>> As telling in the subject,because "list" and "tuple" aren't
>> functions,they are types.Is that right?

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.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#9938 — Re: list(), tuple() should not place at "Built-in functions" in documentation

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

[toc] | [prev] | [next] | [standalone]

#9991 — Re: list(), tuple() should not place at "Built-in functions" in documentation

On 7/20/2011 2:21 AM, Stefan Behnel wrote:
> 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.

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.

-- 
Terry Jan Reedy

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web