[GRASS-user] GRASS Python functions

[Mark Seibel]

Thank you for your time in detail in the explanations.  I sincerely appreciate it.  That helps immensely.  I dream to one day contribute some code.

Thank you.
Mark

"Glynn Clements" <glynn at gclements.plus.com> wrote:

>
>Mark Seibel wrote:
>
>> I'm unclear about the difference between some of these library
>> functions, and when they are applicable.
>> 
>> Specifically:
>> Uses for read, feed and pipe commands, as well as start and exec command. 
>> 
>> I've read the page which gives the explanations, but am having a
>> hard time seeing which ones are applicable for certain tasks.
>> 
>> I've been using a lot of subprocess calls, and these seem cleaner.(?)
>
>All of the *_command functions use make_command to construct a command
>line for a program which uses the GRASS parser. Most of them then pass
>that command line to subprocess.Popen() via start_command(), except
>for exec_command() which uses os.execvpe().
>
>[To be precise, they use grass.Popen(), which just calls
>subprocess.Popen() with shell=True on Windows and shell=False
>otherwise. On Windows, you need to use shell=True to be able to
>execute scripts (including batch files); shell=False only works with
>binary executables.]
>
>start_command() separates the arguments into those which
>subprocess.Popen() understands and the rest. The rest are passed to
>make_command() to construct a command line which is passed as the
>"args" parameter to subprocess.Popen().
>
>IOW, start_command() is a GRASS-oriented interface to
>subprocess.Popen(). It should be suitable for any situation where you
>would use subprocess.Popen() to execute a normal GRASS command (one
>which uses the GRASS parser, which is almost all of them; the main
>exception is r.mapcalc in 6.x).
>
>Most of the others are convenience wrappers around start_command(),
>for common use cases.
>
>run_command() calls the wait() method on the process, so it doesn't
>return until the command has finished, and returns the command's exit
>code. Similar to system().
>
>pipe_command() calls start_command() with stdout=PIPE and returns the
>process object. You can use the process' .stdout member to read the
>command's stdout. Similar to popen(..., "r").
>
>feed_command() calls start_command() with stdin=PIPE and returns the
>process object. You can use the process' .stdin member to write to the
>command's stdout. Similar to popen(..., "w")
>
>read_command() calls pipe_command(), reads the data from the command's
>stdout, and returns it as a string. Similar to `backticks` in the
>shell.
>
>write_command() calls feed_command(), sends the string specified by
>the "stdin" argument to the command's stdin, waits for the command to
>finish and returns its exit code. Similar to "echo ... | command".
>
>parse_command() calls read_command() and parses its output as
>key-value pairs. Useful for obtaining information from g.region,
>g.proj, r.info, etc.
>
>exec_command() doesn't use start_command() but os.execvpe(). This
>causes the specified command to replace the current program (i.e. the
>Python script), so exec_command() never returns. Similar to bash's
>"exec" command. This can be useful if the script is a "wrapper" around
>a single command, where you construct the command line and execute the
>command as the final step.
>
>If you have any other questions, you might want to look at the code
>($GISBASE/etc/python/grass/script/core.py). Most of these functions
>are only a few lines long.
>
>-- 
>Glynn Clements <glynn at gclements.plus.com>