1 """!@package grass.script.core
3 @brief GRASS Python scripting module (core functions)
5 Core functions to be used in Python scripts.
10 from grass.script import core as grass
16 (C) 2008-2011 by the GRASS Development Team
17 This program is free software under the GNU General Public
18 License (>=v2). Read the file COPYING that comes with GRASS
21 @author Glynn Clements
22 @author Martin Landa <landa.martin gmail.com>
23 @author Michael Barton <michael.barton asu.edu>
38 gettext.install(
'grasslibs', os.path.join(os.getenv(
"GISBASE"),
'locale'), unicode=
True)
43 def __init__(self, args, bufsize = 0, executable = None,
44 stdin =
None, stdout =
None, stderr =
None,
45 preexec_fn =
None, close_fds =
False, shell =
None,
46 cwd =
None, env =
None, universal_newlines =
False,
47 startupinfo =
None, creationflags = 0):
50 shell = (sys.platform ==
"win32")
52 subprocess.Popen.__init__(self, args, bufsize, executable,
53 stdin, stdout, stderr,
54 preexec_fn, close_fds, shell,
55 cwd, env, universal_newlines,
56 startupinfo, creationflags)
58 PIPE = subprocess.PIPE
59 STDOUT = subprocess.STDOUT
66 return repr(self.
value)
68 raise_on_error =
False
72 return Popen(*args, **kwargs).wait()
76 _popen_args = [
"bufsize",
"executable",
"stdin",
"stdout",
"stderr",
77 "preexec_fn",
"close_fds",
"cwd",
"env",
78 "universal_newlines",
"startupinfo",
"creationflags"]
81 enc = locale.getdefaultlocale()[1]
83 return string.decode(enc)
88 if isinstance(val, types.StringType)
or \
89 isinstance(val, types.UnicodeType):
91 if isinstance(val, types.ListType):
92 return ",".join(
map(_make_val, val))
93 if isinstance(val, types.TupleType):
94 return _make_val(list(val))
97 def make_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **options):
98 """!Return a list of strings suitable for use as the args parameter to
99 Popen() or call(). Example:
102 >>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
103 ['g.message', '-w', 'message=this is a warning']
106 @param prog GRASS module
107 @param flags flags to be used (given as a string)
108 @param overwrite True to enable overwriting the output (<tt>--o</tt>)
109 @param quiet True to run quietly (<tt>--q</tt>)
110 @param verbose True to run verbosely (<tt>--v</tt>)
111 @param options module's parameters
113 @return list of arguments
125 args.append(
"-%s" % flags)
126 for opt, val
in options.iteritems():
130 args.append(
"%s=%s" % (opt, _make_val(val)))
133 def start_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **kwargs):
134 """!Returns a Popen object with the command created by make_command.
135 Accepts any of the arguments which Popen() accepts apart from "args"
139 >>> p = grass.start_command("g.gisenv", stdout = subprocess.PIPE)
141 <subprocess.Popen object at 0xb7c12f6c>
142 >>> print p.communicate()[0]
143 GISDBASE='/opt/grass-data';
144 LOCATION_NAME='spearfish60';
146 GRASS_DB_ENCODING='ascii';
151 @param prog GRASS module
152 @param flags flags to be used (given as a string)
153 @param overwrite True to enable overwriting the output (<tt>--o</tt>)
154 @param quiet True to run quietly (<tt>--q</tt>)
155 @param verbose True to run verbosely (<tt>--v</tt>)
156 @param kwargs module's parameters
162 for opt, val
in kwargs.iteritems():
163 if opt
in _popen_args:
167 args =
make_command(prog, flags, overwrite, quiet, verbose, **options)
168 if sys.platform ==
'win32' and os.path.splitext(prog)[1] ==
'.py':
169 os.chdir(os.path.join(os.getenv(
'GISBASE'),
'etc',
'gui',
'scripts'))
170 args.insert(0, sys.executable)
174 sys.stderr.write(
"D1/%d: %s.start_command(): %s\n" % (debug_level, __name__,
' '.join(args)))
177 return Popen(args, **popts)
180 """!Passes all arguments to start_command(), then waits for the process to
181 complete, returning its exit code. Similar to subprocess.call(), but
182 with the make_command() interface.
184 @param args list of unnamed arguments (see start_command() for details)
185 @param kwargs list of named arguments (see start_command() for details)
187 @return exit code (0 for success)
193 """!Passes all arguments to start_command(), but also adds
194 "stdout = PIPE". Returns the Popen object.
197 >>> p = grass.pipe_command("g.gisenv")
199 <subprocess.Popen object at 0xb7c12f6c>
200 >>> print p.communicate()[0]
201 GISDBASE='/opt/grass-data';
202 LOCATION_NAME='spearfish60';
204 GRASS_DB_ENCODING='ascii';
209 @param args list of unnamed arguments (see start_command() for details)
210 @param kwargs list of named arguments (see start_command() for details)
214 kwargs[
'stdout'] = PIPE
218 """!Passes all arguments to start_command(), but also adds
219 "stdin = PIPE". Returns the Popen object.
221 @param args list of unnamed arguments (see start_command() for details)
222 @param kwargs list of named arguments (see start_command() for details)
226 kwargs[
'stdin'] = PIPE
230 """!Passes all arguments to pipe_command, then waits for the process to
231 complete, returning its stdout (i.e. similar to shell `backticks`).
233 @param args list of unnamed arguments (see start_command() for details)
234 @param kwargs list of named arguments (see start_command() for details)
239 return ps.communicate()[0]
242 """!Passes all arguments to read_command, then parses the output
245 Parsing function can be optionally given by <em>parse</em> parameter
246 including its arguments, e.g.
249 parse_command(..., parse = (grass.parse_key_val, { 'sep' : ':' }))
252 or you can simply define <em>delimiter</em>
255 parse_command(..., delimiter = ':')
258 @param args list of unnamed arguments (see start_command() for details)
259 @param kwargs list of named arguments (see start_command() for details)
261 @return parsed module output
265 if 'parse' in kwargs:
266 if type(kwargs[
'parse'])
is types.TupleType:
267 parse = kwargs[
'parse'][0]
268 parse_args = kwargs[
'parse'][1]
271 if 'delimiter' in kwargs:
272 parse_args = {
'sep' : kwargs[
'delimiter'] }
273 del kwargs[
'delimiter']
276 parse = parse_key_val
280 return parse(res, **parse_args)
283 """!Passes all arguments to feed_command, with the string specified
284 by the 'stdin' argument fed to the process' stdin.
286 @param args list of unnamed arguments (see start_command() for details)
287 @param kwargs list of named arguments (see start_command() for details)
291 stdin = kwargs[
'stdin']
297 def exec_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, env = None, **kwargs):
298 """!Interface to os.execvpe(), but with the make_command() interface.
300 @param prog GRASS module
301 @param flags flags to be used (given as a string)
302 @param overwrite True to enable overwriting the output (<tt>--o</tt>)
303 @param quiet True to run quietly (<tt>--q</tt>)
304 @param verbose True to run verbosely (<tt>--v</tt>)
305 @param env directory with enviromental variables
306 @param kwargs module's parameters
309 args =
make_command(prog, flags, overwrite, quiet, verbose, **kwargs)
312 os.execvpe(prog, args, env)
317 """!Display a message using `g.message`
319 @param msg message to be displayed
320 @param flag flags (given as string)
322 run_command(
"g.message", flags = flag, message = msg)
325 """!Display a debugging message using `g.message -d`
327 @param msg debugging message to be displayed
328 @param debug debug level (0-5)
330 run_command(
"g.message", flags =
'd', message = msg, debug = debug)
333 """!Display a verbose message using `g.message -v`
335 @param msg verbose message to be displayed
340 """!Display an informational message using `g.message -i`
342 @param msg informational message to be displayed
347 """!Display a progress info message using `g.message -p`
350 message(_("Percent complete..."))
357 @param i current item
358 @param n total number of items
359 @param s increment size
361 message(
"%d %d %d" % (i, n, s), flag =
'p')
364 """!Display a warning message using `g.message -w`
366 @param msg warning message to be displayed
371 """!Display an error message using `g.message -e`
373 Raise exception when on_error is 'raise'.
375 @param msg error message to be displayed
377 global raise_on_error
384 """!Display an error message using `g.message -e`, then abort
386 @param msg error message to be displayed
392 """!Define behaviour on error (error() called)
394 @param raise_exp True to raise ScriptError instead of calling
397 @return current status
399 global raise_on_error
400 tmp_raise = raise_on_error
401 raise_on_error = raise_exp
405 def _parse_opts(lines):
409 line = line.rstrip(
'\r\n')
413 [var, val] = line.split(
'=', 1)
415 raise SyntaxError(
"invalid output from g.parser: %s" % line)
417 if var.startswith(
'flag_'):
418 flags[var[5:]] = bool(int(val))
419 elif var.startswith(
'opt_'):
420 options[var[4:]] = val
421 elif var
in [
'GRASS_OVERWRITE',
'GRASS_VERBOSE']:
422 os.environ[var] = val
424 raise SyntaxError(
"invalid output from g.parser: %s" % line)
426 return (options, flags)
429 """!Interface to g.parser, intended to be run from the top-level, e.g.:
432 if __name__ == "__main__":
433 options, flags = grass.parser()
437 Thereafter, the global variables "options" and "flags" will be
438 dictionaries containing option/flag values, keyed by lower-case
439 option/flag names. The values in "options" are strings, those in
440 "flags" are Python booleans.
442 if not os.getenv(
"GISBASE"):
443 print >> sys.stderr,
"You must be in GRASS GIS to run this program."
447 cmdline += [
'"' + arg +
'"' for arg
in sys.argv[1:]]
448 os.environ[
'CMDLINE'] =
' '.join(cmdline)
452 if not os.path.isabs(name):
453 if os.sep
in name
or (os.altsep
and os.altsep
in name):
454 argv[0] = os.path.abspath(name)
456 argv[0] = os.path.join(sys.path[0], name)
458 p =
Popen([
'g.parser',
'-s'] + argv, stdout = PIPE)
459 s = p.communicate()[0]
460 lines = s.splitlines()
462 if not lines
or lines[0].rstrip(
'\r\n') !=
"@ARGS_PARSED@":
464 sys.exit(p.returncode)
466 return _parse_opts(lines[1:])
471 """!Returns the name of a temporary file, created with g.tempfile."""
472 return read_command(
"g.tempfile", pid = os.getpid()).strip()
475 """!Returns the name of a temporary dir, created with g.tempfile."""
476 tmp =
read_command(
"g.tempfile", pid = os.getpid()).strip()
485 """!Parse a string into a dictionary, where entries are separated
486 by newlines and the key and value are separated by `sep' (default: `=')
488 @param s string to be parsed
489 @param sep key/value separator
490 @param dflt default value to be used
491 @param val_type value type (None for no cast)
492 @param vsep vertical separator (default os.linesep)
494 @return parsed input (dictionary of keys/values)
502 lines = s.split(vsep)
508 lines = s.splitlines()
511 kv = line.split(sep, 1)
518 result[k] = val_type(v)
526 """!Returns the output from running g.gisenv (with no arguments), as a
530 >>> env = grass.gisenv()
531 >>> print env['GISDBASE']
535 @return list of GRASS variables
543 """!Returns the output from running "g.region -g", as a
547 >>> region = grass.region()
548 >>> [region[key] for key in "nsew"]
549 [228500.0, 215000.0, 645000.0, 630000.0]
550 >>> (region['nsres'], region['ewres'])
554 @return dictionary of region values
558 for k
in [
'rows',
'cols']:
563 """!Copies the current region to a temporary region with "g.region save=",
564 then sets WIND_OVERRIDE to refer to that region. Installs an atexit
565 handler to delete the temporary region upon termination.
567 name =
"tmp.%s.%d" % (os.path.basename(sys.argv[0]), os.getpid())
568 run_command(
"g.region", save = name, overwrite =
True)
569 os.environ[
'WIND_OVERRIDE'] = name
570 atexit.register(del_temp_region)
573 """!Unsets WIND_OVERRIDE and removes any region named by it."""
575 name = os.environ.pop(
'WIND_OVERRIDE')
576 run_command(
"g.remove", quiet =
True, region = name)
583 """!Returns the output from running g.findfile as a
587 >>> result = grass.find_file('fields', element = 'vector')
588 >>> print result['fullname']
590 >>> print result['file']
591 /opt/grass-data/spearfish60/PERMANENT/vector/fields
594 @param name file name
595 @param element element type (default 'cell')
596 @param mapset mapset name (default all mapsets in search path)
598 @return parsed output of g.findfile
600 s =
read_command(
"g.findfile", flags=
'n', element = element, file = name, mapset = mapset)
606 """!List elements grouped by mapsets.
608 Returns the output from running g.list, as a dictionary where the
609 keys are mapset names and the values are lists of maps in that
613 >>> grass.list_grouped('rast')['PERMANENT']
614 ['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...
617 @param type element type (rast, vect, rast3d, region, ...)
618 @param check_search_path True to add mapsets for the search path with no found elements
620 @return directory of mapsets/elements
622 dashes_re = re.compile(
"^----+$")
623 mapset_re = re.compile(
"<(.*)>")
625 if check_search_path:
626 for mapset
in mapsets(search_path =
True):
630 for line
in read_command(
"g.list", type = type).splitlines():
633 if dashes_re.match(line):
635 m = mapset_re.search(line)
638 if mapset
not in result.keys():
642 result[mapset].extend(line.split())
653 """!List of elements as tuples.
655 Returns the output from running g.list, as a list of (map, mapset)
659 >>> grass.list_pairs('rast')
660 [('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...
663 @param type element type (rast, vect, rast3d, region, ...)
665 @return list of tuples (map, mapset)
667 return _concat([[(map, mapset)
for map
in maps]
671 """!List of elements as strings.
673 Returns the output from running g.list, as a list of qualified
677 >>> grass.list_strings('rast')
678 ['aspect@PERMANENT', 'erosion1@PERMANENT', 'quads@PERMANENT', 'soils@PERMANENT', ...
681 @param type element type
683 @return list of strings ('map@@mapset')
685 return [
"%s@%s" % pair
for pair
in list_pairs(type)]
690 """!List of elements grouped by mapsets.
692 Returns the output from running g.mlist, as a dictionary where the
693 keys are mapset names and the values are lists of maps in that
697 >>> grass.mlist_grouped('rast', pattern='r*')['PERMANENT']
698 ['railroads', 'roads', 'rstrct.areas', 'rushmore']
701 @param type element type (rast, vect, rast3d, region, ...)
702 @param pattern pattern string
703 @param check_search_path True to add mapsets for the search path with no found elements
705 @return directory of mapsets/elements
708 if check_search_path:
709 for mapset
in mapsets(search_path =
True):
714 type = type, pattern = pattern).splitlines():
716 name, mapset = line.split(
'@')
718 warning(_(
"Invalid element '%s'") % line)
722 result[mapset].append(name)
724 result[mapset] = [name, ]
731 "white": (1.00, 1.00, 1.00),
732 "black": (0.00, 0.00, 0.00),
733 "red": (1.00, 0.00, 0.00),
734 "green": (0.00, 1.00, 0.00),
735 "blue": (0.00, 0.00, 1.00),
736 "yellow": (1.00, 1.00, 0.00),
737 "magenta": (1.00, 0.00, 1.00),
738 "cyan": (0.00, 1.00, 1.00),
739 "aqua": (0.00, 0.75, 0.75),
740 "grey": (0.75, 0.75, 0.75),
741 "gray": (0.75, 0.75, 0.75),
742 "orange": (1.00, 0.50, 0.00),
743 "brown": (0.75, 0.50, 0.25),
744 "purple": (0.50, 0.00, 1.00),
745 "violet": (0.50, 0.00, 1.00),
746 "indigo": (0.00, 0.50, 1.00)}
749 """!Parses the string "val" as a GRASS colour, which can be either one of
750 the named colours or an R:G:B tuple e.g. 255:255:255. Returns an
751 (r,g,b) triple whose components are floating point values between 0
755 >>> grass.parse_color("red")
757 >>> grass.parse_color("255:0:0")
761 @param val color value
762 @param dflt default color value
766 if val
in named_colors:
767 return named_colors[val]
769 vals = val.split(
':')
771 return tuple(float(v) / 255
for v
in vals)
778 """!Return True if existing files may be overwritten"""
779 owstr =
'GRASS_OVERWRITE'
780 return owstr
in os.environ
and os.environ[owstr] !=
'0'
785 """!Return the verbosity level selected by GRASS_VERBOSE"""
786 vbstr = os.getenv(
'GRASS_VERBOSE')
797 """!Remove leading directory components and an optional extension
798 from the specified path
803 name = os.path.basename(path)
806 fs = name.rsplit(
'.', 1)
807 if len(fs) > 1
and fs[1].lower() == ext:
814 """!Attempt to run a program, with optional arguments.
816 @param pgm program name
817 @param args list of arguments
819 @return False if the attempt failed due to a missing executable
820 @return True otherwise
822 nuldev = file(os.devnull,
'w+')
824 ret =
call([pgm] + args, stdin = nuldev, stdout = nuldev, stderr = nuldev)
838 """!Attempt to remove a file; no exception is generated if the
841 @param path path to file to remove
851 """!Attempt to remove a directory; no exception is generated if the
854 @param path path to directory to remove
859 shutil.rmtree(path, ignore_errors =
True)
862 """!Convert DMS to float.
868 return sum(float(x) / 60 ** n
for (n, x)
in enumerate(s.split(
':')))
873 """!List available mapsets
875 @param searchPatch True to list mapsets only in search path
877 @return list of mapsets
888 fatal(_(
"Unable to list mapsets"))
890 return mapsets.splitlines()
895 epsg =
None, proj4 =
None, filename =
None, wkt =
None,
896 datum =
None, desc =
None):
897 """!Create new location
899 Raise ScriptError on error.
901 @param dbase path to GRASS database
902 @param location location name to create
903 @param epgs if given create new location based on EPSG code
904 @param proj4 if given create new location based on Proj4 definition
905 @param filename if given create new location based on georeferenced file
906 @param wkt if given create new location based on WKT definition (path to PRJ file)
907 @param datum datum transformation parameters (used for epsg and proj4)
908 @param desc description of the location (creates MYNAME file)
911 if epsg
or proj4
or filename
or wkt:
912 gisdbase =
gisenv()[
'GISDBASE']
914 set =
'GISDBASE=%s' % dbase)
915 if not os.path.exists(dbase):
920 kwargs[
'datum'] = datum
953 _create_location_xy(dbase, location)
955 if epsg
or proj4
or filename
or wkt:
956 error = ps.communicate()[1]
958 set =
'GISDBASE=%s' % gisdbase)
960 if ps.returncode != 0
and error:
964 fd = codecs.open(os.path.join(dbase, location,
965 'PERMANENT',
'MYNAME'),
966 encoding =
'utf-8', mode =
'w')
968 fd.write(desc + os.linesep)
975 def _create_location_xy(database, location):
976 """!Create unprojected location
978 Raise ScriptError on error.
980 @param database GRASS database where to create new location
981 @param location location name
983 cur_dir = os.getcwd()
987 os.mkdir(os.path.join(location,
'PERMANENT'))
990 regioninfo = [
'proj: 0',
1009 defwind = open(os.path.join(location,
1010 "PERMANENT",
"DEFAULT_WIND"),
'w')
1011 for param
in regioninfo:
1012 defwind.write(param +
'%s' % os.linesep)
1015 shutil.copy(os.path.join(location,
"PERMANENT",
"DEFAULT_WIND"),
1016 os.path.join(location,
"PERMANENT",
"WIND"))
1025 """!Get GRASS version as dictionary
1030 {'date': '2011', 'libgis_date': '2011-04-13 13:19:03 +0200 (Wed, 13 Apr 2011)',
1031 'version': '6.4.2svn', 'libgis_revision': '45934', 'revision': '47445'}
1036 for k, v
in data.iteritems():
1037 data[k.strip()] = v.replace(
'"',
'').strip()
1043 debug_level = int(
gisenv().get(
'DEBUG', 0))