467,075 Members | 997 Online
Bytes | Developer Community
Ask Question

Home New Posts Topics Members FAQ

Post your question to a community of 467,075 developers. It's quick & easy.

Where are list methods documented?

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
list.sort.__doc__

'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
Jul 18 '05 #1
  • viewed: 1913
Share:
17 Replies
[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.
Jul 18 '05 #2
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

list.sort.__doc__


'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
Jul 18 '05 #3
Grant Edwards wrote:
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

list.sort.__doc__


'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

Jul 18 '05 #4
On 2005-02-01, Tim Peters <ti********@gmail.com> wrote:
[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 grante Yow! YOW!! Everybody out
at of the GENETIC POOL!
visi.com
Jul 18 '05 #5
On 2005-02-01, Brian van den Broek <bv****@po-box.mcgill.ca> wrote:
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".

--
Grant Edwards grante Yow! I think my CAREER
at is RUINED!!
visi.com
Jul 18 '05 #6
Grant Edwards <gr****@visi.com> writes:
On 2005-02-01, Brian van den Broek <bv****@po-box.mcgill.ca> wrote:
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".

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


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
Jul 18 '05 #7
[Tim Peters]
You could have found the above by, e.g., looking up "sort" in the
Library manual's index.

[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.
Jul 18 '05 #8
On 2005-02-01, Tim Peters <ti********@gmail.com> wrote:
[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. :(

--
Grant Edwards grante Yow! I'm definitely not
at in Omaha!
visi.com
Jul 18 '05 #9
In article <r7**********@python.net>,
Thomas Heller <th*****@python.net> wrote:

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 (aa**@pythoncraft.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
Jul 18 '05 #10
Tim Peters <ti********@gmail.com> wrote:
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.

--
Nick Craig-Wood <ni**@craig-wood.com> -- http://www.craig-wood.com/nick
Jul 18 '05 #11
[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)
Jul 18 '05 #12
[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)
Jul 18 '05 #13
Tim Peters wrote:
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.

--
Nick Coghlan | nc******@email.com | Brisbane, Australia
---------------------------------------------------------------
http://boredomandlaziness.skystorm.net
Jul 18 '05 #14

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/...e-builtin.html

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

http://www.python.org/dev/doc/devel/...n.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

Jul 18 '05 #15
Nick Craig-Wood wrote:
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).

--
Hans Nowak
http://zephyrfalcon.org/

Jul 18 '05 #16
Skip Montanaro wrote:
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/...e-builtin.html

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

http://www.python.org/dev/doc/devel/...n.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

Jul 18 '05 #17
On 01 Feb 2005 18:46:35 GMT, Grant Edwards <gr****@visi.com> declaimed
the following in comp.lang.python:

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.

-- ================================================== ============ <
wl*****@ix.netcom.com | Wulfraed Dennis Lee Bieber KD6MOG <
wu******@dm.net | Bestiaria Support Staff <
================================================== ============ <
Home Page: <http://www.dm.net/~wulfraed/> <
Overflow Page: <http://wlfraed.home.netcom.com/> <

Jul 18 '05 #18

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

10 posts views Thread by Benny Raymond | last post: by
5 posts views Thread by David Longnecker | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.