[GRASS-SVN] r56793 - grass/trunk/lib/python/script

[svn_grass at osgeo.org]

Author: hamish
Date: 2013-06-19 04:23:34 -0700 (Wed, 19 Jun 2013)
New Revision: 56793

Modified:
   grass/trunk/lib/python/script/core.py
Log:
add usage example for find_program, note that the exe needs to return with a non-zero exit code

Modified: grass/trunk/lib/python/script/core.py
===================================================================
--- grass/trunk/lib/python/script/core.py	2013-06-19 10:12:53 UTC (rev 56792)
+++ grass/trunk/lib/python/script/core.py	2013-06-19 11:23:34 UTC (rev 56793)
@@ -1159,11 +1159,25 @@
 
 def find_program(pgm, args = []):
     """!Attempt to run a program, with optional arguments.
+    You must call the program in a way that will return a successful
+    exit code. For GRASS modules this means you need to pass it some
+    valid CLI option, like "--help". For other programs a common
+    valid do-little option is "--version".
+    
+    Example:
 
+    @code
+    >>> grass.find_program('r.sun', ['help'])
+    True
+    >>> grass.find_program('gdalwarp', ['--version'])
+    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
     """
     nuldev = file(os.devnull, 'w+')