[GRASS-SVN] r56804 - grass/trunk/lib/python/script
svn_grass at osgeo.org
svn_grass at osgeo.org
Wed Jun 19 08:38:58 PDT 2013
Author: wenzeslaus
Date: 2013-06-19 08:38:57 -0700 (Wed, 19 Jun 2013)
New Revision: 56804
Modified:
grass/trunk/lib/python/script/core.py
Log:
pythonlib: turning documentation into doctests (for grass.core)
Modified: grass/trunk/lib/python/script/core.py
===================================================================
--- grass/trunk/lib/python/script/core.py 2013-06-19 15:22:59 UTC (rev 56803)
+++ grass/trunk/lib/python/script/core.py 2013-06-19 15:38:57 UTC (rev 56804)
@@ -104,7 +104,7 @@
>>> cmds = list(get_commands()[0])
>>> cmds.sort()
>>> cmds[:5]
- ['d.barscale', 'd.colorlist', 'd.colortable', 'd.erase', 'd.font']
+ ['d.barscale', 'd.colorlist', 'd.colortable', 'd.correlate', 'd.erase']
@endcode
"""
@@ -142,8 +142,9 @@
Popen() or call(). Example:
@code
- >>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
+ >>> make_command("g.message", flags = 'w', message = 'this is a warning')
['g.message', '-w', 'message=this is a warning']
+
@endcode
@param prog GRASS module
@@ -178,19 +179,20 @@
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]
+ @code
+ >>> p = start_command("g.gisenv", stdout = subprocess.PIPE)
+ >>> print p # doctest: +ELLIPSIS
+ <...Popen object at 0x...>
+ >>> print p.communicate()[0] # doctest: +SKIP
GISDBASE='/opt/grass-data';
LOCATION_NAME='spearfish60';
MAPSET='glynn';
GRASS_DB_ENCODING='ascii';
GUI='text';
MONITOR='x0';
- \endcode
+ @endcode
+
@param prog GRASS module
@param flags flags to be used (given as a string)
@param overwrite True to enable overwriting the output (<tt>--o</tt>)
@@ -233,19 +235,20 @@
"""!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]
+ @code
+ >>> p = pipe_command("g.gisenv")
+ >>> print p # doctest: +ELLIPSIS
+ <....Popen object at 0x...>
+ >>> print p.communicate()[0] # doctest: +SKIP
GISDBASE='/opt/grass-data';
LOCATION_NAME='spearfish60';
MAPSET='glynn';
GRASS_DB_ENCODING='ascii';
GUI='text';
MONITOR='x0';
- \endcode
+ @endcode
+
@param args list of unnamed arguments (see start_command() for details)
@param kwargs list of named arguments (see start_command() for details)
@@ -536,11 +539,14 @@
written using attribute syntax. Example:
\code
- >>> region = grass.region()
- >>> region['rows']
- 477
- >>> region.rows
- 477
+ >>> reg = KeyValue()
+ >>> reg['north'] = 489
+ >>> reg.north
+ 489
+ >>> reg.south = 205
+ >>> reg['south']
+ 205
+
\endcode
"""
@@ -721,12 +727,13 @@
"""!Returns the output from running g.gisenv (with no arguments), as a
dictionary. Example:
- \code
- >>> env = grass.gisenv()
- >>> print env['GISDBASE']
+ @code
+ >>> env = gisenv()
+ >>> print env['GISDBASE'] # doctest: +SKIP
/opt/grass-data
- \endcode
+ @endcode
+
@return list of GRASS variables
"""
s = read_command("g.gisenv", flags='n')
@@ -751,16 +758,19 @@
"""!Returns the output from running "g.region -g", as a
dictionary. Example:
- \param region3d True to get 3D region
+ @param region3d True to get 3D region
- \code
- >>> region = grass.region()
- >>> [region[key] for key in "nsew"]
- [228500.0, 215000.0, 645000.0, 630000.0]
- >>> (region['nsres'], region['ewres'])
- (10.0, 10.0)
- \endcode
+ @code
+ >>> curent_region = region()
+ >>> # obtain n, s, e and w values
+ >>> [curent_region[key] for key in "nsew"] # doctest: +ELLIPSIS
+ [..., ..., ..., ...]
+ >>> # obtain ns and ew resulutions
+ >>> (curent_region['nsres'], curent_region['ewres']) # doctest: +ELLIPSIS
+ (..., ...)
+ @endcode
+
@return dictionary of region values
"""
flgs = 'g'
@@ -878,14 +888,15 @@
"""!Returns the output from running g.findfile as a
dictionary. Example:
- \code
- >>> result = grass.find_file('fields', element = 'vector')
+ @code
+ >>> result = find_file('elevation', element='cell')
>>> print result['fullname']
- fields at PERMANENT
- >>> print result['file']
- /opt/grass-data/spearfish60/PERMANENT/vector/fields
- \endcode
+ elevation at PERMANENT
+ >>> print result['file'] # doctest: +ELLIPSIS
+ /.../PERMANENT/cell/elevation
+ @endcode
+
@param name file name
@param element element type (default 'cell')
@param mapset mapset name (default all mapsets in search path)
@@ -908,8 +919,9 @@
mapset. Example:
@code
- >>> grass.list_grouped('rast')['PERMANENT']
- ['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...
+ >>> list_grouped('rast')['PERMANENT'] # doctest: +ELLIPSIS
+ [..., 'lakes', ..., 'slope', ...
+
@endcode
@param type element type (rast, vect, rast3d, region, ...)
@@ -957,8 +969,9 @@
pairs. Example:
@code
- >>> grass.list_pairs('rast')
- [('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...
+ >>> list_pairs('rast') # doctest: +ELLIPSIS
+ [..., ('lakes', 'PERMANENT'), ..., ('slope', 'PERMANENT'), ...
+
@endcode
@param type element type (rast, vect, rast3d, region, ...)
@@ -975,8 +988,9 @@
names. Example:
@code
- >>> grass.list_strings('rast')
- ['aspect at PERMANENT', 'erosion1 at PERMANENT', 'quads at PERMANENT', 'soils at PERMANENT', ...
+ >>> list_strings('rast') # doctest: +ELLIPSIS
+ [..., 'lakes at PERMANENT', ..., 'slope at PERMANENT', ...
+
@endcode
@param type element type
@@ -1037,8 +1051,9 @@
mapset. Example:
@code
- >>> grass.mlist_grouped('rast', pattern='r*')['PERMANENT']
- ['railroads', 'roads', 'rstrct.areas', 'rushmore']
+ >>> mlist_grouped('vect', pattern='*roads*')['PERMANENT']
+ ['railroads', 'roadsmajor']
+
@endcode
@param type element type (rast, vect, rast3d, region, ...)
@@ -1098,13 +1113,14 @@
(r,g,b) triple whose components are floating point values between 0
and 1. Example:
- \code
- >>> grass.parse_color("red")
+ @code
+ >>> parse_color("red")
(1.0, 0.0, 0.0)
- >>> grass.parse_color("255:0:0")
+ >>> parse_color("255:0:0")
(1.0, 0.0, 0.0)
- \endcode
+ @endcode
+
@param val color value
@param dflt default color value
@@ -1167,6 +1183,24 @@
of os.environ.get("PATH"), or can be overridden with a custom search
path.
+ Example:
+
+ @code
+ >>> find_program('r.sun') # doctest: +ELLIPSIS
+ '.../bin/r.sun'
+ >>> bool(find_program('ls'))
+ True
+ >>> bool(find_program('gdalwarp'))
+ True
+
+ @endcode
+
+ @param pgm program name
+ @param args list of arguments
+
+ @return False if the attempt failed due to a missing executable
+ or non-zero return code
+ @return True otherwise
"""
# Check that a given file can be accessed with the correct mode.
# Additionally check that `file` is not a directory, as on Windows
@@ -1460,3 +1494,9 @@
return False
return True
+
+
+if __name__ == '__main__':
+ import doctest
+ doctest.testmod()
+
More information about the grass-commit
mailing list