[GRASS-dev] Python script test

[Michael Barton]

Thanks Glynn. These will make all Python scripting easier.

Michael


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