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 <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
- setup.py

<b>Table of content</b>

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

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

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

 - python::core::debug()

 - python::core::error()

 - python::core::fatal()

 - python::core::info()

 - python::core::message()

 - python::core::verbose()

 - python::core::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

 - python::core::parser()

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

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

 - python::core::tempfile()

<b>Key-value parsers</b>

 - python::core::parse_key_val()

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

 - python::core::gisenv()

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

 - python::core::del_temp_region()

 - python::core::region()

 - python::core::use_temp_region()

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

 - python::core::find_file()

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

 - python::core::list_grouped()

 - python::core::list_pairs()

 - python::core::list_strings()

 - python::core::mlist_grouped()

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

 - python::core::mapsets()

<b>Color parsing</b>

 - python::core::parse_color()

<b>Check GRASS environment variables</b>

 - python::core::overwrite()

 - python::core::verbosity()

<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

 - python::setup::init()

\section pythonAuthors Authors

 Glynn Clements

 Martin Landa <landa.martin gmail.com>

*/