[GRASS-dev] Python script test

[Glynn Clements]

Michael Barton wrote:

> Thanks again Glynn. This will be very useful. When you get a chance,  
> can you provide a quick summary of these new python interfaces in  
> grass.py? Once I get my system back up and running, I'll update from  
> the SVN and look at this library.

Most of them are simple enough to be self-explanatory, but some comments:

[I have added this as lib/python/README.txt]

def make_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **options):

Return a list of strings suitable for use as the args parameter to
Popen() or call(). Example:

>>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
['g.message', '-w', 'message=this is a warning']

def start_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **kwargs):

Returns a Popen object with the command created by make_command.
Accepts any of the arguments which Popen() accepts apart from "args"
and "shell". Example:

>>> p = grass.start_command("g.gisenv", stdout = subprocess.PIPE)
>>> print p
<subprocess.Popen object at 0xb7c12f6c>
>>> print p.communicate()[0]
GISDBASE='/opt/grass-data';
LOCATION_NAME='spearfish57';
MAPSET='glynn';
GRASS_DB_ENCODING='ascii';
GRASS_GUI='text';
MONITOR='x0';

def run_command(*args, **kwargs):

Passes all arguments to start_command, then waits for the process to
complete, returning its exit code. Similar to subprocess.call(), but
with the make_command() interface.

def read_command(*args, **kwargs):

Passes all arguments to start_command, then waits for the process to
complete, returning its stdout (i.e. similar to shell "backticks").

def message(msg, flag = None):
def debug(msg):
def verbose(msg):
def info(msg):
def warning(msg):
def error(msg):

These all run g.message, differing only in which flag (if any) is used.

def fatal(msg):

Like error(), but also calls sys.exit(1).

def parser():

Interface to g.parser, intended to be run from the top-level, e.g.:

	if __name__ == "__main__":
	    options, flags = grass.parser()
	    main()

Thereafter, the global variables "options" and "flags" will be
dictionaries containing option/flag values, keyed by lower-case
option/flag names. The values in "options" are strings, those in
"flags" are Python booleans.

def tempfile():

Returns the name of a temporary file, created with g.tempfile.

def gisenv():

Returns the output from running g.gisenv (with no arguments), as a
dictionary. Example:

>>> env = grass.gisenv()
>>> print env['GISDBASE']
/opt/grass-data

def region():

Returns the output from running "g.region -g", as a dictionary. 
Example:

>>> region = grass.region()
>>> [region[key] for key in "nsew"]
['4928000', '4914020', '609000', '590010']
>>> (region['nsres'], region['ewres'])
('30', '30')

def use_temp_region():

Copies the current region to a temporary region with "g.region save=",
then sets WIND_OVERRIDE to refer to that region. Installs an atexit
handler to delete the temporary region upon termination.

def del_temp_region():

Unsets WIND_OVERRIDE and removes any region named by it.

def find_file(name, element = 'cell'):

Returns the output from running g.findfile as a dictionary. Example:

>>> result = grass.find_file('fields', element = 'vector')
>>> print result['fullname']
fields at PERMANENT
>>> print result['file']
/opt/grass-data/spearfish57/PERMANENT/vector/fields

def list_grouped(type):

Returns the output from running g.list, as a dictionary where the keys
are mapset names and the values are lists of maps in that mapset. 
Example:

>>> grass.list_grouped('rast')['PERMANENT']
['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...

def list_pairs(type):

Returns the output from running g.list, as a list of (map, mapset)
pairs. Example:

>>> grass.list_pairs('rast')
[('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...

def list_strings(type):

Returns the output from running g.list, as a list of qualified names. 
Example:

>>> grass.list_strings('rast')
['aspect at PERMANENT', 'erosion1 at PERMANENT', 'quads at PERMANENT', 'soils at PERMANENT', ...

-- 
Glynn Clements <glynn at gclements.plus.com>