|
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 |