[GRASS-SVN] r70140 - grass/branches/releasebranch_7_2/lib/python/docs/src
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue Dec 27 03:34:10 PST 2016
Author: martinl
Date: 2016-12-27 03:34:10 -0800 (Tue, 27 Dec 2016)
New Revision: 70140
Modified:
grass/branches/releasebranch_7_2/lib/python/docs/src/
grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_gis.rst
grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_index.rst
grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_messages.rst
grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_modules.rst
grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_raster.rst
grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_vector.rst
Log:
PyGRASS docs cosmentics + svn prop update (relbr72: merge 70138,70139 from trunk)
Property changes on: grass/branches/releasebranch_7_2/lib/python/docs/src
___________________________________________________________________
Added: svn:ignore
+ exceptions.rst
gunittest.rst
imaging.rst
pydispatch.rst
pygrass.gis.rst
pygrass.messages.rst
pygrass.modules.grid.rst
pygrass.modules.interface.rst
pygrass.modules.rst
pygrass.raster.rst
pygrass.rpc.rst
pygrass.rst
pygrass.shell.rst
pygrass.tests.rst
pygrass.vector.rst
script.rst
temporal.rst
Modified: grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_gis.rst
===================================================================
--- grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_gis.rst 2016-12-27 11:30:36 UTC (rev 70139)
+++ grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_gis.rst 2016-12-27 11:34:10 UTC (rev 70140)
@@ -1,21 +1,30 @@
.. _GRASSdatabase-label:
GRASS database management
-===============================
+=========================
-These classes are used to manage the infrastructure
-of GRASS database: Gisdbase, Location and Mapset
+PyGRASS imlements the classes described bellow:
-Details about the GRASS GIS database management (locations and mapsets)
-can be found in the `GRASS GIS 7 User's Manual: GRASS GIS Quickstart <http://grass.osgeo.org/grass72/manuals/helptext.html>`_
+* :class:`~pygrass.gis.Gisdbase`
+* :class:`~pygrass.gis.Location`
+* :class:`~pygrass.gis.Mapset`
+* :class:`~pygrass.gis.VisibleMapset`
+
+These classes are used to manage the infrastructure of GRASS database:
+GIS data directory, Location and Mapset. Details about the GRASS GIS
+database management (locations and mapsets) can be found in the `GRASS
+GIS 7 User's Manual: GRASS GIS Quickstart
+<http://grass.osgeo.org/grass72/manuals/helptext.html>`_.
.. _Region-label:
Region management
-======================
+=================
-The Region class it is useful to obtain information
-about the computational region and to change it.
+The :class:`~pygrass.gis.region.Region` class it is useful to obtain
+information about the computational region and to change it. Details
+about the GRASS GIS computational region management can be found in
+the `GRASS GIS Wiki: Computational region
+<http://grasswiki.osgeo.org/wiki/Computational_region>`_.
-Details about the GRASS GIS computational region management can be found
-in the `GRASS GIS Wiki: Computational region <http://grasswiki.osgeo.org/wiki/Computational_region>`_
+The classes are part of the :mod:`~pygrass.gis` module.
Modified: grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_index.rst
===================================================================
--- grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_index.rst 2016-12-27 11:30:36 UTC (rev 70139)
+++ grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_index.rst 2016-12-27 11:34:10 UTC (rev 70140)
@@ -1,12 +1,12 @@
PyGRASS documentation
-===================================
+=====================
Python is a programming language which is more powerful than shell
-scripting but easier and more forgiving than C. ``PyGRASS`` is an
+scripting but easier and more forgiving than C. *PyGRASS* is an
object-oriented Python Application Programming Interface (API) for
-GRASS GIS. ``PyGRASS`` offers interfaces to GRASS modules and
+GRASS GIS. *PyGRASS* offers interfaces to GRASS modules and
functionality, as well as to vector and raster data. For details,
-see Zambelli et al. (2013) in the references below. ``PyGRASS``
+see Zambelli et al. (2013) in the references below. *PyGRASS*
improves the integration between GRASS GIS and Python, making the
use of Python under GRASS more consistent with the language itself.
Furthermore, it simplifies GRASS scripting and programming and more
@@ -17,15 +17,15 @@
and developers converted all shell scripts from GRASS GIS 6 to Python
for GRASS GIS 7.
-To work with ``PyGRASS`` you need an up-to-date version of GRASS
-GIS 7. The only action before starting to work with ``PyGRASS`` is
-to launch GRASS GIS 7 and from the console launch ``python`` or
-``ipython`` (the second one is the recommended way).
+To work with *PyGRASS* you need an up-to-date version of GRASS
+GIS 7. The only action before starting to work with *PyGRASS* is
+to launch GRASS GIS 7 and from the console launch *python* or
+*ipython* (the second one is the recommended way).
-Read more about how to work with ``pygrass`` in this documentation.
+Read more about how to work with *PyGRASS* in this documentation.
-Contents:
+**Contents:**
.. toctree::
:maxdepth: 2
@@ -39,15 +39,23 @@
References
-^^^^^^^^^^^^^
+^^^^^^^^^^
-* Zambelli P, Gebbert S, Ciolli M., 2013. *Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)*. ISPRS International Journal of Geo-Information. 2(1):201-219. `doi:10.3390/ijgi2010201 <http://dx.doi.org/10.3390/ijgi2010201>`_
-* `Python related articles in the GRASS GIS Wiki <http://grasswiki.osgeo.org/wiki/Category:Python>`_
-* `GRASS GIS 7 Programmer's Manual <http://grass.osgeo.org/programming7/>`_
+* Zambelli P, Gebbert S, Ciolli M., 2013. *Pygrass: An Object Oriented
+ Python Application Programming Interface (API) for Geographic
+ Resources Analysis Support System (GRASS) Geographic Information
+ System (GIS)*. ISPRS International Journal of
+ Geo-Information. 2(1):201-219. `doi:10.3390/ijgi2010201
+ <http://dx.doi.org/10.3390/ijgi2010201>`_
+* `Python related articles in the GRASS GIS Wiki
+ <http://grasswiki.osgeo.org/wiki/Category:Python>`_
+* `GRASS GIS 7 Programmer's Manual
+ <http://grass.osgeo.org/programming7/>`_
-This project has been funded with support from the `Google Summer of Code 2012 <http://trac.osgeo.org/grass/wiki/GSoC#PythonhighlevelmapinteractionforGRASSGIS>`_
+This project has been funded with support from the `Google Summer of
+Code 2012
+<http://trac.osgeo.org/grass/wiki/GSoC#PythonhighlevelmapinteractionforGRASSGIS>`_
-
..
Indices and tables
==================
Modified: grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_messages.rst
===================================================================
--- grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_messages.rst 2016-12-27 11:30:36 UTC (rev 70139)
+++ grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_messages.rst 2016-12-27 11:34:10 UTC (rev 70140)
@@ -1,12 +1,14 @@
PyGRASS message interface
=========================
-The PyGRASS message interface is a fast and exit-safe
-interface to the `GRASS C-library message functions <http://grass.osgeo.org/programming7/gis_2error_8c.html>`_.
+The PyGRASS message interface is a fast and exit-safe interface to the
+`GRASS C-library message functions
+<http://grass.osgeo.org/programming7/gis_2error_8c.html>`_.
-This class implements a fast and exit-safe interface to the GRASS
-C-library message functions like: G_message(), G_warning(),
-G_important_message(), G_verbose_message(), G_percent() and G_debug().
+The :class:`~pygrass.messages.Messenger` class implements a fast and
+exit-safe interface to the GRASS C-library message functions like:
+``G_message()``, ``G_warning()``, ``G_important_message()``,
+``G_verbose_message()``, ``G_percent()`` and ``G_debug()``.
Usage:
Modified: grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_modules.rst
===================================================================
--- grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_modules.rst 2016-12-27 11:30:36 UTC (rev 70139)
+++ grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_modules.rst 2016-12-27 11:34:10 UTC (rev 70140)
@@ -1,9 +1,11 @@
Interface to GRASS GIS modules
==============================
-In "modules", GRASS GIS modules are represented as objects. These objects
-are generated based on the XML module description that is used also for
-the generation of the graphical user interface (GUI). ::
+In :mod:`~pygrass.modules` module, GRASS GIS modules are represented
+by :class:`~pygrass.modules.interface.module.Module` class
+objects. These objects are generated based on the XML module
+description that is used also for the generation of the graphical user
+interface (GUI). ::
>>> from grass.pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
@@ -138,7 +140,7 @@
information. To see all module inputs, just type: ::
>>> slope_aspect.inputs #doctest: +NORMALIZE_WHITESPACE
- TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> (required:no, type:string, multiple:no)), ('prec', Parameter <prec> (required:no, type:string, multiple:no)), ('zfactor', Parameter <zfactor> (required:no, type:float, multiple:no)), ('min_slp_allowed', Parameter <min_slp_allowed> (required:no, type:float, multiple:no))])
+ TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> ...)])
To get information for each parameter: ::
@@ -204,6 +206,13 @@
>>> category = Module("r.category", map="elevation",
... stdin_=info.popen.stdout, finish_=True)
+Launching GRASS GIS modules in parallel
+---------------------------------------
+PyGRASS implements simple mechanism for launching GRASS modules in
+parallel. See
+:class:`~pygrass.modules.interface.module.ParallelModuleQueue` class
+for details.
+
.. _Popen: http://docs.python.org/library/subprocess.html#Popen
Modified: grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_raster.rst
===================================================================
--- grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_raster.rst 2016-12-27 11:30:36 UTC (rev 70139)
+++ grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_raster.rst 2016-12-27 11:34:10 UTC (rev 70140)
@@ -4,18 +4,20 @@
==============================
Details about the GRASS GIS raster architecture can be found in the
-`GRASS GIS 7 Programmer's Manual: GRASS Raster Library <http://grass.osgeo.org/programming7/rasterlib.html>`_
+`GRASS GIS 7 Programmer's Manual: GRASS Raster Library
+<http://grass.osgeo.org/programming7/rasterlib.html>`_.
-PyGRASS uses 3 different Raster classes, that respect the 3 different approaches
-of GRASS-C API. The classes use a standardized interface to keep methods
-consistent between them. The read access is row wise for :ref:`RasterRow-label`
-and :ref:`RasterRowIO-label` and additionally
-cached in the RowIO class. Both classes write sequentially.
-RowIO is row cached, :ref:`RasterSegment-label`
-is tile cached for reading and writing; therefore, random access is possible.
-Hence RasterRow and RasterRowIO should be used for fast (cached)
-row read access and RasterRow for fast sequential writing.
-RasterSegment should be used for random access.
+PyGRASS uses 3 different raster classes, that respect the 3 different
+approaches of GRASS-C API. The classes use a standardized interface to
+keep methods consistent between them. The read access is row wise for
+:ref:`RasterRow-label` and :ref:`RasterRowIO-label` and additionally
+cached in the RowIO class. Both classes write sequentially. RowIO is
+row cached, :ref:`RasterSegment-label` is tile cached for reading and
+writing; therefore, random access is possible. Hence RasterRow and
+RasterRowIO should be used for fast (cached) row read access and
+RasterRow for fast sequential writing. RasterSegment should be used
+for random access. The classes are part of the :mod:`~pygrass.raster`
+module.
========================== ======================= ======== ============
@@ -64,12 +66,12 @@
RasterRow
---------
-The PyGrass :class:`~pygrass.raster.RasterRow` class allow user to open maps row
+The PyGRASS :class:`~pygrass.raster.RasterRow` class allow user to open maps row
by row in either read or write mode using the `Raster library`_. Reading and writing
to the same map at the same time is not supported. For this functionality,
please see the :ref:`RasterSegment-label` class.
The RasterRow class allows map rows to be read in any order, but map rows can
-only be written in sequential order. Therefore, each now row written to a map is
+only be written in sequential order. Therefore, each row written to a map is
added to the file as the last row. ::
>>> raster = reload(raster)
@@ -124,7 +126,7 @@
The :class:`~pygrass.raster.RasterRowIO` class uses the GRASS `RowIO library`_, and implements a row
cache. The RasterRowIO class only supports reading rasters; because raster rows
can only be written in sequential order, writing by row id is not
-supported by design. Hence, the rowio lib can only be used to cache rows
+supported by design. Hence, the RowIO lib can only be used to cache rows
for reading, and any write access should use the :ref:`RasterRow-label` class. ::
>>> raster = reload(raster)
@@ -174,7 +176,7 @@
Due to the unique behavior of this class, the RasterSegment class defines two
methods to read a map:
- * ``get_row`` calls the C function ``Segment_get_row`` and returns a buffer
+ * ``get_row`` calls the C function ``Segment_get_row()`` and returns a buffer
object with the row. ::
>>> # call explicitly the method
@@ -182,7 +184,7 @@
>>> # call implicitly the method
>>> elev_row0 = elev[0]
- * ``get`` calls the C function ``Segment_get`` and returns the value of the
+ * ``get`` calls the C function ``Segment_get()`` and returns the value of the
map cell. ::
>>> # call explicitly the method
@@ -190,8 +192,8 @@
>>> # call implicitly the method
>>> elev_val_0_0 = elev[0, 0]
-Similarly, writing to a map uses two methods: ``put_row`` to write a row and
-``put`` to write a single value to the map. ::
+Similarly, writing to a map uses two methods: ``put_row()`` to write a row and
+``put()`` to write a single value to the map. ::
>>> # compare the cell value get using the ``get`` method, and take the first
>>> # value of the row with the ``get_row`` method
Modified: grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_vector.rst
===================================================================
--- grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_vector.rst 2016-12-27 11:30:36 UTC (rev 70139)
+++ grass/branches/releasebranch_7_2/lib/python/docs/src/pygrass_vector.rst 2016-12-27 11:34:10 UTC (rev 70140)
@@ -2,21 +2,25 @@
==============================
Details about the GRASS GIS vector architecture can be found in the
-`GRASS GIS 7 Programmer's Manual: GRASS Vector Library <http://grass.osgeo.org/programming7/vectorlib.html>`_
+`GRASS GIS 7 Programmer's Manual: GRASS Vector Library
+<http://grass.osgeo.org/programming7/vectorlib.html>`_.
-PyGrass has two classes for vector maps: :ref:`Vector-label` and :ref:`VectorTopo-label`.
-As the names suggest, the Vector class is for vector maps, while VectorTopo
-opens vector maps with `GRASS GIS topology <http://grass.osgeo.org/programming7/vlibTopology.html>`_.
-VectorTopo is an extension of the Vector class, so supports all the Vector class methods, with additions.
+PyGRASS has two classes for vector maps: :ref:`Vector-label` and
+:ref:`VectorTopo-label`. As the names suggest, the Vector class is
+for vector maps, while VectorTopo opens vector maps with `GRASS GIS
+topology <http://grass.osgeo.org/programming7/vlibTopology.html>`_.
+VectorTopo is an extension of the Vector class, so supports all the
+Vector class methods, with additions. The classes are part of the
+:mod:`~pygrass.vector` module.
.. _Vector-label:
Vector
------
-The :class:`~pygrass.vector.Vector` class is part of the :mod:`~pygrass.vector`
-module. It is based on the :class:`~pygrass.vector.abstract.Info` class, which
-provides methods for accessing basic information about the vector map: ::
+The :class:`~pygrass.vector.Vector` class is based on the
+:class:`~pygrass.vector.abstract.Info` class, which provides methods
+for accessing basic information about the vector map: ::
>>> from grass.pygrass.vector import Vector
>>> cens = Vector('census')
@@ -55,8 +59,8 @@
'user1'
-Working with Vector Objects
----------------------------
+Working with Vector Maps
+------------------------
As the VectorTopo class is so similar to the Vector class, the following examples
exclusively demonstrate the VectorTopo class.
@@ -67,13 +71,16 @@
>>> municip = VectorTopo('boundary_municp_sqlite')
>>> municip.open(mode='r')
-The ``open()`` method supports a number of option arguments (see the :class:`~pygrass.vector.abstract.Info`
-documentation for a complete list). In particular, the mode argument can take a
-a value of:
+The ``open()`` method supports a number of option arguments (see the
+:class:`~pygrass.vector.abstract.Info` documentation for a complete
+list). In particular, the mode argument can take a a value of:
-'r': read-only mode, vector features are read-only (attribute table is modifiable since are handle by a database);
-'w': write-only mode, write a new vector map in case of an old vector map all the previous features will be removed/overwritten;
-'rw': read-write mode, add new/update vector features without removing the existing ones. Add/remove vector layers.
+* 'r': read-only mode, vector features are read-only (attribute table
+ is modifiable since are handle by a database);
+* 'w': write-only mode, write a new vector map in case of an old
+ vector map all the previous features will be removed/overwritten;
+* 'rw': read-write mode, add new/update vector features without
+ removing the existing ones. Add/remove vector layers.
The geometry of a vector map can be read sequentially using the ``next()`` method.
@@ -118,7 +125,7 @@
>>> new.write(point0, cat=1, attrs=('pub',))
>>> new.write(point1, cat=2, attrs=('resturant',))
-Commit the db changes:
+Commit the DB changes (attributes):
>>> new.table.conn.commit()
>>> new.table.execute().fetchall()
@@ -208,19 +215,25 @@
Link(1, census, sqlite)
>>> table = link.table()
-Here, ``DBlinks()`` is a class (:class:`~pygrass.vector.table.DBlinks`) that
-contains all the links of a vector map. Each link is also a class
+Here, :class:`~pygrass.vector.table.DBlinks` is a class that contains
+all the links of a vector map. Each link is also a class
(:class:`~pygrass.vector.table.Link`) that contains a specific link's
-parameters. The ``table()`` method of the link class return the linked table as
-a table object (:class:`~pygrass.vector.table.Table`).
+parameters. The ``table()`` method of the link class return the linked
+table as a table object (:class:`~pygrass.vector.table.Table`).
Geometry Classes
----------------
-The vector package also includes a number of geometry classes, including Area,
-Boundary, Centroid, Isle, Line, and Point classes. Please consult the
-:mod:`~pygrass.vector.geometry` module for a complete list of methods for these
-classes, as there are many. Some basic examples are given below.
+The vector package also includes a number of geometry classes,
+including :class:`~pygrass.vector.geometry.Area`,
+:class:`~pygrass.vector.geometry.Boundary`,
+:class:`~pygrass.vector.geometry.Centroid`,
+:class:`~pygrass.vector.geometry.Isle`,
+:class:`~pygrass.vector.geometry.Line`, and
+:class:`~pygrass.vector.geometry.Point` classes. Please consult the
+:mod:`~pygrass.vector.geometry` module for a complete list of methods
+for these classes, as there are many. Some basic examples are given
+below.
Instantiate a Point object that could be 2 or 3D, default parameters are 0: ::
@@ -278,7 +291,7 @@
>>> big = [area for area in municip.viter('areas')
... if area.alive() and area.area >= 10000]
-The PyGrass vector methods make complex operations rather easy. Notice the
+The PyGRASS vector methods make complex operations rather easy. Notice the
``viter()`` method: this returns an iterator object of the vector features, so
the user can choose on which vector features to iterate without loading all the
features into memory.
@@ -293,7 +306,6 @@
Area(2682) 320224369.66
Area(2552) 298356117.948
-
Or sort for the number of isles that are contained inside: ::
>>> big.sort(key = lambda x: x.isles.__len__(), reverse = True)
More information about the grass-commit
mailing list