[GRASS-SVN] r37349 - grass/trunk/lib/python
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu May 21 18:18:46 EDT 2009
Author: martinl
Date: 2009-05-21 18:18:45 -0400 (Thu, 21 May 2009)
New Revision: 37349
Modified:
grass/trunk/lib/python/core.py
grass/trunk/lib/python/db.py
grass/trunk/lib/python/grasspythonlib.dox
grass/trunk/lib/python/raster.py
grass/trunk/lib/python/vector.py
Log:
grass.script: fn description improved
Modified: grass/trunk/lib/python/core.py
===================================================================
--- grass/trunk/lib/python/core.py 2009-05-21 22:08:15 UTC (rev 37348)
+++ grass/trunk/lib/python/core.py 2009-05-21 22:18:45 UTC (rev 37349)
@@ -73,8 +73,19 @@
"""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 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 options
+
+ @return list of arguments
"""
args = [prog]
if overwrite:
@@ -96,6 +107,15 @@
"""Returns a Popen object with the command created by make_command.
Accepts any of the arguments which Popen() accepts apart from "args"
and "shell".
+
+ @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 = {}
@@ -111,6 +131,11 @@
"""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.
+
+ @param args
+ @param kwargs
+
+ @return exit code
"""
ps = start_command(*args, **kwargs)
return ps.wait()
@@ -118,6 +143,11 @@
def pipe_command(*args, **kwargs):
"""Passes all arguments to start_command, but also adds
"stdout = PIPE". Returns the Popen object.
+
+ @param args
+ @param kwargs
+
+ @return Popen object
"""
kwargs['stdout'] = PIPE
return start_command(*args, **kwargs)
@@ -125,6 +155,11 @@
def feed_command(*args, **kwargs):
"""Passes all arguments to start_command, but also adds
"stdin = PIPE". Returns the Popen object.
+
+ @param args
+ @param kwargs
+
+ @return Popen object
"""
kwargs['stdin'] = PIPE
return start_command(*args, **kwargs)
@@ -132,6 +167,11 @@
def read_command(*args, **kwargs):
"""Passes all arguments to pipe_command, then waits for the process to
complete, returning its stdout (i.e. similar to shell `backticks`).
+
+ @param args
+ @param kwargs
+
+ @return stdout
"""
ps = pipe_command(*args, **kwargs)
return ps.communicate()[0]
@@ -146,6 +186,11 @@
@code
parse_command(..., parse = (grass.parse_key_val, { 'sep' : ':' }))
@endcode
+
+ @param args
+ @param kwargs
+
+ @return parsed module output
"""
parse = None
if kwargs.has_key('parse'):
@@ -165,6 +210,11 @@
def write_command(*args, **kwargs):
"""Passes all arguments to feed_command, with the string specified
by the 'stdin' argument fed to the process' stdin.
+
+ @param args
+ @param kwargs
+
+ @return return code
"""
stdin = kwargs['stdin']
p = feed_command(*args, **kwargs)
@@ -173,7 +223,16 @@
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 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 env environment variable (default os.environ)
+ @param kwargs
+ """
args = make_command(prog, flags, overwrite, quiet, verbose, **kwargs)
if env == None:
env = os.environ
@@ -182,31 +241,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)
@@ -227,9 +323,11 @@
def parser():
"""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
@@ -272,6 +370,14 @@
def parse_key_val(s, sep = '=', dflt = None, val_type = None, vsep = None):
"""Parse a string into a dictionary, where entries are separated
by newlines and the key and value are separated by `sep' (default: `=')
+
+ @param s string to be parsed
+ @param sep key/value separator
+ @param dflt default value to be used
+ @param val_type value type (None for no cast)
+ @param vsep vertical separator (default os.linesep)
+
+ @return parsed input (dictionary of keys/values)
"""
result = {}
@@ -337,7 +443,14 @@
# 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.
+
+ @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 +458,9 @@
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.
+
+ @param type element type
"""
dashes_re = re.compile("^----+$")
mapset_re = re.compile("<(.*)>")
@@ -368,6 +483,9 @@
def mlist_grouped(type, mapset = None, pattern = None):
"""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 type element type
+ @param mapset mapset name (default all mapset in search path)
"""
result = {}
mapset_element = None
@@ -395,12 +513,17 @@
def list_pairs(type):
"""Returns the output from running g.list, as a list of (map, mapset)
pairs.
+
+ @param type element type
"""
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.
+
+ @param element type
+ """
return ["%s@%s" % pair for pair in list_pairs(type)]
# color parsing
@@ -428,6 +551,9 @@
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.
+
+ @param val color value
+ @param dflt default color value
"""
if val in named_colors:
return named_colors[val]
@@ -462,6 +588,9 @@
def basename(path, ext = None):
"""Remove leading directory components and an optional extension
from the specified path
+
+ @param path path
+ @param ext extension
"""
name = os.path.basename(path)
if not ext:
@@ -476,6 +605,9 @@
def find_program(pgm, args = []):
"""Attempt to run a program, with optional arguments. Return False
if the attempt failed due to a missing executable, True otherwise
+
+ @param pgm program name
+ @param args list of arguments
"""
nuldev = file(os.devnull, 'w+')
try:
@@ -491,6 +623,8 @@
def try_remove(path):
"""Attempt to remove a file; no exception is generated if the
attempt fails.
+
+ @param path path
"""
try:
os.remove(path)
@@ -502,6 +636,8 @@
def try_rmdir(path):
"""Attempt to remove a directory; no exception is generated if the
attempt fails.
+
+ @param path path
"""
try:
os.rmdir(path)
@@ -509,4 +645,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/trunk/lib/python/db.py
===================================================================
--- grass/trunk/lib/python/db.py 2009-05-21 22:08:15 UTC (rev 37348)
+++ grass/trunk/lib/python/db.py 2009-05-21 22:18:45 UTC (rev 37349)
@@ -26,11 +26,14 @@
from core import *
-# run "db.describe -c ..." and parse output
-
def db_describe(table, **args):
"""Return the list of columns for a database table
(interface to `db.describe -c').
+
+ @param table table name
+ @param args
+
+ @return parsed module output
"""
s = read_command('db.describe', flags = 'c', table = table, **args)
if not s:
@@ -59,4 +62,3 @@
"""
s = read_command('db.connect', flags = 'p')
return parse_key_val(s, sep = ':')
-
Modified: grass/trunk/lib/python/grasspythonlib.dox
===================================================================
--- grass/trunk/lib/python/grasspythonlib.dox 2009-05-21 22:08:15 UTC (rev 37348)
+++ grass/trunk/lib/python/grasspythonlib.dox 2009-05-21 22:18:45 UTC (rev 37349)
@@ -1,17 +1,27 @@
-/*! \page pythonlib GRASS 7 Python library
+/*! \page pythonlib GRASS 7 Python scripting library
by GRASS Development Team
http://grass.osgeo.org
-See code in: grass.py
+See code in:
+<ul>
+<li>core.py</li>
+<li>db.py</li>
+<li>raster.py</li>
+<li>vector.py</li>
-\section scripting GRASS scripting tasks for Python provided by "grass.py".
+\section scripting GRASS scripting tasks for Python provided by "grass.script".
-Usage: "import grass"
+Usage:
+\code
+from grass.script import core[,db[,raster,[vector]]] as grass
+\endcode
+
\section make_command
+
\code
def make_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **options):
\endcode
Modified: grass/trunk/lib/python/raster.py
===================================================================
--- grass/trunk/lib/python/raster.py 2009-05-21 22:08:15 UTC (rev 37348)
+++ grass/trunk/lib/python/raster.py 2009-05-21 22:18:45 UTC (rev 37349)
@@ -35,6 +35,8 @@
"""Set the command history for a raster map to the command used to
invoke the script (interface to `r.support').
+ @param map map name
+
@return True on success
@return False on failure
"""
@@ -49,7 +51,12 @@
# run "r.info -rgstmpud ..." and parse output
def raster_info(map):
- """Return information about a raster map (interface to `r.info')."""
+ """Return information about a raster map (interface to `r.info').
+
+ @param map map name
+
+ @return parsed modile output
+ """
s = read_command('r.info', flags = 'rgstmpud', map = map)
kv = parse_key_val(s)
for k in ['min', 'max', 'north', 'south', 'east', 'west']:
@@ -61,6 +68,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/trunk/lib/python/vector.py
===================================================================
--- grass/trunk/lib/python/vector.py 2009-05-21 22:08:15 UTC (rev 37348)
+++ grass/trunk/lib/python/vector.py 2009-05-21 22:18:45 UTC (rev 37349)
@@ -35,6 +35,7 @@
(interface to `v.db.connect -g').
@param map vector map
+ @param args
@return dictionary { layer : { 'layer', 'table, 'database', 'driver', 'key' }
"""
@@ -66,7 +67,13 @@
def vector_layer_db(map, layer):
"""Return the database connection details for a vector map layer.
- If db connection for given layer is not defined, fatal() is called."""
+ If db connection for given layer is not defined, fatal() is called.
+
+ @param map map name
+ @param layer layer number
+
+ @return parsed output
+ """
try:
f = vector_db(map)[int(layer)]
except KeyError:
@@ -79,6 +86,12 @@
def vector_columns(map, layer = None, **args):
"""Return a dictionary of the columns for the database table connected to
a vector map (interface to `v.info -c').
+
+ @param map map name
+ @param layer layer number (None for all layers)
+ @param args
+
+ @return parsed output
"""
s = read_command('v.info', flags = 'c', map = map, layer = layer, quiet = True, **args)
result = {}
@@ -94,12 +107,21 @@
def vector_history(map):
"""Set the command history for a vector map to the command used to
invoke the script (interface to `v.support').
+
+ @param map mapname
+
+ @return v.support output
"""
run_command('v.support', map = map, cmdhist = os.environ['CMDLINE'])
# run "v.info -t" and parse output
def vector_info_topo(map):
- """Return information about a vector map (interface to `v.info -t')."""
+ """Return information about a vector map (interface to `v.info -t').
+
+ @param map map name
+
+ @return parsed output
+ """
s = read_command('v.info', flags = 't', map = map)
return parse_key_val(s, val_type = int)
More information about the grass-commit
mailing list