Python Documentation?

[Daniel R. Smorey Jr.]

I'm looking for a good place for Python documentation. I'm really lost
on why it's so hard to find anything when it comes to me looking up a
particular function in Python. My example would be the split() function
of the string module. Why can't I just go to www.python.org and click
on Search and then type in split and it bring me to the split() function
of the string module? Why does it have to be so hard? This is what I
get when I search for split on www.python.org...

http://search.python.org/query.html?qt=split&col=ftp&col=python&col=peps&col=starship

Most of those hits are for the re module, not the string module (which
in my opinion should be part of python and not a module, but I digress).
Why would it not bring up the split function of the string module
first and foremost?

If I do a search right now on www.perldoc.com for split, I get...

http://www.perldoc.com/cgi-bin/htsearch?words=split&restrict=perl5.8.0

Right there, the top hit is the slit function, how convenient.

If I go to www.php.net and type in split in the function list search, I
get...

http://www.php.net/manual/en/function.split.php

I don't even get a hit list, it goes right to the split() function.
Even more convenient.

I'm trying to learn Python because we're doing some work on the Zaurus
and there are so many supporting python modules for the Zaurus, that I'd
like to use it. I love learning new languages also. It just gives me a
bad taste in my mouth when I even think of searching for anything in Python.

Am I searching the wrong place? Am I choosing the wrong checkboxes on
the Search page? I'm at a loss. Is it really that hard to find
documentation on the python.org site?

Thanks for hearing my rant and I'm hoping I'm just doing something
wrong. I really can't imagine such an organized programming language
having such a horrible search on their website.

 

[Steven Taschuk]

Quoth Daniel R. Smorey Jr.:

I'm looking for a good place for Python documentation. I'm really lost
on why it's so hard to find anything when it comes to me looking up a
particular function in Python. My example would be the split() function
of the string module. [...trouble searching for it at python.org...]

For full-text searches, try <http://www.pydoc.org/>.

For functions and whatnot, there's the index of the Library
Reference, <http://www.python.org/doc/2.3/lib/genindex.html>.

[...]

Most of those hits are for the re module, not the string module (which
in my opinion should be part of python and not a module, but I digress).

Indeed, in sufficiently recent Pythons (2.0+, I think), split() is
a method of string objects: ['foo', 'bar']
Likewise for many other functions in the string module.

(This method is the second hit for "split" at pydoc.org, and is
listed in the Library Reference index.)

 

[Nick Welch]

pydoc is pretty nice, try "pydoc str", and then use / to search for
"split".

As far as searching the online docs, it takes a little adaptation. To
look for str.split, I'd do a google "site:www.python.org built-in
types", and then look for str, and then look at split.

And doing just that, and clicking once or twice, brought me to:

http://www.python.org/doc/current/lib/string-methods.html

Although I agree, it would be cool if the online documentation supported
such direct search methods as e.g. www.php.net/split.

 

[Chad Netzer]

Why can't I just go to www.python.org and click
on Search and then type in split and it bring me to the split() function
of the string module?

Not a bad idea.

Why does it have to be so hard?

Start up a python interpreter and type:

help('string.split')

To see the whole string module:

help('string')

It also work directly on module and function objects:

import string
help(string)

Finally, the string module is being slowly phased out. You can use the
string constructor type instead (in Python 2.2 and later):

help(str.split)
help(str)
etc...

 

[Robert Kern]

I'm looking for a good place for Python documentation. I'm really lost
on why it's so hard to find anything when it comes to me looking up a
particular function in Python. My example would be the split() function
of the string module. Why can't I just go to www.python.org and click
on Search and then type in split and it bring me to the split() function
of the string module?

Well, since you know which module the function is in, you can go to the
documentation page, look up string in the Global Module Index and find
split(). Only a few more clicks.

Or, even easier, you can fire up the interpreter, and do the following:

Or, on the commandline, type

pydoc string.split

Why does it have to be so hard? This is what I
get when I search for split on www.python.org...

http://search.python.org/query.html?qt=split&col=ftp&col=python&col=peps&col=starship

Most of those hits are for the re module, not the string module (which
in my opinion should be part of python and not a module, but I digress).

Most of them are since 2.0. Check out string methods.

http://python.org/doc/current/lib/string-methods.html

Why would it not bring up the split function of the string module
first and foremost?

Because no one has asked for it to do so before? Because the unpaid
volunteers with limited time who run the site don't need the feature
themselves and never realized that others might want it? Because the
string method and re function split() are equally good or better options
to return first?

Although I agree that there should be a checkbox option to search only
the current docs.

--
Robert Kern
(e-mail address removed)

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

 

[John Burton]

I'm looking for a good place for Python documentation. I'm really lost
on why it's so hard to find anything when it comes to me looking up a
particular function in Python. My example would be the split() function

The help within python itsself is a good start.
For your example try

import string
help(string.split)

No need to visit a web site.

 

[Dan Thrue]

I'm looking for a good place for Python documentation. I'm really lost
on why it's so hard to find anything when it comes to me looking up a
particular function in Python. My example would be the split() function
of the string module. Why can't I just go to www.python.org and click
on Search and then type in split and it bring me to the split() function
of the string module? Why does it have to be so hard? This is what I
get when I search for split on www.python.org...

http://search.python.org/query.html?qt=split&col=ftp&col=python&col=peps&col=starship


Most of those hits are for the re module, not the string module (which
in my opinion should be part of python and not a module, but I digress).
Why would it not bring up the split function of the string module first
and foremost?

If I do a search right now on www.perldoc.com for split, I get...

http://www.perldoc.com/cgi-bin/htsearch?words=split&restrict=perl5.8.0

Right there, the top hit is the slit function, how convenient.

If I go to www.php.net and type in split in the function list search, I
get...

http://www.php.net/manual/en/function.split.php

I don't even get a hit list, it goes right to the split() function. Even
more convenient.

I'm trying to learn Python because we're doing some work on the Zaurus
and there are so many supporting python modules for the Zaurus, that I'd
like to use it. I love learning new languages also. It just gives me a
bad taste in my mouth when I even think of searching for anything in
Python.

Am I searching the wrong place? Am I choosing the wrong checkboxes on
the Search page? I'm at a loss. Is it really that hard to find
documentation on the python.org site?

Thanks for hearing my rant and I'm hoping I'm just doing something
wrong. I really can't imagine such an organized programming language
having such a horrible search on their website.

Hi Daniel,

Me and a friend am about to finish a project in a couple of weeks, that
maybe fits your needs.

We are currently documenting the parts if python, we meet in our daily
python development (Some gaming software where we mix native delphi with
python. This mixture has surprised us a lot, we are indeed python
fanatics now, hehe).

The documentation takes contributions on example snippets, description,
etc. so when the site is completely done and a base of documentation
have been posted, im gonna post link in here, then maybe the community
will help us to create a great documentation source And find the
errors we might post

Regards all,
Dan

 

[Larz]

The documentation takes contributions on example snippets,

description, etc. so when the site is completely done and a base of
documentation have been posted, im gonna post link in here, then maybe
the community will help us to create a great documentation source

Hi all, I'm the friend that Dan is talking about

Just wanted to clarify our project a little bit.

Dan and I are long time php programmers. One thing that is superb about
php, is it's online documentation that everyone in the community can
contribute to (not the actual documentation, just comments with
examples).

Every since I first started using python, I've truly missed a
documentation source similar to that of PHP's. So Dan and I have started
our little project to make a documentation site in the spirit of that
documentation.

So far it looks great, and you can see some python documentation by using
URLs like http://example.com/doc/string.split and there will of course be
a search function.

Also, it will not only be the "standard" modules of Python, by suggestion
(and perhaps permission), we will include third party modules, such as
MySQLdb and the like.

As Dan writes, it will be ready very soon, within a few weeks. It will of
course be devoid of user comments in the beginning, but we're hoping that
users will contribute with some of their invaluable experience!



Best regards,

Lars Petersen

 

[Cameron Laird]

.
.
.

Dan and I are long time php programmers. One thing that is superb about
php, is it's online documentation that everyone in the community can
contribute to (not the actual documentation, just comments with
examples).

Every since I first started using python, I've truly missed a
documentation source similar to that of PHP's. So Dan and I have started
our little project to make a documentation site in the spirit of that
documentation.

.
.
.
PHP's documentation has indeed been a great success as a
collaborative adventure.

Python already has a structure--and much content!--for
comparable collaboration in <URL: http://
www.python.org/cgi-bin/moinmoin/ >. Moreover, as several
follow-ups have explained, Python developers have differ-
ent work practices than PHPers, and a different relation
to documentation. In particular, it's hard to overempha-
size how much working Python programmers depend on
interactive introspection: use of the interpreter's
built-in help, pydoc, and related facilities to discover
and confirm details that, in PHPonia, are regarded as
matters for online documentation.

 

[Michael Hudson]

I'm looking for a good place for Python documentation.

In addition to what others said, there's Thomas Heller's pyhelp.cgi
thingy:

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

and Mark Hammond's Mozilla sidebar:

http://starship.python.net/crew/mhammond/mozilla/index.html

(which provides an interface to Thomas' script).

I'm really lost on why it's so hard to find anything when it comes
to me looking up a particular function in Python. My example would
be the split() function of the string module.

You mean you weren't born knowing what that did? Sheesh, kids these
days... <wink>.

Cheers,
mwh

 

[Dan Thrue]

.
.
.


.
.
.
PHP's documentation has indeed been a great success as a
collaborative adventure.

Python already has a structure--and much content!--for
comparable collaboration in <URL: http://
www.python.org/cgi-bin/moinmoin/ >. Moreover, as several
follow-ups have explained, Python developers have differ-
ent work practices than PHPers, and a different relation
to documentation. In particular, it's hard to overempha-
size how much working Python programmers depend on
interactive introspection: use of the interpreter's
built-in help, pydoc, and related facilities to discover
and confirm details that, in PHPonia, are regarded as
matters for online documentation.

Hi Cameron,

Thank for your feedback, i personally uses pydoc when im in need of
documentation, but sometimes i have been in such situations where code
snippets was necessary for me. The background for this project is to
gain a great database public of snippets hooked in a structure that is
easily for all to use, novice as well as expert.

Maybe its the way i think, but i understand and learn a lot faster
(better?) when the the theory is put into practice.

At my daily work im a .net programmer, and the documentation im using
there is also "practice based". Im not a theoretic person, and I think
there is a lot like myself out there

Best Regards
Dan

 

[Larz]

(e-mail address removed) (Cameron Laird) wrote in @corp.supernews.com:

Python already has a structure--and much content!--for
comparable collaboration in <URL: http://
www.python.org/cgi-bin/moinmoin/ >. Moreover, as several
follow-ups have explained, Python developers have differ-
ent work practices than PHPers, and a different relation
to documentation. In particular, it's hard to overempha-
size how much working Python programmers depend on
interactive introspection: use of the interpreter's
built-in help, pydoc, and related facilities to discover
and confirm details that, in PHPonia, are regarded as
matters for online documentation.

Yes, I agree that a lot of python programmers think differently.
Even though, I sense a general consensus, especially among beginning
Pythoneers, that the community lacks a great tool, like the one PHP has.
Of course I am not just thinking about the documentation itself, which you
could get with pydoc/help(), but also experience, pointers, pitfalls that
other people ran in to. That's what makes it a community

Anyway, I am pretty sure we're going to fill a much needed niche, and if
not, we're certainly going to meet our own needs

 

[Cameron Laird]

(e-mail address removed) (Cameron Laird) wrote in @corp.supernews.com:


Yes, I agree that a lot of python programmers think differently.
Even though, I sense a general consensus, especially among beginning
Pythoneers, that the community lacks a great tool, like the one PHP has.
Of course I am not just thinking about the documentation itself, which you
could get with pydoc/help(), but also experience, pointers, pitfalls that
other people ran in to. That's what makes it a community

Anyway, I am pretty sure we're going to fill a much needed niche, and if
not, we're certainly going to meet our own needs

.
.
.
Larz, my own career has been almost entirely an
exploration of the relation between meeting my
own needs and filling much-needed niches; any
words of support would be only superfluous.

I fear, though, that I didn't write clearly. I
made *two* observations; not only do Pythoneers
rely on introspection, but we *already* have a
vehicle for sharing code examples, commentary,
and related matters: the Wiki (complementing,
incidentally, the Cookbook).

 

[Cameron Laird]

.
.
.
Thank for your feedback, i personally uses pydoc when im in need of
documentation, but sometimes i have been in such situations where code
snippets was necessary for me. The background for this project is to
gain a great database public of snippets hooked in a structure that is
easily for all to use, novice as well as expert.

.
.
.
I apologize for muddling my message. I completely agree
that a public knowledge store of code fragments and re-
lated matters, that is easy for all to access, is a great
blessing. That's the aim of the Wiki. Or were you
judging the Wiki a failure in that, but too polite to
make it explicit?

 

[Dan Thrue]

.
.
.
I apologize for muddling my message. I completely agree
that a public knowledge store of code fragments and re-
lated matters, that is easy for all to access, is a great
blessing. That's the aim of the Wiki. Or were you
judging the Wiki a failure in that, but too polite to
make it explicit?

No i wont judge anything a failure in this community To say it
shortly, the wiki doesnt actually fill my requirements.

Hope that isnt an too arrogant attitude I put up, but remember we do
this effort for the community as well for our selves.

Best regards,
Dan

 

[=?ISO-8859-1?Q?Gerhard_H=E4ring?=]

[...] Pythoneers [...] have a vehicle for sharing code examples,
commentary, and related matters: the Wiki (complementing,
incidentally, the Cookbook).

Well, these are already two places, not one My observation is that in
Pythonia, there is quite a diversity in places where code snippets and
tips are collected. In addition to the two big sources you mentioned,
there's also the Python FAQ, for example.

As far as Wikis are concerned, I'd like to humbly suggest that people
really use the Wiki at python.org, instead of putting content that
concerns Python itself into their own wikis. Yes, I also mean you,
Twisted guys!

Decentralisation may have its places, but not for documentation and
knowledge bases, IMO. That is, if you want to improve on Google being
your documentation index

-- Gerhard

 

[Daniel R. Smorey Jr.]

You mean you weren't born knowing what that did? Sheesh, kids these
days... <wink>.

haha, yeah, there's only one problem with knowing that function so well,
some crazy programmers change the variable order. Take a look at php's
split() and python's split(). The order's are different and believe me,
split() was only a small example of problems I've had with python
documentation so far. I'm working on a Zaurus problem with PyQT at the
moment. I know "some" C, not a lot though and have never worked with
QT. Man is it hard to find documentation on PyQT. I found a great
online book, but of course it's only a book, can't possibly have every
feature and every snippet of PyQT. So, since there is virtually no
documentation on it, I have to use the C documentation and just convert
it over. Which I'm finding isn't really that hard since Python is such
an object-oriented language.

My main problem is I love learning new languages. However, my boss
loves me getting my work done also. If I had a place where I could go
to find partially what I needed 70% of the time, then I'd like the
language even more. Python hasn't been that way so far. But I'm
learning and thanks to all the posts here, I'll have a better idea of
where to find this documentation.

Thanks all...

 

[=?ISO-8859-1?Q?Gerhard_H=E4ring?=]

No i wont judge anything a failure in this community To say it
shortly, the wiki doesnt actually fill my requirements.

I actually find the PHP approach of being able to attach user comments
to doc pages useful. I try to stay clear from PHP ;-), but I do use it
in the PostgreSQL interactive documentation:

Here's an example:
http://www.postgresql.org/docs/7.3/interactive/ddl-alter.html#AEN1984

I find it's a good way to add notes about what's not clear and what
information is wrong or lacking to the docs. Certainly an easier
approach than to file a bug report or a doc patch for the Python docs at
Sourceforge.

The PostgreSQL docs are created from SGML, while the Python docs are
created from a LaTeX subset, so I don't know if there's any solution
that could easily be set up for the Python documentation. I'd like to
see it implemented, though. [1]

-- Gerhard

[1] If nothing else, I could then add "does anybody actually directly
use this cra^wmodule?" to the page for ftplib <0.1 wink>

 

[=?ISO-8859-1?Q?Gerhard_H=E4ring?=]

Cc-ing python-list because it might be of general interest.

[1] If nothing else, I could then add "does anybody actually directly
use this cra^wmodule?" to the page for ftplib <0.1 wink>

What *is* going on there? Do you use Twisted instead?

I needed a quick way to "stat" files via FTP (it's a mirror script that
synchronizes the maps, etc. on Unreal Tournament 2003 gameservers). As
ftplib lacks any methods whatsoever to parse the output of the LIST
command, I searched for something higher level and found ftputil [1],
which is quite nice to use.

Unfortunately, the stat command of ftputil was very inefficient (it
basically does a LIST for every stat() you call), so I extended it with
a statall() method for my mirror script.

Being annoyed with Python's ftplib I wasn't surprised that the ftpcp
function in the module didn't work for me, while calling the Linux ftp
client (well, whatever /usr/bin/ftp was at that machine ;-) worked fine
when using the appropriate PROXY commands.

My current solution creates a script that is then fed into the ftp
client program. Yes, I need an appropriate ~/.netrc file :-/ It's quite
a hack, but I needed a solution fast ;-)

The good part was [2] that I learnt that FTP actually has one useful
feature: server-to-server copy, which has the additional benefit of not
creating any significant traffic on the controlling client.

-- Gerhard

[1] http://www.ndh.net/home/sschwarzer/python/python_software.html
[2] thanks to deltab on #python

 

[Daniel R. Smorey Jr.]

Quoth Daniel R. Smorey Jr.:


For full-text searches, try <http://www.pydoc.org/>.

For functions and whatnot, there's the index of the Library
Reference, <http://www.python.org/doc/2.3/lib/genindex.html>.

That's exactly what I was looking for! I didn't even know until now
that you don't have to import string and that split is part of python
now. pydoc.org gave me that in the first page of hits, I think the
second hit. Thanks...