«

Python Doc Problem Example: os.system

Xah Lee, 2005-09

today i'm trying to use Python to call shell commands. e.g. in Perl
something like

output=qx(ls)

in Python i quickly located the the function due to its
well-named-ness:

import os
os.system("ls")


however, according to the doc
http://www.python.org/doc/2.4/lib/os-process.html the os.system()
returns some esoteric unix thing, not the command output. The doc
doesn't say how to get the output of the command.

by chance someone told me that in python 2.4 the os.system is
supplanted by subprocess.call(), but this isn't mentioned in the doc!

upon finding the new doc location
http://www.python.org/doc/2.4/lib/mo...ubprocess.html i'm told that
this module replaces:

os.system
os.spawn*
os.popen*
popen2.*
commands.*


interesting. Since i'm not Python expert, i like to look at these. But
****, the incompetent doc gives ample gratis links to OpenSource this
or that or author masturbation links to remote book i don't really care
about, but here there's no link.

Problem summary:

* does not focus on the task users need to do. Instead, the doc is
oriented towards tech geeking.

* does not inform the reader at the right place where a new function is
replacing the old.

* does not provide relevant cross-links. (while provding many
irrelevant links because of OpenSource or Tech Geeking fanaticism)

Solution Suggestion:

* Add examples.

* Add cross-links to relevant modules.

* Mention and add link at the right place supplanted functions.

* Orient the doc to tasks and manifest functionalities. Think like
functional programing: input and output specification, and document
them. This will help focus and precision in the doc. Avoid prose-like
descriptions. Avoid drilling on remotely related tech/unix/C esoterica.
e.g. Do not mention as a documentation how they are implemented.
Mention implementation on the side if necessary. This way, the language
becomes focused as a independent tool (e.g. Mathematica, Java, Scheme,
emacs) (which may provide ample capabilities to interface/connect to
other technologies), instead of heavily intermixed and dependent with a
bunch of other things (unix things: Perl, Apache, shells).

-----------------------------
This article is archive at:
http://xahlee.org/UnixResource_dir/w...on_doc_os.html

Xah

∑ http://xahlee.org/

Xah Lee schrieb:
> Python Doc Problem Example: os.system
>
> Xah Lee, 2005-09
>
> today i'm trying to use Python to call shell commands. e.g. in Perl
> something like
>
> output=qx(ls)
>
> in Python i quickly located the the function due to its
> well-named-ness:
>
> import os
> os.system("ls")
>
>
> however, according to the doc
> http://www.python.org/doc/2.4/lib/os-process.html the os.system()
> returns some esoteric unix thing, not the command output. The doc
> doesn't say how to get the output of the command.
>

The os.popen(...) function will return a file like object, so you can
use a read() - method of these object to get the called programms output.

hope that helps - I' m very new to python

The documentation may be not well for all circumstances but the fine
thing is: the documentation is part of the code itself - inform of the
docstrings - and this is a very good approach. The bad thing is the
person who wrote the docstring was documenting his/her own code and not
code of other programmers.