python::core Namespace Reference

Data Structures
class	Popen
class	ScriptError
Functions
def	call
def	decode
def	make_command
	Return a list of strings suitable for use as the args parameter to Popen() or call().
def	start_command
	Returns a Popen object with the command created by make_command.
def	run_command
	Passes all arguments to start_command(), then waits for the process to complete, returning its exit code.
def	pipe_command
	Passes all arguments to start_command(), but also adds "stdout = PIPE".
def	feed_command
	Passes all arguments to start_command(), but also adds "stdin = PIPE".
def	read_command
	Passes all arguments to pipe_command, then waits for the process to complete, returning its stdout (i.e.
def	parse_command
	Passes all arguments to read_command, then parses the output by parse_key_val().
def	write_command
	Passes all arguments to feed_command, with the string specified by the 'stdin' argument fed to the process' stdin.
def	exec_command
	Interface to os.execvpe(), but with the make_command() interface.
def	message
	Display a message using `g.message`.
def	debug
	Display a debugging message using `g.message -d`.
def	verbose
	Display a verbose message using `g.message -v`.
def	info
	Display an informational message using `g.message -i`.
def	percent
	Display a progress info message using `g.message -p`.
def	warning
	Display a warning message using `g.message -w`.
def	error
	Display an error message using `g.message -e`.
def	fatal
	Display an error message using `g.message -e`, then abort.
def	set_raise_on_error
	Define behaviour on error (error() called)
def	parser
	Interface to g.parser, intended to be run from the top-level, e.g.
def	tempfile
	Returns the name of a temporary file, created with g.tempfile.
def	tempdir
	Returns the name of a temporary dir, created with g.tempfile.
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: `=')
def	gisenv
	Returns the output from running g.gisenv (with no arguments), as a dictionary.
def	region
	Returns the output from running "g.region -g", as a dictionary.
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.
def	del_temp_region
	Unsets WIND_OVERRIDE and removes any region named by it.
def	find_file
	Returns the output from running g.findfile as a dictionary.
def	list_grouped
	List elements grouped by mapsets.
def	list_pairs
	List of elements as tuples.
def	list_strings
	List of elements as strings.
def	mlist_grouped
	List of elements grouped by mapsets.
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.
def	overwrite
	Return True if existing files may be overwritten.
def	verbosity
	Return the verbosity level selected by GRASS_VERBOSE.
def	basename
	various utilities, not specific to GRASS
def	find_program
	Attempt to run a program, with optional arguments.
def	try_remove
	Attempt to remove a file; no exception is generated if the attempt fails.
def	try_rmdir
	Attempt to remove a directory; no exception is generated if the attempt fails.
def	float_or_dms
	Convert DMS to float.
def	mapsets
	List available mapsets.
def	create_location
	Create new location.
def	version
	Get GRASS version as dictionary.
Variables
	PIPE = subprocess.PIPE
	STDOUT = subprocess.STDOUT
	raise_on_error = False
int	debug_level = 0
list	_popen_args
dictionary	named_colors

---

Function Documentation

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

Parameters:

path	path
ext	extension

Definition at line 796 of file lib/python/core.py.

def python::core::call	(		args,
			kwargs
	)

Definition at line 71 of file lib/python/core.py.

def python::core::create_location	(		dbase,
			location,
			epsg = None,
			proj4 = None,
			filename = None,
			wkt = None,
			datum = None,
			desc = None
	)

Create new location.

Raise ScriptError on error.

Parameters:

dbase	path to GRASS database
location	location name to create
epgs	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	datum transformation parameters (used for epsg and proj4)
desc	description of the location (creates MYNAME file)

Definition at line 894 of file lib/python/core.py.

def python::core::debug	(		msg,
			debug = 1
	)

Display a debugging message using `g.message -d`.

Parameters:

msg	debugging message to be displayed
debug	debug level (0-5)

Definition at line 324 of file lib/python/core.py.

def python::core::decode

(

string

)

Definition at line 80 of file lib/python/core.py.

def python::core::del_temp_region

(

)

Unsets WIND_OVERRIDE and removes any region named by it.

Definition at line 572 of file lib/python/core.py.

def python::core::error

(

msg

)

Display an error message using `g.message -e`.

Raise exception when on_error is 'raise'.

Parameters:

msg	error message to be displayed

Definition at line 370 of file lib/python/core.py.

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.

Parameters:

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 enviromental variables
kwargs	module's parameters

Definition at line 297 of file lib/python/core.py.

def python::core::fatal

(

msg

)

Display an error message using `g.message -e`, then abort.

Parameters:

msg	error message to be displayed

Definition at line 383 of file lib/python/core.py.

def python::core::feed_command	(		args,
			kwargs
	)

Passes all arguments to start_command(), but also adds "stdin = PIPE".

Returns the Popen object.

Parameters:

args	list of unnamed arguments (see start_command() for details)
kwargs	list of named arguments (see start_command() for details)

Returns:

Popen object

Definition at line 217 of file lib/python/core.py.

def python::core::find_file	(		name,
			element = 'cell',
			mapset = None
	)

Returns the output from running g.findfile as a dictionary.

Example:

>>> result = grass.find_file('fields', element = 'vector')
>>> print result['fullname']
fields@PERMANENT
>>> print result['file']
/opt/grass-data/spearfish60/PERMANENT/vector/fields

Parameters:

name	file name
element	element type (default 'cell')
mapset	mapset name (default all mapsets in search path)

Returns:

parsed output of g.findfile

Definition at line 582 of file lib/python/core.py.

def python::core::find_program	(		pgm,
			args = []
	)

Attempt to run a program, with optional arguments.

Parameters:

pgm	program name
args	list of arguments

Returns:

False if the attempt failed due to a missing executable

True otherwise

Definition at line 813 of file lib/python/core.py.

def python::core::float_or_dms

(

s

)

Convert DMS to float.

Parameters:

s

DMS value

Returns:

float value

Definition at line 861 of file lib/python/core.py.

def python::core::gisenv

(

)

Returns the output from running g.gisenv (with no arguments), as a dictionary.

Example:

>>> env = grass.gisenv()
>>> print env['GISDBASE']
/opt/grass-data

Returns:

list of GRASS variables

Definition at line 525 of file lib/python/core.py.

def python::core::info

(

msg

)

Display an informational message using `g.message -i`.

Parameters:

msg	informational message to be displayed

Definition at line 339 of file lib/python/core.py.

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:

>>> grass.list_grouped('rast')['PERMANENT']
['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...

Parameters:

type	element type (rast, vect, rast3d, region, ...)
check_search_path	True to add mapsets for the search path with no found elements

Returns:

directory of mapsets/elements

Definition at line 605 of file lib/python/core.py.

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:

>>> grass.list_pairs('rast')
[('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...

Parameters:

type	element type (rast, vect, rast3d, region, ...)

Returns:

list of tuples (map, mapset)

Definition at line 652 of file lib/python/core.py.

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:

>>> grass.list_strings('rast')
['aspect@PERMANENT', 'erosion1@PERMANENT', 'quads@PERMANENT', 'soils@PERMANENT', ...

Parameters:

type	element type

Returns:

list of strings ('map@mapset')

Definition at line 670 of file lib/python/core.py.

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:

>>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
['g.message', '-w', 'message=this is a warning']

Parameters:

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

Returns:

list of arguments

Definition at line 97 of file lib/python/core.py.

def python::core::mapsets

(

search_path = False

)

List available mapsets.

Parameters:

searchPatch

True to list mapsets only in search path

Returns:

list of mapsets

Definition at line 872 of file lib/python/core.py.

Referenced by G_available_mapsets(), and list_mapsets().

def python::core::message	(		msg,
			flag = None
	)

Display a message using `g.message`.

Parameters:

msg	message to be displayed
flag	flags (given as string)

Definition at line 316 of file lib/python/core.py.

def python::core::mlist_grouped	(		type,
			pattern = None,
			check_search_path = True
	)

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:

>>> grass.mlist_grouped('rast', pattern='r*')['PERMANENT']
['railroads', 'roads', 'rstrct.areas', 'rushmore']

Parameters:

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

Returns:

directory of mapsets/elements

Definition at line 689 of file lib/python/core.py.

def python::core::overwrite

(

)

Return True if existing files may be overwritten.

Definition at line 777 of file lib/python/core.py.

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:

>>> grass.parse_color("red")
(1.0, 0.0, 0.0)
>>> grass.parse_color("255:0:0")
(1.0, 0.0, 0.0)

Parameters:

val	color value
dflt	default color value

Returns:

tuple RGB

Definition at line 748 of file lib/python/core.py.

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.

parse_command(..., parse = (grass.parse_key_val, { 'sep' : ':' }))

or you can simply define delimiter

parse_command(..., delimiter = ':')

Parameters:

args	list of unnamed arguments (see start_command() for details)
kwargs	list of named arguments (see start_command() for details)

Returns:

parsed module output

Definition at line 241 of file lib/python/core.py.

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: `=')

Parameters:

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)

Returns:

parsed input (dictionary of keys/values)

Definition at line 484 of file lib/python/core.py.

def python::core::parser

(

)

Interface to g.parser, intended to be run from the top-level, e.g.

:

    if __name__ == "__main__":
        options, flags = grass.parser()
        main()

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 lib/python/core.py.

def python::core::percent	(		i,
			n,
			s
	)

Display a progress info message using `g.message -p`.

message(_("Percent complete..."))
n = 100
for i in range(n):
    percent(i, n, 1)
percent(1, 1, 1)

Parameters:

i	current item
n	total number of items
s	increment size

Definition at line 346 of file lib/python/core.py.

def python::core::pipe_command	(		args,
			kwargs
	)

Passes all arguments to start_command(), but also adds "stdout = PIPE".

Returns the Popen object.

>>> p = grass.pipe_command("g.gisenv")
>>> print p
<subprocess.Popen object at 0xb7c12f6c>
>>> print p.communicate()[0]
GISDBASE='/opt/grass-data';
LOCATION_NAME='spearfish60';
MAPSET='glynn';
GRASS_DB_ENCODING='ascii';
GRASS_GUI='text';
MONITOR='x0';

Parameters:

args	list of unnamed arguments (see start_command() for details)
kwargs	list of named arguments (see start_command() for details)

Returns:

Popen object

Definition at line 192 of file lib/python/core.py.

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`).

Parameters:

args	list of unnamed arguments (see start_command() for details)
kwargs	list of named arguments (see start_command() for details)

Returns:

stdout

Definition at line 229 of file lib/python/core.py.

def python::core::region

(

)

Returns the output from running "g.region -g", as a dictionary.

Example:

>>> region = grass.region()
>>> [region[key] for key in "nsew"]
[228500.0, 215000.0, 645000.0, 630000.0]
>>> (region['nsres'], region['ewres'])
(10.0, 10.0)

Returns:

dictionary of region values

Definition at line 542 of file lib/python/core.py.

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.

Parameters:

args	list of unnamed arguments (see start_command() for details)
kwargs	list of named arguments (see start_command() for details)

Returns:

exit code (0 for success)

Definition at line 179 of file lib/python/core.py.

def python::core::set_raise_on_error

(

raise_exp = True

)

Define behaviour on error (error() called)

Parameters:

raise_exp

True to raise ScriptError instead of calling error()

Returns:

current status

Definition at line 391 of file lib/python/core.py.

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

>>> p = grass.start_command("g.gisenv", stdout = subprocess.PIPE)
>>> print p
<subprocess.Popen object at 0xb7c12f6c>
>>> print p.communicate()[0]
GISDBASE='/opt/grass-data';
LOCATION_NAME='spearfish60';
MAPSET='glynn';
GRASS_DB_ENCODING='ascii';
GRASS_GUI='text';
MONITOR='x0';

Parameters:

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

Returns:

Popen object

Definition at line 133 of file lib/python/core.py.

def python::core::tempdir

(

)

Returns the name of a temporary dir, created with g.tempfile.

Definition at line 474 of file lib/python/core.py.

def python::core::tempfile

(

)

Returns the name of a temporary file, created with g.tempfile.

Definition at line 470 of file lib/python/core.py.

def python::core::try_remove

(

path

)

Attempt to remove a file; no exception is generated if the attempt fails.

Parameters:

path	path to file to remove

Definition at line 837 of file lib/python/core.py.

def python::core::try_rmdir

(

path

)

Attempt to remove a directory; no exception is generated if the attempt fails.

Parameters:

path	path to directory to remove

Definition at line 850 of file lib/python/core.py.

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 562 of file lib/python/core.py.

def python::core::verbose

(

msg

)

Display a verbose message using `g.message -v`.

Parameters:

msg	verbose message to be displayed

Definition at line 332 of file lib/python/core.py.

def python::core::verbosity

(

)

Return the verbosity level selected by GRASS_VERBOSE.

Definition at line 784 of file lib/python/core.py.

def python::core::version

(

)

Get GRASS version as dictionary.

print version()

{'date': '2011', 'libgis_date': '2011-02-26 21:31:24 +0100 (Sat, 26 Feb 2011)',
'version': '6.5.svn', 'libgis_revision': '45467', 'revision': '47305'}

Definition at line 1024 of file lib/python/core.py.

Referenced by main().

def python::core::warning

(

msg

)

Display a warning message using `g.message -w`.

Parameters:

msg	warning message to be displayed

Definition at line 363 of file lib/python/core.py.

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.

Parameters:

args	list of unnamed arguments (see start_command() for details)
kwargs	list of named arguments (see start_command() for details)

Returns:

return code

Definition at line 282 of file lib/python/core.py.

---

Variable Documentation

list python::core::_popen_args

Initial value:

["bufsize", "executable", "stdin", "stdout", "stderr",
               "preexec_fn", "close_fds", "cwd", "env",
               "universal_newlines", "startupinfo", "creationflags"]

Definition at line 76 of file lib/python/core.py.

tuple python::core::debug_level = 0

Definition at line 69 of file lib/python/core.py.

dictionary python::core::named_colors

Initial value:

{
    "white":   (1.00, 1.00, 1.00),
    "black":   (0.00, 0.00, 0.00),
    "red":     (1.00, 0.00, 0.00),
    "green":   (0.00, 1.00, 0.00),
    "blue":    (0.00, 0.00, 1.00),
    "yellow":  (1.00, 1.00, 0.00),
    "magenta": (1.00, 0.00, 1.00),
    "cyan":    (0.00, 1.00, 1.00),
    "aqua":    (0.00, 0.75, 0.75),
    "grey":    (0.75, 0.75, 0.75),
    "gray":    (0.75, 0.75, 0.75),
    "orange":  (1.00, 0.50, 0.00),
    "brown":   (0.75, 0.50, 0.25),
    "purple":  (0.50, 0.00, 1.00),
    "violet":  (0.50, 0.00, 1.00),
    "indigo":  (0.00, 0.50, 1.00)}

Definition at line 730 of file lib/python/core.py.

python::core::PIPE = subprocess.PIPE

Definition at line 58 of file lib/python/core.py.

python::core::raise_on_error = False

Definition at line 68 of file lib/python/core.py.

python::core::STDOUT = subprocess.STDOUT

Definition at line 59 of file lib/python/core.py.