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

/*! \page pythonlib GRASS Python Scripting Library

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

\section pythonIntro Introduction

The code in <a
href="http://svn.osgeo.org/grass/grass/trunk/lib/python/">lib/python/</a>
provides <b>grass.script</b> in order to support GRASS scripts written
in Python. The <a
href="http://svn.osgeo.org/grass/grass/trunk/scripts">scripts/</a>
directory of GRASS contains a series of examples actually provided to
the end users.

See code in:

- python::core
- python::db
- python::raster
- python::vector
- python::setup
- python::array

<b>Table of content</b>

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

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

The statement

\code
import grass.script as grass
\endcode

imports core.py, db.py, raster.py and vector.py modules.

To import only selected module

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

Sample script (See the GRASS Wiki at 
<a href="http://grass.osgeo.org/wiki/GRASS_and_Python">http://grass.osgeo.org/wiki/GRASS_and_Python</a> for more examples)

\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.vector_info_topo(map = options['map'])
    if info['map3d']:
        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>

 - python::core::exec_command()

 - python::core::feed_command()

 - python::core::make_command()

 - python::core::parse_command()

 - python::core::pipe_command()

 - python::core::read_command()

 - python::core::run_command()

 - python::core::start_command()

 - python::core::write_command()

<b>Interface to \gmod{g.message}</b>

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

 - python::core::debug()

 - python::core::error()

 - python::core::fatal()

 - python::core::info()

 - python::core::message()

 - python::core::verbose()

 - python::core::warning()

<b>Interface to \gmod{g.parser}</b>

Interface to \gmod{g.parser}, intended to be run from the top-level, e.g.

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

 - python::core::parser()

<b>Interface to \gmod{g.tempfile}</b>

Returns the name of a temporary file, created with \gmod{g.tempfile}.

 - python::core::tempfile()

<b>Key-value parsers</b>

 - python::core::parse_key_val()

<b>Interface to \gmod{g.gisenv}</b>

 - python::core::gisenv()

<b>Interface to \gmod{g.region}</b>

 - python::core::del_temp_region()

 - python::core::region()

 - python::core::region_env()

 - python::core::use_temp_region()

<b>Interface to \gmod{g.findfile}</b>

 - python::core::find_file()

<b>Interface to \gmod{g.list}</b>

 - python::core::list_grouped()

 - python::core::list_pairs()

 - python::core::list_strings()

 - python::core::mlist_grouped()

<b>Interface to \gmod{g.mapsets}</b>

 - python::core::mapsets()

<b>Interface to \gmod{g.version}</b>

 - python::core::version()

<b>Color parsing</b>

 - python::core::parse_color()

<b>Check GRASS environment variables</b>

 - python::core::overwrite()

 - python::core::verbosity()

<b>Create new GRASS location</b>

 - python::core::create_location()

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

 - python::core::find_program()

 - python::core::try_remove()

 - python::core::try_rmdir()

 - python::core::float_or_dms()

\section pythonDb Database

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

 - python::db::db_connection()

 - python::db::db_describe()

 - python::db::db_select()

\section pythonRaster Raster

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

 - python::raster::raster_history()

 - python::raster::raster_info()

 - python::raster::mapcalc()

\section pythonVector Vector

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

 - python::vector::vector_columns()

 - python::vector::vector_db()

 - python::vector::vector_db_select()

 - python::vector::vector_history()

 - python::vector::vector_info_topo()

 - python::vector::vector_layer_db()

\section pythonSetup Setup

\code
from grass.script import setup as gsetup
\endcode

 - python::setup::init()

\section pythonArray Array

\code
from grass.script import array as garray
\endcode

 - python::array::array

\section pythonAuthors Authors

 Glynn Clements

 Martin Landa <landa.martin gmail.com>

*/