Geografic-Information-System/lib/python/grasspythonlib.dox

/*! \page pythonlib GRASS Python Scripting Library

by GRASS Development Team (http://grass.osgeo.org)

\section pythonIntro Introduction

The code in <tt>lib/python/</tt> provides <b>grass.script</b> in order
to support GRASS scripts written in Python. The <tt>scripts/</tt>
directory of GRASS contains a series of examples actually provided to
the end users.

See code in:

- core.py
- db.py
- raster.py
- vector.py

<b>Table of content</b>

- \subpage pythonScripting
- \subpage pythonModules
 - \subpage pythonCore
 - \subpage pythonDb
 - \subpage pythonRaster
 - \subpage pythonVector

\section pythonScripting GRASS scripting tasks for Python provided by "grass.script"

Usage:

\code
import grass.script as grass
\endcode

or just import selected module, e.g.

\code
from grass.script import core as grass
\endcode

Sample script

\code
#!/usr/bin/env python

#%module
#% description: Checks if vector map is 3D
#% keywords: vector
#%end
#%option
#% key: map
#% type: string
#% gisprompt: old,vector,vector
#% key_desc: name
#% description: Name of vector map 
#% required: yes
#%end

import sys
import grass.script as grass

def main():
    info = grass.parse_command('v.info',
                               flags = 't',
                               map = options['map'])
    if info['map3d'] == '1':
        print 'Vector map is 3D'
    else:
        print 'Vector map is 2D'

    return 0

if __name__ == "__main__":
    options, flags = grass.parser()
    sys.exit(main())
\endcode

\section pythonModules List of modules

\subsection pythonCore Core

<b>GRASS-oriented interface to subprocess module</b>

 - exec_command()

 - feed_command()

 - make_command()

 - parse_command()

 - pipe_command()

 - read_command()

 - run_command()

 - start_command()

 - write_command()

<b>Interface to g.message</b>

These all run g.message, differing only in which flag (if any) is
used. fatal() is error(), but also calls sys.exit(1).

 - debug()

 - error()

 - fatal()

 - info()

 - message()

 - verbose()

 - warning()

<b>Interface to g.parser</b>

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

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

 - parser()

<b>Interface to g.tempfile</b>

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

 - tempfile()

<b>Key-value parsers</b>

 - parse_key_val()

<b>Interface to g.gisenv</b>

 - gisenv()

<b>Interface to g.region</b>

 - del_temp_region()

 - region()

 - use_temp_region()

<b>Interface to g.findfile</b>

 - find_file()

<b>Interface to g.list</b>

 - list_grouped()

 - list_pairs()

 - list_strings()

 - mlist_grouped()

<b>Color parsing</b>

 - parse_color()

<b>Check GRASS environment variables</b>

 - overwrite()

 - verbosity()

<b>Various utilities, not specific to GRASS</b>
 
 - basename()

 - find_program()

 - try_remove()

 - try_rmdir()

 - float_or_dms()

\section pythonDb Database

Interface for <tt>db.*</tt> modules.

\code
from grass.script import db as grass
\endcode

 - db_connection()

 - db_describe()

 - db_select()

\section pythonRaster Raster

Interface for <tt>r.*</tt> modules.

\code
from grass.script import raster as grass
\endcode

 - raster_history()

 - raster_info()

 - mapcalc()

\section pythonVector Vector

Interface for <tt>v.*</tt> modules.

\code
from grass.script import vector as grass
\endcode

 - vector_columns()

 - vector_db()

 - vector_db_select()

 - vector_history()

 - vector_info_topo()

 - vector_layer_db()

\section pythonAuthors Authors

 Glynn Clements

 Martin Landa <landa.martin gmail.com>

*/