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

svn_grass at osgeo.org svn_grass at osgeo.org
Thu May 28 04:19:46 EDT 2009


Author: martinl
Date: 2009-05-28 04:19:45 -0400 (Thu, 28 May 2009)
New Revision: 37560

Modified:
   grass/branches/develbranch_6/lib/python/core.py
   grass/branches/develbranch_6/lib/python/db.py
   grass/branches/develbranch_6/lib/python/raster.py
   grass/branches/develbranch_6/lib/python/vector.py
Log:
parse doc strings by doxygen
      (mmerge from trunk, r37559)


Modified: grass/branches/develbranch_6/lib/python/core.py
===================================================================
--- grass/branches/develbranch_6/lib/python/core.py	2009-05-28 08:15:59 UTC (rev 37559)
+++ grass/branches/develbranch_6/lib/python/core.py	2009-05-28 08:19:45 UTC (rev 37560)
@@ -1,5 +1,4 @@
-"""
- at package grass.script.core
+"""!@package grass.script.core
 
 @brief GRASS Python scripting module
 
@@ -70,11 +69,22 @@
     return str(val)
 
 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
+    """!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
+
+    @param prog GRASS module
+    @param flags flags to be used
+    @param overwrite True to enable overwriting the output (--o)
+    @param quiet run quietly (--q)
+    @param verbose run verbosely (--v)
+    @param options
+
+    @return list of arguments
     """
     args = [prog]
     if overwrite:
@@ -93,7 +103,7 @@
     return args
 
 def start_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **kwargs):
-    """Returns a Popen object with the command created by make_command.
+    """!Returns a Popen object with the command created by make_command.
     Accepts any of the arguments which Popen() accepts apart from "args"
     and "shell".
 
@@ -111,7 +121,7 @@
     \endcode
     
     @param prog GRASS module
-    @param flag flags to be used
+    @param flags flags to be used
     @param overwrite True to enable overwriting the output (--o)
     @param quiet run quietly (--q)
     @param verbose run verbosely (--v)
@@ -130,7 +140,7 @@
     return Popen(args, **popts)
 
 def run_command(*args, **kwargs):
-    """Passes all arguments to start_command, then waits for the process to
+    """!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.
     """
@@ -138,7 +148,7 @@
     return ps.wait()
 
 def pipe_command(*args, **kwargs):
-    """Passes all arguments to start_command, but also adds
+    """!Passes all arguments to start_command, but also adds
     "stdout = PIPE". Returns the Popen object.
 
     \code
@@ -163,21 +173,21 @@
     return start_command(*args, **kwargs)
 
 def feed_command(*args, **kwargs):
-    """Passes all arguments to start_command, but also adds
+    """!Passes all arguments to start_command, but also adds
     "stdin = PIPE". Returns the Popen object.
     """
     kwargs['stdin'] = PIPE
     return start_command(*args, **kwargs)
 
 def read_command(*args, **kwargs):
-    """Passes all arguments to pipe_command, then waits for the process to
+    """!Passes all arguments to pipe_command, then waits for the process to
     complete, returning its stdout (i.e. similar to shell `backticks`).
     """
     ps = pipe_command(*args, **kwargs)
     return ps.communicate()[0]
 
 def parse_command(*args, **kwargs):
-    """Passes all arguments to read_command, then parses the output by
+    """!Passes all arguments to read_command, then parses the output by
     parse_key_val().
 
     Parsing function can be optionally given by <b>parse</b> parameter
@@ -203,7 +213,7 @@
     return parse(res, **parse_args)
 
 def write_command(*args, **kwargs):
-    """Passes all arguments to feed_command, with the string specified
+    """!Passes all arguments to feed_command, with the string specified
     by the 'stdin' argument fed to the process' stdin.
     """
     stdin = kwargs['stdin']
@@ -213,7 +223,17 @@
     return p.wait()
 
 def exec_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, env = None, **kwargs):
-    """Interface to os.execvpe(), but with the make_command() interface."""
+    """!Interface to os.execvpe(), but with the make_command() interface.
+
+    @param prog GRASS module
+    @param flags flags to be used
+    @param overwrite True to enable overwriting the output (--o)
+    @param quiet run quietly (--q)
+    @param verbose run verbosely (--v)
+    @param env environment variable (default os.environ)
+    @param kwargs
+    """
+>>>>>>> .merge-right.r37559
     args = make_command(prog, flags, overwrite, quiet, verbose, **kwargs)
     if env == None:
 	env = os.environ
@@ -222,31 +242,68 @@
 # interface to g.message
 
 def message(msg, flag = None):
-    """Display a message using g.message"""
+    """!Display a message using g.message
+
+    @param msg message to be displayed
+    @param flag flags (given as string)
+
+    @return g.message's exit code
+    """
     run_command("g.message", flags = flag, message = msg)
 
 def debug(msg, debug = 1):
-    """Display a debugging message using g.message -d"""
+    """!Display a debugging message using g.message -d
+
+    @param msg message to be displayed
+    @param debug debug level (0-5)
+
+    @return g.message's exit code
+    """
     run_command("g.message", flags = 'd', message = msg, debug = debug)
     
 def verbose(msg):
-    """Display a verbose message using g.message -v"""
+    """!Display a verbose message using g.message -v
+    
+    @param msg message to be displayed
+
+    @return g.message's exit code
+    """
     message(msg, flag = 'v')
 
 def info(msg):
-    """Display an informational message using g.message -i"""
+    """!Display an informational message using g.message -i
+
+    @param msg message to be displayed
+
+    @return g.message's exit code
+    """
     message(msg, flag = 'i')
 
 def warning(msg):
-    """Display a warning message using g.message -w"""
+    """!Display a warning message using g.message -w
+
+    @param msg message to be displayed
+
+    @return g.message's exit code
+    """
     message(msg, flag = 'w')
 
 def error(msg):
-    """Display an error message using g.message -e"""
+    """!Display an error message using g.message -e
+
+    @param msg message to be displayed
+
+    @return g.message's exit code
+    """
     message(msg, flag = 'e')
 
 def fatal(msg):
-    """Display an error message using g.message -e, then abort"""
+    """!Display an error message using g.message -e, then abort
+
+    @param msg message to be displayed
+
+    @return g.message's exit code
+    """
     error(msg)
     sys.exit(1)
 
@@ -265,7 +322,7 @@
     return (options, flags)
 
 def parser():
-    """Interface to g.parser, intended to be run from the top-level, e.g.:
+    """!Interface to g.parser, intended to be run from the top-level, e.g.:
 
 	if __name__ == "__main__":
 	    options, flags = grass.parser()
@@ -304,13 +361,13 @@
 # interface to g.tempfile
 
 def tempfile():
-    """Returns the name of a temporary file, created with g.tempfile."""
+    """!Returns the name of a temporary file, created with g.tempfile."""
     return read_command("g.tempfile", pid = os.getpid()).strip()
 
 # key-value parsers
 
 def parse_key_val(s, sep = '=', dflt = None, val_type = None, vsep = None):
-    """Parse a string into a dictionary, where entries are separated
+    """!Parse a string into a dictionary, where entries are separated
     by newlines and the key and value are separated by `sep' (default: `=')
     """
     result = {}
@@ -343,7 +400,7 @@
 # interface to g.gisenv
 
 def gisenv():
-    """Returns the output from running g.gisenv (with no arguments), as a
+    """!Returns the output from running g.gisenv (with no arguments), as a
     dictionary. Example:
 
     \code
@@ -360,7 +417,7 @@
 # interface to g.region
 
 def region():
-    """Returns the output from running "g.region -g", as a
+    """!Returns the output from running "g.region -g", as a
     dictionary. Example:
 
     \code
@@ -377,7 +434,7 @@
     return parse_key_val(s, val_type = float)
 
 def use_temp_region():
-    """Copies the current region to a temporary region with "g.region save=",
+    """!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.
     """
@@ -387,7 +444,7 @@
     atexit.register(del_temp_region)
 
 def del_temp_region():
-    """Unsets WIND_OVERRIDE and removes any region named by it."""
+    """!Unsets WIND_OVERRIDE and removes any region named by it."""
     try:
 	name = os.environ.pop('WIND_OVERRIDE')
 	run_command("g.remove", quiet = True, region = name)
@@ -397,7 +454,7 @@
 # interface to g.findfile
 
 def find_file(name, element = 'cell', mapset = None):
-    """Returns the output from running g.findfile as a
+    """!Returns the output from running g.findfile as a
     dictionary. Example:
 
     \code
@@ -420,7 +477,7 @@
 # interface to g.list
 
 def list_grouped(type):
-    """Returns the output from running g.list, as a dictionary where the keys
+    """!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
@@ -449,8 +506,9 @@
     return result
 
 def mlist_grouped(type, mapset = None, pattern = None):
-    """Returns the output from running g.mlist, as a dictionary where the keys
+    """!Returns the output from running g.mlist, as a dictionary where the keys
     are mapset names and the values are lists of maps in that mapset. 
+    @param pattern pattern string
     """
     result = {}
     mapset_element = None
@@ -476,7 +534,7 @@
     return result
 
 def list_pairs(type):
-    """Returns the output from running g.list, as a list of (map, mapset)
+    """!Returns the output from running g.list, as a list of (map, mapset)
     pairs. Example:
 
     \code
@@ -492,7 +550,7 @@
 		    for mapset, maps in list_grouped(type).iteritems()])
 
 def list_strings(type):
-    """Returns the output from running g.list, as a list of qualified
+    """!Returns the output from running g.list, as a list of qualified
     names. Example:
 
     \code
@@ -500,9 +558,9 @@
     ['aspect at PERMANENT', 'erosion1 at PERMANENT', 'quads at PERMANENT', 'soils at PERMANENT', ...
     \endcode
 
-    @param element type
-
-    @return list of strings ('map at mapset')
+    @param type element type
+    
+    @return list of strings ('map@@mapset')
     """
     return ["%s@%s" % pair for pair in list_pairs(type)]
 
@@ -527,7 +585,7 @@
     "indigo":  (0.00, 0.50, 1.00)}
 
 def parse_color(val, dflt = None):
-    """Parses the string "val" as a GRASS colour, which can be either one of
+    """!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:
@@ -556,14 +614,14 @@
 # check GRASS_OVERWRITE
 
 def overwrite():
-    """Return True if existing files may be overwritten"""
+    """!Return True if existing files may be overwritten"""
     owstr = 'GRASS_OVERWRITE'
     return owstr in os.environ and os.environ[owstr] != '0'
 
 # check GRASS_VERBOSE
 
 def verbosity():
-    """Return the verbosity level selected by GRASS_VERBOSE"""
+    """!Return the verbosity level selected by GRASS_VERBOSE"""
     vbstr = os.getenv('GRASS_VERBOSE')
     if vbstr:
 	return int(vbstr)
@@ -575,7 +633,7 @@
 # basename inc. extension stripping
 
 def basename(path, ext = None):
-    """Remove leading directory components and an optional extension
+    """!Remove leading directory components and an optional extension
     from the specified path
     """
     name = os.path.basename(path)
@@ -589,7 +647,7 @@
 # find a program (replacement for "which")
 
 def find_program(pgm, args = []):
-    """Attempt to run a program, with optional arguments. Return False
+    """!Attempt to run a program, with optional arguments. Return False
     if the attempt failed due to a missing executable, True otherwise
     """
     nuldev = file(os.devnull, 'w+')
@@ -604,7 +662,7 @@
 # try to remove a file, without complaints
 
 def try_remove(path):
-    """Attempt to remove a file; no exception is generated if the
+    """!Attempt to remove a file; no exception is generated if the
     attempt fails.
     """
     try:
@@ -615,7 +673,7 @@
 # try to remove a directory, without complaints
 
 def try_rmdir(path):
-    """Attempt to remove a directory; no exception is generated if the
+    """!Attempt to remove a directory; no exception is generated if the
     attempt fails.
     """
     try:
@@ -624,4 +682,10 @@
 	pass
 
 def float_or_dms(s):
+    """!Convert DMS to float.
+
+    @param s DMS value
+
+    @return float value
+    """
     return sum(float(x) / 60 ** n for (n, x) in enumerate(s.split(':')))

Modified: grass/branches/develbranch_6/lib/python/db.py
===================================================================
--- grass/branches/develbranch_6/lib/python/db.py	2009-05-28 08:15:59 UTC (rev 37559)
+++ grass/branches/develbranch_6/lib/python/db.py	2009-05-28 08:19:45 UTC (rev 37560)
@@ -1,5 +1,4 @@
-"""
- at package grass.script.db
+"""!@package grass.script.db
 
 @brief GRASS Python scripting module
 
@@ -29,7 +28,7 @@
 # run "db.describe -c ..." and parse output
 
 def db_describe(table, **args):
-    """Return the list of columns for a database table
+    """!Return the list of columns for a database table
     (interface to `db.describe -c'). Example:
     
     \code
@@ -67,7 +66,7 @@
 # run "db.connect -p" and parse output
 
 def db_connection():
-    """Return the current database connection parameters
+    """!Return the current database connection parameters
     (interface to `db.connect -p'). Example:
 
     \code

Modified: grass/branches/develbranch_6/lib/python/raster.py
===================================================================
--- grass/branches/develbranch_6/lib/python/raster.py	2009-05-28 08:15:59 UTC (rev 37559)
+++ grass/branches/develbranch_6/lib/python/raster.py	2009-05-28 08:19:45 UTC (rev 37560)
@@ -1,5 +1,4 @@
-"""
- at package grass.script.raster
+"""!@package grass.script.raster
 
 @brief GRASS Python scripting module
 
@@ -32,7 +31,7 @@
 # add raster history
 
 def raster_history(map):
-    """Set the command history for a raster map to the command used to
+    """!Set the command history for a raster map to the command used to
     invoke the script (interface to `r.support').
 
     @return True on success
@@ -49,7 +48,7 @@
 # run "r.info -rgstmpud ..." and parse output
 
 def raster_info(map):
-    """Return information about a raster map (interface to
+    """!Return information about a raster map (interface to
     `r.info'). Example:
 
     \code
@@ -76,6 +75,11 @@
 # interface to r.mapcalc
 
 def mapcalc(exp, **kwargs):
+    """!Interface to r.mapcalc.
+
+    @param exp expression
+    @param kwargs
+    """
     t = string.Template(exp)
     e = t.substitute(**kwargs)
     if run_command('r.mapcalc', expression = e) != 0:

Modified: grass/branches/develbranch_6/lib/python/vector.py
===================================================================
--- grass/branches/develbranch_6/lib/python/vector.py	2009-05-28 08:15:59 UTC (rev 37559)
+++ grass/branches/develbranch_6/lib/python/vector.py	2009-05-28 08:19:45 UTC (rev 37560)
@@ -1,5 +1,4 @@
-"""
- at package grass.script.vector
+"""!@package grass.script.vector
 
 @brief GRASS Python scripting module
 
@@ -31,7 +30,7 @@
 # run "v.db.connect -g ..." and parse output
 
 def vector_db(map, **args):
-    """Return the database connection details for a vector map
+    """!Return the database connection details for a vector map
     (interface to `v.db.connect -g'). Example:
     
     \code
@@ -72,7 +71,7 @@
     return result
 
 def vector_layer_db(map, layer):
-    """Return the database connection details for a vector map layer.
+    """!Return the database connection details for a vector map layer.
     If db connection for given layer is not defined, fatal() is called."""
     try:
         f = vector_db(map)[int(layer)]
@@ -84,7 +83,7 @@
 # run "v.info -c ..." and parse output
 
 def vector_columns(map, layer = None, **args):
-    """Return a dictionary of the columns for the database table connected to
+    """!Return a dictionary of the columns for the database table connected to
     a vector map (interface to `v.info -c').
     """
     s = read_command('v.info', flags = 'c', map = map, layer = layer, quiet = True, **args)
@@ -99,7 +98,7 @@
 # add vector history
 
 def vector_history(map):
-    """Set the command history for a vector map to the command used to
+    """!Set the command history for a vector map to the command used to
     invoke the script (interface to `v.support').
     """
     run_command('v.support', map = map, cmdhist = os.environ['CMDLINE'])
@@ -107,7 +106,7 @@
 # run "v.info -t" and parse output
 
 def vector_info_topo(map):
-    """Return information about a vector map (interface to `v.info
+    """!Return information about a vector map (interface to `v.info
     -t'). Example:
 
     \code
@@ -127,7 +126,7 @@
 # interface for v.db.select
 
 def vector_db_select(map, layer = 1, **kwargs):
-    """Get attribute data of selected vector map layer.
+    """!Get attribute data of selected vector map layer.
 
     Function returns list of columns and dictionary of values ordered by
     key column value. Example:



More information about the grass-commit mailing list