Python Doc Problem Example: os.system

Discussion in 'Python' started by Xah Lee, Sep 5, 2005.

  1. Xah Lee

    Xah Lee Guest

    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/module-subprocess.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/writ/python_doc_os.html

    Xah

    ∑ http://xahlee.org/
     
    Xah Lee, Sep 5, 2005
    #1
    1. Advertising

  2. Xah Lee

    Jeremy Jones Guest

    Xah Lee wrote:

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

    """

    *system*( command)

    Execute the command (a string) in a subshell. This is implemented by
    calling the Standard C function system(), and has the same
    limitations. Changes to |posix.environ|, |sys.stdin|, etc. are not
    reflected in the environment of the executed command.

    On Unix, the return value is the exit status of the process encoded
    in the format specified for wait(). Note that POSIX does not specify
    the meaning of the return value of the C system() function, so the
    return value of the Python function is system-dependent.

    On Windows, the return value is that returned by the system shell
    after running command, given by the Windows environment variable
    COMSPEC: on *command.com* systems (Windows 95, 98 and ME) this is
    always |0|; on *cmd.exe* systems (Windows NT, 2000 and XP) this is
    the exit status of the command run; on systems using a non-native
    shell, consult your shell documentation.

    Availability: Unix, Windows.

    """

    Yup. Nothing more esoteric than a process's exit status. That's one of
    those really tricky jargons that computer scientist idiots like to throw
    around. You've got to watch out for those.

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

    I'm presuming you mean in the os.system docs as you mention below that
    you found such documentation.

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

    """


    6.8 subprocess -- Subprocess management

    New in version 2.4.

    The subprocess module allows you to spawn new processes, connect to
    their input/output/error pipes, and obtain their return codes. This
    module intends to replace several other, older modules and functions,
    such as:

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

    """
    Yeah. There's a really tricky word up there in the beginning of the
    subprocess doc. "intends". In this context, it means that it is
    currently the plan of the Python developers to replace said modules with
    the subprocess module, *however*, that has not totally come about now.
    If the doc had said, "This module *has replaced* several others", then I
    would have to agree with you that the stated module docs should be
    updated to reflect the fact that they have been deprecated.

    > Since i'm not Python expert
    >

    Really?

    >, i like to look at these. But
    >****, the incompetent doc gives ample gratis links to OpenSource this
    >or that or author masturbation
    >

    OK - I just scanned through the subprocess module docs and I really
    don't see where you're getting this from. I'll just chalk the former up
    to your bad experience with the regular expression module docs referring
    to the book "Mastering Regular Expressions." And since you're quite the
    linguistic scholar, I'll chalk up the latter to your unique construction
    of the book title I just cited.

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

    Are you talking about the subprocess docs? If so, I'd like to see an
    example of what you're talking about. Subprocess docs seem really
    straightforward, terse, and to the point.

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

    I would leave it in the hands of the Python doc maintainers what to do
    with this since subprocess hasn't yet totally replaced the other modules.

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

    I'd really like to see what you're talking about here. I just went
    through the subprocess docs *again* and I don't see *any* links to any
    other open source anything and I don't see any "tech geeking" to use
    your jargon. I think you're full of crap. And I think you don't have
    the balls to reply back to this message and show me what you're talking
    about. You're just a little boy inside, making a call to a bowling
    alley and asking if they have 15 pound balls and hanging up laughing
    after they reply "yes" and you reply "Then how do you walk!!!" Oh,
    you're so witty.

    >Solution Suggestion:
    >
    >* Add examples.
    >
    >

    Yeah, the

    """


    6.8.3.2 Replacing shell pipe line

    output=`dmesg | grep hda`
    ==>
    p1 = Popen(["dmesg"], stdout=PIPE)
    p2 = Popen(["grep", "hda"], stdin=p1.stdout)
    output = p2.communicate()[0]
    """

    subprocess module

    """


    6.8.3.3 Replacing os.system()

    sts = os.system("mycmd" + " myarg")
    ==>
    p = Popen("mycmd" + " myarg", shell=True)
    sts = os.waitpid(p.pid, 0)
    """

    just

    """


    6.8.3.4 Replacing os.spawn*

    P_NOWAIT example:

    pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
    ==>
    pid = Popen(["/bin/mycmd", "myarg"]).pid

    P_WAIT example:

    retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
    ==>
    retcode = call(["/bin/mycmd", "myarg"])

    Vector example:

    os.spawnvp(os.P_NOWAIT, path, args)
    ==>
    Popen([path] + args[1:])

    Environment example:

    os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
    ==>
    Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
    """

    doesn't have


    """


    6.8.3.5 Replacing os.popen*

    pipe = os.popen(cmd, mode='r', bufsize)
    ==>
    pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout

    pipe = os.popen(cmd, mode='w', bufsize)
    ==>
    pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin

    (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
    ==>
    p = Popen(cmd, shell=True, bufsize=bufsize,
    stdin=PIPE, stdout=PIPE, close_fds=True)
    (child_stdin, child_stdout) = (p.stdin, p.stdout)

    (child_stdin,
    child_stdout,
    child_stderr) = os.popen3(cmd, mode, bufsize)
    ==>
    p = Popen(cmd, shell=True, bufsize=bufsize,
    stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
    (child_stdin,
    child_stdout,
    child_stderr) = (p.stdin, p.stdout, p.stderr)

    (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
    ==>
    p = Popen(cmd, shell=True, bufsize=bufsize,
    stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
    (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

    """

    any examples

    """


    6.8.3.6 Replacing popen2.*

    *Note:* If the cmd argument to popen2 functions is a string, the command
    is executed through /bin/sh. If it is a list, the command is directly
    executed.

    (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
    ==>
    p = Popen(["somestring"], shell=True, bufsize=bufsize
    stdin=PIPE, stdout=PIPE, close_fds=True)
    (child_stdout, child_stdin) = (p.stdout, p.stdin)

    (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
    ==>
    p = Popen(["mycmd", "myarg"], bufsize=bufsize,
    stdin=PIPE, stdout=PIPE, close_fds=True)

    (child_stdout, child_stdin) = (p.stdout, p.stdin)

    """

    at all.

    >* Add cross-links to relevant modules.
    >
    >

    Bah. Whatever. I've wasted enough time on this thread. I think the
    only reason I read your posts is because you're just so comically and
    consistently off base.

    >* 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/writ/python_doc_os.html
    >
    > Xah
    >
    >∑ http://xahlee.org/
    >
    >
    >

    JMJ
     
    Jeremy Jones, Sep 5, 2005
    #2
    1. Advertising

  3. 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.
     
    Robert Wierschke, Sep 5, 2005
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Matt
    Replies:
    3
    Views:
    510
    Tor Iver Wilhelmsen
    Sep 17, 2004
  2. Xah Lee
    Replies:
    12
    Views:
    684
    Steve Holden
    Sep 20, 2005
  3. Xah Lee
    Replies:
    25
    Views:
    882
    Jeffrey Schwab
    Nov 9, 2005
  4. Byron Rios
    Replies:
    0
    Views:
    245
    Byron Rios
    Jun 22, 2008
  5. Xah Lee

    Python Doc Problem Example: os.system

    Xah Lee, Sep 5, 2005, in forum: Perl Misc
    Replies:
    1
    Views:
    146
    Robert Wierschke
    Sep 5, 2005
Loading...

Share This Page