GRASS Programmer's Manual
6.5.svn(2014)-r66266
|
Data Structures | |
class | Popen |
class | ScriptError |
class | KeyValue |
Functions | |
def | call |
def | decode |
def | make_command |
Return a list of strings suitable for use as the args parameter to Popen() or call(). More... | |
def | start_command |
Returns a Popen object with the command created by make_command. More... | |
def | run_command |
Passes all arguments to start_command(), then waits for the process to complete, returning its exit code. More... | |
def | pipe_command |
Passes all arguments to start_command(), but also adds "stdout = PIPE". More... | |
def | feed_command |
Passes all arguments to start_command(), but also adds "stdin = PIPE". More... | |
def | read_command |
Passes all arguments to pipe_command, then waits for the process to complete, returning its stdout (i.e. More... | |
def | parse_command |
Passes all arguments to read_command, then parses the output by parse_key_val(). More... | |
def | write_command |
Passes all arguments to feed_command, with the string specified by the 'stdin' argument fed to the process' stdin. More... | |
def | exec_command |
Interface to os.execvpe(), but with the make_command() interface. More... | |
def | message |
Display a message using g.message More... | |
def | debug |
Display a debugging message using g.message -d More... | |
def | verbose |
Display a verbose message using g.message -v More... | |
def | info |
Display an informational message using g.message -i More... | |
def | percent |
Display a progress info message using g.message -p More... | |
def | warning |
Display a warning message using g.message -w More... | |
def | error |
Display an error message using g.message -e More... | |
def | fatal |
Display an error message using g.message -e , then abort. More... | |
def | set_raise_on_error |
Define behaviour on error (error() called) More... | |
def | parser |
Interface to g.parser, intended to be run from the top-level, e.g. More... | |
def | tempfile |
Returns the name of a temporary file, created with g.tempfile. More... | |
def | tempdir |
Returns the name of a temporary dir, created with g.tempfile. More... | |
def | parse_key_val |
Parse a string into a dictionary, where entries are separated by newlines and the key and value are separated by `sep' (default: `=') More... | |
def | gisenv |
Returns the output from running g.gisenv (with no arguments), as a dictionary. More... | |
def | locn_is_latlong |
Tests if location is lat/long. More... | |
def | region |
Returns the output from running "g.region -gu", as a dictionary. More... | |
def | region_env |
Returns region settings as a string which can used as GRASS_REGION environmental variable. More... | |
def | use_temp_region |
Copies the current region to a temporary region with "g.region save=", then sets WIND_OVERRIDE to refer to that region. More... | |
def | del_temp_region |
Unsets WIND_OVERRIDE and removes any region named by it. More... | |
def | find_file |
Returns the output from running g.findfile as a dictionary. More... | |
def | list_grouped |
List elements grouped by mapsets. More... | |
def | list_pairs |
List of elements as tuples. More... | |
def | list_strings |
List of elements as strings. More... | |
def | mlist_strings |
List of elements as strings. More... | |
def | mlist_pairs |
List of elements as pairs. More... | |
def | mlist_grouped |
List of elements grouped by mapsets. More... | |
def | parse_color |
Parses the string "val" as a GRASS colour, which can be either one of the named colours or an R:G:B tuple e.g. More... | |
def | overwrite |
Return True if existing files may be overwritten. More... | |
def | verbosity |
Return the verbosity level selected by GRASS_VERBOSE. More... | |
def | basename |
various utilities, not specific to GRASS More... | |
def | find_program |
Attempt to run a program, with optional arguments. More... | |
def | try_remove |
Attempt to remove a file; no exception is generated if the attempt fails. More... | |
def | try_rmdir |
Attempt to remove a directory; no exception is generated if the attempt fails. More... | |
def | float_or_dms |
Convert DMS to float. More... | |
def | mapsets |
List available mapsets. More... | |
def | create_location |
Create new location. More... | |
def | version |
Get GRASS version as dictionary. More... | |
def | legal_name |
Checks if the string contains only allowed characters. More... | |
Variables | |
PIPE = subprocess.PIPE | |
STDOUT = subprocess.STDOUT | |
raise_on_error = False | |
int | debug_level = 0 |
list | _popen_args |
dictionary | named_colors |
def python.core.basename | ( | path, | |
ext = None |
|||
) |
various utilities, not specific to GRASS
Remove leading directory components and an optional extension from the specified path
path | path |
ext | extension |
Definition at line 955 of file core.py.
Referenced by python.core.parser().
def python.core.call | ( | args, | |
kwargs | |||
) |
Definition at line 71 of file core.py.
Referenced by N_alloc_les_callback_2d(), and N_alloc_les_callback_3d().
def python.core.create_location | ( | dbase, | |
location, | |||
epsg = None , |
|||
proj4 = None , |
|||
filename = None , |
|||
wkt = None , |
|||
datum = None , |
|||
datumtrans = None , |
|||
desc = None |
|||
) |
Create new location.
Raise ScriptError on error.
dbase | path to GRASS database |
location | location name to create |
epsg | if given create new location based on EPSG code |
proj4 | if given create new location based on Proj4 definition |
filename | if given create new location based on georeferenced file |
wkt | if given create new location based on WKT definition (path to PRJ file) |
datum | GRASS format datum code |
datumtrans | datum transformation parameters (used for epsg and proj4) |
desc | description of the location (creates MYNAME file) |
def python.core.debug | ( | msg, | |
debug = 1 |
|||
) |
Display a debugging message using g.message -d
msg | debugging message to be displayed |
debug | debug level (0-5) |
Definition at line 324 of file core.py.
References python.core.run_command().
def python.core.decode | ( | string | ) |
Definition at line 80 of file core.py.
Referenced by python.task.get_interface_description(), forms.GUI.GetCommandInputMapParamKey(), python.task.parse_interface(), and instructions.Text.Read().
def python.core.del_temp_region | ( | ) |
Unsets WIND_OVERRIDE and removes any region named by it.
Definition at line 691 of file core.py.
References python.core.run_command().
def python.core.error | ( | msg | ) |
Display an error message using g.message -e
Raise exception when on_error is 'raise'.
msg | error message to be displayed |
Definition at line 370 of file core.py.
References python.core.message().
Referenced by python.core.fatal().
def python.core.exec_command | ( | prog, | |
flags = "" , |
|||
overwrite = False , |
|||
quiet = False , |
|||
verbose = False , |
|||
env = None , |
|||
kwargs | |||
) |
Interface to os.execvpe(), but with the make_command() interface.
prog | GRASS module |
flags | flags to be used (given as a string) |
overwrite | True to enable overwriting the output (–o ) |
quiet | True to run quietly (–q ) |
verbose | True to run verbosely (–v ) |
env | directory with environmental variables |
kwargs | module's parameters |
Definition at line 297 of file core.py.
References python.core.make_command().
def python.core.fatal | ( | msg | ) |
Display an error message using g.message -e
, then abort.
msg | error message to be displayed |
Definition at line 383 of file core.py.
References python.core.error().
Referenced by python.db.db_describe(), python.db.db_select(), python.raster.mapcalc(), and python.vector.vector_layer_db().
def python.core.feed_command | ( | args, | |
kwargs | |||
) |
Passes all arguments to start_command(), but also adds "stdin = PIPE".
Returns the Popen object.
args | list of unnamed arguments (see start_command() for details) |
kwargs | list of named arguments (see start_command() for details) |
Definition at line 217 of file core.py.
References python.core.start_command().
Referenced by python.raster.mapcalc_start(), and python.core.write_command().
def python.core.find_file | ( | name, | |
element = 'cell' , |
|||
mapset = None |
|||
) |
Returns the output from running g.findfile as a dictionary.
Example:
name | file name |
element | element type (default 'cell') |
mapset | mapset name (default all mapsets in search path) |
Definition at line 701 of file core.py.
References python.core.parse_key_val(), and python.core.read_command().
def python.core.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:
pgm | program name |
args | list of arguments |
Definition at line 972 of file core.py.
Referenced by ogc_services.WMSDialog.OnConnect().
def python.core.float_or_dms | ( | s | ) |
Convert DMS to float.
s | DMS value |
Definition at line 1034 of file core.py.
Referenced by python.raster.raster_info().
def python.core.gisenv | ( | ) |
Returns the output from running g.gisenv (with no arguments), as a dictionary.
Example:
Definition at line 546 of file core.py.
References python.core.parse_key_val(), and python.core.read_command().
Referenced by python.raster.raster_history(), and python.core.region_env().
def python.core.info | ( | msg | ) |
Display an informational message using g.message -i
msg | informational message to be displayed |
Definition at line 339 of file core.py.
References python.core.message().
Referenced by MT_tree_info_new().
def python.core.legal_name | ( | s | ) |
Checks if the string contains only allowed characters.
This is the Python implementation of G_legal_filename() function.
def python.core.list_grouped | ( | type, | |
check_search_path = True |
|||
) |
List elements grouped by mapsets.
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. Example:
type | element type (rast, vect, rast3d, region, ...) |
check_search_path | True to add mapsets for the search path with no found elements |
Definition at line 724 of file core.py.
References python.core.mapsets(), and python.core.read_command().
Referenced by python.core.list_pairs().
def python.core.list_pairs | ( | type | ) |
List of elements as tuples.
Returns the output from running g.list, as a list of (map, mapset) pairs. Example:
type | element type (rast, vect, rast3d, region, ...) |
Definition at line 771 of file core.py.
References python.core.list_grouped().
Referenced by python.core.list_strings().
def python.core.list_strings | ( | type | ) |
List of elements as strings.
Returns the output from running g.list, as a list of qualified names. Example:
type | element type |
Definition at line 789 of file core.py.
References python.core.list_pairs().
def python.core.locn_is_latlong | ( | ) |
Tests if location is lat/long.
Value is obtained by checking the "g.region -pu" projection code.
Definition at line 561 of file core.py.
References python.core.parse_key_val(), python.core.read_command(), and utils.split().
def python.core.make_command | ( | prog, | |
flags = "" , |
|||
overwrite = False , |
|||
quiet = False , |
|||
verbose = False , |
|||
options | |||
) |
Return a list of strings suitable for use as the args parameter to Popen() or call().
Example:
prog | GRASS module |
flags | flags to be used (given as a string) |
overwrite | True to enable overwriting the output (–o ) |
quiet | True to run quietly (–q ) |
verbose | True to run verbosely (–v ) |
options | module's parameters |
Definition at line 97 of file core.py.
Referenced by python.core.exec_command(), and python.core.start_command().
def python.core.mapsets | ( | search_path = False | ) |
List available mapsets.
searchPatch | True to list mapsets only in search path |
Definition at line 1045 of file core.py.
Referenced by G_available_mapsets(), python.core.list_grouped(), and list_mapsets().
def python.core.message | ( | msg, | |
flag = None |
|||
) |
Display a message using g.message
msg | message to be displayed |
flag | flags (given as string) |
Definition at line 316 of file core.py.
References python.core.run_command().
Referenced by python.core.error(), python.core.info(), python.core.percent(), python.core.verbose(), and python.core.warning().
def python.core.mlist_grouped | ( | type, | |
pattern = None , |
|||
check_search_path = True , |
|||
flag = '' |
|||
) |
List of elements grouped by mapsets.
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. Example:
type | element type (rast, vect, rast3d, region, ...) |
pattern | pattern string |
check_search_path | True to add mapsets for the search path with no found elements |
flag | pattern type: 'r' (basic regexp), 'e' (extended regexp), or '' (glob pattern) |
def python.core.mlist_pairs | ( | type, | |
pattern = None , |
|||
mapset = None , |
|||
flag = '' |
|||
) |
List of elements as pairs.
Returns the output from running g.mlist, as a list of (name, mapset) pairs
type | element type (rast, vect, rast3d, region, ...) |
pattern | pattern string |
mapset | mapset name (if not given use search path) |
flag | pattern type: 'r' (basic regexp), 'e' (extended regexp), or '' (glob pattern) |
def python.core.mlist_strings | ( | type, | |
pattern = None , |
|||
mapset = None , |
|||
flag = '' |
|||
) |
List of elements as strings.
Returns the output from running g.mlist, as a list of qualified names.
type | element type (rast, vect, rast3d, region, ...) |
pattern | pattern string |
mapset | mapset name (if not given use search path) |
flag | pattern type: 'r' (basic regexp), 'e' (extended regexp), or '' (glob pattern) |
def python.core.overwrite | ( | ) |
def python.core.parse_color | ( | val, | |
dflt = None |
|||
) |
Parses the string "val" as a GRASS colour, which can be either one of 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. Example:
val | color value |
dflt | default color value |
def python.core.parse_command | ( | args, | |
kwargs | |||
) |
Passes all arguments to read_command, then parses the output by parse_key_val().
Parsing function can be optionally given by parse parameter including its arguments, e.g.
or you can simply define delimiter
args | list of unnamed arguments (see start_command() for details) |
kwargs | list of named arguments (see start_command() for details) |
Definition at line 241 of file core.py.
References python.core.read_command(), and dialogs.type.
def python.core.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: `=')
s | string to be parsed |
sep | key/value separator |
dflt | default value to be used |
val_type | value type (None for no cast) |
vsep | vertical separator (default os.linesep) |
Definition at line 505 of file core.py.
Referenced by python.db.db_connection(), python.core.find_file(), python.core.gisenv(), python.core.locn_is_latlong(), python.raster.raster_info(), python.core.region(), python.core.region_env(), and python.vector.vector_info_topo().
def python.core.parser | ( | ) |
Interface to g.parser, intended to be run from the top-level, e.g.
:
Thereafter, the global variables "options" and "flags" will be dictionaries containing option/flag values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans.
Definition at line 428 of file core.py.
References python.core.basename().
Referenced by python.task.parse_interface().
def python.core.percent | ( | i, | |
n, | |||
s | |||
) |
def python.core.pipe_command | ( | args, | |
kwargs | |||
) |
Passes all arguments to start_command(), but also adds "stdout = PIPE".
Returns the Popen object.
args | list of unnamed arguments (see start_command() for details) |
kwargs | list of named arguments (see start_command() for details) |
Definition at line 192 of file core.py.
References python.core.start_command().
Referenced by python.core.read_command().
def python.core.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
).
args | list of unnamed arguments (see start_command() for details) |
kwargs | list of named arguments (see start_command() for details) |
Definition at line 229 of file core.py.
References python.core.pipe_command().
Referenced by python.db.db_connection(), python.db.db_describe(), python.core.find_file(), python.core.gisenv(), python.core.list_grouped(), python.core.locn_is_latlong(), python.core.parse_command(), python.raster.raster_info(), python.core.region(), python.core.region_env(), python.core.tempdir(), python.core.tempfile(), python.vector.vector_columns(), python.vector.vector_db(), python.vector.vector_db_select(), python.vector.vector_info_topo(), and python.vector.vector_what().
def python.core.region | ( | region3d = False | ) |
Returns the output from running "g.region -gu", as a dictionary.
Example:
region3d | True to get 3D region |
Definition at line 576 of file core.py.
References python.core.parse_key_val(), python.core.read_command(), and python.core.region_env().
def python.core.region_env | ( | region3d = False , |
|
kwargs | |||
) |
Returns region settings as a string which can used as GRASS_REGION environmental variable.
If no 'kwargs' are given then the current region is used. Note that this function doesn't modify the current region!
See also use_temp_region() for alternative method how to define temporary region used for raster-based computation.
region3d | True to get 3D region |
kwargs | g.region's parameters like 'rast', 'vect' or 'region' |
Definition at line 607 of file core.py.
References python.core.gisenv(), python.core.parse_key_val(), and python.core.read_command().
Referenced by python.core.region().
def python.core.run_command | ( | args, | |
kwargs | |||
) |
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.
args | list of unnamed arguments (see start_command() for details) |
kwargs | list of named arguments (see start_command() for details) |
Definition at line 179 of file core.py.
References python.core.start_command().
Referenced by python.db.db_select(), python.core.debug(), python.core.del_temp_region(), python.core.message(), python.raster.raster_history(), python.core.use_temp_region(), and python.vector.vector_history().
def python.core.set_raise_on_error | ( | raise_exp = True | ) |
Define behaviour on error (error() called)
raise_exp | True to raise ScriptError instead of calling error() |
def python.core.start_command | ( | prog, | |
flags = "" , |
|||
overwrite = False , |
|||
quiet = False , |
|||
verbose = False , |
|||
kwargs | |||
) |
Returns a Popen object with the command created by make_command.
Accepts any of the arguments which Popen() accepts apart from "args" and "shell".
prog | GRASS module |
flags | flags to be used (given as a string) |
overwrite | True to enable overwriting the output (–o ) |
quiet | True to run quietly (–q ) |
verbose | True to run verbosely (–v ) |
kwargs | module's parameters |
Definition at line 133 of file core.py.
References python.core.make_command().
Referenced by python.core.feed_command(), python.core.pipe_command(), and python.core.run_command().
def python.core.tempdir | ( | ) |
Returns the name of a temporary dir, created with g.tempfile.
Definition at line 474 of file core.py.
References python.core.read_command(), and python.core.try_remove().
def python.core.tempfile | ( | ) |
Returns the name of a temporary file, created with g.tempfile.
Definition at line 470 of file core.py.
References python.core.read_command().
def python.core.try_remove | ( | path | ) |
Attempt to remove a file; no exception is generated if the attempt fails.
path | path to file to remove |
Definition at line 1010 of file core.py.
Referenced by python.db.db_select(), and python.core.tempdir().
def python.core.try_rmdir | ( | path | ) |
def python.core.use_temp_region | ( | ) |
Copies the current region to a temporary region with "g.region save=", then sets WIND_OVERRIDE to refer to that region.
Installs an atexit handler to delete the temporary region upon termination.
Definition at line 681 of file core.py.
References python.core.run_command().
def python.core.verbose | ( | msg | ) |
Display a verbose message using g.message -v
msg | verbose message to be displayed |
Definition at line 332 of file core.py.
References python.core.message().
def python.core.verbosity | ( | ) |
def python.core.version | ( | ) |
def python.core.warning | ( | msg | ) |
Display a warning message using g.message -w
msg | warning message to be displayed |
Definition at line 363 of file core.py.
References python.core.message().
Referenced by python.raster.raster_history().
def python.core.write_command | ( | args, | |
kwargs | |||
) |
Passes all arguments to feed_command, with the string specified by the 'stdin' argument fed to the process' stdin.
args | list of unnamed arguments (see start_command() for details) |
kwargs | list of named arguments (see start_command() for details) |
Definition at line 282 of file core.py.
References python.core.feed_command().
Referenced by python.raster.mapcalc().
list python.core._popen_args |
tuple python.core.debug_level = 0 |
Definition at line 69 of file core.py.
Referenced by dig_angle_next_line(), dig_build_area_with_line(), and Vect_select_areas_by_box().
dictionary python.core.named_colors |