grass.script doxygen page updated

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@37495 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/python/core.py

@@ -108,6 +108,19 @@ def start_command(prog, flags = "", overwrite = False, quiet = False, verbose =
     Accepts any of the arguments which Popen() accepts apart from "args"
     and "shell".
 
+    \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='spearfish60';
+    MAPSET='glynn';
+    GRASS_DB_ENCODING='ascii';
+    GRASS_GUI='text';
+    MONITOR='x0';
+    \endcode
+    
     @param prog GRASS module
     @param flag flags to be used
     @param overwrite True to enable overwriting the output (--o)
@@ -144,6 +157,19 @@ def pipe_command(*args, **kwargs):
     """Passes all arguments to start_command, but also adds
     "stdout = PIPE". Returns the Popen object.
 
+    \code
+    >>> p = grass.pipe_command("g.gisenv")
+    >>> print p
+    <subprocess.Popen object at 0xb7c12f6c>
+    >>> print p.communicate()[0]
+    GISDBASE='/opt/grass-data';
+    LOCATION_NAME='spearfish60';
+    MAPSET='glynn';
+    GRASS_DB_ENCODING='ascii';
+    GRASS_GUI='text';
+    MONITOR='x0';
+    \endcode
+    
     @param args
     @param kwargs
 
@@ -410,7 +436,15 @@ def parse_key_val(s, sep = '=', dflt = None, val_type = None, vsep = None):
 
 def gisenv():
     """Returns the output from running g.gisenv (with no arguments), as a
-    dictionary.
+    dictionary. Example:
+
+    \code
+    >>> env = grass.gisenv()
+    >>> print env['GISDBASE']
+    /opt/grass-data
+    \endcode
+
+    @return list of GRASS variables
     """
     s = read_command("g.gisenv", flags='n')
     return parse_key_val(s)
@@ -418,7 +452,19 @@ def gisenv():
 # interface to g.region
 
 def region():
-    """Returns the output from running "g.region -g", as a dictionary."""
+    """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
+
+    @return dictionary of region values
+    """
     s = read_command("g.region", flags='g')
     return parse_key_val(s, val_type = float)
 
@@ -443,8 +489,17 @@ def del_temp_region():
 # interface to g.findfile
 
 def find_file(name, element = 'cell', mapset = None):
-    """Returns the output from running g.findfile as a dictionary.
-
+    """Returns the output from running g.findfile as a
+    dictionary. Example:
+
+    \code
+    >>> result = grass.find_file('fields', element = 'vector')
+    >>> print result['fullname']
+    fields@PERMANENT
+    >>> print result['file']
+    /opt/grass-data/spearfish60/PERMANENT/vector/fields
+    \endcode
+    
     @param name file name
     @param element element type (default 'cell')
     @param mapset mapset name (default all mapsets in search path)
@@ -458,8 +513,13 @@ def find_file(name, element = 'cell', mapset = None):
 
 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.
+    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
+    
     @param type element type
     """
     dashes_re = re.compile("^----+$")
@@ -512,17 +572,32 @@ def _concat(xs):
 
 def list_pairs(type):
     """Returns the output from running g.list, as a list of (map, mapset)
-    pairs.
+    pairs. Example:
+
+    \code
+    >>> grass.list_pairs('rast')
+    [('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...
+    \endcode
 
     @param type element type
+
+    @return list of tuples (map, mapset)
     """
     return _concat([[(map, mapset) for map in maps]
 		    for mapset, maps in list_grouped(type).iteritems()])
 
 def list_strings(type):
-    """Returns the output from running g.list, as a list of qualified names.
+    """Returns the output from running g.list, as a list of qualified
+    names. Example:
+
+    \code
+    >>> grass.list_strings('rast')
+    ['aspect@PERMANENT', 'erosion1@PERMANENT', 'quads@PERMANENT', 'soils@PERMANENT', ...
+    \endcode
 
     @param element type
+
+    @return list of strings ('map@mapset')
     """
     return ["%s@%s" % pair for pair in list_pairs(type)]
 
@@ -550,10 +625,19 @@ def parse_color(val, dflt = None):
     """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.
+    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
 
     @param val color value
     @param dflt default color value
+
+    @return tuple RGB
     """
     if val in named_colors:
         return named_colors[val]

lib/python/grasspythonlib.dox

@@ -1,280 +1,193 @@
-/*! \page pythonlib GRASS 7 Python scripting library
+/*! \page pythonlib GRASS Python scripting library
 
 by GRASS Development Team (http://grass.osgeo.org)
 
 \section intro Introduction
 
-The code in lib/python/ provides "grass.script" in order to support GRASS 
-scripts written in Python. The scripts/ directory of GRASS contains a
-series of examples actually provided to the end users.
+The code in <tt>lib/python/</tt> provides <b>grass.script</b> in order
+to support GRASS scripts written in Python. The <tt>scripts/</tt>
+directory of GRASS contains a series of examples actually provided to
+the end users.
 
 See code in:
-<ul>
-<li>core.py</li>
-<li>db.py</li>
-<li>raster.py</li>
-<li>vector.py</li>
-</ul>
 
-\section scripting GRASS scripting tasks for Python provided by "grass.script".
+ - core.py
+ - db.py
+ - raster.py
+ - vector.py
 
-Usage:
+<h2>Table of content</h2>
 
-\code
-from grass.script import core[,db[,raster,[vector]]] as grass
-\endcode
+ - \subpage scripting
+ - \subpage modules
+  - \subpage core
+  - \subpage db
+  - \subpage raster
+  - \subpage vector
 
-\section make_command
+\section scripting GRASS scripting tasks for Python provided by "grass.script"
 
-\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:
+Usage:
 
 \code
->>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
-['g.message', '-w', 'message=this is a warning']
+from grass.script import core[,db[,raster,[vector]]] as grass
 \endcode
 
+e.g. to import functions from "core" and "vector" modules use
 
-\section start_command
 \code
-def start_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **kwargs):
+from grass.script import core, vector as grass
 \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:
+Sample script
 
 \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='spearfish60';
-MAPSET='glynn';
-GRASS_DB_ENCODING='ascii';
-GRASS_GUI='text';
-MONITOR='x0';
-\endcode
-
+#!/usr/bin/env python
 
-\section pipe_command
-\code
-def pipe_command(*args, **kwargs):
-\endcode
+#%Module
+#% description: Checks if vector map is 3D
+#% keywords: vector
+#%End
+#%option
+#% key: map
+#% type: string
+#% gisprompt: old,vector,vector
+#% key_desc: name
+#% description: Name of vector map 
+#% required: yes
+#%end
 
-Passes all arguments to start_command, but also adds
-"stdout = subprocess.PIPE". Returns the Popen object. Example:
+import sys
+from grass.script import core as grass
 
-\code
->>> p = grass.pipe_command("g.gisenv")
->>> print p
-<subprocess.Popen object at 0xb7c12f6c>
->>> print p.communicate()[0]
-GISDBASE='/opt/grass-data';
-LOCATION_NAME='spearfish60';
-MAPSET='glynn';
-GRASS_DB_ENCODING='ascii';
-GRASS_GUI='text';
-MONITOR='x0';
-\endcode
+def main():
+    info = grass.parse_command('v.info',
+                               flags = 't',
+                               map = options['map'])
+    if info['map3d'] == '1':
+        print 'Vector map is 3D'
+    else:
+        print 'Vector map is 2D'
 
+    return 0
 
-\section run_command
-\code
-def run_command(*args, **kwargs):
+if __name__ == "__main__":
+    options, flags = grass.parser()
+    sys.exit(main())
 \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 modules List of modules
 
+\subsection core Core
 
-\section read_command
-\code
-def read_command(*args, **kwargs):
-\endcode
+<b>GRASS-oriented interface to subprocess module</b>
 
-Passes all arguments to start_command, then waits for the process to
-complete, returning its stdout (i.e. similar to shell "backticks").
+ - exec_command()
 
+ - feed_command()
 
-\section messages
-\code
-def message(msg, flag = None):
-def debug(msg):
-def verbose(msg):
-def info(msg):
-def warning(msg):
-def error(msg):
-\endcode
+ - make_command()
 
-These all run g.message, differing only in which flag (if any) is used.
+ - parse_command()
 
+ - pipe_command()
 
-\section fatal
-\code
-def fatal(msg):
-\endcode
+ - read_command()
 
-Like error(), but also calls sys.exit(1).
+ - run_command()
 
+ - start_command()
 
-\section parser
-\code
-def parser():
-\endcode
+ - write_command()
 
-Interface to g.parser, intended to be run from the top-level, e.g.:
+<b>Interface to g.message</b>
 
-\code
-	if __name__ == "__main__":
-	    options, flags = grass.parser()
-	    main()
-\endcode
+These all run g.message, differing only in which flag (if any) is
+used. fatal() is error(), but also calls sys.exit(1).
 
-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.
+ - debug()
 
+ - error()
 
-\section tempfile
-\code
-def tempfile():
-\endcode
+ - fatal()
 
-Returns the name of a temporary file, created with g.tempfile.
+ - info()
 
+ - message()
 
-\section gisenv
-\code
-def gisenv():
-\endcode
+ - verbose()
 
-Returns the output from running g.gisenv (with no arguments), as a
-dictionary. Example:
+ - warning()
 
-\code
->>> env = grass.gisenv()
->>> print env['GISDBASE']
-/opt/grass-data
-\endcode
+<b>Interface to g.parser</b>
 
+Interface to g.parser, intended to be run from the top-level, e.g.
 
-\section region
 \code
-def region():
+	if __name__ == "__main__":
+	    options, flags = grass.parser()
+	    main()
 \endcode
 
-Returns the output from running "g.region -g", as a dictionary. 
-Example:
+ - parser()
 
-\code
->>> region = grass.region()
->>> [region[key] for key in "nsew"]
-['4928000', '4914020', '609000', '590010']
->>> (region['nsres'], region['ewres'])
-('30', '30')
-\endcode
+<b>Interface to g.tempfile</b>
 
+Returns the name of a temporary file, created with g.tempfile.
 
-\section use_temp_region
-\code
-def use_temp_region():
-\endcode
+ - tempfile()
 
-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.
+<b>Key-value parsers</b>
 
+ - parse_key_val()
 
-\section del_temp_region
-\code
-def del_temp_region():
-\endcode
+<b>Interface to g.gisenv</b>
 
-Unsets WIND_OVERRIDE and removes any region named by it.
+ - gisenv()
 
+<b>Interface to g.region</b>
 
-\section find_file
-\code
-def find_file(name, element = 'cell'):
-\endcode
+ - del_temp_region()
 
-Returns the output from running g.findfile as a dictionary. Example:
+ - region()
 
-\code
->>> result = grass.find_file('fields', element = 'vector')
->>> print result['fullname']
-fields@PERMANENT
->>> print result['file']
-/opt/grass-data/spearfish60/PERMANENT/vector/fields
-\endcode
+ - use_temp_region()
 
+<b>Interface to g.findfile</b>
 
-\section list_grouped
-\code
-def list_grouped(type):
-\endcode
+ - find_file()
 
-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:
+<b>Interface to g.list</b>
 
-\code
->>> grass.list_grouped('rast')['PERMANENT']
-['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...
-\endcode
+ - list_grouped()
 
+ - list_pairs()
 
-\section list_pairs
-\code
-def list_pairs(type):
+ - list_strings()
 
-Returns the output from running g.list, as a list of (map, mapset)
-pairs. Example:
+ - mlist_grouped()
 
-\code
->>> grass.list_pairs('rast')
-[('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...
-\endcode
+<b>Color parsing</b>
 
+ - parse_color()
 
-\section list_strings
-\code
-def list_strings(type):
-\endcode
+<b>Check GRASS environment variables</b>
 
-Returns the output from running g.list, as a list of qualified names. 
-Example:
+ - overwrite()
 
-\code
->>> grass.list_strings('rast')
-['aspect@PERMANENT', 'erosion1@PERMANENT', 'quads@PERMANENT', 'soils@PERMANENT', ...
-\endcode
+ - verbosity()
 
+<b>Various utilities, not specific to GRASS</b>
+ 
+ - basename()
 
-\section parse_color
-\code
-def parse_color(val, dflt = None):
-\endcode
+ - find_program()
 
-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:
+ - try_remove()
 
-\code
->>> grass.parse_color("red")
-(1.0, 0.0, 0.0)
->>> grass.parse_color("255:0:0")
-(1.0, 0.0, 0.0)
-\endcode
+ - try_rmdir()
+
+ - float_or_dms()
 
 */