[GRASS-SVN] r37561 - grass/branches/releasebranch_6_4/lib/python
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu May 28 04:22:54 EDT 2009
Author: martinl
Date: 2009-05-28 04:22:54 -0400 (Thu, 28 May 2009)
New Revision: 37561
Modified:
grass/branches/releasebranch_6_4/lib/python/core.py
grass/branches/releasebranch_6_4/lib/python/db.py
grass/branches/releasebranch_6_4/lib/python/raster.py
grass/branches/releasebranch_6_4/lib/python/vector.py
Log:
parse doc strings by doxygen
(merge from devbr6, r37560)
Modified: grass/branches/releasebranch_6_4/lib/python/core.py
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/core.py 2009-05-28 08:19:45 UTC (rev 37560)
+++ grass/branches/releasebranch_6_4/lib/python/core.py 2009-05-28 08:22:54 UTC (rev 37561)
@@ -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/releasebranch_6_4/lib/python/db.py
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/db.py 2009-05-28 08:19:45 UTC (rev 37560)
+++ grass/branches/releasebranch_6_4/lib/python/db.py 2009-05-28 08:22:54 UTC (rev 37561)
@@ -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/releasebranch_6_4/lib/python/raster.py
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/raster.py 2009-05-28 08:19:45 UTC (rev 37560)
+++ grass/branches/releasebranch_6_4/lib/python/raster.py 2009-05-28 08:22:54 UTC (rev 37561)
@@ -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/releasebranch_6_4/lib/python/vector.py
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/vector.py 2009-05-28 08:19:45 UTC (rev 37560)
+++ grass/branches/releasebranch_6_4/lib/python/vector.py 2009-05-28 08:22:54 UTC (rev 37561)
@@ -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