Python Doc Problem: os.system
Today i'm trying to use Python to call shell commands. In Perl, it's something like:
$output = qx(ls);
In Python i quickly located 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/module-subprocess.html
i'm told that this module replaces:
os.system os.spawn* os.popen* popen2.* commands.*
Interesting. Since i'm not a Python expert, i'd like to look at these. But the doc gives ample gratis links to Open Source this or that or author know-how exhibition links to remote book i don't really care about, but here there is 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 places where a new function is replacing the old.
- Does not provide relevant cross-links. (while provding many irrelevant links because of Open Source 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 manifested 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 if the programer must know it in order to use it properly, and as side note. This way, the language becomes focused as a independent tool (For example, 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).
For a tutorial on using subprocess.Popen(), see: Python: Make System Call
.