[GRASS-SVN] r37497 - grass/branches/releasebranch_6_4/lib/python
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue May 26 05:03:43 EDT 2009
Author: martinl
Date: 2009-05-26 05:03:43 -0400 (Tue, 26 May 2009)
New Revision: 37497
Modified:
grass/branches/releasebranch_6_4/lib/python/core.py
grass/branches/releasebranch_6_4/lib/python/grasspythonlib.dox
Log:
grass.script doxygen page updated
(merge from devbr6, r37496)
Modified: grass/branches/releasebranch_6_4/lib/python/core.py
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/core.py 2009-05-26 09:01:27 UTC (rev 37496)
+++ grass/branches/releasebranch_6_4/lib/python/core.py 2009-05-26 09:03:43 UTC (rev 37497)
@@ -96,6 +96,28 @@
"""Returns a Popen object with the command created by make_command.
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)
+ @param quiet run quietly (--q)
+ @param verbose run verbosely (--v)
+ @param kwargs
+
+ @return Popen object
"""
options = {}
popts = {}
@@ -118,6 +140,24 @@
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
+
+ @return Popen object
"""
kwargs['stdout'] = PIPE
return start_command(*args, **kwargs)
@@ -304,7 +344,15 @@
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)
@@ -312,7 +360,19 @@
# 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)
@@ -337,7 +397,23 @@
# 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 at 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)
+
+ @return parsed output of g.findfile
+ """
s = read_command("g.findfile", flags='n', element = element, file = name, mapset = mapset)
return parse_key_val(s)
@@ -345,7 +421,14 @@
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("^----+$")
mapset_re = re.compile("<(.*)>")
@@ -394,13 +477,33 @@
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 at PERMANENT', 'erosion1 at PERMANENT', 'quads at PERMANENT', 'soils at PERMANENT', ...
+ \endcode
+
+ @param element type
+
+ @return list of strings ('map at mapset')
+ """
return ["%s@%s" % pair for pair in list_pairs(type)]
# color parsing
@@ -427,7 +530,19 @@
"""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]
Modified: grass/branches/releasebranch_6_4/lib/python/grasspythonlib.dox
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/grasspythonlib.dox 2009-05-26 09:01:27 UTC (rev 37496)
+++ grass/branches/releasebranch_6_4/lib/python/grasspythonlib.dox 2009-05-26 09:03:43 UTC (rev 37497)
@@ -1,278 +1,193 @@
-/*! \page pythonlib GRASS 6 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>grass.py</li>
-</ul>
-</ul>
-\section scripting GRASS scripting tasks for Python provided by "grass".
+ - core.py
+ - db.py
+ - raster.py
+ - vector.py
-Usage:
+<h2>Table of content</h2>
-\code
-import 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
+Usage:
-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']
+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
+#%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
-\section pipe_command
-\code
-def pipe_command(*args, **kwargs):
-\endcode
+import sys
+from grass.script import core as grass
-Passes all arguments to start_command, but also adds
-"stdout = subprocess.PIPE". Returns the Popen object. Example:
+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'
-\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
+ 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 at 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 at PERMANENT', 'erosion1 at PERMANENT', 'quads at PERMANENT', 'soils at 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()
+
*/
More information about the grass-commit
mailing list