[GRASS-SVN] r61156 - grass/trunk/lib/python/pygrass/modules/interface

svn_grass at osgeo.org svn_grass at osgeo.org
Fri Jul 4 07:01:41 PDT 2014


Author: zarch
Date: 2014-07-04 07:01:41 -0700 (Fri, 04 Jul 2014)
New Revision: 61156

Modified:
   grass/trunk/lib/python/pygrass/modules/interface/module.py
Log:
pygrass: Move and add documentation

Modified: grass/trunk/lib/python/pygrass/modules/interface/module.py
===================================================================
--- grass/trunk/lib/python/pygrass/modules/interface/module.py	2014-07-04 13:59:30 UTC (rev 61155)
+++ grass/trunk/lib/python/pygrass/modules/interface/module.py	2014-07-04 14:01:41 UTC (rev 61156)
@@ -1,131 +1,4 @@
 # -*- coding: utf-8 -*-
-"""
-Created on Tue Apr  2 18:41:27 2013
-
- at author: pietro
-
- at code
-
->>> import grass.pygrass.modules as pymod
->>> from subprocess import PIPE
->>> import copy
-
->>> region = pymod.Module("g.region")
->>> region.flags["p"].value = True
->>> region.flags["u"].value = True
->>> region.flags["3"].value = True
->>> region.get_bash()
-u'g.region -p -3 -u'
->>> new_region = copy.deepcopy(region)
->>> new_region.inputs["res"].value = "10"
->>> new_region.get_bash()
-u'g.region res=10 -p -3 -u'
-
->>> neighbors = pymod.Module("r.neighbors")
->>> neighbors.inputs["input"].value = "mapA"
->>> neighbors.outputs["output"].value = "mapB"
->>> neighbors.inputs["size"].value = 5
->>> neighbors.inputs["quantile"].value = 0.5
->>> neighbors.get_bash()
-u'r.neighbors input=mapA method=average size=5 quantile=0.5 output=mapB'
-
->>> new_neighbors1 = copy.deepcopy(neighbors)
->>> new_neighbors1.inputs["input"].value = "mapD"
->>> new_neighbors1.inputs["size"].value = 3
->>> new_neighbors1.inputs["quantile"].value = 0.5
->>> new_neighbors1.get_bash()
-u'r.neighbors input=mapD method=average size=3 quantile=0.5 output=mapB'
-
->>> new_neighbors2 = copy.deepcopy(neighbors)
->>> new_neighbors2(input="mapD", size=3, run_=False)
->>> new_neighbors2.get_bash()
-u'r.neighbors input=mapD method=average size=3 quantile=0.5 output=mapB'
-
->>> neighbors = pymod.Module("r.neighbors")
->>> neighbors.get_bash()
-u'r.neighbors method=average size=3'
-
->>> new_neighbors3 = copy.deepcopy(neighbors)
->>> new_neighbors3(input="mapA", size=3, output="mapB", run_=False)
->>> new_neighbors3.get_bash()
-u'r.neighbors input=mapA method=average size=3 output=mapB'
-
->>> mapcalc = pymod.Module("r.mapcalc", expression="test_a = 1",
-...                        overwrite=True, run_=False)
->>> mapcalc.run()
-Module('r.mapcalc')
->>> mapcalc.popen.returncode
-0
-
->>> colors = pymod.Module("r.colors", map="test_a", rules="-",
-...                        run_=False, stdout_=PIPE,
-...                        stderr_=PIPE, stdin_="1 red")
->>> colors.run()
-Module('r.colors')
->>> colors.popen.returncode
-0
->>> colors.inputs["stdin"].value
-u'1 red'
->>> colors.outputs["stdout"].value
-u''
->>> colors.outputs["stderr"].value.strip()
-"Color table for raster map <test_a> set to 'rules'"
-
->>> colors = pymod.Module("r.colors", map="test_a", rules="-",
-...                        run_=False, finish_=False, stdin_=PIPE)
->>> colors.run()
-Module('r.colors')
->>> stdout, stderr = colors.popen.communicate(input="1 red")
->>> colors.popen.returncode
-0
->>> stdout
->>> stderr
-
->>> colors = pymod.Module("r.colors", map="test_a", rules="-",
-...                        run_=False, finish_=False,
-...                        stdin_=PIPE, stderr_=PIPE)
->>> colors.run()
-Module('r.colors')
->>> stdout, stderr = colors.popen.communicate(input="1 red")
->>> colors.popen.returncode
-0
->>> stdout
->>> stderr.strip()
-"Color table for raster map <test_a> set to 'rules'"
-
-Run a second time
->>> colors.run()
-Module('r.colors')
->>> stdout, stderr = colors.popen.communicate(input="1 blue")
->>> colors.popen.returncode
-0
->>> stdout
->>> stderr.strip()
-"Color table for raster map <test_a> set to 'rules'"
-
-Multiple run test
->>> colors = pymod.Module("r.colors", map="test_a",
-...                                            color="ryb", run_=False)
->>> colors.run()
-Module('r.colors')
->>> colors(color="gyr")
->>> colors.run()
-Module('r.colors')
->>> colors(color="ryg")
->>> colors(stderr_=PIPE)
->>> colors.run()
-Module('r.colors')
->>> print(colors.outputs["stderr"].value.strip())
-Color table for raster map <test_a> set to 'ryg'
->>> colors(color="byg")
->>> colors(stdout_=PIPE)
->>> colors.run()
-Module('r.colors')
->>> print(colors.outputs["stderr"].value.strip())
-Color table for raster map <test_a> set to 'byg'
-
- at endcode
-"""
 from __future__ import (nested_scopes, generators, division, absolute_import,
                         with_statement, print_function, unicode_literals)
 import sys
@@ -162,12 +35,10 @@
        Usage:
 
        >>> import copy
-       >>> import grass.pygrass.modules as pymod
+       >>> from grass.pygrass.modules import Module, ParallelModuleQueue
        >>> mapcalc_list = []
-       >>> mapcalc = pymod.Module("r.mapcalc",
-       ...                        overwrite=True,
-       ...                        run_=False)
-       >>> queue = pymod.ParallelModuleQueue(max_num_procs=3)
+       >>> mapcalc = Module("r.mapcalc", overwrite=True, run_=False)
+       >>> queue = ParallelModuleQueue(max_num_procs=3)
        >>> for i in xrange(5):
        ...     new_mapcalc = copy.deepcopy(mapcalc)
        ...     mapcalc_list.append(new_mapcalc)
@@ -268,31 +139,155 @@
 
 
 class Module(object):
-    """
+    """This class is design to wrap/run/interact with the GRASS modules.
+
+    The class during the init phase read the XML description generate using
+    the ``--interface-description`` in order to understand which parameters
+    are required which optionals. ::
+
+        >>> from grass.pygrass.modules import Module
+        >>> from subprocess import PIPE
+        >>> import copy
+
+        >>> region = Module("g.region")
+        >>> region.flags.p = True  # set flags
+        >>> region.flags.u = True
+        >>> region.flags["3"].value = True  # set numeric flags
+        >>> region.get_bash()
+        u'g.region -p -3 -u'
+        >>> new_region = copy.deepcopy(region)
+        >>> new_region.inputs.res = "10"
+        >>> new_region.get_bash()
+        u'g.region res=10 -p -3 -u'
+
+        >>> neighbors = Module("r.neighbors")
+        >>> neighbors.inputs.input = "mapA"
+        >>> neighbors.outputs.output = "mapB"
+        >>> neighbors.inputs.size = 5
+        >>> neighbors.inputs.quantile = 0.5
+        >>> neighbors.get_bash()
+        u'r.neighbors input=mapA method=average size=5 quantile=0.5 output=mapB'
+
+        >>> new_neighbors1 = copy.deepcopy(neighbors)
+        >>> new_neighbors1.inputs.input = "mapD"
+        >>> new_neighbors1.inputs.size = 3
+        >>> new_neighbors1.inputs.quantile = 0.5
+        >>> new_neighbors1.get_bash()
+        u'r.neighbors input=mapD method=average size=3 quantile=0.5 output=mapB'
+
+        >>> new_neighbors2 = copy.deepcopy(neighbors)
+        >>> new_neighbors2(input="mapD", size=3, run_=False)
+        >>> new_neighbors2.get_bash()
+        u'r.neighbors input=mapD method=average size=3 quantile=0.5 output=mapB'
+
+        >>> neighbors = Module("r.neighbors")
+        >>> neighbors.get_bash()
+        u'r.neighbors method=average size=3'
+
+        >>> new_neighbors3 = copy.deepcopy(neighbors)
+        >>> new_neighbors3(input="mapA", size=3, output="mapB", run_=False)
+        >>> new_neighbors3.get_bash()
+        u'r.neighbors input=mapA method=average size=3 output=mapB'
+
+        >>> mapcalc = Module("r.mapcalc", expression="test_a = 1",
+        ...                  overwrite=True, run_=False)
+        >>> mapcalc.run()
+        Module('r.mapcalc')
+        >>> mapcalc.popen.returncode
+        0
+
+        >>> colors = Module("r.colors", map="test_a", rules="-",
+        ...                 run_=False, stdout_=PIPE,
+        ...                 stderr_=PIPE, stdin_="1 red")
+        >>> colors.run()
+        Module('r.colors')
+        >>> colors.popen.returncode
+        0
+        >>> colors.inputs["stdin"].value
+        u'1 red'
+        >>> colors.outputs["stdout"].value
+        u''
+        >>> colors.outputs["stderr"].value.strip()
+        "Color table for raster map <test_a> set to 'rules'"
+
+        >>> colors = Module("r.colors", map="test_a", rules="-",
+        ...                 run_=False, finish_=False, stdin_=PIPE)
+        >>> colors.run()
+        Module('r.colors')
+        >>> stdout, stderr = colors.popen.communicate(input="1 red")
+        >>> colors.popen.returncode
+        0
+        >>> stdout
+        >>> stderr
+
+        >>> colors = Module("r.colors", map="test_a", rules="-",
+        ...                 run_=False, finish_=False,
+        ...                 stdin_=PIPE, stderr_=PIPE)
+        >>> colors.run()
+        Module('r.colors')
+        >>> stdout, stderr = colors.popen.communicate(input="1 red")
+        >>> colors.popen.returncode
+        0
+        >>> stdout
+        >>> stderr.strip()
+        "Color table for raster map <test_a> set to 'rules'"
+
+        Run a second time
+        >>> colors.run()
+        Module('r.colors')
+        >>> stdout, stderr = colors.popen.communicate(input="1 blue")
+        >>> colors.popen.returncode
+        0
+        >>> stdout
+        >>> stderr.strip()
+        "Color table for raster map <test_a> set to 'rules'"
+
+        Multiple run test
+        >>> colors = Module("r.colors", map="test_a",
+        ...                                            color="ryb", run_=False)
+        >>> colors.run()
+        Module('r.colors')
+        >>> colors(color="gyr")
+        >>> colors.run()
+        Module('r.colors')
+        >>> colors(color="ryg")
+        >>> colors(stderr_=PIPE)
+        >>> colors.run()
+        Module('r.colors')
+        >>> print(colors.outputs["stderr"].value.strip())
+        Color table for raster map <test_a> set to 'ryg'
+        >>> colors(color="byg")
+        >>> colors(stdout_=PIPE)
+        >>> colors.run()
+        Module('r.colors')
+        >>> print(colors.outputs["stderr"].value.strip())
+        Color table for raster map <test_a> set to 'byg'
+
+    Often in the Module class you can find ``*args`` and ``kwargs`` annotation
+    in methods, like in the __call__ method.
     Python allow developers to not specify all the arguments and
-    keyword arguments of a method or function.
+    keyword arguments of a method or function. ::
 
-
         def f(*args):
             for arg in args:
                 print arg
 
-    therefore if we call the function like:
+    therefore if we call the function like: ::
 
-        >>> f('grass', 'gis', 'modules')
+        >>> f('grass', 'gis', 'modules')                     # doctest: +SKIP
         grass
         gis
         modules
 
-    or we can define a new list:
+    or we can define a new list: ::
 
-        >>> words = ['grass', 'gis', 'modules']
-        >>> f(*words)
+        >>> words = ['grass', 'gis', 'modules']              # doctest: +SKIP
+        >>> f(*words)                                        # doctest: +SKIP
         grass
         gis
         modules
 
-    we can do the same with keyword arguments, rewrite the above function:
+    we can do the same with keyword arguments, rewrite the above function: ::
 
         def f(*args, **kargs):
             for arg in args:
@@ -300,9 +295,10 @@
             for key, value in kargs.items():
                 print "%s = %r" % (key, value)
 
-    now we can use the new function, with:
+    now we can use the new function, with: ::
 
         >>> f('grass', 'gis', 'modules', os = 'linux', language = 'python')
+        ...                                                  # doctest: +SKIP
         grass
         gis
         modules
@@ -310,10 +306,11 @@
         language = 'python'
 
     or, as before we can, define a dictionary and give the dictionary to
-    the function, like:
+    the function, like: ::
 
         >>> keywords = {'os' : 'linux', 'language' : 'python'}
-        >>> f(*words, **keywords)
+        ...                                                  # doctest: +SKIP
+        >>> f(*words, **keywords)                            # doctest: +SKIP
         grass
         gis
         modules
@@ -398,6 +395,11 @@
         self.__call__.__func__.__doc__ = self.__doc__
 
     def __call__(self, *args, **kargs):
+        """Set module paramters to the class and, if run_ is True execute the
+        module, therefore valid parameters are all the module parameters
+        plus some extra parameters that are: run_, stdin_, stdout_, stderr_,
+        env_ and finish_.
+        """
         if not args and not kargs:
             self.run()
             return
@@ -459,11 +461,11 @@
             return self.run()
 
     def get_bash(self):
-        """Prova"""
+        """Return a BASH rapresentation of the Module."""
         return ' '.join(self.make_cmd())
 
     def get_python(self):
-        """Prova"""
+        """Return a Python rapresentation of the Module."""
         prefix = self.name.split('.')[0]
         name = '_'.join(self.name.split('.')[1:])
         params = ', '.join([par.get_python() for par in self.params_list
@@ -486,8 +488,7 @@
             return "%s.%s(%s)" % (prefix, name, params)
 
     def __str__(self):
-        """Return the command string that can be executed in a shell
-        """
+        """Return the command string that can be executed in a shell"""
         return ' '.join(self.make_cmd())
 
     def __repr__(self):



More information about the grass-commit mailing list