[GRASS-user] GRASS Python functions

[Glynn Clements]

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>