[GRASS-SVN] r37002 - grass/branches/develbranch_6/lib/python

svn_grass at osgeo.org svn_grass at osgeo.org
Tue May 5 15:29:27 EDT 2009


Author: neteler
Date: 2009-05-05 15:29:27 -0400 (Tue, 05 May 2009)
New Revision: 37002

Added:
   grass/branches/develbranch_6/lib/python/grasspythonlib.dox
Modified:
   grass/branches/develbranch_6/lib/python/Makefile
Log:
document GRASS-Python lib

Modified: grass/branches/develbranch_6/lib/python/Makefile
===================================================================
--- grass/branches/develbranch_6/lib/python/Makefile	2009-05-05 19:28:57 UTC (rev 37001)
+++ grass/branches/develbranch_6/lib/python/Makefile	2009-05-05 19:29:27 UTC (rev 37002)
@@ -3,6 +3,7 @@
 include $(MODULE_TOPDIR)/include/Make/Platform.make
 include $(MODULE_TOPDIR)/include/Make/Grass.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
+include $(MODULE_TOPDIR)/include/Make/Doxygen.make
 
 default: $(ETC)/python
 
@@ -13,3 +14,6 @@
 .PHONY: $(ETC)/python
 
 clean:
+
+#doxygen:
+DOXNAME=grasspython

Added: grass/branches/develbranch_6/lib/python/grasspythonlib.dox
===================================================================
--- grass/branches/develbranch_6/lib/python/grasspythonlib.dox	                        (rev 0)
+++ grass/branches/develbranch_6/lib/python/grasspythonlib.dox	2009-05-05 19:29:27 UTC (rev 37002)
@@ -0,0 +1,264 @@
+/*! \page GRASS_LIB_PYTHON GRASS 6 Python library
+
+<h2>GRASS 6 Python library</h2>
+
+See code in: grass.py
+
+
+\section scripting GRASS scripting tasks for Python provided by "grass.py".
+
+Usage: "import grass"
+
+\section make_command
+\code
+def make_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **options):
+\endcode
+
+Return a list of strings suitable for use as the args parameter to
+Popen() or call(). Example:
+
+\code
+>>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
+['g.message', '-w', 'message=this is a warning']
+\endcode
+
+
+\section start_command
+\code
+def start_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **kwargs):
+\endcode
+
+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:
+
+\code
+>>> 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';
+\endcode
+
+
+\section pipe_command
+\code
+def pipe_command(*args, **kwargs):
+\endcode
+
+Passes all arguments to start_command, but also adds
+"stdout = subprocess.PIPE". Returns the Popen object. Example:
+
+\code
+>>> p = grass.pipe_command("g.gisenv")
+>>> 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';
+\endcode
+
+
+\section run_command
+\code
+def run_command(*args, **kwargs):
+\endcode
+
+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.
+
+
+\section read_command
+\code
+def read_command(*args, **kwargs):
+\endcode
+
+Passes all arguments to start_command, then waits for the process to
+complete, returning its stdout (i.e. similar to shell "backticks").
+
+
+\section messages
+\code
+def message(msg, flag = None):
+def debug(msg):
+def verbose(msg):
+def info(msg):
+def warning(msg):
+def error(msg):
+\endcode
+
+These all run g.message, differing only in which flag (if any) is used.
+
+
+\section fatal
+\code
+def fatal(msg):
+\endcode
+
+Like error(), but also calls sys.exit(1).
+
+
+\section parser
+\code
+def parser():
+\endcode
+
+Interface to g.parser, intended to be run from the top-level, e.g.:
+
+\code
+	if __name__ == "__main__":
+	    options, flags = grass.parser()
+	    main()
+\endcode
+
+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.
+
+
+\section tempfile
+\code
+def tempfile():
+\endcode
+
+Returns the name of a temporary file, created with g.tempfile.
+
+
+\section gisenv
+\code
+def gisenv():
+\endcode
+
+Returns the output from running g.gisenv (with no arguments), as a
+dictionary. Example:
+
+\code
+>>> env = grass.gisenv()
+>>> print env['GISDBASE']
+/opt/grass-data
+\endcode
+
+
+\section region
+\code
+def region():
+\endcode
+
+Returns the output from running "g.region -g", as a dictionary. 
+Example:
+
+\code
+>>> region = grass.region()
+>>> [region[key] for key in "nsew"]
+['4928000', '4914020', '609000', '590010']
+>>> (region['nsres'], region['ewres'])
+('30', '30')
+\endcode
+
+
+\section use_temp_region
+\code
+def use_temp_region():
+\endcode
+
+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.
+
+
+\section del_temp_region
+\code
+def del_temp_region():
+\endcode
+
+Unsets WIND_OVERRIDE and removes any region named by it.
+
+
+\section find_file
+\code
+def find_file(name, element = 'cell'):
+\endcode
+
+Returns the output from running g.findfile as a dictionary. Example:
+
+\code
+>>> result = grass.find_file('fields', element = 'vector')
+>>> print result['fullname']
+fields at PERMANENT
+>>> print result['file']
+/opt/grass-data/spearfish60/PERMANENT/vector/fields
+\endcode
+
+
+\section list_grouped
+\code
+def list_grouped(type):
+\endcode
+
+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:
+
+\code
+>>> grass.list_grouped('rast')['PERMANENT']
+['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...
+\endcode
+
+
+\section list_pairs
+\code
+def list_pairs(type):
+
+Returns the output from running g.list, as a list of (map, mapset)
+pairs. Example:
+
+\code
+>>> grass.list_pairs('rast')
+[('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...
+\endcode
+
+
+\section list_strings
+\code
+def list_strings(type):
+\endcode
+
+Returns the output from running g.list, as a list of qualified names. 
+Example:
+
+\code
+>>> grass.list_strings('rast')
+['aspect at PERMANENT', 'erosion1 at PERMANENT', 'quads at PERMANENT', 'soils at PERMANENT', ...
+\endcode
+
+
+\section parse_color
+\code
+def parse_color(val, dflt = None):
+\endcode
+
+Parses the string "val" as a GRASS colour, which can be either one of
+the named colours or an R:G:B tuple e.g. 255:255:255. Returns an
+(r,g,b) triple whose components are floating point values between 0
+and 1. Example:
+
+\code
+>>> grass.parse_color("red")
+(1.0, 0.0, 0.0)
+>>> grass.parse_color("255:0:0")
+(1.0, 0.0, 0.0)
+\endcode
+
+*/
+



More information about the grass-commit mailing list