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
'L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1'

 

[Tim Peters]

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

The only thing I can find on a list's sort() method is in the tutorial
where it states:

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

 

[Brian van den Broek]

Grant Edwards said unto the world upon 2005-02-01 12:21:

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



'L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1'

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]

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



'L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1'

Grant,
For a quick, short doc string list: >>> help(list)
wes

 

[Grant Edwards]

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

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

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]

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>

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

 

[Thomas Heller]

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

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]

[Tim Peters]
[Grant Edwards]

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

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

....

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

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]

[Grant Edwards]

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

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

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.

 

[Aahz]

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.

....and as a link from python.org's documentation pages.
--
Aahz ([email protected]) <*> 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]

You could have gotten to the same place in several ways.

[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.stringtimes - 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.

 

[Timothy Fitz]

[Tim Peters]

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

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]

[Tim Peters]

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

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]

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.

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.

 

[Skip Montanaro]

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

 

[Hans Nowak]

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

pydoc -k sort

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

FYI, you can get this info using the not-very-intuitive

pydoc __builtin__.list.sort

e.g.

(C:\Python23\Lib) $ pydoc __builtin__.list.sort
Help on method_descriptor in __builtin__.list:

__builtin__.list.sort = sort(...)
L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) ->
-1, 0, 1

(Rather terse...)

Info on the sort function (together with all the other list methods) is
also available if you do

pydoc list

....but for some reason, "pydoc list.sort" doesn't work on my machine
(Python 2.3.4, Windows XP).

 

[Bryan]

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

wow, that's pretty obscure. i barely even saw the link to chapter 2. i always
the modules index page open and i always wished there was an explicit link to
lists, tuples, dict, set, etc. maybe these explicit links could be at the top
of the __builtins__ page.

bryan

 

[Dennis Lee Bieber]

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.

Read the language reference once, then forget it exists <G>

The Python language, itself, is so small you should seldom need
the language reference. After all, how often do you need to look up the
syntax for def, class, try/except... <G>

Practically all the details of what can be done with data hides
in the library manual.

--

 

[Nelson Minar]

You're not the only one with a hard time finding the list
documentation. It's even crazier for string docs.

If you want to see how to strip strings in Python you have to go to
the library docs, then click "sequence types" (betcha don't think of
strings as sequences), then scroll to the bottom, then click "String
Methods", then scroll to find "strip()". This makes perfect sense if
you understand that strings are "mutable sequences". But if you're
coming from (say) Perl and are looking for the quick way to work with
strings, it's pretty deeply buried.

A simple internal link or two would help a lot. Say, something in
"built-in functions" which says "see also..."

 

[Terry Reedy]

You're not the only one with a hard time finding the list
documentation. It's even crazier for string docs.

To repeat the advice I gave someone asking about dict methods:

Read or at least skim thru chapter 2 of the Library Reference Manual on
builtin functions and types so you have a general idea of what is where.
And either before or after, look at the table of contents for general
organization and index availability

Terry J. Reedy