pygrass.modules.interface package

Submodules

pygrass.modules.interface.docstring module

class pygrass.modules.interface.docstring.DocstringProperty(class_doc, fget)

Bases: object

Property for the __doc__ attribute.

Different than property in the following two ways:

• When the attribute is accessed from the main class, it returns the value of class_doc, not the property itself. This is necessary so Sphinx and other documentation tools can access the class docstring.
• Only supports getting the attribute; setting and deleting raise an AttributeError.

pygrass.modules.interface.docstring.docstring_property(class_doc)

Property attribute for docstrings. Took from: https://gist.github.com/bfroehle/4041015

>>> class A(object):
...     '''Main docstring'''
...     def __init__(self, x):
...         self.x = x
...     @docstring_property(__doc__)
...     def __doc__(self):
...         return "My value of x is %s." % self.x

>>> A.__doc__
'Main docstring'

>>> a = A(10)
>>> a.__doc__
'My value of x is 10.'

pygrass.modules.interface.env module

Created on Thu May 28 17:41:32 2015

@author: pietro

pygrass.modules.interface.env.G_debug(level, *msg)

Print or write a debug message, this is a pure python implementation of the G_debug function in the C API.

pygrass.modules.interface.env.get_debug_level()

Return the debug level

pygrass.modules.interface.env.get_env()

Parse the GISRC file and return the GRASS variales

pygrass.modules.interface.flag module

class pygrass.modules.interface.flag.Flag(xflag=None, diz=None)

Bases: object

The Flag object store all information about a flag of module.

It is possible to set flags of command using this object.

>>> flag = Flag(diz=dict(name='a', description='Flag description',
...                      default=True))
>>> flag.name
u'a'
>>> flag.special
False
>>> flag.description
u'Flag description'
>>> flag = Flag(diz=dict(name='overwrite'))
>>> flag.name
u'overwrite'
>>> flag.special
True

get_bash()

Return the BASH representation of a flag.

>>> flag = Flag(diz=dict(name='a', description='Flag description',
...                      default=True))
>>> flag.get_bash()
u''
>>> flag.value = True
>>> flag.get_bash()
u'-a'
>>> flag = Flag(diz=dict(name='overwrite'))
>>> flag.get_bash()
u''
>>> flag.value = True
>>> flag.get_bash()
u'--o'

get_python()

Return the python representation of a flag.

>>> flag = Flag(diz=dict(name='a', description='Flag description',
...                      default=True))
>>> flag.get_python()
u''
>>> flag.value = True
>>> flag.get_python()
u'a'
>>> flag = Flag(diz=dict(name='overwrite'))
>>> flag.get_python()
u''
>>> flag.value = True
>>> flag.get_python()
u'overwrite=True'

pygrass.modules.interface.module module

class pygrass.modules.interface.module.Module(cmd, *args, **kargs)

Bases: 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)
Module('r.neighbors')
>>> 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)
Module('r.neighbors')
>>> 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.get_bash()
u'r.colors map=test_a color=ryb'
>>> colors.run()
Module('r.colors')
>>> colors(color="gyr")
Module('r.colors')
>>> colors.run()
Module('r.colors')
>>> colors(color="ryg")
Module('r.colors')
>>> colors(stderr_=PIPE)
Module('r.colors')
>>> colors.run()
Module('r.colors')
>>> print(colors.outputs["stderr"].value.strip())
Color table for raster map <test_a> set to 'ryg'
>>> colors(color="byg")
Module('r.colors')
>>> colors(stdout_=PIPE)
Module('r.colors')
>>> 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.

def f(*args):
    for arg in args:
        print arg

therefore if we call the function like:

>>> f('grass', 'gis', 'modules')                     
grass
gis
modules

or we can define a new list:

>>> words = ['grass', 'gis', 'modules']              
>>> f(*words)                                        
grass
gis
modules

we can do the same with keyword arguments, rewrite the above function:

def f(*args, **kargs):
    for arg in args:
        print arg
    for key, value in kargs.items():
        print "%s = %r" % (key, value)

now we can use the new function, with:

>>> f('grass', 'gis', 'modules', os = 'linux', language = 'python')
...                                                  
grass
gis
modules
os = 'linux'
language = 'python'

or, as before we can, define a dictionary and give the dictionary to the function, like:

>>> keywords = {'os' : 'linux', 'language' : 'python'}  
>>> f(*words, **keywords)                            
grass
gis
modules
os = 'linux'
language = 'python'

In the Module class we heavily use this language feature to pass arguments and keyword arguments to the grass module.

check()

Check the correctness of the provide parameters

get_bash()

Return a BASH representation of the Module.

get_dict()

Return a dictionary that includes the name, all valid inputs, outputs and flags

get_python()

Return a Python representation of the Module.

make_cmd()

Create the command string that can be executed in a shell

Returns:the command string

run()

Run the module

Parameters:node –

This function will wait for the process to terminate in case finish_==True and sets up stdout and stderr. If finish_==False this function will return after starting the process. Use self.popen.communicate() of self.popen.wait() to wait for the process termination. The handling of stdout and stderr must then be done outside of this function.

class pygrass.modules.interface.module.ParallelModuleQueue(nprocs=1)

Bases: object

This class is designed to run an arbitrary number of pygrass Module processes in parallel.

Objects of type grass.pygrass.modules.Module can be put into the queue using put() method. When the queue is full with the maximum number of parallel processes it will wait for all processes to finish, sets the stdout and stderr of the Module object and removes it from the queue when its finished.

To finish the queue before the maximum number of parallel processes was reached call wait() .

This class will raise a GrassError in case a Module process exits with a return code other than 0.

Usage:

Check with a queue size of 3 and 5 processes

>>> import copy
>>> from grass.pygrass.modules import Module, ParallelModuleQueue
>>> mapcalc_list = []

Setting run_ to False is important, otherwise a parallel processing is not possible

>>> mapcalc = Module("r.mapcalc", overwrite=True, run_=False)
>>> queue = ParallelModuleQueue(nprocs=3)
>>> for i in xrange(5):
...     new_mapcalc = copy.deepcopy(mapcalc)
...     mapcalc_list.append(new_mapcalc)
...     m = new_mapcalc(expression="test_pygrass_%i = %i"%(i, i))
...     queue.put(m)
>>> queue.wait()
>>> queue.get_num_run_procs()
0
>>> queue.get_max_num_procs()
3
>>> for mapcalc in mapcalc_list:
...     print(mapcalc.popen.returncode)
0
0
0
0
0

Check with a queue size of 8 and 5 processes

>>> queue = ParallelModuleQueue(nprocs=8)
>>> mapcalc_list = []
>>> for i in xrange(5):
...     new_mapcalc = copy.deepcopy(mapcalc)
...     mapcalc_list.append(new_mapcalc)
...     m = new_mapcalc(expression="test_pygrass_%i = %i"%(i, i))
...     queue.put(m)
>>> queue.wait()
>>> queue.get_num_run_procs()
0
>>> queue.get_max_num_procs()
8
>>> for mapcalc in mapcalc_list:
...     print(mapcalc.popen.returncode)
0
0
0
0
0

Check with a queue size of 8 and 4 processes

>>> queue = ParallelModuleQueue(nprocs=8)
>>> mapcalc_list = []
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_1 =1")
>>> queue.put(m)
>>> queue.get_num_run_procs()
1
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_2 =2")
>>> queue.put(m)
>>> queue.get_num_run_procs()
2
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_3 =3")
>>> queue.put(m)
>>> queue.get_num_run_procs()
3
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_4 =4")
>>> queue.put(m)
>>> queue.get_num_run_procs()
4
>>> queue.wait()
>>> queue.get_num_run_procs()
0
>>> queue.get_max_num_procs()
8
>>> for mapcalc in mapcalc_list:
...     print(mapcalc.popen.returncode)
0
0
0
0

Check with a queue size of 3 and 4 processes

>>> queue = ParallelModuleQueue(nprocs=3)
>>> mapcalc_list = []
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_1 =1")
>>> queue.put(m)
>>> queue.get_num_run_procs()
1
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_2 =2")
>>> queue.put(m)
>>> queue.get_num_run_procs()
2
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_3 =3")
>>> queue.put(m) # Now it will wait until all procs finish and set the counter back to 0
>>> queue.get_num_run_procs()
0
>>> new_mapcalc = copy.deepcopy(mapcalc)
>>> mapcalc_list.append(new_mapcalc)
>>> m = new_mapcalc(expression="test_pygrass_%i = %i"%(i, i))
>>> queue.put(m)
>>> queue.get_num_run_procs()
1
>>> queue.wait()
>>> queue.get_num_run_procs()
0
>>> queue.get_max_num_procs()
3
>>> for mapcalc in mapcalc_list:
...     print(mapcalc.popen.returncode)
0
0
0
0

get(num)

Get a Module object from the queue

Parameters:num (int) – the number of the object in queue Returns:the Module object or None if num is not in the queue

get_max_num_procs()

Return the maximum number of parallel Module processes

Returns:the maximum number of parallel Module processes

get_num_run_procs()

Get the number of Module processes that are in the queue running or finished

Returns:the number fo Module processes running/finished in the queue

put(module)

Put the next Module object in the queue

To run the Module objects in parallel the run_ and finish_ options of the Module must be set to False.

Parameters:module (Module object) – a preconfigured Module object with run_ and finish_ set to False

set_max_num_procs(nprocs)

Set the maximum number of Module processes that should run in parallel

Parameters:nprocs (int) – The maximum number of Module processes that can be run in parallel

wait()

Wait for all Module processes that are in the list to finish and set the modules stdout and stderr output options

pygrass.modules.interface.parameter module

Created on Tue Apr 2 18:31:47 2013

@author: pietro

class pygrass.modules.interface.parameter.Parameter(xparameter=None, diz=None)

Bases: object

The Parameter object store all information about a parameter of a GRASS GIS module.

>>> param = Parameter(diz=dict(name='int_number', required='yes',
...                            multiple='no', type='integer',
...                            values=[2, 4, 6, 8]))
>>> param.value = 2
>>> param.value
2
>>> param.value = 3
Traceback (most recent call last):
   ...
ValueError: The Parameter <int_number>, must be one of the following values: [2, 4, 6, 8]
Traceback (most recent call last):
   ...
ValueError: The Parameter <int_number>, must be one of the following values: [2, 4, 6, 8]

...

get_bash()

Return the BASH representation of the parameter.

>>> param = Parameter(diz=dict(name='int_number', required='yes',
...                            multiple='no', type='integer',
...                            values=[2, 4, 6, 8], default=8))
>>> param.get_bash()
u'int_number=8'

get_python()

Return a string with the Python representation of the parameter.

>>> param = Parameter(diz=dict(name='int_number', required='yes',
...                            multiple='no', type='integer',
...                            values=[2, 4, 6, 8], default=8))
>>> param.get_python()
u'int_number=8'

rawvalue

Parameter value as insert by user without transformation

value

Parameter value transformed and validated.

pygrass.modules.interface.read module

Created on Tue Apr 2 18:30:34 2013

@author: pietro

pygrass.modules.interface.read.do_nothing(p)

pygrass.modules.interface.read.element2dict(xparameter)

pygrass.modules.interface.read.get_None(p)

pygrass.modules.interface.read.get_dict(p)

pygrass.modules.interface.read.get_values(p)

pygrass.modules.interface.read.read_keydesc(par)

pygrass.modules.interface.read.read_text(p)

pygrass.modules.interface.typedict module

Created on Tue Apr 2 18:37:02 2013

@author: pietro

class pygrass.modules.interface.typedict.TypeDict(dict_type, *args, **kargs)

Bases: collections.OrderedDict

Created on Tue Apr 2 18:37:02 2013

@author: pietro

used()

Module contents

Created on Tue Apr 2 18:40:39 2013

@author: pietro