Where are list methods documented?

[Grant Edwards]

I'm trying to figure out how to sort a list, and I've run into
a problem that that I have tripped over constantly for years:
where are the methods of basic types documented? The only
thing I can find on a list's sort() method is in the tutorial
where it states:

sort()
Sort the items of the list, in place.

Doesn't the list method would accept a callable to be used as a
comparison function? Where is that sort of thing in the
documentation? I've looking in the library reference, the
language reference, the global module index.

I have figured out I can do
[color=blue][color=green][color=darkred]
>>> list.sort.__doc __[/color][/color][/color]
'L.sort(cmpfunc =None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1'

--
Grant Edwards grante Yow! But they went to MARS
at around 1953!!
visi.com

[Tim Peters]

Re: Where are list methods documented?

[Grant Edwards][color=blue]
> I'm trying to figure out how to sort a list, and I've run into
> a problem that that I have tripped over constantly for years:
> where are the methods of basic types documented?[/color]

The methods on mutable sequence types are documented in the Library
manual's section on mutable sequence types:

http://docs.python.org/lib/typesseq-mutable.html

[color=blue]
> The only thing I can find on a list's sort() method is in the tutorial
> where it states:[/color]

You could have found the above by, e.g., looking up "sort" in the
Library manual's index.

[Brian van den Broek]

Re: Where are list methods documented?

Grant Edwards said unto the world upon 2005-02-01 12:21:[color=blue]
> I'm trying to figure out how to sort a list, and I've run into
> a problem that that I have tripped over constantly for years:
> where are the methods of basic types documented? The only
> thing I can find on a list's sort() method is in the tutorial
> where it states:
>
> sort()
> Sort the items of the list, in place.
>
> Doesn't the list method would accept a callable to be used as a
> comparison function? Where is that sort of thing in the
> documentation? I've looking in the library reference, the
> language reference, the global module index.
>
> I have figured out I can do
>
>[color=green][color=darkred]
>>>>list.sort._ _doc__[/color][/color]
>
> 'L.sort(cmpfunc =None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1'
>[/color]

Hi,

I'm not positive I understand what you are looking for, but do these
help?:

<http://www.python.org/doc/2.4/lib/built-in-funcs.html#l2h-15>
<http://www.python.org/doc/2.4/lib/typesseq.html>
<http://www.python.org/doc/2.4/lib/typesseq-mutable.html>

Best,
Brian vdB

[wes weston]

Re: Where are list methods documented?

Grant Edwards wrote:[color=blue]
> I'm trying to figure out how to sort a list, and I've run into
> a problem that that I have tripped over constantly for years:
> where are the methods of basic types documented? The only
> thing I can find on a list's sort() method is in the tutorial
> where it states:
>
> sort()
> Sort the items of the list, in place.
>
> Doesn't the list method would accept a callable to be used as a
> comparison function? Where is that sort of thing in the
> documentation? I've looking in the library reference, the
> language reference, the global module index.
>
> I have figured out I can do
>
>[color=green][color=darkred]
>>>>list.sort._ _doc__[/color][/color]
>
> 'L.sort(cmpfunc =None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1'
>[/color]
Grant,
For a quick, short doc string list: >>> help(list)
wes

[Grant Edwards]

Re: Where are list methods documented?

On 2005-02-01, Tim Peters <tim.peters@gma il.com> wrote:[color=blue]
> [Grant Edwards][color=green]
>> I'm trying to figure out how to sort a list, and I've run into
>> a problem that that I have tripped over constantly for years:
>> where are the methods of basic types documented?[/color]
>
> The methods on mutable sequence types are documented in the
> Library manual's section on mutable sequence types:
>
> http://docs.python.org/lib/typesseq-mutable.html[/color]
[color=blue]
> You could have found the above by, e.g., looking up "sort" in the
> Library manual's index.[/color]

I did. I looked up sort in the library index, and it took me
to 3.3.5 Emulating container types, which said:

Mutable sequences should provide methods append(), count(),
index(), extend(), insert(), pop(), remove(), reverse() and
sort(), like Python standard list objects.

I also looked at quite a few "list" links in the index.

I don't think it's at all obvious that the documentation for
list.sort would be under "mutable sequence object".

--
Grant Edwards grante Yow! YOW!! Everybody out
at of the GENETIC POOL!
visi.com

[Grant Edwards]

Re: Where are list methods documented?

On 2005-02-01, Brian van den Broek <bvande@po-box.mcgill.ca> wrote:
[color=blue]
> I'm not positive I understand what you are looking for, but do these
> help?:
>
><http://www.python.org/doc/2.4/lib/built-in-funcs.html#l2h-15>
><http://www.python.org/doc/2.4/lib/typesseq.html>
><http://www.python.org/doc/2.4/lib/typesseq-mutable.html>[/color]

Yes, that last page was the one I was looking for. I didn't
know enough to spell list as "mutable sequence type".

--
Grant Edwards grante Yow! I think my CAREER
at is RUINED!!
visi.com

[Thomas Heller]

Re: Where are list methods documented?

Grant Edwards <grante@visi.co m> writes:
[color=blue]
> On 2005-02-01, Brian van den Broek <bvande@po-box.mcgill.ca> wrote:
>[color=green]
>> I'm not positive I understand what you are looking for, but do these
>> help?:
>>
>><http://www.python.org/doc/2.4/lib/built-in-funcs.html#l2h-15>
>><http://www.python.org/doc/2.4/lib/typesseq.html>
>><http://www.python.org/doc/2.4/lib/typesseq-mutable.html>[/color]
>
> Yes, that last page was the one I was looking for. I didn't
> know enough to spell list as "mutable sequence type".
>
> --
> Grant Edwards grante Yow! I think my CAREER
> at is RUINED!!
> visi.com[/color]

You could also have typed 'sort' in the box here:

http://starship.python.net/crew/theller/pyhelp.cgi

This search is also available in Mark Hammond's Mozilla Python sidebar.

Thomas

[Tim Peters]

Re: Where are list methods documented?

[Tim Peters][color=blue][color=green]
>> You could have found the above by, e.g., looking up "sort" in the
>> Library manual's index.[/color][/color]

[Grant Edwards][color=blue]
> I did. I looked up sort in the library index, and it took me
> to 3.3.5 Emulating container types,[/color]

It doesn't for me. Here:

http://docs.python.org/lib/genindex.html#letter-s

There are two entries for "sort":

sort (IMAP4_stream method)
sort (list method)

You're looking for the second one <wink>.

....[color=blue]
>
> I don't think it's at all obvious that the documentation for
> list.sort would be under "mutable sequence object".[/color]

I was just answering your question ("where are the docs?"), not trying
to imply you were an idiot for not guessing that.

You could have gotten to the same place in several ways. Another
would have been to look up "list" in the Library index, and click on

list
type, operations on

For good or ill, the Library manual takes a rather abstract view of
the types currently implemented, as reflected in its table of
contents:

2. Built-In Objects
2.1 Built-in Functions
2.2 Non-essential Built-in Functions
2.3 Built-in Types
2.3.1 Truth Value Testing
2.3.2 Boolean Operations
2.3.3 Comparisons
2.3.4 Numeric Types
2.3.5 Iterator Types
2.3.6 Sequence Types
2.3.7 Set Types
2.3.8 Mapping Types
2.3.9 File Objects
2.3.10 Other Built-in Types
2.3.11 Special Attributes
2.4 Built-in Exceptions
2.5 Built-in Constants

So, e.g., it doesn't mention floats or dicts by those names either.
It's well worthwhile to spend some time browsing that entire chapter.

[Grant Edwards]

Re: Where are list methods documented?

On 2005-02-01, Tim Peters <tim.peters@gma il.com> wrote:
[color=blue]
> [Grant Edwards][color=green]
>> I did. I looked up sort in the library index, and it took me
>> to 3.3.5 Emulating container types,[/color]
>
> It doesn't for me. Here:
>
> http://docs.python.org/lib/genindex.html#letter-s
>
> There are two entries for "sort":
>
> sort (IMAP4_stream method)
> sort (list method)
>
> You're looking for the second one <wink>.[/color]

Aargh. My bad. I was in the language reference index. I seem
to have a very hard time ending up in the document I'm trying
for. For some reason, I fairly consistently click on the wrong
link in the document index. :(

--
Grant Edwards grante Yow! I'm definitely not
at in Omaha!
visi.com

[Aahz]

Re: Where are list methods documented?

In article <r7k0f8sm.fsf@p ython.net>,
Thomas Heller <theller@python .net> wrote:[color=blue]
>
>You could also have typed 'sort' in the box here:
>
>http://starship.python.net/crew/theller/pyhelp.cgi
>
>This search is also available in Mark Hammond's Mozilla Python sidebar.[/color]

....and as a link from python.org's documentation pages.
--
Aahz (aahz@pythoncra ft.com) <*> http://www.pythoncraft.com/

"Given that C++ has pointers and typecasts, it's really hard to have a serious
conversation about type safety with a C++ programmer and keep a straight face.
It's kind of like having a guy who juggles chainsaws wearing body armor
arguing with a guy who juggles rubber chickens wearing a T-shirt about who's
in more danger." --Roy Smith, c.l.py, 2004.05.23

[Nick Craig-Wood]

Re: Where are list methods documented?

Tim Peters <tim.peters@gma il.com> wrote:[color=blue]
> You could have gotten to the same place in several ways.[/color]
[snip]

Since I'm a unix person, I would have typed

pydoc -k sort

But it doesn't come up with anything useful :-(

$ pydoc -k sort
MySQLdb.stringt imes - Use strings to handle date and time columns as a last resort.

....

In fact I've never had any luck with pydoc -k. I think what it
searches through is too narrow - from its man page

Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines
of all available modules.

This is the NAME line that appears in pydoc I think.

If it did a full text search that would be much more useful, or at
least a search through all the names of the functions & variables that
are exported.

....

My top wish for pydoc is to have the rest of the documentation in it!
Each module has lots of nice documentation which is only available in
HTML format - I'd much rather type "pydoc whatever" to see it all,
rather than have to load my browser, and click through several layers
of web pages.

--
Nick Craig-Wood <nick@craig-wood.com> -- http://www.craig-wood.com/nick

[Timothy Fitz]

Re: Where are list methods documented?

[Tim Peters][color=blue]
> The methods on mutable sequence types are documented in the Library
> manual's section on mutable sequence types:
>
> http://docs.python.org/lib/typesseq-mutable.html
>[/color]

And like -many- python programmers, when he thinks "List" he doesn't
immediately think "Mutable Sequence Type." The title should stay but
perhaps the tutorial should be updated to point people in the right
direction when they're "done" and need to know specifics? (This link
of the documentation was non-obvious to me also)

[Timothy Fitz]

Re: Where are list methods documented?

[Tim Peters][color=blue]
> The methods on mutable sequence types are documented in the Library
> manual's section on mutable sequence types:
>
> http://docs.python.org/lib/typesseq-mutable.html
>[/color]

And like -many- python programmers, when he thinks "List" he doesn't
immediately think "Mutable Sequence Type." The title should stay but
perhaps the tutorial should be updated to point people in the right
direction when they're "done" and need to know specifics? (This link
of the documentation was non-obvious to me also)

[Nick Coghlan]

Re: Where are list methods documented?

Tim Peters wrote:[color=blue]
> 2. Built-In Objects
> 2.1 Built-in Functions
> 2.2 Non-essential Built-in Functions
> 2.3 Built-in Types
> 2.3.1 Truth Value Testing
> 2.3.2 Boolean Operations
> 2.3.3 Comparisons
> 2.3.4 Numeric Types
> 2.3.5 Iterator Types
> 2.3.6 Sequence Types
> 2.3.7 Set Types
> 2.3.8 Mapping Types
> 2.3.9 File Objects
> 2.3.10 Other Built-in Types
> 2.3.11 Special Attributes
> 2.4 Built-in Exceptions
> 2.5 Built-in Constants
>
> So, e.g., it doesn't mention floats or dicts by those names either.
> It's well worthwhile to spend some time browsing that entire chapter.[/color]

I wonder if adding a small table to the end of the introductory text in Section
2.3 would help. Something like:

""""
The documentation in this section is written in terms of type categories. The
table below associates specific builtin types with the most relevant categories.

Type Category Specific Built-in Types
Boolean bool
Numeric int, long, float, complex
Iterator N/A
Sequence tuple
String Sequence str, unicode
Mutable Sequence list
Set set, frozenset
Mapping dict
File file
"""

Cheers,
Nick.

--
Nick Coghlan | ncoghlan@email. com | Brisbane, Australia
---------------------------------------------------------------

http://boredomandlaziness.skystorm.net

[Skip Montanaro]

Re: Where are list methods documented?


Grant> where are the methods of basic types documented?

The other day I suggested the most valuable doc page to bookmark is the
global module index. Here's a demonstration. Start at:

http://www.python.org/dev/doc/devel/modindex.html

Click "__builtin_ _", which takes you to

http://www.python.org/dev/doc/devel/lib/module-builtin.html

Click the "2" in "See Chapter 2", which takes you to

http://www.python.org/dev/doc/devel/lib/builtin.html#builtin

Scroll down to section 2.3.6 and choose your sequence poison.

I use the dev docs instead of the latest release docs because I generally
run from CVS on my system, however in this case it has the added advantage
that the link on the __builtin__ page is more useful.

Skip