[GRASS-SVN] r60913 - in grass/branches/releasebranch_7_0: . lib/python/pygrass lib/python/pygrass/docs lib/python/pygrass/gis lib/python/pygrass/messages lib/python/pygrass/modules lib/python/pygrass/modules/grid lib/python/pygrass/modules/interface lib/python/pygrass/raster lib/python/pygrass/vector lib/python/pygrass/vector/testsuite
svn_grass at osgeo.org
svn_grass at osgeo.org
Sat Jun 21 02:34:04 PDT 2014
Author: zarch
Date: 2014-06-21 02:34:04 -0700 (Sat, 21 Jun 2014)
New Revision: 60913
Added:
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/_static/
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/_templates/
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/gis.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/messages.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules_grid.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster_elements.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_attributes.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_features.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_utils.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_geometry.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_vector3d.py
Removed:
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/attributes.rst
Modified:
grass/branches/releasebranch_7_0/
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/Makefile
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/conf.py
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/index.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/intro.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector.rst
grass/branches/releasebranch_7_0/lib/python/pygrass/gis/__init__.py
grass/branches/releasebranch_7_0/lib/python/pygrass/gis/region.py
grass/branches/releasebranch_7_0/lib/python/pygrass/messages/__init__.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/grid.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/patch.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/split.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/flag.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/module.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/parameter.py
grass/branches/releasebranch_7_0/lib/python/pygrass/modules/shortcuts.py
grass/branches/releasebranch_7_0/lib/python/pygrass/pygrasslib.dox
grass/branches/releasebranch_7_0/lib/python/pygrass/raster/__init__.py
grass/branches/releasebranch_7_0/lib/python/pygrass/raster/category.py
grass/branches/releasebranch_7_0/lib/python/pygrass/raster/history.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/__init__.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/abstract.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/basic.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/find.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/geometry.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/sql.py
grass/branches/releasebranch_7_0/lib/python/pygrass/vector/table.py
Log:
pygrass update from trunk: backport documentation improvements (thanks: Luca, MarkusN and Martin) and recent fix on modules/interface/parameter and vector 3D
Property changes on: grass/branches/releasebranch_7_0
___________________________________________________________________
Modified: svn:mergeinfo
- /grass/trunk:59907,60880
+ /grass/trunk:59907,60031,60443,60448,60880
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/Makefile
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/Makefile 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/Makefile 2014-06-21 09:34:04 UTC (rev 60913)
@@ -14,6 +14,7 @@
endif
PAPER =
BUILDDIR = _build
+BUILDDIR_HTML = $(HTMLDIR)/pygrass
MYGISBASE = $(GISBASE)
@@ -33,75 +34,31 @@
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
- @echo " text to make text files"
@echo " man to make manual pages"
- @echo " texinfo to make Texinfo files"
- @echo " info to make Texinfo files and run them through makeinfo"
- @echo " gettext to make PO message catalogs"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
+ -rm -f _templates/layout.html
html:
- $(call run_grass,$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html)
+ $(call run_grass,$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
@echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html/"
+ @echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
dirhtml:
- $(call run_grass,$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml)
+ $(call run_grass,$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
@echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml/"
+ @echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
singlehtml:
- $(call run_grass,$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml)
+ $(call run_grass,$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
@echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml/"
+ @echo "Build finished. The HTML page is in $(BUILDDIR_HTML)"
-pickle:
- $(call run_grass,$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle)
- @echo
- @echo "Build finished; now you can process the pickle files in $(BUILDDIR)/pickle/."
-
-json:
- $(call run_grass,$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json)
- @echo
- @echo "Build finished; now you can process the JSON files in $(BUILDDIR)/json/"
-
-htmlhelp:
- $(call run_grass,$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp)
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in $(BUILDDIR)/htmlhelp/"
-
-qthelp:
- $(call run_grass,$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp)
- @echo
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PyGrass.qhcp"
- @echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyGrass.qhc"
-
-devhelp:
- $(call run_grass,$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp)
- @echo
- @echo "Build finished."
- @echo "To view the help file:"
- @echo "# mkdir -p $$HOME/.local/share/devhelp/PyGrass"
- @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PyGrass"
- @echo "# devhelp"
-
epub:
$(call run_grass,$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub)
@echo
@@ -120,45 +77,11 @@
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/"
-text:
- $(call run_grass,$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text)
- @echo
- @echo "Build finished. The text files are in $(BUILDDIR)/text/"
-
man:
- $(call run_grass,$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man)
+ $(call run_grass,$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(MANDIR))
@echo
- @echo "Build finished. The manual pages are in $(BUILDDIR)/man/"
+ @echo "Build finished. The manual pages are in $(MANDIR)/"
-texinfo:
- $(call run_grass,$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo)
- @echo
- @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
- @echo "Run \`make' in that directory to run these through makeinfo" \
- "(use \`make info' here to do that automatically)."
-
-info:
- $(call run_grass,$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo)
- @echo "Running Texinfo files through makeinfo..."
- make -C $(BUILDDIR)/texinfo info
- @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo/"
-
-gettext:
- $(call run_grass,$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale)
- @echo
- @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale/"
-
-changes:
- $(call run_grass,$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes)
- @echo
- @echo "The overview file is in $(BUILDDIR)/changes/"
-
-linkcheck:
- $(call run_grass,$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck)
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in $(BUILDDIR)/linkcheck/output.txt."
-
doctest:
$(call run_grass,$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest)
@echo "Testing of doctests in the sources finished, look at the " \
Deleted: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/attributes.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/attributes.rst 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/attributes.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -1,138 +0,0 @@
-Attributes
-===========
-
-It is possible to access the vector attributes with: ::
-
- >>> from pygrass.vector import Vector
- >>> municip = Vector('boundary_municp_sqlite')
- >>> municip.open()
- >>> municip.dblinks
- DBlinks([[Link(1, boundary_municp, sqlite)]])
-
-The vector map have a ``table`` attributes that contain a Table object, that
-have some useful attributes like: layer, name, driver, etc.
-
- >>> link = municip.dblinks[1]
- >>> link.number
- 1
- >>> link.name
- 'boundary_municp'
- >>> link.table_name
- 'boundary_municp_sqlite'
- >>> link.driver
- 'sqlite'
- >>> link.database # doctest: +ELLIPSIS
- '.../sqlite.db'
- >>> link.key
- 'cat'
-
-It is possible to change values, like: ::
-
- >>> link.name = 'boundary'
- >>> link.driver = 'pg'
- >>> link.database = 'host=localhost,dbname=grassdb'
- >>> link.key = 'gid'
-
-Now change again to old values: ::
-
- >>> link.name = 'boundary_municp_sqlite'
- >>> link.driver = 'sqlite'
- >>> link.database = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite.db'
- >>> link.key = 'cat'
-
-Link object have methods that return a
-:ref:`Connection object <python:library:sqlite3:connection-objects>`, and to
-return a Table object: ::
-
- >>> conn = link.connection()
- >>> cur = conn.cursor()
- >>> import sql
- >>> cur.execute(sql.SELECT.format(cols=', '.join(['cat', 'AREA']),
- ... tname=link.name)) # doctest: +ELLIPSIS
- <sqlite3.Cursor object at ...>
- >>> cur.fetchone()
- (1, 0.0)
- >>> cur.close()
- >>> conn.close()
-
-From the Link object we can instantiate a Table object that allow user to
-make simple query with the Filters object: ::
-
- >>> table = link.table()
- >>> table.filters.select('cat', 'COUNTY',
- ... 'AREA','PERIMETER').order_by('AREA').limit(3)
- Filters('SELECT cat, COUNTY, AREA, PERIMETER FROM boundary_municp_sqlite ORDER BY AREA LIMIT 3;')
- >>> cur = table.execute()
- >>> for row in cur.fetchall():
- ... print repr(row)
- ...
- (1, u'SURRY', 0.0, 1415.331)
- (2, u'SURRY', 0.0, 48286.011)
- (3, u'CASWELL', 0.0, 5750.087)
-
-
-Then we can get table information about table columns, from the columns
-attribute that is an instantiation of a Columns class.
-
-
- >>> table.columns # doctest: +ELLIPSIS
- Columns([(u'cat', u'integer'), ..., (u'ACRES', u'double precision')])
- >>> table.columns.names() # doctest: +ELLIPSIS
- [u'cat', u'OBJECTID', u'AREA', u'PERIMETER', ..., u'ACRES']
- >>> table.columns.types() # doctest: +ELLIPSIS
- [u'integer', u'integer', u'double precision', ..., u'double precision']
-
-
-.. note ::
- If the map use postgresql it is possible to: add/rename/cast/remove columns
- the sqlite does not support these operations.
-
-
-For people that are used to the standardized Python SQL 2.0 interface:
-
- * http://docs.python.org/library/sqlite3.html
- * http://www.python.org/dev/peps/pep-0249/
-
-Therefore advanced user can just use, the connect attribute to build
-a new cursor object and interact with the database. ::
-
- >>> cur = table.conn.cursor()
- >>> cur.execute("SELECT * FROM %s" % table.name) # doctest: +ELLIPSIS
- <sqlite3.Cursor object at ...>
- >>> cur.fetchone()[:5] # doctest: +ELLIPSIS
- (1, 1, 0.0, 1415.331, 2.0)
- >>> # Close communication with the database
- >>> cur.close()
- >>> conn.close()
-
-
-
-Link
--------
-
-.. autoclass:: pygrass.vector.table.Link
- :members:
-
-DBlinks
--------
-
-.. autoclass:: pygrass.vector.table.DBlinks
- :members:
-
-Filters
--------
-
-.. autoclass:: pygrass.vector.table.Filters
- :members:
-
-Columns
--------
-
-.. autoclass:: pygrass.vector.table.Columns
- :members:
-
-Table
------
-
-.. autoclass:: pygrass.vector.table.Table
- :members:
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/conf.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/conf.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/conf.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -12,6 +12,9 @@
# serve to show the default.
import sys, os
+from datetime import date
+import string
+from shutil import copy
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -20,6 +23,24 @@
sys.exit("GISBASE not defined")
sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass')))
+from grass.script import core
+
+footer_tmpl = string.Template(\
+r"""
+{% block footer %}<hr class="header">
+<p><a href="../index.html">Help Index</a> | <a href="../topics.html">Topics Index</a> | <a href="../keywords.html">Keywords Index</a> | <a href="../full_index.html">Full Index</a></p>
+<p>© 2003-${year} <a href="http://grass.osgeo.org">GRASS Development Team</a>, GRASS GIS ${grass_version} Reference Manual</p>
+{% endblock %}
+""")
+
+grass_version = core.version()['version']
+today = date.today()
+
+copy("_templates/layout.html.template", "_templates/layout.html")
+with open("_templates/layout.html", "a+b") as f:
+ f.write(footer_tmpl.substitute(grass_version=grass_version, year=today.year))
+ f.close()
+
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@@ -50,9 +71,9 @@
# built documents.
#
# The short X.Y version.
-version = '0.2'
+#version = '0.2'
# The full version, including alpha/beta/rc tags.
-release = 'beta'
+#release = 'beta'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -100,7 +121,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'default'
+html_theme = 'traditional'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -140,7 +161,7 @@
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {"**":["localtoc.html",'relations.html','searchbox.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/gis.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/gis.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/gis.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,30 @@
+.. _GRASSdatabase-label:
+
+GRASS database management
+===============================
+
+These classes are used to manage the infrastructure
+of GRASS database: Gisdbase, Location and Mapset
+
+.. autoclass:: pygrass.gis.Gisdbase
+ :members:
+
+.. autoclass:: pygrass.gis.Location
+ :members:
+
+.. autoclass:: pygrass.gis.Mapset
+ :members:
+
+.. autoclass:: pygrass.gis.VisibleMapset
+ :members:
+
+.. _Region-label:
+
+Region management
+======================
+
+The Region class it is useful to obtain information
+about the computational region and to change it.
+
+.. autoclass:: pygrass.gis.region.Region
+ :members:
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/index.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/index.rst 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/index.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -3,20 +3,15 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to PyGrass documentation!
+PyGRASS documentation
===================================
-In 2006, GRASS GIS developers started to adopt Python for the new GUI. Due
-to this Python became more and more important and developers converted all
-shell scripts from GRASS GIS 6 to Python for GRASS GIS 7.
+Python is a programming language which is more powerful than shell 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 functionality, as well as to vector and raster data. For details, 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 natural for the user.
-``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 natural for the user.
+Background: In 2006, GRASS GIS developers started to adopt Python for the new GUI. Due to this Python became more and more important and developers converted all shell scripts from GRASS GIS 6 to Python for GRASS GIS 7.
-This project has been funded with support from the Google Summer of Code 2012.
+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).
-
Contents:
.. toctree::
@@ -25,15 +20,30 @@
intro
gis
raster
+ raster_elements
vector
- attributes
+ vector_attributes
+ vector_features
+ vector_utils
modules
+ modules_grid
+ messages
-Indices and tables
-==================
+References
+============
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+* 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>`_
+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
+ ==================
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`
+
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/intro.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/intro.rst 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/intro.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -4,11 +4,11 @@
To work with ``pygrass`` you need an up-to-date version of GRASS GIS 7.
You can obtain a recent version following the information provided on the
`main Web site <http://grass.osgeo.org/download/software/>`_
-of GRASS, and you can read more about compilation on the
+of GRASS, and you can read more about compilation in the
`GRASS GIS Wiki <http://grasswiki.osgeo.org/wiki/Compile_and_Install>`_
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)
+(the second one is the recommended way).
-Read more about how to work with :doc:`gis`, :doc:`raster`, :doc:`vector`, :doc:`attributes`, :doc:`modules`.
+Read more about how to work with ``pygrass`` in this documentation.
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/messages.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/messages.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/messages.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,15 @@
+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>`_.
+
+.. autoclass:: pygrass.messages.Messenger
+ :members:
+
+.. autoclass:: pygrass.messages.FatalError
+ :members:
+
+.. autofunction:: pygrass.messages.message_server
+
+.. autofunction:: pygrass.messages.get_msgr
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules.rst 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -1,8 +1,9 @@
-Modules
-=======
+Interface to GRASS GIS modules
+==============================
-Grass modules are represented as objects. These objects are generated based
-on the XML module description that is used for GUI generation already. ::
+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). ::
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
@@ -10,7 +11,9 @@
... format='percent', overwrite=True)
-It is possible to create a run-able module object and run later:
+It is possible to create a run-able module object and run it later (this
+is also needed for registering GRASS GIS commands with more than one dot
+in their name, e.g. r.slope.aspect):
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
@@ -61,7 +64,8 @@
-It is possible to access the module info with:
+It is possible to access the module descriptions (name, one line description,
+keywords, label) with:
>>> slope_aspect.name
'r.slope.aspect'
@@ -130,13 +134,13 @@
-For each inputs and outputs parameters it is possible to get info, to see all
-the module inputs, just type: ::
+For each input and output parameter it is possible to obtain specific
+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))])
-To get info for each parameter: ::
+To get information for each parameter: ::
>>> slope_aspect.inputs["elevation"].description
'Name of input elevation raster map'
@@ -156,13 +160,13 @@
Name of input elevation raster map
-User or developer can check which parameter are set, with: ::
+User or developer can check which parameters have been set, with: ::
if slope_aspect.outputs['aspect'].value == None:
print "Aspect is not computed"
-After we set the parameter and run the module, the execution of the module
+After we set the parameters and run the module, the execution of the module
instantiate a popen attribute to the class. The `Popen`_ class allow user
to kill/wait/ the process. ::
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules_grid.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules_grid.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/modules_grid.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,25 @@
+GridModule for raster multiprocessing
+=====================================
+
+The GridModule class permits to work with raster data and all the
+processor cores of your computer. It divides the input data into the
+number of choosen rows and columns and after it patches the results
+together to obtain only one output map.
+
+.. automodule:: pygrass.modules.grid.grid
+ :members:
+
+Functions
+------------
+
+Split
+^^^^^^^^
+
+.. automodule:: pygrass.modules.grid.split
+ :members:
+
+Patch
+^^^^^^^^
+
+.. automodule:: pygrass.modules.grid.patch
+ :members:
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster.rst 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -1,8 +1,10 @@
.. _raster-label:
-Raster
-======
+Introduction to Raster classes
+==============================
+Details about the architecture can be found in the `GRASS GIS 7 Programmer's Manual: GRASS Raster Library <http://grass.osgeo.org/programming7/rasterlib.html>`_
+
PyGRASS uses 4 different Raster classes, that respect the 4 different approaches
of GRASS-C API.
The read access is row wise for :ref:`RasterRow-label` and
@@ -58,102 +60,6 @@
>>> print(new)
new
-
-
-
-.. _RasterCategory-label:
-
-Categories
-----------
-
-All the raster classes support raster categories and share commons methods
-to modify the raster category.
-It is possible to check if the map has or not the categories with the
-``has_cats`` method. ::
-
- >>> elev.has_cats()
- False
-
-Opening a map that has category, for example the "landcove_1m" raster map
-from the North Carolina mapset. The ``has_cats`` method return True. ::
-
- >>> land = raster.RasterRow('landcover_1m')
- >>> land.has_cats()
- True
-
-Get and set the categories title, with: ::
-
- >>> land.cats_title
- 'Rural area: Landcover'
- >>> land.cats_title = 'Rural area: Landcover2'
- >>> land.cats_title
- 'Rural area: Landcover2'
- >>> land.cats_title = 'Rural area: Landcover'
-
-Get the number of categories of the map with: ::
-
- >>> land.num_cats()
- 11
-
-See all the categories with: ::
-
- >>> land.cats
- [('pond', 1, None),
- ('forest', 2, None),
- ('developed', 3, None),
- ('bare', 4, None),
- ('paved road', 5, None),
- ('dirt road', 6, None),
- ('vineyard', 7, None),
- ('agriculture', 8, None),
- ('wetland', 9, None),
- ('bare ground path', 10, None),
- ('grass', 11, None)]
-
-Access a single category, using Rast_get_ith_cat(), with: ::
-
- >>> land.cats[0]
- ('pond', 1, None)
- >>> land.cats['pond']
- ('pond', 1, None)
- >>> land.get_cat(0)
- ('pond', 1, None)
- >>> land.get_cat('pond')
- ('pond', 1, None)
-
-Add new or change existing categories: ::
-
- >>> land.set_cat('label', 1)
- >>> land.get_cat('label')
- ('label', 1, None)
- >>> land.set_cat('pond', 1, 1)
-
-
-Sort categories, with: ::
-
- >>> land.sort_cats()
-
-
-Copy categories from another raster map with: ::
-
- >>> land.copy_cats(elev)
-
-Read and Write: ::
-
- >>> land.read_cats()
- >>> #land.write_cats()
-
-Get a Category object or set from a Category object: ::
-
- >>> cats = land.get_cats()
- >>> land.set_cats(cats)
-
-Export and import from a file: ::
-
- >>> land.write_cats_rules('land_rules.csv', ';')
- >>> land.read_cats_rules('land_rules.csv', ';')
-
-
.. _RasterRow-label:
RastRow
@@ -210,6 +116,8 @@
>>> new.exist()
False
+.. autoclass:: pygrass.raster.RasterRow
+ :members:
.. _RasterRowIO-label:
@@ -233,8 +141,9 @@
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
+.. autoclass:: pygrass.raster.RasterRowIO
+ :members:
-
.. _RasterSegment-label:
RastSegment
@@ -302,8 +211,9 @@
>>> elev.close()
>>> elev.remove()
+.. autoclass:: pygrass.raster.RasterSegment
+ :members:
-
.. _RasterNumpy-label:
RasterNumpy
@@ -342,56 +252,10 @@
True
>>> el.remove()
-
-
-.. _Buffer-label:
-
-Buffer
-------
-
-The buffer class is used to interact with a memory buffer of a map like a
-raster row. The buffer class is based on the `numpy.ndarray`_ class. Therefore
-all the nice feature of the ndarray are allowed.
-
-.. autoclass:: pygrass.raster.buffer.Buffer
+.. autoclass:: pygrass.raster.RasterNumpy
:members:
-.. _numpy.ndarray: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
-
-.. _RowIO-label:
-
-RowIO
-------
-
-.. autoclass:: pygrass.raster.rowio.RowIO
- :members:
-
-.. _Segment-label:
-
-Segment
--------
-
-.. autoclass:: pygrass.raster.segment.Segment
- :members:
-
-.. _History-label:
-
-History
---------
-
-.. autoclass:: pygrass.raster.history.History
- :members:
-
-
-.. _Category-label:
-
-Category
---------
-
-.. autoclass:: pygrass.raster.category.Category
- :members:
-
.. _Raster library: http://grass.osgeo.org/programming7/rasterlib.html
.. _RowIO library: http://grass.osgeo.org/programming7/rowiolib.html
.. _Segmentation library: http://grass.osgeo.org/programming7/segmentlib.html
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster_elements.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster_elements.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/raster_elements.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,136 @@
+Raster elements
+=================
+
+.. _RasterCategory-label:
+
+Categories
+----------
+
+All the raster classes support raster categories and share commons methods
+to modify the raster category.
+It is possible to check if the map has or not the categories with the
+``has_cats`` method. ::
+
+ >>> elev.has_cats()
+ False
+
+Opening a map that has category, for example the "landcove_1m" raster map
+from the North Carolina mapset. The ``has_cats`` method return True. ::
+
+ >>> land = raster.RasterRow('landcover_1m')
+ >>> land.has_cats()
+ True
+
+Get and set the categories title, with: ::
+
+ >>> land.cats_title
+ 'Rural area: Landcover'
+ >>> land.cats_title = 'Rural area: Landcover2'
+ >>> land.cats_title
+ 'Rural area: Landcover2'
+ >>> land.cats_title = 'Rural area: Landcover'
+
+Get the number of categories of the map with: ::
+
+ >>> land.num_cats()
+ 11
+
+See all the categories with: ::
+
+ >>> land.cats
+ [('pond', 1, None),
+ ('forest', 2, None),
+ ('developed', 3, None),
+ ('bare', 4, None),
+ ('paved road', 5, None),
+ ('dirt road', 6, None),
+ ('vineyard', 7, None),
+ ('agriculture', 8, None),
+ ('wetland', 9, None),
+ ('bare ground path', 10, None),
+ ('grass', 11, None)]
+
+Access a single category, using Rast_get_ith_cat(), with: ::
+
+ >>> land.cats[0]
+ ('pond', 1, None)
+ >>> land.cats['pond']
+ ('pond', 1, None)
+ >>> land.get_cat(0)
+ ('pond', 1, None)
+ >>> land.get_cat('pond')
+ ('pond', 1, None)
+
+Add new or change existing categories: ::
+
+ >>> land.set_cat('label', 1)
+ >>> land.get_cat('label')
+ ('label', 1, None)
+ >>> land.set_cat('pond', 1, 1)
+
+
+Sort categories, with: ::
+
+ >>> land.sort_cats()
+
+
+Copy categories from another raster map with: ::
+
+ >>> land.copy_cats(elev)
+
+Read and Write: ::
+
+ >>> land.read_cats()
+ >>> #land.write_cats()
+
+Get a Category object or set from a Category object: ::
+
+ >>> cats = land.get_cats()
+ >>> land.set_cats(cats)
+
+Export and import from a file: ::
+
+ >>> land.write_cats_rules('land_rules.csv', ';')
+ >>> land.read_cats_rules('land_rules.csv', ';')
+
+.. autoclass:: pygrass.raster.category.Category
+ :members:
+
+.. _Buffer-label:
+
+Buffer
+------
+
+The buffer class is used to interact with a memory buffer of a map like a
+raster row. The buffer class is based on the `numpy.ndarray`_ class. Therefore
+all the nice feature of the ndarray are allowed.
+
+.. autoclass:: pygrass.raster.buffer.Buffer
+ :members:
+
+.. _numpy.ndarray: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
+
+
+.. _RowIO-label:
+
+RowIO
+------
+
+.. autoclass:: pygrass.raster.rowio.RowIO
+ :members:
+
+.. _Segment-label:
+
+Segment
+-------
+
+.. autoclass:: pygrass.raster.segment.Segment
+ :members:
+
+.. _History-label:
+
+History
+--------
+
+.. autoclass:: pygrass.raster.history.History
+ :members:
\ No newline at end of file
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector.rst 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -1,7 +1,11 @@
+.. _vector-label:
-Vector
-========
+Introduction to Vector classes
+==============================
+Details about the architecture can be found in the `GRASS GIS 7 Programmer's Manual: GRASS Vector Library <http://grass.osgeo.org/programming7/vectorlib.html>`_
+
+
Instantiation and basic interaction. ::
>>> from pygrass.vector import VectTopo
@@ -114,84 +118,15 @@
Bbox(199947.296494, 199280.969494, 754920.623987, 754351.812986)
-VectorTopo
-----------
-.. autoclass:: pygrass.vector.VectorTopo
- :members:
-
Vector
----------
.. autoclass:: pygrass.vector.Vector
:members:
+VectorTopo
+----------
-Vector Features
-===============
-
-Point
-------
-
-.. autoclass:: pygrass.vector.geometry.Point
+.. autoclass:: pygrass.vector.VectorTopo
:members:
-
-
-Line
------
-
-.. autoclass:: pygrass.vector.geometry.Line
- :members:
-
-Boundary
---------
-
-.. autoclass:: pygrass.vector.geometry.Boundary
- :members:
-
-Isle
------
-
-.. autoclass:: pygrass.vector.geometry.Isle
- :members:
-
-
-Isles
------
-
-.. autoclass:: pygrass.vector.geometry.Isles
- :members:
-
-Area
---------
-
-.. autoclass:: pygrass.vector.geometry.Boundary
- :members:
-
-Utils
-=====
-
-Bbox
-----
-
-.. autoclass:: pygrass.vector.basic.Bbox
- :members:
-
-
-BoxList
---------
-
-.. autoclass:: pygrass.vector.basic.BoxList
- :members:
-
-Ilist
------
-
-.. autoclass:: pygrass.vector.basic.Ilist
- :members:
-
-Cats
------
-
-.. autoclass:: pygrass.vector.basic.Cats
- :members:
\ No newline at end of file
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_attributes.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_attributes.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_attributes.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,144 @@
+Vector Attributes
+===================
+
+It is possible to access the vector attributes with: ::
+
+ >>> from pygrass.vector import Vector
+ >>> municip = Vector('boundary_municp_sqlite')
+ >>> municip.open()
+ >>> municip.dblinks
+ DBlinks([[Link(1, boundary_municp, sqlite)]])
+
+The vector map have a ``table`` attributes that contain a Table object, that
+have some useful attributes like: layer, name, driver, etc.
+
+ >>> link = municip.dblinks[1]
+ >>> link.number
+ 1
+ >>> link.name
+ 'boundary_municp'
+ >>> link.table_name
+ 'boundary_municp_sqlite'
+ >>> link.driver
+ 'sqlite'
+ >>> link.database # doctest: +ELLIPSIS
+ '.../sqlite.db'
+ >>> link.key
+ 'cat'
+
+It is possible to change values, like: ::
+
+ >>> link.name = 'boundary'
+ >>> link.driver = 'pg'
+ >>> link.database = 'host=localhost,dbname=grassdb'
+ >>> link.key = 'gid'
+
+Now change again to old values: ::
+
+ >>> link.name = 'boundary_municp_sqlite'
+ >>> link.driver = 'sqlite'
+ >>> link.database = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite.db'
+ >>> link.key = 'cat'
+
+Link object have methods that return a
+:ref:`Connection object <python:library:sqlite3:connection-objects>`, and to
+return a Table object: ::
+
+ >>> conn = link.connection()
+ >>> cur = conn.cursor()
+ >>> import sql
+ >>> cur.execute(sql.SELECT.format(cols=', '.join(['cat', 'AREA']),
+ ... tname=link.name)) # doctest: +ELLIPSIS
+ <sqlite3.Cursor object at ...>
+ >>> cur.fetchone()
+ (1, 0.0)
+ >>> cur.close()
+ >>> conn.close()
+
+From the Link object we can instantiate a Table object that allow user to
+make simple query with the Filters object: ::
+
+ >>> table = link.table()
+ >>> table.filters.select('cat', 'COUNTY',
+ ... 'AREA','PERIMETER').order_by('AREA').limit(3)
+ Filters('SELECT cat, COUNTY, AREA, PERIMETER FROM boundary_municp_sqlite ORDER BY AREA LIMIT 3;')
+ >>> cur = table.execute()
+ >>> for row in cur.fetchall():
+ ... print repr(row)
+ ...
+ (1, u'SURRY', 0.0, 1415.331)
+ (2, u'SURRY', 0.0, 48286.011)
+ (3, u'CASWELL', 0.0, 5750.087)
+
+
+Then we can get table information about table columns, from the columns
+attribute that is an instantiation of a Columns class.
+
+
+ >>> table.columns # doctest: +ELLIPSIS
+ Columns([(u'cat', u'integer'), ..., (u'ACRES', u'double precision')])
+ >>> table.columns.names() # doctest: +ELLIPSIS
+ [u'cat', u'OBJECTID', u'AREA', u'PERIMETER', ..., u'ACRES']
+ >>> table.columns.types() # doctest: +ELLIPSIS
+ [u'integer', u'integer', u'double precision', ..., u'double precision']
+
+
+.. note ::
+ If the map use postgresql it is possible to: add/rename/cast/remove columns
+ the sqlite does not support these operations.
+
+
+For people that are used to the standardized Python SQL 2.0 interface:
+
+ * http://docs.python.org/library/sqlite3.html
+ * http://www.python.org/dev/peps/pep-0249/
+
+Therefore advanced user can just use, the connect attribute to build
+a new cursor object and interact with the database. ::
+
+ >>> cur = table.conn.cursor()
+ >>> cur.execute("SELECT * FROM %s" % table.name) # doctest: +ELLIPSIS
+ <sqlite3.Cursor object at ...>
+ >>> cur.fetchone()[:5] # doctest: +ELLIPSIS
+ (1, 1, 0.0, 1415.331, 2.0)
+ >>> # Close communication with the database
+ >>> cur.close()
+ >>> conn.close()
+
+
+DBlinks
+---------
+
+.. autoclass:: pygrass.vector.table.DBlinks
+ :members:
+
+Link
+---------
+
+.. autoclass:: pygrass.vector.table.Link
+ :members:
+
+Table
+---------
+
+.. autoclass:: pygrass.vector.table.Table
+ :members:
+
+Columns
+---------
+
+.. autoclass:: pygrass.vector.table.Columns
+ :members:
+
+Filters
+---------
+
+.. autoclass:: pygrass.vector.table.Filters
+ :members:
+
+SQL
+---------
+
+.. automodule:: pygrass.vector.sql
+ :members:
+
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_features.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_features.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_features.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,41 @@
+Vector Features
+===============
+
+Point
+------
+
+.. autoclass:: pygrass.vector.geometry.Point
+ :members:
+
+
+Line
+-----
+
+.. autoclass:: pygrass.vector.geometry.Line
+ :members:
+
+Boundary
+--------
+
+.. autoclass:: pygrass.vector.geometry.Boundary
+ :members:
+
+Isle
+-----
+
+.. autoclass:: pygrass.vector.geometry.Isle
+ :members:
+
+
+Isles
+-----
+
+.. autoclass:: pygrass.vector.geometry.Isles
+ :members:
+
+Area
+--------
+
+.. autoclass:: pygrass.vector.geometry.Area
+ :members:
+
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_utils.rst
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_utils.rst (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/docs/vector_utils.rst 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,27 @@
+Vector Utils
+===============
+
+Bbox
+----
+
+.. autoclass:: pygrass.vector.basic.Bbox
+ :members:
+
+
+BoxList
+--------
+
+.. autoclass:: pygrass.vector.basic.BoxList
+ :members:
+
+Ilist
+-----
+
+.. autoclass:: pygrass.vector.basic.Ilist
+ :members:
+
+Cats
+-----
+
+.. autoclass:: pygrass.vector.basic.Cats
+ :members:
\ No newline at end of file
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/gis/__init__.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/gis/__init__.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/gis/__init__.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -9,26 +9,12 @@
import ctypes as ct
import fnmatch
-from grass import script
-#from grass.script import setup
-#
-#
-#GISBASE = "/home/pietro/docdat/src/gis/grass/grass70/dist.x86_64-unknown-linux-gnu"
-#LOCATION = "nc_basic_spm_grass7'"
-#GISDBASE = "/home/pietro/docdat/gis"
-#MAPSET = "sqlite"
-#GUI = "wxpython"
-#
-#setup.init(GISBASE, GISDBASE, LOCATION, MAPSET)
-script.gisenv()
import grass.lib.gis as libgis
from grass.pygrass.functions import getenv
from grass.pygrass.errors import GrassError
-#write dec to check if user have permissions or not
-
ETYPE = {'rast': libgis.G_ELEMENT_RASTER,
'rast3d': libgis.G_ELEMENT_RASTER3D,
'vect': libgis.G_ELEMENT_VECTOR,
@@ -56,10 +42,12 @@
return getenv(type)
else:
raise GrassError("%s <%s> not found" % (type.title(),
- join(path, value)))
+ join(path, value)))
def set_current_mapset(mapset, location=None, gisdbase=None):
+ """Set the current mapset as working area
+ """
libgis.G_setenv('MAPSET', mapset)
if location:
libgis.G_setenv('LOCATION_NAME', location)
@@ -68,6 +56,7 @@
def make_mapset(mapset, location=None, gisdbase=None):
+ """Create a new mapset"""
res = libgis.G_make_mapset(gisdbase, location, mapset)
if res == -1:
raise GrassError("Cannot create new mapset")
@@ -83,6 +72,7 @@
>>> gisdbase.name == gisenv()['GISDBASE']
True
+ ..
"""
def __init__(self, gisdbase=''):
self.name = gisdbase
@@ -93,7 +83,8 @@
def _set_name(self, name):
self._name = _check(name, '', "GISDBASE")
- name = property(fget=_get_name, fset=_set_name)
+ name = property(fget=_get_name, fset=_set_name,
+ doc="Set or obtain the name of GISDBASE")
def __str__(self):
return self.name
@@ -122,6 +113,7 @@
for loc in self.locations():
yield Location(loc, self.name)
+ # TODO remove or complete this function
def new_location(self):
if libgis.G__make_location() != 0:
raise GrassError("Cannot create new location")
@@ -154,6 +146,8 @@
True
>>> location.name == gisenv()['LOCATION_NAME']
True
+
+ ..
"""
def __init__(self, location='', gisdbase=''):
self.gisdbase = gisdbase
@@ -165,7 +159,8 @@
def _set_gisdb(self, gisdb):
self._gisdb = _check(gisdb, '', "GISDBASE")
- gisdbase = property(fget=_get_gisdb, fset=_set_gisdb)
+ gisdbase = property(fget=_get_gisdb, fset=_set_gisdb,
+ doc="Set or obtain the name of GISDBASE")
def _get_name(self):
return self._name
@@ -173,7 +168,8 @@
def _set_name(self, name):
self._name = _check(name, self._gisdb, "LOCATION_NAME")
- name = property(fget=_get_name, fset=_set_name)
+ name = property(fget=_get_name, fset=_set_name,
+ doc="Set or obtain the name of LOCATION")
def __getitem__(self, mapset):
if mapset in self.mapsets():
@@ -196,11 +192,20 @@
return 'Location(%r)' % self.name
def mapsets(self, pattern=None, permissions=True):
- """Return a list of the available mapsets. ::
+ """Return a list of the available mapsets.
+ :param pattern: the pattern to filter the result
+ :type pattern: str
+ :param permissions: check the permission of mapset
+ :type permissions: bool
+ :returns: a list of mapset's names
+
+ ::
+
>>> location = Location()
>>> location.mapsets()
['PERMANENT', 'user1']
+ ..
"""
mapsets = [mapset for mapset in self]
if permissions:
@@ -226,6 +231,8 @@
'nc_basic_spm_grass7'
>>> mapset.name
'user1'
+
+ ..
"""
def __init__(self, mapset='', location='', gisdbase=''):
self.gisdbase = gisdbase
@@ -239,7 +246,8 @@
def _set_gisdb(self, gisdb):
self._gisdb = _check(gisdb, '', "GISDBASE")
- gisdbase = property(fget=_get_gisdb, fset=_set_gisdb)
+ gisdbase = property(fget=_get_gisdb, fset=_set_gisdb,
+ doc="Set or obtain the name of GISDBASE")
def _get_loc(self):
return self._loc
@@ -247,7 +255,8 @@
def _set_loc(self, loc):
self._loc = _check(loc, self._gisdb, "LOCATION_NAME")
- location = property(fget=_get_loc, fset=_set_loc)
+ location = property(fget=_get_loc, fset=_set_loc,
+ doc="Set or obtain the name of LOCATION")
def _get_name(self):
return self._name
@@ -255,7 +264,8 @@
def _set_name(self, name):
self._name = _check(name, join(self._gisdb, self._loc), "MAPSET")
- name = property(fget=_get_name, fset=_set_name)
+ name = property(fget=_get_name, fset=_set_name,
+ doc="Set or obtain the name of MAPSET")
def __str__(self):
return self.name
@@ -279,6 +289,11 @@
* 'vect',
* 'view3d'
+ :param type: the type of element to query
+ :type type: str
+ :param pattern: the pattern to filter the result
+ :type pattern: str
+
::
>>> mapset = Mapset('PERMANENT')
@@ -288,6 +303,8 @@
['basins', 'elevation', ...]
>>> mapset.glist('rast', pattern='el*')
['elevation_shade', 'elevation']
+
+ ..
"""
if type not in ETYPE:
str_err = "Type %s is not valid, valid types are: %s."
@@ -305,6 +322,7 @@
return elist
def is_current(self):
+ """Check if the MAPSET is the working MAPSET"""
return (self.name == libgis.G_getenv('MAPSET') and
self.location == libgis.G_getenv('LOCATION_NAME') and
self.gisdbase == libgis.G_getenv('GISDBASE'))
@@ -324,6 +342,14 @@
class VisibleMapset(object):
+ """VisibleMapset object::
+
+ >>> mapset = VisibleMapset('user1')
+ >>> mapset
+ ['user1', 'PERMANENT']
+
+ ..
+ """
def __init__(self, mapset, location='', gisdbase=''):
self.mapset = mapset
self.location = Location(location, gisdbase)
@@ -338,21 +364,31 @@
yield mapset
def read(self):
+ """Return the mapsets in the search path"""
with open(self.spath, "a+") as f:
lines = f.readlines()
- #lines.remove('')
if lines:
return [l.strip() for l in lines]
lns = ['PERMANENT', ]
self.write(lns)
return lns
- def write(self, mapsets):
+ def _write(self, mapsets):
+ """Write to SEARCH_PATH file the changes in the search path
+
+ :param mapsets: a list of mapset's names
+ :type mapsets: list
+ """
with open(self.spath, "w+") as f:
ms = self.location.mapsets()
f.write('%s' % '\n'.join([m for m in mapsets if m in ms]))
def add(self, mapset):
+ """Add a mapset to the search path
+
+ :param mapset: a mapset's name
+ :type mapset: str
+ """
if mapset not in self.read() and mapset in self.location:
with open(self.spath, "a+") as f:
f.write('\n%s' % mapset)
@@ -360,12 +396,27 @@
raise TypeError('Mapset not found')
def remove(self, mapset):
+ """Remove mapset to the search path
+
+ :param mapset: a mapset's name
+ :type mapset: str
+ """
mapsets = self.read()
mapsets.remove(mapset)
- self.write(mapsets)
+ self._write(mapsets)
def extend(self, mapsets):
+ """Add more mapsets to the search path
+
+ :param mapsets: a list of mapset's names
+ :type mapsets: list
+ """
ms = self.location.mapsets()
final = self.read()
final.extend([m for m in mapsets if m in ms and m not in final])
- self.write(final)
+ self._write(final)
+
+ def reset(self):
+ """Reset to the original search path"""
+ final = [self.mapset, 'PERMANENT']
+ self._write(final)
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/gis/region.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/gis/region.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/gis/region.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -15,34 +15,37 @@
class Region(object):
+ """
+ ::
+
+ >>> default = Region(default=True)
+ >>> current_good = Region()
+ >>> current = Region()
+ >>> current.align('elevation')
+ >>> default == current
+ True
+ >>> current.cols
+ 1500
+ >>> current.ewres
+ 10.0
+ >>> current.cols = 3000
+ >>> current.ewres
+ 5.0
+ >>> current.ewres = 20.0
+ >>> current.cols
+ 750
+ >>> current.set_current()
+ >>> default == current
+ False
+ >>> current.get_default()
+ >>> default = Region(default=True)
+ >>> default == current
+ True
+ >>> current_good.set_current()
+
+ ..
+ """
def __init__(self, default=False):
- """::
-
- >>> default = Region(default=True)
- >>> current_good = Region()
- >>> current = Region()
- >>> current.align('elevation')
- >>> default == current
- True
- >>> current.cols
- 1500
- >>> current.ewres
- 10.0
- >>> current.cols = 3000
- >>> current.ewres
- 5.0
- >>> current.ewres = 20.0
- >>> current.cols
- 750
- >>> current.set_current()
- >>> default == current
- False
- >>> current.get_default()
- >>> default = Region(default=True)
- >>> default == current
- True
- >>> current_good.set_current()
- """
self.c_region = ctypes.pointer(libgis.Cell_head())
if default:
self.get_default()
@@ -61,7 +64,8 @@
"""Private function to set north value"""
self.c_region.contents.north = value
- north = property(fget=_get_n, fset=_set_n)
+ north = property(fget=_get_n, fset=_set_n,
+ doc="Set and obtain north coordinate")
def _get_s(self):
"""Private function to obtain south value"""
@@ -71,7 +75,8 @@
"""Private function to set south value"""
self.c_region.contents.south = value
- south = property(fget=_get_s, fset=_set_s)
+ south = property(fget=_get_s, fset=_set_s,
+ doc="Set and obtain south coordinate")
def _get_e(self):
"""Private function to obtain east value"""
@@ -81,7 +86,8 @@
"""Private function to set east value"""
self.c_region.contents.east = value
- east = property(fget=_get_e, fset=_set_e)
+ east = property(fget=_get_e, fset=_set_e,
+ doc="Set and obtain east coordinate")
def _get_w(self):
"""Private function to obtain west value"""
@@ -91,7 +97,8 @@
"""Private function to set west value"""
self.c_region.contents.west = value
- west = property(fget=_get_w, fset=_set_w)
+ west = property(fget=_get_w, fset=_set_w,
+ doc="Set and obtain west coordinate")
def _get_t(self):
"""Private function to obtain top value"""
@@ -101,7 +108,8 @@
"""Private function to set top value"""
self.c_region.contents.top = value
- top = property(fget=_get_t, fset=_set_t)
+ top = property(fget=_get_t, fset=_set_t,
+ doc="Set and obtain top value")
def _get_b(self):
"""Private function to obtain bottom value"""
@@ -111,7 +119,8 @@
"""Private function to set bottom value"""
self.c_region.contents.bottom = value
- bottom = property(fget=_get_b, fset=_set_b)
+ bottom = property(fget=_get_b, fset=_set_b,
+ doc="Set and obtain bottom value")
#----------RESOLUTION----------
def _get_rows(self):
@@ -123,7 +132,8 @@
self.c_region.contents.rows = value
self.adjust(rows=True)
- rows = property(fget=_get_rows, fset=_set_rows)
+ rows = property(fget=_get_rows, fset=_set_rows,
+ doc="Set and obtain number of rows")
def _get_cols(self):
"""Private function to obtain columns value"""
@@ -134,7 +144,8 @@
self.c_region.contents.cols = value
self.adjust(cols=True)
- cols = property(fget=_get_cols, fset=_set_cols)
+ cols = property(fget=_get_cols, fset=_set_cols,
+ doc="Set and obtain number of columns")
def _get_nsres(self):
"""Private function to obtain north-south value"""
@@ -145,7 +156,8 @@
self.c_region.contents.ns_res = value
self.adjust()
- nsres = property(fget=_get_nsres, fset=_set_nsres)
+ nsres = property(fget=_get_nsres, fset=_set_nsres,
+ doc="Set and obtain north-south resolution value")
def _get_ewres(self):
"""Private function to obtain east-west value"""
@@ -156,7 +168,8 @@
self.c_region.contents.ew_res = value
self.adjust()
- ewres = property(fget=_get_ewres, fset=_set_ewres)
+ ewres = property(fget=_get_ewres, fset=_set_ewres,
+ doc="Set and obtain east-west resolution value")
def _get_tbres(self):
"""Private function to obtain top-botton 3D value"""
@@ -167,7 +180,8 @@
self.c_region.contents.tb_res = value
self.adjust()
- tbres = property(fget=_get_tbres, fset=_set_tbres)
+ tbres = property(fget=_get_tbres, fset=_set_tbres,
+ doc="Set and obtain top-bottom 3D value")
@property
def zone(self):
@@ -228,12 +242,20 @@
#----------METHODS----------
def zoom(self, raster_name):
- """Shrink region until it meets non-NULL data from this raster map:"""
+ """Shrink region until it meets non-NULL data from this raster map
+
+ :param raster_name: the name of raster
+ :type raster_name: str
+ """
self._set_param('zoom', str(raster_name))
self.get_current()
def align(self, raster_name):
- """Adjust region cells to cleanly align with this raster map"""
+ """Adjust region cells to cleanly align with this raster map
+
+ :param raster_name: the name of raster
+ :type raster_name: str
+ """
self._set_param('align', str(raster_name))
self.get_current()
@@ -245,13 +267,20 @@
libgis.G_adjust_Cell_head(self.c_region, bool(rows), bool(cols))
def vect(self, vector_name):
- """Adjust bounding box of region using a vector ::
+ """Adjust bounding box of region using a vector
+ :param vector_name: the name of vector
+ :type vector_name: str
+
+ ::
+
>>> reg = Region()
>>> reg.vect('census')
>>> reg.get_bbox()
Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
>>> reg.get_default()
+
+ ..
"""
from grass.pygrass.vector import VectorTopo
vect = VectorTopo(vector_name)
@@ -289,6 +318,8 @@
>>> reg = Region()
>>> reg.get_bbox()
Bbox(228500.0, 215000.0, 645000.0, 630000.0)
+
+ ..
"""
from grass.pygrass.vector.basic import Bbox
return Bbox(north=self.north, south=self.south,
@@ -296,16 +327,22 @@
top=self.top, bottom=self.bottom)
def set_bbox(self, bbox):
- """Set region from Bbox ::
+ """Set region extent from Bbox
+ :param bbox: a Bbox object to set the extent
+ :type bbox: Bbox object
+
+ ::
+
>>> from grass.pygrass.vector.basic import Bbox
- >>> b = Bbox(230963.640878, 212125.562878,
- ... 645837.437393, 628769.374393)
+ >>> b = Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
>>> reg = Region()
>>> reg.set_bbox(b)
>>> reg.get_bbox()
Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
>>> reg.get_current()
+
+ ..
"""
self.north = bbox.north
self.south = bbox.south
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/messages/__init__.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/messages/__init__.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/messages/__init__.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-"""!@package grass.pygrass.massages
+"""@package grass.pygrass.massages
@brief PyGRASS message interface
@@ -19,7 +19,7 @@
class FatalError(Exception):
- """!This error will be raised in case raise_on_error was set True
+ """This error will be raised in case raise_on_error was set True
when creating the messenger object.
"""
def __init__(self, msg):
@@ -30,12 +30,13 @@
def message_server(lock, conn):
- """!The GRASS message server function designed to be a target for
+ """The GRASS message server function designed to be a target for
multiprocessing.Process
- @param lock A multiprocessing.Lock
- @param conn A multiprocessing.Pipe
+ :param lock: A multiprocessing.Lock
+ :param conn: A multiprocessing.Pipe
+
This function will use the G_* message C-functions from grass.lib.gis
to provide an interface to the GRASS C-library messaging system.
@@ -59,9 +60,11 @@
testing purpose
The that is end through the pipe must be a list of values:
+
- Messages: ["INFO|VERBOSE|WARNING|ERROR|FATAL", "MESSAGE"]
- - Debug: ["DEBUG", level, "MESSAGE"]
- - Percent: ["PERCENT", n, d, s]
+ - Debug: ["DEBUG", level, "MESSAGE"]
+ - Percent: ["PERCENT", n, d, s]
+
"""
libgis.G_debug(1, "Start messenger server")
@@ -110,7 +113,7 @@
class Messenger(object):
- """!Fast and exit-safe interface to GRASS C-library message functions
+ """Fast and exit-safe interface to GRASS C-library message functions
This class implements a fast and exit-safe interface to the GRASS
C-library message functions like: G_message(), G_warning(),
@@ -128,7 +131,6 @@
Usage:
- @code
>>> msgr = Messenger()
>>> msgr.debug(0, "debug 0")
>>> msgr.verbose("verbose message")
@@ -137,7 +139,6 @@
>>> msgr.percent(1, 1, 1)
>>> msgr.warning("Ohh")
>>> msgr.error("Ohh no")
-
D0/0: debug 0
message
important message
@@ -175,7 +176,6 @@
raise FatalError(message)
FatalError: Ohh no no no!
- @endcode
"""
def __init__(self, raise_on_error=False):
self.client_conn = None
@@ -188,6 +188,8 @@
self.stop()
def start_server(self):
+ """Start the messenger server and open the pipe
+ """
self.client_conn, self.server_conn = Pipe()
self.lock = Lock()
self.server = Process(target=message_server, args=(self.lock,
@@ -196,7 +198,7 @@
self.server.start()
def _check_restart_server(self):
- """!Restart the server if it was terminated
+ """Restart the server if it was terminated
"""
if self.server.is_alive() is True:
return
@@ -206,40 +208,55 @@
self.warning("Needed to restart the messenger server")
def message(self, message):
- """!Send a message to stderr
+ """Send a message to stderr
+ :param message: the text of message
+ :type message: str
+
G_message() will be called in the messenger server process
"""
self._check_restart_server()
self.client_conn.send(["INFO", message])
def verbose(self, message):
- """!Send a verbose message to stderr
+ """Send a verbose message to stderr
+ :param message: the text of message
+ :type message: str
+
G_verbose_message() will be called in the messenger server process
"""
self._check_restart_server()
self.client_conn.send(["VERBOSE", message])
def important(self, message):
- """!Send an important message to stderr
+ """Send an important message to stderr
+ :param message: the text of message
+ :type message: str
+
G_important_message() will be called in the messenger server process
"""
self._check_restart_server()
self.client_conn.send(["IMPORTANT", message])
def warning(self, message):
- """!Send a warning message to stderr
+ """Send a warning message to stderr
+ :param message: the text of message
+ :type message: str
+
G_warning() will be called in the messenger server process
"""
self._check_restart_server()
self.client_conn.send(["WARNING", message])
def error(self, message):
- """!Send an error message to stderr
+ """Send an error message to stderr
+ :param message: the text of message
+ :type message: str
+
G_important_message() with an additional "ERROR:" string at
the start will be called in the messenger server process
"""
@@ -247,8 +264,11 @@
self.client_conn.send(["ERROR", message])
def fatal(self, message):
- """!Send an error message to stderr, call sys.exit(1) or raise FatalError
+ """Send an error message to stderr, call sys.exit(1) or raise FatalError
+ :param message: the text of message
+ :type message: str
+
This function emulates the behavior of G_fatal_error(). It prints
an error message to stderr and calls sys.exit(1). If raise_on_error
is set True while creating the messenger object, a FatalError
@@ -264,23 +284,30 @@
sys.exit(1)
def debug(self, level, message):
- """!Send a debug message to stderr
+ """Send a debug message to stderr
+ :param message: the text of message
+ :type message: str
+
G_debug() will be called in the messenger server process
"""
self._check_restart_server()
self.client_conn.send(["DEBUG", level, message])
def percent(self, n, d, s):
- """!Send a percentage to stderr
+ """Send a percentage to stderr
+ :param message: the text of message
+ :type message: str
+
+
G_percent() will be called in the messenger server process
"""
self._check_restart_server()
self.client_conn.send(["PERCENT", n, d, s])
def stop(self):
- """!Stop the messenger server and close the pipe
+ """Stop the messenger server and close the pipe
"""
if self.server is not None and self.server.is_alive():
self.client_conn.send(["STOP", ])
@@ -290,26 +317,30 @@
self.client_conn.close()
def set_raise_on_error(self, raise_on_error=True):
- """!Set the fatal error behavior
+ """Set the fatal error behavior
- - If raise_on_error == True, a FatalError exception will be raised if fatal() is called
- - If raise_on_error == False, sys.exit(1) will be invoked if fatal() is called
+ :param raise_on_error: if True a FatalError exception will be
+ raised instead of calling sys.exit(1)
+ :type raise_on_error: bool
- @param raise_on_error If True a FatalError exception will be raised instead
- of calling sys.exit(1)
+ - If raise_on_error == True, a FatalError exception will be raised
+ if fatal() is called
+ - If raise_on_error == False, sys.exit(1) will be invoked if
+ fatal() is called
+
"""
self.raise_on_error = raise_on_error
def get_raise_on_error(self):
- """!Get the fatal error behavior
+ """Get the fatal error behavior
- @return True if a FatalError exception will be raised
- or False if sys.exit(1) will be called in case of invoking fatal()
+ :returns: True if a FatalError exception will be raised or False if
+ sys.exit(1) will be called in case of invoking fatal()
"""
return self.raise_on_error
def test_fatal_error(self, message):
- """!Force the messenger server to call G_fatal_error()
+ """Force the messenger server to call G_fatal_error()
"""
import time
self._check_restart_server()
@@ -318,18 +349,17 @@
def get_msgr(_instance=[None, ], *args, **kwargs):
- """!Return a Messenger instance.
+ """Return a Messenger instance.
- @return the Messenger instance.
- @code ::
+ :returns: the Messenger instance.
- >>> msgr0 = get_msgr()
- >>> msgr1 = get_msgr()
- >>> msgr2 = Messenger()
- >>> msgr0 is msgr1
- True
- >>> msgr0 is msgr2
- False
+ >>> msgr0 = get_msgr()
+ >>> msgr1 = get_msgr()
+ >>> msgr2 = Messenger()
+ >>> msgr0 is msgr1
+ True
+ >>> msgr0 is msgr2
+ False
"""
if not _instance[0]:
_instance[0] = Messenger(*args, **kwargs)
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/grid.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/grid.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/grid.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -25,36 +25,21 @@
def select(parms, ptype):
"""Select only a certain type of parameters.
- Parameters
- ----------
+ :param parms: a DictType parameter with inputs or outputs of a Module class
+ :type parms: DictType parameters
+ :param ptype: String define the type of parameter that we want to select,
+ valid ptype are: 'raster', 'vector', 'group'
+ :type ptype: str
+ :returns: An iterator with the value of the parameter.
- params : DictType parameters
- A DictType parameter with inputs or outputs of a Module class.
- ptype : string
- String define the type of parameter that we want to select,
- valid ptype are: 'raster', 'vector', 'group'
-
-
- Returns
- -------
-
- An iterator with the value of the parameter.
-
-
- Examples
- --------
-
- ::
-
- >>> slp = Module('r.slope.aspect',
- ... elevation='ele', slope='slp', aspect='asp',
- ... run_=False)
- >>> for rast in select(slp.outputs, 'raster'):
- ... print rast
- ...
- slp
- asp
-
+ >>> slp = Module('r.slope.aspect',
+ ... elevation='ele', slope='slp', aspect='asp',
+ ... run_=False)
+ >>> for rast in select(slp.outputs, 'raster'):
+ ... print rast
+ ...
+ slp
+ asp
"""
for k in parms:
par = parms[k]
@@ -68,7 +53,13 @@
def copy_special_mapset_files(path_src, path_dst):
"""Copy all the special GRASS files that are contained in
- a mapset to another mapset."""
+ a mapset to another mapset
+
+ :param path_src: the path to the original mapset
+ :type path_src: str
+ :param path_dst: the path to the new mapset
+ :type path_dst: str
+ """
for fil in (fi for fi in os.listdir(path_src) if fi.isupper()):
sht.copy(os.path.join(path_src, fil), path_dst)
@@ -76,43 +67,30 @@
def copy_mapset(mapset, path):
"""Copy mapset to another place without copying raster and vector data.
- Parameters
- ----------
+ :param mapset: a Mapset instance to copy
+ :type mapset: Mapset object
+ :param path: path where the new mapset must be copied
+ :type path: str
+ :returns: the instance of the new Mapset.
- mapset : mapset_like
- A Mapset instance.
- path : string
- Path where the new mapset must be copied.
+ >>> mset = Mapset()
+ >>> mset.name
+ 'user1'
+ >>> import tempfile as tmp
+ >>> import os
+ >>> path = os.path.join(tmp.gettempdir(), 'my_loc', 'my_mset')
+ >>> copy_mapset(mset, path)
+ Mapset('user1')
+ >>> sorted(os.listdir(path))
+ [u'PERMANENT', u'user1']
+ >>> sorted(os.listdir(os.path.join(path, 'PERMANENT')))
+ [u'DEFAULT_WIND', u'PROJ_INFO', u'PROJ_UNITS', u'VAR', u'WIND']
+ >>> sorted(os.listdir(os.path.join(path, 'user1')))
+ [u'CURGROUP', u'SEARCH_PATH', u'VAR', u'WIND']
+ >>> import shutil
+ >>> shutil.rmtree(path)
- Returns
- -------
-
- The instance of the new Mapset.
-
-
- Examples
- --------
-
- ::
-
- >>> mset = Mapset()
- >>> mset.name
- 'user1'
- >>> import tempfile as tmp
- >>> import os
- >>> path = os.path.join(tmp.gettempdir(), 'my_loc', 'my_mset')
- >>> copy_mapset(mset, path)
- Mapset('user1')
- >>> sorted(os.listdir(path))
- [u'PERMANENT', u'user1']
- >>> sorted(os.listdir(os.path.join(path, 'PERMANENT')))
- [u'DEFAULT_WIND', u'PROJ_INFO', u'PROJ_UNITS', u'VAR', u'WIND']
- >>> sorted(os.listdir(os.path.join(path, 'user1')))
- [u'CURGROUP', u'SEARCH_PATH', u'VAR', u'WIND']
- >>> import shutil
- >>> shutil.rmtree(path)
-
"""
per_old = os.path.join(mapset.gisdbase, mapset.location, 'PERMANENT')
per_new = os.path.join(path, 'PERMANENT')
@@ -132,14 +110,13 @@
"""Read a GISRC file and return a tuple with the mapset, location
and gisdbase.
- Examples
- --------
+ :param gisrc: the path to GISRC file
+ :type gisrc: str
+ :returns: a tuple with the mapset, location and gisdbase
- ::
-
- >>> import os
- >>> read_gisrc(os.environ['GISRC']) # doctest: +ELLIPSIS
- (u'user1', ...)
+ >>> import os
+ >>> read_gisrc(os.environ['GISRC']) # doctest: +ELLIPSIS
+ (u'user1', ...)
"""
with open(gisrc, 'r') as gfile:
gis = dict([(k.strip(), v.strip())
@@ -150,19 +127,12 @@
def get_mapset(gisrc_src, gisrc_dst):
"""Get mapset from a GISRC source to a GISRC destination.
- Parameters
- ----------
+ :param gisrc_src: path to the GISRC source
+ :type gisrc_src: str
+ :param gisrc_dst: path to the GISRC destination
+ :type gisrc_dst: str
+ :returns: a tuple with Mapset(src), Mapset(dst)
- gisrc_src : path to the GISRC source
-
- gisrc_dst : path to the GISRC destination
-
-
- Returns
- -------
-
- A tuple with Mapset(src), Mapset(dst)
-
"""
msrc, lsrc, gsrc = read_gisrc(gisrc_src)
mdst, ldst, gdst = read_gisrc(gisrc_dst)
@@ -180,28 +150,21 @@
def copy_groups(groups, gisrc_src, gisrc_dst, region=None):
- """Copy group from one mapset to another, crop the raster to the region.
+ """Copy group from one mapset to another, crop the raster to the region
- Parameters
- ----------
+ :param groups: a list of strings with the group that must be copied
+ from a master to another.
+ :type groups: list of strings
+ :param gisrc_src: path of the GISRC file from where we want to copy the groups
+ :type gisrc_src: str
+ :param gisrc_dst: path of the GISRC file where the groups will be created
+ :type gisrc_dst: str
+ :param region: a region like object or a dictionary with the region
+ parameters that will be used to crop the rasters of the
+ groups
+ :type region: Region object or dictionary
+ :returns: None
- groups : list of strings
- A list of strings with the group that must be copied
- from a master to another.
- gisrc_src : path to the GISRC source
- Path of the GISRC file from where we want to copy the groups.
- gisrc_dst : path to the GISRC destination
- Path of the GISRC file where the groups will be created.
- region : region_like or dictionary
- A region like object or a dictionary with the region parameters that
- will be used to crop the rasters of the groups.
-
-
- Returns
- -------
-
- None.
-
"""
env = os.environ.copy()
# instantiate modules
@@ -233,24 +196,17 @@
def set_region(region, gisrc_src, gisrc_dst, env):
"""Set a region into two different mapsets.
- Parameters
- ----------
-
- region : region_like or dictionary
- A region like object or a dictionary with the region parameters that
- will be used to crop the rasters.
- gisrc_src : path to the GISRC source
- Path of the GISRC file from where we want to copy the rasters.
- gisrc_dst : path to the GISRC destination
- Path of the GISRC file where the rasters will be created.
- region : dictionary
- A dictionary with the variable environment to use.
-
-
- Returns
- -------
-
- None.
+ :param region: a region like object or a dictionary with the region
+ parameters that will be used to crop the rasters of the
+ groups
+ :type region: Region object or dictionary
+ :param gisrc_src: path of the GISRC file from where we want to copy the groups
+ :type gisrc_src: str
+ :param gisrc_dst: path of the GISRC file where the groups will be created
+ :type gisrc_dst: str
+ :param env:
+ :type env:
+ :returns: None
"""
reg_str = "g.region n=%(north)r s=%(south)r " \
"e=%(east)r w=%(west)r " \
@@ -265,25 +221,18 @@
def copy_rasters(rasters, gisrc_src, gisrc_dst, region=None):
"""Copy rasters from one mapset to another, crop the raster to the region.
- Parameters
- ----------
-
- rasters : list of strings
- A list of strings with the raster map that must be copied
- from a master to another.
- gisrc_src : path to the GISRC source
- Path of the GISRC file from where we want to copy the rasters.
- gisrc_dst : path to the GISRC destination
- Path of the GISRC file where the rasters will be created.
- region : region_like or dictionary
- A region like object or a dictionary with the region parameters that
- will be used to crop the rasters.
-
-
- Returns
- -------
-
- None.
+ :param rasters: a list of strings with the raster map that must be copied
+ from a master to another.
+ :type rasters: list
+ :param gisrc_src: path of the GISRC file from where we want to copy the groups
+ :type gisrc_src: str
+ :param gisrc_dst: path of the GISRC file where the groups will be created
+ :type gisrc_dst: str
+ :param region: a region like object or a dictionary with the region
+ parameters that will be used to crop the rasters of the
+ groups
+ :type region: Region object or dictionary
+ :returns: None
"""
env = os.environ.copy()
if region:
@@ -316,21 +265,14 @@
def copy_vectors(vectors, gisrc_src, gisrc_dst):
"""Copy vectors from one mapset to another, crop the raster to the region.
- Parameters
- ----------
-
- vectors : list of strings
- A list of strings with the raster map that must be copied
- from a master to another.
- gisrc_src : path to the GISRC source
- Path of the GISRC file from where we want to copy the vectors.
- gisrc_dst : path to the GISRC destination
- Path of the GISRC file where the vectors will be created.
-
- Returns
- -------
-
- None.
+ :param vectors: a list of strings with the vector map that must be copied
+ from a master to another.
+ :type vectors: list
+ :param gisrc_src: path of the GISRC file from where we want to copy the groups
+ :type gisrc_src: str
+ :param gisrc_dst: path of the GISRC file where the groups will be created
+ :type gisrc_dst: str
+ :returns: None
"""
env = os.environ.copy()
path_dst = os.path.join(*read_gisrc(gisrc_dst))
@@ -359,23 +301,14 @@
pickle a Module class and cnvert into a string that can be used with
`Popen(get_cmd(cmdd), shell=True)`.
- Parameters
- ----------
+ :param cmdd: a module dictionary with all the parameters
+ :type cmdd: dict
- cmdd : dict
- A module dictionary with all the parameters.
-
- Examples
- --------
-
- ::
-
- >>> slp = Module('r.slope.aspect',
- ... elevation='ele', slope='slp', aspect='asp',
- ... overwrite=True, run_=False)
- >>> get_cmd(slp.get_dict()) # doctest: +ELLIPSIS
- ['r.slope.aspect', 'elevation=ele', 'format=degrees', ..., '--o']
-
+ >>> slp = Module('r.slope.aspect',
+ ... elevation='ele', slope='slp', aspect='asp',
+ ... overwrite=True, run_=False)
+ >>> get_cmd(slp.get_dict()) # doctest: +ELLIPSIS
+ ['r.slope.aspect', 'elevation=ele', 'format=degrees', ..., '--o']
"""
cmd = [cmdd['name'], ]
cmd.extend(("%s=%s" % (k, v) for k, v in cmdd['inputs']
@@ -396,30 +329,23 @@
def cmd_exe(args):
"""Create a mapset, and execute a cmd inside.
- Parameters
- ----------
+ :param args: is a tuple that contains several information see below
+ :type args: tuple
+ :returns: None
- `args` is a tuple that contains:
+ The puple has to contain:
- bbox : dict
- A dict with the region parameters (n, s, e, w, etc.)
- that we want to set before to apply the command.
- mapnames : dict
- A dictionary to substitute the input if the domain has
- been splitted in several tiles.
- gisrc_src : path to the GISRC source
- Path of the GISRC file from where we want to copy the groups.
- gisrc_dst : path to the GISRC destination
- Path of the GISRC file where the groups will be created.
- cmd : dictionary
- A dictionary with all the parameter of a GRASS module.
- groups: list
- A list of strings with the groups that we want to copy in the mapset.
+ - bbox (dict): a dict with the region parameters (n, s, e, w, etc.)
+ that we want to set before to apply the command.
+ - mapnames (dict): a dictionary to substitute the input if the domain has
+ been splitted in several tiles.
+ - gisrc_src (str): path of the GISRC file from where we want to copy the
+ groups.
+ - gisrc_dst (str): path of the GISRC file where the groups will be created.
+ - cmd (dict): a dictionary with all the parameter of a GRASS module.
+ - groups (list): a list of strings with the groups that we want to copy in
+ the mapset.
- Returns
- -------
-
- None.
"""
bbox, mapnames, gisrc_src, gisrc_dst, cmd, groups = args
src, dst = get_mapset(gisrc_src, gisrc_dst)
@@ -447,39 +373,32 @@
class GridModule(object):
- """Run GRASS raster commands in a multiproccessing mode.
+ # TODO maybe also i.* could be supported easily
+ """Run GRASS raster commands in a multiprocessing mode.
- Parameters
- -----------
+ :param cmd: raster GRASS command, only command staring with r.* are valid.
+ :type cmd: str
+ :param width: width of the tile, in pixel
+ :type width: int
+ :param height: height of the tile, in pixel.
+ :type height: int
+ :param overlap: overlap between tiles, in pixel.
+ :type overlap: int
+ :param processes: number of threads, default value is equal to the number
+ of processor available.
+ :param split: if True use r.tile to split all the inputs.
+ :type split: bool
+ :param run_: if False only instantiate the object
+ :type run_: bool
+ :param args: give all the parameters to the command
+ :param kargs: give all the parameters to the command
- cmd: raster GRASS command
- Only command staring with r.* are valid.
- width: integer
- Width of the tile, in pixel.
- height: integer
- Height of the tile, in pixel.
- overlap: integer
- Overlap between tiles, in pixel.
- processes: number of threads
- Default value is equal to the number of processor available.
- split: boolean
- If True use r.tile to split all the inputs.
- run_: boolean
- If False only instantiate the object.
- args and kargs: cmd parameters
- Give all the parameters to the command.
-
- Examples
- --------
-
- ::
-
- >>> grd = GridModule('r.slope.aspect',
- ... width=500, height=500, overlap=2,
- ... processes=None, split=False,
- ... elevation='elevation',
- ... slope='slope', aspect='aspect', overwrite=True)
- >>> grd.run()
+ >>> grd = GridModule('r.slope.aspect',
+ ... width=500, height=500, overlap=2,
+ ... processes=None, split=False,
+ ... elevation='elevation',
+ ... slope='slope', aspect='aspect', overwrite=True)
+ >>> grd.run()
"""
def __init__(self, cmd, width=None, height=None, overlap=0, processes=None,
split=False, debug=False, region=None, move=None, log=False,
@@ -531,7 +450,11 @@
os.remove(self.gisrc_dst)
def clean_location(self, location=None):
- """Remove all created mapsets."""
+ """Remove all created mapsets.
+
+ :param location: a Location instance where we are running the analysis
+ :type location: Location object
+ """
if location is None:
if self.n_mset:
self.n_mset.current()
@@ -599,7 +522,14 @@
inm.value = inm.value + '@%s' % mset
def run(self, patch=True, clean=True):
- """Run the GRASS command."""
+ """Run the GRASS command
+
+ :param patch: set False if you does not want to patch the results
+ :type patch: bool
+ :param clean: set False if you does not want to remove all the stuff
+ created by GridModule
+ :type clean: bool
+ """
self.module.flags.overwrite = True
self.define_mapset_inputs()
if self.debug:
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/patch.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/patch.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/patch.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -14,6 +14,10 @@
def get_start_end_index(bbox_list):
"""Convert a Bounding Box to a list of the index of
column start, end, row start and end
+
+ :param bbox_list: a list of BBox object to convert
+ :type bbox_list: list of BBox object
+
"""
ss_list = []
reg = Region()
@@ -25,7 +29,15 @@
def rpatch_row(rast, rasts, bboxes):
- """Patch a row of bound boxes."""
+ """Patch a row of bound boxes.
+
+ :param rast: a Raster object to write
+ :type rast: Raster object
+ :param rasts: a list of Raster object to read
+ :type rasts: list of Raster object
+ :param bboxes: a list of BBox object
+ :type bboxes: list of BBox object
+ """
sei = get_start_end_index(bboxes)
# instantiate two buffer
buff = rasts[0][0]
@@ -41,7 +53,26 @@
def rpatch_map(raster, mapset, mset_str, bbox_list, overwrite=False,
start_row=0, start_col=0, prefix=''):
- """Patch raster using a bounding box list to trim the raster."""
+ # TODO is prefix useful??
+ """Patch raster using a bounding box list to trim the raster.
+
+ :param raster: the name of output raster
+ :type raster: str
+ :param mapset: the name of mapset to use
+ :type mapset: str
+ :param mset_str:
+ :type mset_str: str
+ :param bbox_list: a list of BBox object to convert
+ :type bbox_list: list of BBox object
+ :param overwrite: overwrite existing raster
+ :type overwrite: bool
+ :param start_row: the starting row of original raster
+ :type start_row: int
+ :param start_col: the starting column of original raster
+ :type start_col: int
+ :param prefix: the prefix of output raster
+ :type prefix: str
+ """
# Instantiate the RasterRow input objects
rast = RasterRow(prefix + raster, mapset)
rtype = RasterRow(name=raster, mapset=mset_str % (0, 0))
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/split.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/split.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/grid/split.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -11,7 +11,21 @@
def get_bbox(reg, row, col, width, height, overlap):
- """Return a Bbox"""
+ """Return a Bbox
+
+ :param reg: a Region object to split
+ :type reg: Region object
+ :param row: the number of row
+ :type row: int
+ :param col: the number of row
+ :type col: int
+ :param width: the width of tiles
+ :type width: int
+ :param height: the width of tiles
+ :type height: int
+ :param overlap: the value of overlap between tiles
+ :type overlap: int
+ """
north = reg.north - (row * height - overlap) * reg.nsres
south = reg.north - ((row + 1) * height + overlap) * reg.nsres
east = reg.west + ((col + 1) * width + overlap) * reg.ewres
@@ -23,25 +37,34 @@
def split_region_tiles(region=None, width=100, height=100, overlap=0):
- """Spit a region into a list of Bbox. ::
+ """Spit a region into a list of Bbox.
- >>> reg = Region()
- >>> reg.north = 1350
- >>> reg.south = 0
- >>> reg.nsres = 1
- >>> reg.east = 1500
- >>> reg.west = 0
- >>> reg.ewres = 1
- >>> reg.cols
- 1500
- >>> reg.rows
- 1350
- >>> split_region_tiles(region=reg, width=1000, height=700, overlap=0) # doctest: +NORMALIZE_WHITESPACE
- [[Bbox(1350.0, 650.0, 1000.0, 0.0), Bbox(1350.0, 650.0, 1500.0, 1000.0)],
- [Bbox(650.0, 0.0, 1000.0, 0.0), Bbox(650.0, 0.0, 1500.0, 1000.0)]]
- >>> split_region_tiles(region=reg, width=1000, height=700, overlap=10) # doctest: +NORMALIZE_WHITESPACE
- [[Bbox(1350.0, 640.0, 1010.0, 0.0), Bbox(1350.0, 640.0, 1500.0, 990.0)],
- [Bbox(660.0, 0.0, 1010.0, 0.0), Bbox(660.0, 0.0, 1500.0, 990.0)]]
+ :param region: a Region object to split
+ :type region: Region object
+ :param width: the width of tiles
+ :type width: int
+ :param height: the width of tiles
+ :type height: int
+ :param overlap: the value of overlap between tiles
+ :type overlap: int
+
+ >>> reg = Region()
+ >>> reg.north = 1350
+ >>> reg.south = 0
+ >>> reg.nsres = 1
+ >>> reg.east = 1500
+ >>> reg.west = 0
+ >>> reg.ewres = 1
+ >>> reg.cols
+ 1500
+ >>> reg.rows
+ 1350
+ >>> split_region_tiles(region=reg, width=1000, height=700, overlap=0) # doctest: +NORMALIZE_WHITESPACE
+ [[Bbox(1350.0, 650.0, 1000.0, 0.0), Bbox(1350.0, 650.0, 1500.0, 1000.0)],
+ [Bbox(650.0, 0.0, 1000.0, 0.0), Bbox(650.0, 0.0, 1500.0, 1000.0)]]
+ >>> split_region_tiles(region=reg, width=1000, height=700, overlap=10) # doctest: +NORMALIZE_WHITESPACE
+ [[Bbox(1350.0, 640.0, 1010.0, 0.0), Bbox(1350.0, 640.0, 1500.0, 990.0)],
+ [Bbox(660.0, 0.0, 1010.0, 0.0), Bbox(660.0, 0.0, 1500.0, 990.0)]]
"""
reg = region if region else Region()
ncols = (reg.cols + width - 1) // width
@@ -58,25 +81,16 @@
def get_overlap_region_tiles(region=None, width=100, height=100, overlap=0):
- """Get the Bbox ov the overlapped region. ::
+ """Get the Bbox of the overlapped region.
- >>> reg = Region()
- >>> reg.north = 1350
- >>> reg.south = 0
- >>> reg.nsres = 1
- >>> reg.east = 1500
- >>> reg.west = 0
- >>> reg.ewres = 1
- >>> reg.cols
- 1500
- >>> reg.rows
- 1350
- >>> split_region_tiles(region=reg, width=1000, height=700, overlap=0) # doctest: +NORMALIZE_WHITESPACE
- [[Bbox(1350.0, 650.0, 1000.0, 0.0), Bbox(1350.0, 650.0, 1500.0, 1000.0)],
- [Bbox(650.0, 0.0, 1000.0, 0.0), Bbox(650.0, 0.0, 1500.0, 1000.0)]]
- >>> split_region_tiles(region=reg, width=1000, height=700, overlap=10) # doctest: +NORMALIZE_WHITESPACE
- [[Bbox(1350.0, 640.0, 1010.0, 0.0), Bbox(1350.0, 640.0, 1500.0, 990.0)],
- [Bbox(660.0, 0.0, 1010.0, 0.0), Bbox(660.0, 0.0, 1500.0, 990.0)]]
+ :param region: a Region object to split
+ :type region: Region object
+ :param width: the width of tiles
+ :type width: int
+ :param height: the width of tiles
+ :type height: int
+ :param overlap: the value of overlap between tiles
+ :type overlap: int
"""
reg = region if region else Region()
ncols = (reg.cols + width - 1) // width
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/flag.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/flag.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/flag.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -8,8 +8,12 @@
with_statement, print_function, unicode_literals)
from grass.pygrass.modules.interface import read
+# TODO add documentation
+class Flag(object):
+ """The Flag object store all information about a flag of module.
-class Flag(object):
+ It is possible to set flags of command using this object.
+ """
def __init__(self, xflag=None, diz=None):
self.value = False
diz = read.element2dict(xflag) if xflag is not None else diz
@@ -21,6 +25,7 @@
self.guisection = diz.get('guisection', None)
def get_bash(self):
+ """Prova"""
if self.value:
if self.special:
return '--%s' % self.name[0]
@@ -30,6 +35,7 @@
return ''
def get_python(self):
+ """Prova"""
if self.value:
if self.special:
return '%s=True' % self.name
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/module.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/module.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/module.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -68,7 +68,7 @@
class ParallelModuleQueue(object):
- """!This class is designed to run an arbitrary number of pygrass Module
+ """This class is designed to run an arbitrary number of pygrass Module
processes in parallel.
Objects of type grass.pygrass.modules.Module can be put into the
@@ -82,8 +82,6 @@
Usage:
- @code
-
>>> import copy
>>> import grass.pygrass.modules as pymod
>>> mapcalc_list = []
@@ -106,27 +104,27 @@
0
0
- @endcode
-
"""
def __init__(self, max_num_procs=1):
- """!Constructor
+ """Constructor
- @param max_num_procs The maximum number of Module processes that
- can be run in parallel
+ :param max_num_procs: The maximum number of Module processes that
+ can be run in parallel
+ :type max_num_procs: int
"""
self._num_procs = int(max_num_procs)
self._list = int(max_num_procs) * [None]
self._proc_count = 0
def put(self, module):
- """!Put the next Module object in the queue
+ """Put the next Module object in the queue
To run the Module objects in parallel the run_ and finish_ options
of the Module must be set to False.
- @param module A preconfigured Module object with run_ and finish_
- set to False
+ :param module: a preconfigured Module object with run_ and finish_
+ set to False
+ :type module: Module object
"""
self._list[self._proc_count] = module
self._list[self._proc_count].run()
@@ -136,38 +134,43 @@
self.wait()
def get(self, num):
- """!Get a Module object from the queue
+ """Get a Module object from the queue
- @param num The number of the object in queue
- @return The Module object or None if num is not in the queue
+ :param num: the number of the object in queue
+ :type num: int
+ :returns: the Module object or None if num is not in the queue
"""
if num < self._num_procs:
return self._list[num]
return None
def get_num_run_procs(self):
- """!Get the number of Module processes that are in the queue running
+ """Get the number of Module processes that are in the queue running
or finished
- @return The maximum number fo Module processes running/finished in
- the queue
+ :returns: the maximum number fo Module processes running/finished in
+ the queue
"""
return len(self._list)
def get_max_num_procs(self):
- """!Return the maximum number of parallel Module processes
+ """Return the maximum number of parallel Module processes
"""
return self._num_procs
def set_max_num_procs(self, max_num_procs):
- """!Set the maximum number of Module processes that should run
- in parallel
+ """Set the maximum number of Module processes that should run
+ in parallel
+
+ :param max_num_procs: The maximum number of Module processes that
+ can be run in parallel
+ :type max_num_procs: int
"""
self._num_procs = int(max_num_procs)
self.wait()
def wait(self):
- """!Wait for all Module processes that are in the list to finish
+ """Wait for all Module processes that are in the list to finish
and set the modules stdout and stderr output options
"""
for proc in self._list:
@@ -185,24 +188,22 @@
class Module(object):
"""
-
Python allow developers to not specify all the arguments and
keyword arguments of a method or function.
- ::
def f(*args):
for arg in args:
print arg
- therefore if we call the function like: ::
+ therefore if we call the function like:
>>> f('grass', 'gis', 'modules')
grass
gis
modules
- or we can define a new list: ::
+ or we can define a new list:
>>> words = ['grass', 'gis', 'modules']
>>> f(*words)
@@ -210,7 +211,7 @@
gis
modules
- we can do the same with keyword arguments, rewrite the above function: ::
+ we can do the same with keyword arguments, rewrite the above function:
def f(*args, **kargs):
for arg in args:
@@ -218,7 +219,7 @@
for key, value in kargs.items():
print "%s = %r" % (key, value)
- now we can use the new function, with: ::
+ now we can use the new function, with:
>>> f('grass', 'gis', 'modules', os = 'linux', language = 'python')
grass
@@ -228,7 +229,7 @@
language = 'python'
or, as before we can, define a dictionary and give the dictionary to
- the function, like: ::
+ the function, like:
>>> keywords = {'os' : 'linux', 'language' : 'python'}
>>> f(*words, **keywords)
@@ -376,11 +377,12 @@
raise ParameterError(msg % k)
return self.run()
-
def get_bash(self):
+ """Prova"""
return ' '.join(self.make_cmd())
def get_python(self):
+ """Prova"""
prefix = self.name.split('.')[0]
name = '_'.join(self.name.split('.')[1:])
params = ', '.join([par.get_python() for par in self.params_list
@@ -403,7 +405,7 @@
return "%s.%s(%s)" % (prefix, name, params)
def __str__(self):
- """!Return the command string that can be executed in a shell
+ """Return the command string that can be executed in a shell
"""
return ' '.join(self.make_cmd())
@@ -415,7 +417,7 @@
"""{cmd_name}({cmd_params})
"""
head = DOC['head'].format(cmd_name=self.name,
- cmd_params=('\n' + # go to a new line
+ cmd_params=('\n' + # go to a new line
# give space under the function name
(' ' * (len(self.name) + 1))).join([', '.join(
# transform each parameter in string
@@ -427,8 +429,8 @@
return '\n'.join([head, params, DOC['flag_head'], flags, DOC['foot']])
def get_dict(self):
- """!Return a dictionary that includes the name, all valid
- inputs, outputs and flags
+ """Return a dictionary that includes the name, all valid
+ inputs, outputs and flags
"""
dic = {}
dic['name'] = self.name
@@ -440,9 +442,9 @@
return dic
def make_cmd(self):
- """!Create the command string that can be executed in a shell
+ """Create the command string that can be executed in a shell
- @return The command string
+ :returns: the command string
"""
skip = ['stdin', 'stdout', 'stderr']
args = [self.name, ]
@@ -458,15 +460,17 @@
return args
def run(self, node=None):
- """!Run the module
+ """Run the module
- This function will wait for the process to terminate
- in case finish_==True and sets up stdout and stderr.
- If finish_==False this function will return after starting
- the process. Use self.popen.communicate() of self.popen.wait()
- to wait for the process termination. The handling
- of stdout and stderr must then be done outside of this
- function.
+ :param node:
+ :type node:
+
+ This function will wait for the process to terminate in case
+ finish_==True and sets up stdout and stderr. If finish_==False this
+ function will return after starting the process. Use
+ self.popen.communicate() of self.popen.wait() to wait for the process
+ termination. The handling of stdout and stderr must then be done
+ outside of this function.
"""
if self.inputs['stdin'].value:
self.stdin = self.inputs['stdin'].value
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/parameter.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/parameter.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/interface/parameter.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -12,8 +12,12 @@
from grass.pygrass.modules.interface.read import GETTYPE, element2dict, DOC
+# TODO add documentation
class Parameter(object):
+ """The Parameter object store all information about a parameter of module.
+ It is possible to set parameter of command using this object.
+ """
def __init__(self, xparameter=None, diz=None):
self._value = None
diz = element2dict(xparameter) if xparameter is not None else diz
@@ -79,7 +83,7 @@
# gisprompt
#
if 'gisprompt' in diz:
- self.typedesc = diz['gisprompt']['prompt']
+ self.typedesc = diz['gisprompt'].get('prompt', '')
self.input = False if diz['gisprompt']['age'] == 'new' else True
else:
self.input = True
@@ -138,9 +142,11 @@
# here the property function is used to transform value in an attribute
# in this case we define which function must be use to get/set the value
- value = property(fget=_get_value, fset=_set_value)
+ value = property(fget=_get_value, fset=_set_value,
+ doc="Set or obtain value")
def get_bash(self):
+ """Prova"""
if isinstance(self._value, list) or isinstance(self._value, tuple):
value = ','.join([str(v) for v in self._value])
else:
@@ -148,6 +154,7 @@
return """%s=%s""" % (self.name, value)
def get_python(self):
+ """Prova"""
if not self.value:
return ''
return """%s=%r""" % (self.name, self._value)
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/modules/shortcuts.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/modules/shortcuts.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/modules/shortcuts.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -50,7 +50,7 @@
return self.cls('%s.%s' % (self.prefix, name.replace('_', '.')))
-# http://grass.osgeo.org/grass70/manuals/full_index.html
+# http://grass.osgeo.org/grass71/manuals/full_index.html
#[ d.* | db.* | g.* | i.* | m.* | ps.* | r.* | r3.* | t.* | v.* ]
#
# d.* display commands
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/pygrasslib.dox
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/pygrasslib.dox 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/pygrasslib.dox 2014-06-21 09:34:04 UTC (rev 60913)
@@ -4,13 +4,14 @@
\section pygrassIntro Introduction
-PyGRASS improves integration between GRASS and Python (see also \ref
-pythonlib), make the use of Python under GRASS more consistent with
-the language itself and make the GRASS scripting and programming
-activity easier and more natural to the final users.
+PyGRASS improves the integration between GRASS GIS and Python (see
+also \ref pythonlib), making the use of Python under GRASS more
+consistent with the language itself. Furthermore, it simplifies
+GRASS scripting and programming and more natural for the user.
\section pygrassPackages PyGRASS packages
+The following PyGRASS packages are provided:
- \subpage pygrassGis
- \subpage pygrassRaster
- \subpage pygrassVector
@@ -18,19 +19,21 @@
- \subpage pygrassFunctions
- \subpage pygrassMessages
- \subpage pygrassErrors
+
+ Below these packages are illustrated in greater detail.
\subsection pygrassGis GIS Package
- python::pygrass::gis
-Basic elements of GRASS data-base:
+Basic elements of the GRASS data-base:
- python::pygrass::gis::Gisdbase
- python::pygrass::gis::Location
- python::pygrass::gis::Mapset
- python::pygrass::gis::VisibleMapset
-Computation region:
+Computational region:
- python::pygrass::gis::region::Region
@@ -41,6 +44,16 @@
\subsection pygrassRaster Raster Package
+PyGRASS uses 4 different Raster classes, that respect the 4
+different approaches of GRASS-C API. The read access is row wise for
+RastRow and RasterRowIO and additionally cached in the RowIO class.
+Both classes write sequentially. RowIO is row cached, RastSegment
+and RasterNumpy are tile cached for reading and writing therefore a
+randomly access is possible. Hence RasterRow and RasterRowIO should
+be used in case for fast (cached) row read access and RasterRow for
+fast sequential writing. Segment and Numpy should be used for random
+access, but Numpy only for files not larger than 2GB.
+
- python::pygrass::raster
Reading/writing raster maps:
@@ -101,8 +114,12 @@
- python::pygrass::vector::geometry::Isles
- python::pygrass::vector::geometry::Area
-\subsection pygrassModule Interface to GRASS modules
+Vector attribute handling:
+ - python::pygrass::vector::attributes
+
+\subsection pygrassModule Interface to GRASS GIS modules
+
- python::pygrass::modules
List of high-level classes:
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/raster/__init__.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/raster/__init__.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/raster/__init__.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -56,7 +56,6 @@
Examples
--------
- ::
>>> elev = RasterRow('elevation')
>>> elev.exist()
True
@@ -91,7 +90,7 @@
Open a raster map using the *with statement*: ::
- >>> with RasterRow('elevation') as elev:
+ >>> with RasterRow('elevation') as elev:
... for row in elev[:3]:
... row[:4]
...
@@ -111,6 +110,11 @@
"""Private method that return the row using the read mode
call the `Rast_get_row` C function.
+ :param row: the number of row to obtain
+ :type row: int
+ :param row_buffer: specify the Buffer object that will be instantiate
+ :type row_buffer: bool
+
>>> elev = RasterRow('elevation')
>>> elev.open()
>>> elev[0] # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
@@ -129,24 +133,26 @@
@must_be_open
def put_row(self, row):
"""Private method to write the row sequentially.
+
+ :param row: a Row object to insert into raster
+ :type row: Buffer object
"""
libraster.Rast_put_row(self._fd, row.p, self._gtype)
def open(self, mode=None, mtype=None, overwrite=None):
"""Open the raster if exist or created a new one.
- Parameters
- ------------
+ :param mode: Specify if the map will be open with read or write mode
+ ('r', 'w')
+ :type mode: str
+ :param type: If a new map is open, specify the type of the map(`CELL`,
+ `FCELL`, `DCELL`)
+ :type type: str
+ :param overwrite: Use this flag to set the overwrite mode of existing
+ raster maps
+ :type overwrite: bool
- mode: string
- Specify if the map will be open with read or write mode ('r', 'w')
- type: string
- If a new map is open, specify the type of the map(`CELL`, `FCELL`,
- `DCELL`)
- overwrite: Boolean
- Use this flag to set the overwrite mode of existing raster maps
-
if the map already exist, automatically check the type and set:
* self.mtype
@@ -203,11 +209,24 @@
super(RasterRowIO, self).__init__(name, *args, **kargs)
def open(self, mode=None, mtype=None, overwrite=False):
+ """Open the raster if exist or created a new one.
+
+ :param mode: specify if the map will be open with read or write mode
+ ('r', 'w')
+ :type mode: str
+ :param type: if a new map is open, specify the type of the map(`CELL`,
+ `FCELL`, `DCELL`)
+ :type type: str
+ :param overwrite: use this flag to set the overwrite mode of existing
+ raster maps
+ :type overwrite: bool
+ """
super(RasterRowIO, self).open(mode, mtype, overwrite)
self.rowio.open(self._fd, self._rows, self._cols, self.mtype)
@must_be_open
def close(self):
+ """Function to close the raster"""
self.rowio.release()
libraster.Rast_close(self._fd)
# update rows and cols attributes
@@ -222,6 +241,10 @@
* the read mode and
* `rowcache` method
+ :param row: the number of row to obtain
+ :type row: int
+ :param row_buffer: Specify the Buffer object that will be instantiate
+ :type row_buffer: Buffer object
"""
if row_buffer is None:
row_buffer = Buffer((self._cols,), self.mtype)
@@ -260,7 +283,8 @@
raise ValueError(str_err.format(mode))
self._mode = mode
- mode = property(fget=_get_mode, fset=_set_mode)
+ mode = property(fget=_get_mode, fset=_set_mode,
+ doc="Set or obtain the opening mode of raster")
def __setitem__(self, key, row):
"""Return the row of Raster object, slice allowed."""
@@ -303,13 +327,10 @@
def get_row(self, row, row_buffer=None):
"""Return the row using the `segment.get_row` method
- Parameters
- ------------
-
- row: integer
- Specify the row number;
- row_buffer: Buffer object, optional
- Specify the Buffer object that will be instantiate.
+ :param row: specify the row number
+ :type row: int
+ :param row_buffer: specify the Buffer object that will be instantiate
+ :type row_buffer: Buffer object
"""
if row_buffer is None:
row_buffer = Buffer((self._cols), self.mtype)
@@ -319,13 +340,8 @@
def put_row(self, row, row_buffer):
"""Write the row using the `segment.put_row` method
- Parameters
- ------------
-
- row: integer
- Specify the row number;
- row_buffer: Buffer object
- Specify the Buffer object that will be write to the map.
+ :param row: a Row object to insert into raster
+ :type row: Buffer object
"""
self.segment.put_row(row, row_buffer)
@@ -333,13 +349,10 @@
def get(self, row, col):
"""Return the map value using the `segment.get` method
- Parameters
- ------------
-
- row: integer
- Specify the row number;
- col: integer
- Specify the column number.
+ :param row: Specify the row number
+ :type row: int
+ :param col: Specify the column number
+ :type col: int
"""
return self.segment.get(row, col)
@@ -347,15 +360,12 @@
def put(self, row, col, val):
"""Write the value to the map using the `segment.put` method
- Parameters
- ------------
-
- row: integer
- Specify the row number;
- col: integer
- Specify the column number.
- val: value
- Specify the value that will be write to the map cell.
+ :param row: Specify the row number
+ :type row: int
+ :param col: Specify the column number
+ :type col: int
+ :param val: Specify the value that will be write to the map cell
+ :type val: value
"""
self.segment.val.value = val
self.segment.put(row, col)
@@ -365,16 +375,15 @@
and copy the map to the segment files;
else, open a new segment map.
- Parameters
- ------------
-
- mode: string, optional
- Specify if the map will be open with read, write or read/write
- mode ('r', 'w', 'rw')
- mtype: string, optional
- Specify the map type, valid only for new maps: CELL, FCELL, DCELL;
- overwrite: Boolean, optional
- Use this flag to set the overwrite mode of existing raster maps
+ :param mode: specify if the map will be open with read, write or
+ read/write mode ('r', 'w', 'rw')
+ :type mode: str
+ :param mtype: specify the map type, valid only for new maps: CELL,
+ FCELL, DCELL
+ :type mtype: str
+ :param overwrite: use this flag to set the overwrite mode of existing
+ raster maps
+ :type overwrite: bool
"""
# read rows and cols from the active region
self._rows = libraster.Rast_window_rows()
@@ -433,11 +442,8 @@
def close(self, rm_temp_files=True):
"""Close the map, copy the segment files to the map.
- Parameters
- ------------
-
- rm_temp_files: bool
- If True all the segments file will be removed.
+ :param rm_temp_files: if True all the segments file will be removed
+ :type rm_temp_files: bool
"""
if self.mode == "w" or self.mode == "rw":
self.segment.flush()
@@ -537,7 +543,8 @@
raise ValueError(_("Mode type: {0} not supported.").format(mode))
self._mode = mode
- mode = property(fget=_get_mode, fset=_set_mode)
+ mode = property(fget=_get_mode, fset=_set_mode,
+ doc="Set or obtain the opening mode of raster")
def __array_wrap__(self, out_arr, context=None):
"""See:
@@ -584,10 +591,9 @@
self[i] = rst.get_row(i, buff)
def _write(self):
+ """Write the numpy array into map
"""
- r.in.bin input=/home/pietro/docdat/phd/thesis/gis/north_carolina/user1/.tmp/eraclito/14325.0 output=new title='' bytes=1,anull='' --verbose --overwrite north=228500.0 south=215000.0 east=645000.0 west=630000.0 rows=1350 cols=1500
-
- """
+ #r.in.bin input=/home/pietro/docdat/phd/thesis/gis/north_carolina/user1/.tmp/eraclito/14325.0 output=new title='' bytes=1,anull='' --verbose --overwrite north=228500.0 south=215000.0 east=645000.0 west=630000.0 rows=1350 cols=1500
if not self.exist() or self.mode != 'r':
self.flush()
buff = Buffer(self[0].shape, mtype=self.mtype)
@@ -602,11 +608,14 @@
and copy the map to the segment files;
else, open a new segment map.
- Parameters
- ------------
-
- mtype: string, optional
- Specify the map type, valid only for new maps: CELL, FCELL, DCELL;
+ :param mtype: specify the map type, valid only for new maps: CELL,
+ FCELL, DCELL;
+ :type mtype: str
+ :param null:
+ :type null:
+ :param overwrite: use this flag to set the overwrite mode of existing
+ raster maps
+ :type overwrite: bool
"""
if overwrite is not None:
self.overwrite = overwrite
@@ -627,6 +636,11 @@
self._fd = 1
def close(self, name=''):
+ """Function to close the map
+
+ :param name: the name of raster
+ :type name: str
+ """
if self.is_open():
name = name if name else self.name
if not name:
@@ -639,10 +653,10 @@
def get_value(self, point, region=None):
"""This method returns the pixel value of a given pair of coordinates:
- Parameters
- ------------
-
- point = pair of coordinates in tuple object
+ :param point: pair of coordinates in tuple object
+ :type point: tuple
+ :param region: the region to crop the request
+ :type region: Region object
"""
if not region:
region = Region()
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/raster/category.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/raster/category.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/raster/category.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -80,11 +80,12 @@
def _set_mtype(self, mtype):
if mtype.upper() not in ('CELL', 'FCELL', 'DCELL'):
#fatal(_("Raser type: {0} not supported".format(mtype) ) )
- raise ValueError(_("Raser type: {0} not supported".format(mtype)))
+ raise ValueError(_("Raster type: {0} not supported".format(mtype)))
self._mtype = mtype
self._gtype = RTYPE[self.mtype]['grass type']
- mtype = property(fget=_get_mtype, fset=_set_mtype)
+ mtype = property(fget=_get_mtype, fset=_set_mtype,
+ doc="Set or obtain raster data type")
def _get_title(self):
return libraster.Rast_get_cats_title(ctypes.byref(self.c_cats))
@@ -93,7 +94,8 @@
return libraster.Rast_set_cats_title(newtitle,
ctypes.byref(self.c_cats))
- title = property(fget=_get_title, fset=_set_title)
+ title = property(fget=_get_title, fset=_set_title,
+ doc="Set or obtain raster title")
def __str__(self):
return self.__repr__()
@@ -266,7 +268,11 @@
libraster.Rast_write_cats(self.name, ctypes.byref(self.c_cats))
def copy(self, category):
- """Copy from another Category class"""
+ """Copy from another Category class
+
+ :param category: Category class to be copied
+ :type category: Category object
+ """
libraster.Rast_copy_cats(ctypes.byref(self.c_cats), # to
ctypes.byref(category._cats)) # from
self._read_cats()
@@ -293,7 +299,12 @@
0.5:1.0:road
1.0:1.5:urban
- .."""
+ :param filename: the name of file with categories rules
+ :type filename: str
+ :param sep: the separator used to divide values and category
+ :type sep: str
+ ..
+ """
self.reset()
with open(filename, 'r') as f:
for row in f.readlines():
@@ -320,7 +331,12 @@
0.5:1.0:road
1.0:1.5:urban
- .."""
+ :param filename: the name of file with categories rules
+ :type filename: str
+ :param sep: the separator used to divide values and category
+ :type sep: str
+ ..
+ """
with open(filename, 'w') as f:
cats = []
for cat in self.__iter__():
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/raster/history.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/raster/history.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/raster/history.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -10,31 +10,29 @@
class History(object):
- """
- *Examples*
+ """History class help to manage all the metadata of a raster map
- ::
- >>> import grass.lib.gis as libgis
- >>> libgis.G_gisinit('')
- >>> hist = History('elevation')
- >>> hist.creator
- 'helena'
- >>> hist.src1
- ''
- >>> hist.src2
- ''
- >>> hist.keyword
- 'generated by r.proj'
- >>> hist.date
- datetime.datetime(2006, 11, 7, 1, 9, 51)
- >>> hist.mapset
- 'PERMANENT'
- >>> hist.maptype
- 'raster'
- >>> hist.title
- 'elev_ned10m'
+ >>> import grass.lib.gis as libgis
+ >>> libgis.G_gisinit('')
+ >>> hist = History('elevation')
+ >>> hist.read()
+ >>> hist.creator
+ 'helena'
+ >>> hist.src1
+ ''
+ >>> hist.src2
+ ''
+ >>> hist.keyword
+ 'generated by r.proj'
+ >>> hist.date
+ datetime.datetime(2006, 11, 7, 1, 9, 51)
+ >>> hist.mapset
+ 'PERMANENT'
+ >>> hist.maptype
+ 'raster'
+ >>> hist.title
+ 'elev_ned10m'
- ..
"""
def __init__(self, name, mapset='', mtype='',
creator='', src1='', src2='', keyword='',
@@ -76,7 +74,8 @@
libraster.HIST_CREATOR,
ctypes.c_char_p(creator))
- creator = property(fget=_get_creator, fset=_set_creator)
+ creator = property(fget=_get_creator, fset=_set_creator,
+ doc="Set or obtain the creator of map")
#----------------------------------------------------------------------
#libraster.HIST_DATSRC_1
@@ -89,7 +88,8 @@
libraster.HIST_DATSRC_1,
ctypes.c_char_p(src1))
- src1 = property(fget=_get_src1, fset=_set_src1)
+ src1 = property(fget=_get_src1, fset=_set_src1,
+ doc="Set or obtain the first source of map")
#----------------------------------------------------------------------
#libraster.HIST_DATSRC_2
@@ -102,7 +102,8 @@
libraster.HIST_DATSRC_2,
ctypes.c_char_p(src2))
- src2 = property(fget=_get_src2, fset=_set_src2)
+ src2 = property(fget=_get_src2, fset=_set_src2,
+ doc="Set or obtain the second source of map")
#----------------------------------------------------------------------
#libraster.HIST_KEYWORD
@@ -115,7 +116,8 @@
libraster.HIST_KEYWRD,
ctypes.c_char_p(keyword))
- keyword = property(fget=_get_keyword, fset=_set_keyword)
+ keyword = property(fget=_get_keyword, fset=_set_keyword,
+ doc="Set or obtain the keywords of map")
#----------------------------------------------------------------------
#libraster.HIST_MAPID
@@ -132,7 +134,8 @@
libraster.HIST_MAPID,
ctypes.c_char_p(date_str))
- date = property(fget=_get_date, fset=_set_date)
+ date = property(fget=_get_date, fset=_set_date,
+ doc="Set or obtain the date of map")
#----------------------------------------------------------------------
#libraster.HIST_MAPSET
@@ -145,7 +148,8 @@
libraster.HIST_MAPSET,
ctypes.c_char_p(mapset))
- mapset = property(fget=_get_mapset, fset=_set_mapset)
+ mapset = property(fget=_get_mapset, fset=_set_mapset,
+ doc="Set or obtain the mapset of map")
#----------------------------------------------------------------------
#libraster.HIST_MAPTYPE
@@ -158,7 +162,8 @@
libraster.HIST_MAPTYPE,
ctypes.c_char_p(maptype))
- maptype = property(fget=_get_maptype, fset=_set_maptype)
+ maptype = property(fget=_get_maptype, fset=_set_maptype,
+ doc="Set or obtain the type of map")
#----------------------------------------------------------------------
#libraster.HIST_NUM_FIELDS
@@ -186,7 +191,8 @@
libraster.HIST_TITLE,
ctypes.c_char_p(title))
- title = property(fget=_get_title, fset=_set_title)
+ title = property(fget=_get_title, fset=_set_title,
+ doc="Set or obtain the title of map")
def append(self, obj):
"""Rast_append_history"""
@@ -200,7 +206,7 @@
*args)
def clear(self):
- """Rast_clear_history"""
+ """Clear the history"""
libraster.Rast_clear_history(self.c_hist)
def command(self):
@@ -224,7 +230,8 @@
ctypes.c_int(line))
def read(self):
- """Rast_read_history. ::
+ """Read the history of map, users need to use this function to
+ obtain all the information of map. ::
>>> import grass.lib.gis as libgis
>>> libgis.G_gisinit('')
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/__init__.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/__init__.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/__init__.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -40,7 +40,7 @@
#=============================================
class Vector(Info):
- """ ::
+ """Vector class is the grass vector format without topology
>>> from grass.pygrass.vector import Vector
>>> cens = Vector('census')
@@ -55,7 +55,6 @@
>>> cens.overwrite
False
- ..
"""
def __init__(self, name, mapset='', *args, **kwargs):
# Set map name and mapset
@@ -99,10 +98,12 @@
..
"""
- return read_next_line(self.c_mapinfo, self.table, self.writable)
+ return read_next_line(self.c_mapinfo, self.table, self.writable,
+ is2D=not self.is_3D())
@must_be_open
def rewind(self):
+ """Rewind vector map to cause reads to start at beginning."""
if libvect.Vect_rewind(self.c_mapinfo) == -1:
raise GrassError("Vect_rewind raise an error.")
@@ -110,22 +111,18 @@
def write(self, geo_obj, attrs=None, set_cats=True):
"""Write geometry features and attributes.
- Parameters
- ----------
+ :param geo_obj: a geometry grass object define in
+ grass.pygrass.vector.geometry
+ :type geo_obj: geometry GRASS object
+ :param attrs: a list with the values that will be insert in the
+ attribute table.
+ :type attrs: list
+ :param set_cats: if True, the category of the geometry feature is set
+ using the default layer of the vector map and a
+ progressive category value (default), otherwise the
+ c_cats attribute of the geometry object will be used.
+ :type set_cats: bool
- geo_obj : geometry GRASS object
- A geometry grass object define in grass.pygrass.vector.geometry.
- attrs: list, optional
- A list with the values that will be insert in the attribute table.
- set_cats, bool, optional
- If True, the category of the geometry feature is set using the
- default layer of the vector map and a progressive category value
- (default), otherwise the c_cats attribute of the geometry object
- will be used.
-
- Examples
- --------
-
Open a new vector map ::
>>> new = VectorTopo('newvect')
@@ -175,7 +172,6 @@
>>> new.close()
>>> new.remove()
- ..
"""
self.n_lines += 1
if self.table is not None and attrs:
@@ -208,8 +204,6 @@
"""Return if vector has color table associated in file system;
Color table stored in the vector's attribute table well be not checked
- Examples
- --------
>>> cens = Vector('census')
>>> cens.open()
>>> cens.has_color_table()
@@ -252,6 +246,7 @@
>>> schools.is_open()
False
+ ..
"""
def __init__(self, name, mapset='', *args, **kwargs):
super(VectorTopo, self).__init__(name, mapset, *args, **kwargs)
@@ -284,17 +279,21 @@
@must_be_open
def num_primitive_of(self, primitive):
- """Primitive are:
+ """Return the number of primitive
- * "boundary",
- * "centroid",
- * "face",
- * "kernel",
- * "line",
- * "point"
- * "area"
- * "volume"
+ :param primitive: the name of primitive to query; the supported values are:
+ * *boundary*,
+ * *centroid*,
+ * *face*,
+ * *kernel*,
+ * *line*,
+ * *point*
+ * *area*
+ * *volume*
+
+ :type primitive: str
+
::
>>> cens = VectorTopo('boundary_municp_sqlite')
@@ -316,11 +315,14 @@
@must_be_open
def number_of(self, vtype):
- """
- vtype in ["areas", "dblinks", "faces", "holes", "islands", "kernels",
- "line_points", "lines", "nodes", "update_lines",
- "update_nodes", "volumes"]
+ """Return the number of the choosen element type
+ :param vtype: the name of type to query; the supported values are:
+ *areas*, *dblinks*, *faces*, *holes*, *islands*,
+ *kernels*, *line_points*, *lines*, *nodes*,
+ *update_lines*, *update_nodes*, *volumes*
+ :type vtype: str
+
>>> cens = VectorTopo('boundary_municp_sqlite')
>>> cens.open()
>>> cens.number_of("areas")
@@ -365,7 +367,15 @@
def viter(self, vtype, idonly=False):
"""Return an iterator of vector features
- ::
+ :param vtype: the name of type to query; the supported values are:
+ *areas*, *dblinks*, *faces*, *holes*, *islands*,
+ *kernels*, *line_points*, *lines*, *nodes*,
+ *update_lines*, *update_nodes*, *volumes*
+ :type vtype: str
+ :param idonly: variable to return only the id of features instead of
+ full features
+ :type idonly: bool
+
>>> cens = VectorTopo('census')
>>> cens.open()
>>> big = [area for area in cens.viter('areas')
@@ -385,7 +395,6 @@
Area(2552) 298356117.948
>>> cens.close()
- ..
"""
if vtype in _GEOOBJ.keys():
if _GEOOBJ[vtype] is not None:
@@ -425,16 +434,15 @@
def cat(self, cat_id, vtype, layer=None, generator=False, geo=None):
"""Return the geometry features with category == cat_id.
- Parameters
- ----------
- cat_id : integer
- Integer with the category number.
- vtype : string
- String of the type of geometry feature that we are looking for.
- layer : integer, optional
- Integer of the layer that will be used.
- generator : bool, optional
- If True return a generator otherwise it return a list of features.
+ :param cat_id: the category number
+ :type cat_id: int
+ :param vtype: the type of geometry feature that we are looking for
+ :type vtype: str
+ :param layer: the layer number that will be used
+ :type layer: int
+ :param generator: if True return a generator otherwise it return a
+ list of features
+ :type generator: bool
"""
if geo is None and vtype not in _GEOOBJ:
keys = "', '".join(sorted(_GEOOBJ.keys()))
@@ -444,19 +452,26 @@
libvect.Vect_cidx_find_all(self.c_mapinfo,
layer if layer else self.layer,
Obj.gtype, cat_id, ilist.c_ilist)
+ is2D = not self.is_3D()
if generator:
return (read_line(feature_id=v_id, c_mapinfo=self.c_mapinfo,
- table=self.table, writable=self.writable)
+ table=self.table, writable=self.writable,
+ is2D=is2D)
for v_id in ilist)
else:
return [read_line(feature_id=v_id, c_mapinfo=self.c_mapinfo,
- table=self.table, writable=self.writable)
+ table=self.table, writable=self.writable,
+ is2D=is2D)
for v_id in ilist]
@must_be_open
def read(self, feature_id):
- """Return a geometry object given the feature id. ::
+ """Return a geometry object given the feature id.
+ :param feature_id: the id of feature to obtain
+ :type feature_id: int
+
+
>>> mun = VectorTopo('boundary_municp_sqlite')
>>> mun.open()
>>> feature1 = mun.read(0) #doctest: +ELLIPSIS
@@ -480,9 +495,9 @@
IndexError: Index out of range
>>> mun.close()
- ..
"""
- return read_line(feature_id, self.c_mapinfo, self.table, self.writable)
+ return read_line(feature_id, self.c_mapinfo, self.table, self.writable,
+ is2D=not self.is_3D())
@must_be_open
def is_empty(self):
@@ -504,7 +519,9 @@
attr = [line, ]
attr.extend(attrs)
self.table.update(key=line, values=attr)
-
+ elif self.table is None and attrs:
+ print "Table for vector {name} does not exist, attributes not" \
+ " loaded".format(name=self.name)
libvect.Vect_cat_set(geo_obj.c_cats, self.layer, line)
result = libvect.Vect_rewrite_line(self.c_mapinfo,
line, geo_obj.gtype,
@@ -518,6 +535,11 @@
@must_be_open
def delete(self, feature_id):
+ """Remove a feature by its id
+
+ :param feature_id: the id of the feature
+ :type feature_id: int
+ """
if libvect.Vect_rewrite_line(self.c_mapinfo, feature_id) == -1:
raise GrassError("C funtion: Vect_rewrite_line.")
@@ -541,8 +563,9 @@
@must_be_open
def select_by_bbox(self, bbox):
- """Return the BBox of the vecor map
+ """Return the BBox of the vector map
"""
+ # TODO replace with bbox if bbox else Bbox() ??
bbox = Bbox()
if libvect.Vect_get_map_box(self.c_mapinfo, bbox.c_bbox) == 0:
raise GrassError("I can not find the Bbox.")
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/abstract.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/abstract.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/abstract.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -77,7 +77,7 @@
>>> cens.close()
"""
- def __init__(self, name, mapset='', layer=None, mode='r'):
+ def __init__(self, name, mapset='', layer=None, mode='r', with_z=False):
self._name = ''
self._mapset = ''
# Set map name and mapset
@@ -90,6 +90,7 @@
self.date_fmt = '%a %b %d %H:%M:%S %Y'
self.layer = layer
self.mode = mode
+ self.with_z = with_z
def __enter__(self, *args, **kwargs):
self.open(*args, **kwargs)
@@ -111,18 +112,20 @@
self.rename(newname)
self._name = newname
- name = property(fget=_get_name, fset=_set_name)
+ name = property(fget=_get_name, fset=_set_name,
+ doc="Set or obtain the Vector name")
def _get_mapset(self):
- """Private method to obtain the Vector name"""
+ """Private method to obtain the Vector mapset"""
return self._mapset
def _set_mapset(self, mapset):
- """Private method to change the Vector name"""
+ """Private method to change the Vector mapset"""
if mapset:
self._mapset = mapset
- mapset = property(fget=_get_mapset, fset=_set_mapset)
+ mapset = property(fget=_get_mapset, fset=_set_mapset,
+ doc="Set or obtain the Vector mapset")
def _get_organization(self):
"""Private method to obtain the Vector organization"""
@@ -132,7 +135,8 @@
"""Private method to change the Vector organization"""
libvect.Vect_get_organization(self.c_mapinfo, ctypes.c_char_p(org))
- organization = property(fget=_get_organization, fset=_set_organization)
+ organization = property(fget=_get_organization, fset=_set_organization,
+ doc="Set or obtain the Vector organization")
def _get_date(self):
"""Private method to obtain the Vector date"""
@@ -142,7 +146,8 @@
"""Private method to change the Vector date"""
return libvect.Vect_set_date(self.c_mapinfo, ctypes.c_char_p(date))
- date = property(fget=_get_date, fset=_set_date)
+ date = property(fget=_get_date, fset=_set_date,
+ doc="Set or obtain the Vector date")
def _get_person(self):
"""Private method to obtain the Vector person"""
@@ -152,7 +157,8 @@
"""Private method to change the Vector person"""
libvect.Vect_set_person(self.c_mapinfo, ctypes.c_char_p(person))
- person = property(fget=_get_person, fset=_set_person)
+ person = property(fget=_get_person, fset=_set_person,
+ doc="Set or obtain the Vector author")
def _get_title(self):
"""Private method to obtain the Vector title"""
@@ -162,7 +168,8 @@
"""Private method to change the Vector title"""
libvect.Vect_set_map_name(self.c_mapinfo, ctypes.c_char_p(title))
- title = property(fget=_get_title, fset=_set_title)
+ title = property(fget=_get_title, fset=_set_title,
+ doc="Set or obtain the Vector title")
def _get_map_date(self):
"""Private method to obtain the Vector map date"""
@@ -174,7 +181,8 @@
date_str = datetimeobj.strftime(self.date_fmt)
libvect.Vect_set_map_date(self.c_mapinfo, ctypes.c_char_p(date_str))
- map_date = property(fget=_get_map_date, fset=_set_map_date)
+ map_date = property(fget=_get_map_date, fset=_set_map_date,
+ doc="Set or obtain the Vector map date")
def _get_scale(self):
"""Private method to obtain the Vector scale"""
@@ -184,7 +192,8 @@
"""Private method to set the Vector scale"""
return libvect.Vect_set_scale(self.c_mapinfo, ctypes.c_int(scale))
- scale = property(fget=_get_scale, fset=_set_scale)
+ scale = property(fget=_get_scale, fset=_set_scale,
+ doc="Set or obtain the Vector scale")
def _get_comment(self):
"""Private method to obtain the Vector comment"""
@@ -194,7 +203,8 @@
"""Private method to set the Vector comment"""
return libvect.Vect_set_comment(self.c_mapinfo, ctypes.c_char_p(comm))
- comment = property(fget=_get_comment, fset=_set_comment)
+ comment = property(fget=_get_comment, fset=_set_comment,
+ doc="Set or obtain the Vector comment")
def _get_zone(self):
"""Private method to obtain the Vector projection zone"""
@@ -204,7 +214,8 @@
"""Private method to set the Vector projection zone"""
return libvect.Vect_set_zone(self.c_mapinfo, ctypes.c_int(zone))
- zone = property(fget=_get_zone, fset=_set_zone)
+ zone = property(fget=_get_zone, fset=_set_zone,
+ doc="Set or obtain the Vector projection zone")
def _get_proj(self):
"""Private method to obtain the Vector projection code"""
@@ -214,7 +225,8 @@
"""Private method to set the Vector projection code"""
libvect.Vect_set_proj(self.c_mapinfo, ctypes.c_int(proj))
- proj = property(fget=_get_proj, fset=_set_proj)
+ proj = property(fget=_get_proj, fset=_set_proj,
+ doc="Set or obtain the Vector projection code")
def _get_thresh(self):
"""Private method to obtain the Vector threshold"""
@@ -224,7 +236,8 @@
"""Private method to set the Vector threshold"""
return libvect.Vect_set_thresh(self.c_mapinfo, ctypes.c_double(thresh))
- thresh = property(fget=_get_thresh, fset=_set_thresh)
+ thresh = property(fget=_get_thresh, fset=_set_thresh,
+ doc="Set or obtain the Vector threshold")
@property
@must_be_open
@@ -248,7 +261,11 @@
libvect.Vect_write_header(self.c_mapinfo)
def rename(self, newname):
- """Method to rename the Vector map"""
+ """Method to rename the Vector map
+
+ :param newname: the new name for the Vector map
+ :type newname: str
+ """
if self.exist():
if not self.is_open():
functions.rename(self.name, newname, 'vect')
@@ -275,43 +292,49 @@
"""Return if the Vector is open"""
return is_open(self.c_mapinfo)
- def open(self, mode=None, layer=1, overwrite=None,
+ def open(self, mode=None, layer=1, overwrite=None, with_z=None,
# parameters valid only if mode == 'w'
tab_name='', tab_cols=None, link_name=None, link_key='cat',
link_db='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db',
link_driver='sqlite'):
"""Open a Vector map.
- Parameters
- ----------
- mode : string
- Open a vector map in ``r`` in reading, ``w`` in writing and
- in ``rw`` read and write mode
- layer: int, optional
- Specify the layer that you want to use
+
+ :param mode: open a vector map in ``r`` in reading, ``w`` in writing
+ and in ``rw`` read and write mode
+ :type mode: str
+ :param layer: specify the layer that you want to use
+ :type layer: int
+ :param overwrite: valid only for ``w`` mode
+ :type overwrite: bool
+ :param with_z: specify if vector map must be open with third dimension
+ enabled or not. Valid only for ``w`` mode,
+ default: False
+ :type with_z: bool
+ :param tab_name: define the name of the table that will be generate
+ :type tab_name: str
+ :param tab_cols: define the name and type of the columns of the
+ attribute table of the vecto map
+ :type tab_cols: list of pairs
+ :param link_name: define the name of the link connecttion with the
+ database
+ :type link_name: str
+ :param link_key: define the nema of the column that will be use as
+ vector category
+ :type link_key: str
+ :param link_db: define the database connection parameters
+ :type link_db: str
+ :param link_driver: define witch database driver will be used
+ :param link_driver: str
- Some parameters are valid only if we open use the writing mode (``w``)
+ Some of the parameters are valid only with mode ``w`` or ``rw``
- overwrite: bool, optional
- valid only for ``w`` mode
- tab_name: string, optional
- Define the name of the table that will be generate
- tab_cols: list of pairs, optional
- Define the name and type of the columns of the attribute table
- of the vecto map
- link_name: string, optional
- Define the name of the link connecttion with the database
- link_key: string, optional
- Define the nema of the column that will be use as vector category
- link_db: string, optional
- Define the database connection parameters
- link_driver: string, optional
- Define witch database driver will be used
-
See more examples in the documentation of the ``read`` and ``write``
- methods.
+ methods
"""
self.mode = mode if mode else self.mode
+ self.with_z = self.with_z if with_z is None else with_z
+ with_z = libvect.WITH_Z if self.with_z else libvect.WITHOUT_Z
# check if map exists or not
if not self.exist() and self.mode != 'w':
raise OpenError("Map <%s> not found." % self._name)
@@ -339,8 +362,7 @@
# If it is opened in write mode
if self.mode == 'w':
- openvect = libvect.Vect_open_new(self.c_mapinfo, self.name,
- libvect.WITHOUT_Z)
+ openvect = libvect.Vect_open_new(self.c_mapinfo, self.name, with_z)
self.dblinks = DBlinks(self.c_mapinfo)
if tab_cols:
# create a link
@@ -377,7 +399,11 @@
self.writable), }
def close(self, build=False):
- """Method to close the Vector"""
+ """Method to close the Vector
+
+ :param build: True if the vector map should be build before close it
+ :type build: bool
+ """
if hasattr(self, 'table') and self.table is not None:
self.table.conn.close()
if self.is_open():
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/basic.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/basic.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/basic.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -55,7 +55,8 @@
"""Private method to set the north value"""
self.c_bbox.contents.N = value
- north = property(fget=_get_n, fset=_set_n)
+ north = property(fget=_get_n, fset=_set_n,
+ doc="Set and obtain north value")
def _get_s(self):
"""Private method to obtain the south value"""
@@ -65,7 +66,8 @@
"""Private method to set the south value"""
self.c_bbox.contents.S = value
- south = property(fget=_get_s, fset=_set_s)
+ south = property(fget=_get_s, fset=_set_s,
+ doc="Set and obtain south value")
def _get_e(self):
"""Private method to obtain the east value"""
@@ -75,7 +77,8 @@
"""Private method to set the east value"""
self.c_bbox.contents.E = value
- east = property(fget=_get_e, fset=_set_e)
+ east = property(fget=_get_e, fset=_set_e,
+ doc="Set and obtain east value")
def _get_w(self):
"""Private method to obtain the west value"""
@@ -85,7 +88,8 @@
"""Private method to set the west value"""
self.c_bbox.contents.W = value
- west = property(fget=_get_w, fset=_set_w)
+ west = property(fget=_get_w, fset=_set_w,
+ doc="Set and obtain west value")
def _get_t(self):
"""Private method to obtain the top value"""
@@ -95,7 +99,8 @@
"""Private method to set the top value"""
self.c_bbox.contents.T = value
- top = property(fget=_get_t, fset=_set_t)
+ top = property(fget=_get_t, fset=_set_t,
+ doc="Set and obtain top value")
def _get_b(self):
"""Private method to obtain the bottom value"""
@@ -105,7 +110,8 @@
"""Private method to set the bottom value"""
self.c_bbox.contents.B = value
- bottom = property(fget=_get_b, fset=_set_b)
+ bottom = property(fget=_get_b, fset=_set_b,
+ doc="Set and obtain bottom value")
def __repr__(self):
return "Bbox({n}, {s}, {e}, {w})".format(n=self.north, s=self.south,
@@ -119,15 +125,17 @@
return ['north', 'south', 'west', 'east', 'top', 'bottom']
def contains(self, point):
- """Return True if the object is contained by the BoundingBox. ::
+ """Return True if the object is contained by the BoundingBox
- >>> from grass.pygrass.vector.geometry import Point
- >>> poi = Point(5,5)
- >>> bbox = Bbox(north=10, south=0, west=0, east=10)
- >>> bbox.contains(poi)
- True
+ :param point: the point to analyze
+ :type point: a Point object or a tuple with the coordinates
- ..
+ >>> from grass.pygrass.vector.geometry import Point
+ >>> poi = Point(5,5)
+ >>> bbox = Bbox(north=10, south=0, west=0, east=10)
+ >>> bbox.contains(poi)
+ True
+
"""
return bool(libvect.Vect_point_in_box(point.x, point.y,
point.z if point.z else 0,
@@ -137,10 +145,12 @@
return [(k, self.__getattribute__(k)) for k in self.keys()]
def nsewtb(self, tb=True):
- """Return a list
+ """Return a list of values from bounding box
- If tb parameter is False return only:
- north, south, east, west
+ :param tb: if tb parameter is False return only: north, south, east,
+ west and not top and bottom
+ :type tb: bool
+
"""
if tb:
return (self.north, self.south, self.east, self.west,
@@ -193,21 +203,23 @@
def append(self, box):
"""Append a Bbox object to a Boxlist object, using the
- ``Vect_boxlist_append`` C fuction. ::
+ ``Vect_boxlist_append`` C fuction.
- >>> box0 = Bbox()
- >>> box1 = Bbox(1,2,3,4)
- >>> box2 = Bbox(5,6,7,8)
- >>> boxlist = BoxList([box0, box1])
- >>> boxlist
- Boxlist([Bbox(0.0, 0.0, 0.0, 0.0), Bbox(1.0, 2.0, 3.0, 4.0)])
- >>> len(boxlist)
- 2
- >>> boxlist.append(box2)
- >>> len(boxlist)
- 3
+ :param bbox: the bounding box to add to the list
+ :param bbox: a Bbox object
- ..
+ >>> box0 = Bbox()
+ >>> box1 = Bbox(1,2,3,4)
+ >>> box2 = Bbox(5,6,7,8)
+ >>> boxlist = BoxList([box0, box1])
+ >>> boxlist
+ Boxlist([Bbox(0.0, 0.0, 0.0, 0.0), Bbox(1.0, 2.0, 3.0, 4.0)])
+ >>> len(boxlist)
+ 2
+ >>> boxlist.append(box2)
+ >>> len(boxlist)
+ 3
+
"""
indx = self.__len__()
libvect.Vect_boxlist_append(self.c_boxlist, indx, box.c_bbox)
@@ -247,16 +259,18 @@
def remove(self, indx):
"""Remove Bbox from the boxlist, given an integer or a list of integer
or a boxlist, using ``Vect_boxlist_delete`` C function or the
- ``Vect_boxlist_delete_boxlist``. ::
+ ``Vect_boxlist_delete_boxlist``.
- >>> boxlist = BoxList([Bbox(),
- ... Bbox(1, 0, 0, 1),
- ... Bbox(1, -1, -1, 1)])
- >>> boxlist.remove(0)
- >>> boxlist
- Boxlist([Bbox(1.0, 0.0, 0.0, 1.0), Bbox(1.0, -1.0, -1.0, 1.0)])
+ :param indx: the index value of the Bbox to remove
+ :param indx: int
- ..
+ >>> boxlist = BoxList([Bbox(),
+ ... Bbox(1, 0, 0, 1),
+ ... Bbox(1, -1, -1, 1)])
+ >>> boxlist.remove(0)
+ >>> boxlist
+ Boxlist([Bbox(1.0, 0.0, 0.0, 1.0), Bbox(1.0, -1.0, -1.0, 1.0)])
+
"""
if hasattr(indx, 'c_boxlist'):
libvect.Vect_boxlist_delete_boxlist(self.c_boxlist, indx.c_boxlist)
@@ -268,18 +282,17 @@
def reset(self):
"""Reset the c_boxlist C struct, using the ``Vect_reset_boxlist`` C
- function. ::
+ function.
- >>> boxlist = BoxList([Bbox(),
- ... Bbox(1, 0, 0, 1),
- ... Bbox(1, -1, -1, 1)])
- >>> len(boxlist)
- 3
- >>> boxlist.reset()
- >>> len(boxlist)
- 0
+ >>> boxlist = BoxList([Bbox(),
+ ... Bbox(1, 0, 0, 1),
+ ... Bbox(1, -1, -1, 1)])
+ >>> len(boxlist)
+ 3
+ >>> boxlist.reset()
+ >>> len(boxlist)
+ 0
- ..
"""
libvect.Vect_reset_boxlist(self.c_boxlist)
@@ -335,7 +348,11 @@
def extend(self, ilist):
"""Extend the list with another Ilist object or
- with a list of integers"""
+ with a list of integers
+
+ :param ilist: the ilist to append
+ :type ilist: a Ilist object
+ """
if isinstance(ilist, Ilist):
libvect.Vect_list_append_list(self.c_ilist, ilist.ilist)
else:
@@ -416,19 +433,34 @@
def get(self, layer=1):
"""Return the first found category of given layer
- and the number of category found. """
+ and the number of category found.
+
+ :param layer: the number of layer
+ :type layer: int
+ """
cat = ctypes.c_int()
n_cats = libvect.Vect_cat_get(self.c_cats, layer, ctypes.byref(cat))
return cat.value, n_cats
def set(self, cat, layer=1):
- """Add new field/cat to category structure if doesn't exist yet."""
+ """Add new field/cat to category structure if doesn't exist yet.
+
+ :param cat: the cat to add
+ :type cat: int
+ :param layer: the number of layer
+ :type layer: int
+ """
libvect.Vect_cat_set(self.c_cats, layer, cat)
def delete(self, cat=None, layer=1):
"""If cat is given delete cat from line_cats structure
(using Vect_field_cat_del) else delete all categories of given layer
(using Vect_cat_del).
+
+ :param cat: the cat to add
+ :type cat: int
+ :param layer: the number of layer
+ :type layer: int
"""
if cat:
self.n_del = libvect.Vect_field_cat_del(self.c_cats, layer, cat)
@@ -441,12 +473,22 @@
raise ValueError(err_msg)
def check_cats_constraints(self, cats_list, layer=1):
- """Check if categories match with category constraints"""
+ """Check if categories match with category constraints
+
+ :param cats_list: a list of categories
+ :type cats_list: list
+ :param layer: the number of layer
+ :type layer: int
+ """
return bool(libvect.Vect_cats_in_constraint(self.c_cats, layer,
cats_list.c_cat_list))
def get_list(self, layer=1):
- """Get list of categories of given field."""
+ """Get list of categories of given field.
+
+ :param layer: the number of layer
+ :type layer: int
+ """
ilist = Ilist()
if libvect.Vect_field_cat_get(self.c_cats, layer,
ilist.c_ilist) < 0:
@@ -504,19 +546,30 @@
def from_string(self, string):
"""Converts string of categories and cat ranges separated by commas
- to cat_list."""
+ to cat_list.
+
+ :param string: a string containing the cats separated by commas
+ :type string: str
+ """
num_errors = libvect.Vect_str_to_cat_list(string, self.c_cat_list)
if num_errors:
from grass.pygrass.errors import GrassError
raise GrassError("%d number of errors in ranges" % num_errors)
def from_array(self, array):
- """Convert ordered array of integers to cat_list structure."""
+ """Convert ordered array of integers to cat_list structure.
+
+ :param array: the input array containing the cats
+ :type array: array
+ """
# Vect_array_to_cat_list(const int *vals, int nvals, ***)
# TODO: it's not working
libvect.Vect_array_to_cat_list(array, len(array), self.c_cat_list)
def __contains__(self, cat):
"""Check if category number is in list.
- int Vect_cat_in_cat_list (int cat, const struct cat_list *list)"""
+
+ :param cat: the category number
+ :type cat: int
+ """
return bool(libvect.Vect_cat_in_cat_list(cat, self.c_cat_list))
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/find.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/find.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/find.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -14,7 +14,10 @@
class AbstractFinder(object):
def __init__(self, c_mapinfo, table=None, writable=False):
- """Find geometry feature around a point.
+ """AbstractFinder
+ -----------------
+
+ Find geometry feature around a point.
"""
self.c_mapinfo = c_mapinfo
self.table = table
@@ -32,7 +35,9 @@
class PointFinder(AbstractFinder):
- """Find the geomtry features of a vector map that are close to a point. ::
+ """PointFinder
+ ------------------
+ Find the geomtry features of a vector map that are close to a point. ::
>>> from grass.pygrass.vector import VectorTopo
>>> zipcodes = VectorTopo('zipcodes', 'PERMANENT')
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/geometry.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/geometry.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/geometry.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -143,7 +143,8 @@
# update condition
self.cond = "%s=%d" % (self.table.key, value)
- cat = property(fget=_get_cat, fset=_set_cat)
+ cat = property(fget=_get_cat, fset=_set_cat,
+ doc="Set and obtain cat value")
def __getitem__(self, key):
"""Return the value stored in the attribute table. ::
@@ -342,7 +343,8 @@
def _set_x(self, value):
self.c_points.contents.x[0] = value
- x = property(fget=_get_x, fset=_set_x)
+ x = property(fget=_get_x, fset=_set_x,
+ doc="Set and obtain x coordinate")
def _get_y(self):
return self.c_points.contents.y[0]
@@ -350,7 +352,8 @@
def _set_y(self, value):
self.c_points.contents.y[0] = value
- y = property(fget=_get_y, fset=_set_y)
+ y = property(fget=_get_y, fset=_set_y,
+ doc="Set and obtain y coordinate")
def _get_z(self):
if self.is2D:
@@ -365,7 +368,8 @@
self.c_points.contents.z[0] = value
self.is2D = False
- z = property(fget=_get_z, fset=_set_z)
+ z = property(fget=_get_z, fset=_set_z,
+ doc="Set and obtain z coordinate")
def __str__(self):
return self.get_wkt()
@@ -429,8 +433,11 @@
def distance(self, pnt):
"""Calculate distance of 2 points, using the Vect_points_distance
C function, If one of the point have z == None, return the 2D distance.
- ::
+ :param pnt: the point for calculate the distance
+ :type pnt: a Point object or a tuple with the coordinates
+
+
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
@@ -441,8 +448,6 @@
>>> pnt0.distance(pnt1)
1.4142135623730951
- The distance method require a :class:Point or a tuple with
- the coordinates.
"""
if self.is2D or pnt.is2D:
return libvect.Vect_points_distance(self.x, self.y, 0,
@@ -456,40 +461,30 @@
"""Return the buffer area around the point, using the
``Vect_point_buffer2`` C function.
- Parameters
- ----------
- dist : numeric
- The distance around the line.
- dist_x: numeric, optional
- The distance along x
- dist_y: numeric, optional
- The distance along y
- angle: numeric, optional
- The angle between 0x and major axis
- round_: bool, optional
- To make corners round
- tol: float, optional
- Fix the maximum distance between theoretical arc
- and output segments
+ :param dist: the distance around the point
+ :type dist: num
+ :param dist_x: the distance along x
+ :type dist_x: num
+ :param dist_y: the distance along y
+ :type dist_y: num
+ :param angle: the angle between 0x and major axis
+ :type angle: num
+ :param round_: to make corners round
+ :type round_: bool
+ :param tol: fix the maximum distance between theoretical arc and
+ output segments
+ :type tol: float
+ :returns: the buffer as Area object
- Returns
- -------
- buffer : Area
- The buffer area around the line.
+ >>> pnt = Point(0, 0)
+ >>> area = pnt.buffer(10)
+ >>> area.boundary #doctest: +ELLIPSIS
+ Line([Point(10.000000, 0.000000),...Point(10.000000, 0.000000)])
+ >>> area.centroid
+ Point(0.000000, 0.000000)
+ >>> area.isles
+ []
- Example
- ---------
-
- ::
- >>> pnt = Point(0, 0)
- >>> area = pnt.buffer(10)
- >>> area.boundary #doctest: +ELLIPSIS
- Line([Point(10.000000, 0.000000),...Point(10.000000, 0.000000)])
- >>> area.centroid
- Point(0.000000, 0.000000)
- >>> area.isles
- []
-
"""
if dist is not None:
dist_x = dist
@@ -623,7 +618,10 @@
def append(self, pnt):
"""Appends one point to the end of a line, using the
- ``Vect_append_point`` C function. ::
+ ``Vect_append_point`` C function.
+
+ :param pnt: the point to add to line
+ :type pnt: a Point object or a tuple with the coordinates
>>> line = Line()
>>> line.append((10, 100))
@@ -656,12 +654,14 @@
def extend(self, line, forward=True):
"""Appends points to the end of a line.
- It is possible to extend a line, give a list of points, or directly
- with a line_pnts struct.
+ :param line: it is possible to extend a line, give a list of points,
+ or directly with a line_pnts struct.
+ :type line: Line object ot list of points
+ :param forward: if forward is True the line is extend forward otherwise
+ is extend backward. The method use the
+ `Vect_append_points` C function.
+ :type forward: bool
- If forward is True the line is extend forward otherwise is extend
- backward. The method use the `Vect_append_points` C function. ::
-
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line #doctest: +NORMALIZE_WHITESPACE
@@ -670,8 +670,6 @@
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
- Like python list, it is possible to extend a line, with another line
- or with a list of points.
"""
# set direction
if forward:
@@ -694,8 +692,13 @@
def insert(self, indx, pnt):
"""Insert new point at index position and move all old points at
that position and above up, using ``Vect_line_insert_point``
- C function. ::
+ C function.
+ :param indx: the index where add new point
+ :type indx: int
+ :param pnt: the point to add
+ :type pnt: a Point object
+
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line #doctest: +NORMALIZE_WHITESPACE
@@ -703,7 +706,6 @@
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
- ..
"""
if indx < 0: # Handle negative indices
indx += self.c_points.contents.n_points
@@ -737,7 +739,12 @@
return libvect.Vect_line_geodesic_length(self.c_points)
def distance(self, pnt):
- """Return a tuple with:
+ """Calculate the distance between line and a point.
+
+ :param pnt: the point to calculate distance
+ :type pnt: a Point object or a tuple with the coordinates
+
+ Return a tuple with:
* the closest point on the line,
* the distance between these two points,
@@ -746,15 +753,10 @@
The distance is compute using the ``Vect_line_distance`` C function.
- Example
- ---------
-
- ::
>>> line = Line([(0, 0), (0, 2)])
>>> line.distance(Point(1, 1))
(Point(0.000000, 1.000000), 1.0, 1.0, 1.0)
- ..
"""
# instantite outputs
cx = ctypes.c_double(0)
@@ -789,8 +791,11 @@
pass
def pop(self, indx):
- """Return the point in the index position and remove from the Line. ::
+ """Return the point in the index position and remove from the Line.
+ :param indx: the index where add new point
+ :type indx: int
+
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
@@ -798,7 +803,6 @@
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
- ..
"""
if indx < 0: # Handle negative indices
indx += self.c_points.contents.n_points
@@ -809,14 +813,15 @@
return pnt
def delete(self, indx):
- """Remove the point in the index position. ::
+ """Remove the point in the index position.
+ :param indx: the index where add new point
+ :type indx: int
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
- ..
"""
if indx < 0: # Handle negative indices
indx += self.c_points.contents.n_points
@@ -841,7 +846,10 @@
def prune_thresh(self, threshold):
"""Remove points in threshold, using the ``Vect_line_prune_thresh``
- C funtion. ::
+ C funtion.
+
+ :param threshold: the threshold value where prune points
+ :type threshold: num
>>> line = Line([(0, 0), (1.0, 1.0), (1.2, 0.9), (2, 2)])
>>> line.prune_thresh(0.5)
@@ -858,7 +866,10 @@
def remove(self, pnt):
"""Delete point at given index and move all points above down, using
- `Vect_line_delete_point` C function. ::
+ `Vect_line_delete_point` C function.
+
+ :param pnt: the point to remove
+ :type pnt: a Point object or a tuple with the coordinates
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
@@ -889,7 +900,9 @@
libvect.Vect_line_reverse(self.c_points)
def segment(self, start, end):
- """Create line segment. using the ``Vect_line_segment`` C function."""
+ # TODO improve documentation
+ """Create line segment. using the ``Vect_line_segment`` C function.
+ """
line = Line()
libvect.Vect_line_segment(self.c_points, start, end, line.c_points)
return line
@@ -933,8 +946,11 @@
for pnt in self.__iter__()])
def from_wkt(self, wkt):
- """Read a WKT string. ::
+ """Create a line reading a WKT string.
+ :param wkt: the WKT string containing the LINESTRING
+ :type wkt: str
+
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line #doctest: +NORMALIZE_WHITESPACE
@@ -966,42 +982,30 @@
"""Return the buffer area around the line, using the
``Vect_line_buffer2`` C function.
- Parameters
- ----------
- dist : numeric
- The distance around the line.
- dist_x: numeric, optional
- The distance along x
- dist_y: numeric, optional
- The distance along y
- angle: numeric, optional
- The angle between 0x and major axis
- round_: bool, optional
- To make corners round
- caps: bool, optional
- To add caps at line ends
- tol: float, optional
- Fix the maximum distance between theoretical arc
- and output segments
+ :param dist: the distance around the line
+ :type dist: num
+ :param dist_x: the distance along x
+ :type dist_x: num
+ :param dist_y: the distance along y
+ :type dist_y: num
+ :param angle: the angle between 0x and major axis
+ :type angle: num
+ :param round_: to make corners round
+ :type round_: bool
+ :param tol: fix the maximum distance between theoretical arc and
+ output segments
+ :type tol: float
+ :returns: the buffer as Area object
- Returns
- -------
- buffer : Area
- The buffer area around the line.
+ >>> line = Line([(0, 0), (0, 2)])
+ >>> area = line.buffer(10)
+ >>> area.boundary #doctest: +ELLIPSIS
+ Line([Point(-10.000000, 0.000000),...Point(-10.000000, 0.000000)])
+ >>> area.centroid
+ Point(0.000000, 0.000000)
+ >>> area.isles
+ []
- Example
- ---------
-
- ::
- >>> line = Line([(0, 0), (0, 2)])
- >>> area = line.buffer(10)
- >>> area.boundary #doctest: +ELLIPSIS
- Line([Point(-10.000000, 0.000000),...Point(-10.000000, 0.000000)])
- >>> area.centroid
- Point(0.000000, 0.000000)
- >>> area.isles
- []
-
..
"""
if dist is not None:
@@ -1080,9 +1084,19 @@
return cntr
def get_left_centroid(self, idonly=False):
+ """Return left value
+
+ :param idonly: True to return only the cat of feature
+ :type idonly: bool
+ """
return self._get_centroid(self.left_id, idonly)
def get_right_centroid(self, idonly=False):
+ """Return right value
+
+ :param idonly: True to return only the cat of feature
+ :type idonly: bool
+ """
return self._get_centroid(self.left_id, idonly)
def get_left_right(self):
@@ -1094,13 +1108,13 @@
def area(self):
"""Return the area of the polygon.
- ::
+
>>> bound = Boundary(points=[(0, 0), (0, 2), (2, 2), (2, 0),
... (0, 0)])
>>> bound.area()
4.0
- .."""
+ """
libgis.G_begin_polygon_area_calculations()
return libgis.G_area_of_polygon(self.c_points.contents.x,
self.c_points.contents.y,
@@ -1170,12 +1184,14 @@
return "Isle(%d)" % (self.id)
def boundaries(self):
+ """Return a list of boundaries"""
ilist = Ilist()
libvect.Vect_get_isle_boundaries(self.c_mapinfo, self.id,
ilist.c_ilist)
return ilist
def bbox(self, bbox=None):
+ """Return bounding box of Isle"""
bbox = bbox if bbox else Bbox()
libvect.Vect_get_isle_box(self.c_mapinfo, self.id, bbox.c_bbox)
return bbox
@@ -1200,7 +1216,11 @@
return bool(libvect.Vect_isle_alive(self.c_mapinfo, self.id))
def contain_pnt(self, pnt):
- """Check if point is in area."""
+ """Check if point is in area.
+
+ :param pnt: the point to remove
+ :type pnt: a Point object or a tuple with the coordinates
+ """
bbox = self.bbox()
return bool(libvect.Vect_point_in_island(pnt.x, pnt.y,
self.c_mapinfo, self.id,
@@ -1245,15 +1265,22 @@
return self._isles[key]
def get_isles_id(self):
+ """Return the id of isles"""
return [libvect.Vect_get_area_isle(self.c_mapinfo, self.area_id, i)
for i in range(self.__len__())]
def get_isles(self):
+ """Return isles"""
return [Isle(v_id=isle_id, c_mapinfo=self.c_mapinfo)
for isle_id in self._isles_id]
def select_by_bbox(self, bbox):
- """Vect_select_isles_by_box"""
+ """Vect_select_isles_by_box
+
+ .. warning::
+
+ Not implemented yet.
+ """
pass
@@ -1309,12 +1336,21 @@
self.get_isles()
def get_points(self, line=None):
- """Return a Line object with the outer ring"""
+ """Return a Line object with the outer ring
+
+ :param line: a Line object to fill with info from points of area
+ :type line: a Line object
+ """
line = Line() if line is None else line
libvect.Vect_get_area_points(self.c_mapinfo, self.id, line.c_points)
return line
def get_centroid(self, centroid=None):
+ """Return the centroid
+
+ :param centroid: a Centroid object to fill with info from centroid of area
+ :type centroid: a Centroid object
+ """
centroid_id = libvect.Vect_get_area_centroid(self.c_mapinfo, self.id)
if centroid:
centroid.id = centroid_id
@@ -1346,9 +1382,11 @@
return bool(libvect.Vect_area_alive(self.c_mapinfo, self.id))
def bbox(self, bbox=None):
+ """Return the Bbox of area
+
+ :param bbox: a Bbox object to fill with info from bounding box of area
+ :type bbox: a Bbox object
"""
- Vect_get_area_box
- """
bbox = bbox if bbox else Bbox()
libvect.Vect_get_area_box(self.c_mapinfo, self.id, bbox.c_bbox)
return bbox
@@ -1358,29 +1396,21 @@
"""Return the buffer area around the area, using the
``Vect_area_buffer2`` C function.
- Parameters
- ----------
- dist : numeric
- The distance around the line.
- dist_x: numeric, optional
- The distance along x
- dist_y: numeric, optional
- The distance along y
- angle: numeric, optional
- The angle between 0x and major axis
- round_: bool, optional
- To make corners round
- caps: bool, optional
- To add caps at line ends
- tol: float, optional
- Fix the maximum distance between theoretical arc
- and output segments
+ :param dist: the distance around the area
+ :type dist: num
+ :param dist_x: the distance along x
+ :type dist_x: num
+ :param dist_y: the distance along y
+ :type dist_y: num
+ :param angle: the angle between 0x and major axis
+ :type angle: num
+ :param round_: to make corners round
+ :type round_: bool
+ :param tol: fix the maximum distance between theoretical arc and
+ output segments
+ :type tol: float
+ :returns: the buffer as Area object
- Returns
- -------
- buffer : Area
- The buffer area around the line.
-
"""
if dist is not None:
dist_x = dist
@@ -1415,8 +1445,9 @@
def cats(self, cats=None):
"""Get area categories.
- int Vect_get_area_cats (const struct Map_info *Map,
- int area, struct line_cats *Cats)
+
+ :param cats: a Cats object to fill with info with area categories
+ :type cats: a Cats object
"""
cats = cats if cats else Cats()
libvect.Vect_get_area_cats(self.c_mapinfo, self.id, cats.c_cats)
@@ -1431,9 +1462,11 @@
def contain_pnt(self, pnt, bbox=None):
"""Check if point is in area.
- int Vect_point_in_area(double x, double y,
- const struct Map_info *Map,
- int area, struct bound_box box)
+
+ :param pnt: the point to analyze
+ :type pnt: a Point object or a tuple with the coordinates
+ :param bbox: the bounding box where run the analysis
+ :type bbox: a Bbox object
"""
bbox = bbox if bbox else self.bbox()
return bool(libvect.Vect_point_in_area(pnt.x, pnt.y,
@@ -1495,7 +1528,7 @@
def read_next_line(c_mapinfo, table=None, writable=False,
- c_points=None, c_cats=None):
+ c_points=None, c_cats=None, is2D=True):
"""Return the next geometry feature of a vector map."""
c_points = c_points if c_points else ctypes.pointer(libvect.line_pnts())
c_cats = c_cats if c_cats else ctypes.pointer(libvect.line_cats())
@@ -1503,7 +1536,7 @@
c_cats)
return GV_TYPE[ftype]['obj'](v_id=v_id, c_mapinfo=c_mapinfo,
c_points=c_points, c_cats=c_cats,
- table=table, writable=writable)
+ table=table, writable=writable, is2D=is2D)
def c_read_line(feature_id, c_mapinfo, c_points, c_cats):
@@ -1520,7 +1553,7 @@
def read_line(feature_id, c_mapinfo, table=None, writable=False,
- c_points=None, c_cats=None):
+ c_points=None, c_cats=None, is2D=True):
"""Return a geometry object given the feature id and the c_mapinfo.
"""
c_points = c_points if c_points else ctypes.pointer(libvect.line_pnts())
@@ -1530,7 +1563,7 @@
if GV_TYPE[ftype]['obj'] is not None:
return GV_TYPE[ftype]['obj'](v_id=feature_id, c_mapinfo=c_mapinfo,
c_points=c_points, c_cats=c_cats,
- table=table, writable=writable)
+ table=table, writable=writable, is2D=is2D)
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/sql.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/sql.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/sql.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -1,17 +1,12 @@
# -*- coding: utf-8 -*-
"""
-SQL
-===
+It is a collection of strings to avoid to repeat the code.
-It is a collection of strings to avoid to repeat the code. ::
-
>>> SELECT.format(cols=', '.join(['cat', 'area']), tname='table')
'SELECT cat, area FROM table;'
>>> SELECT_WHERE.format(cols=', '.join(['cat', 'area']),
... tname='table', condition='area>10000')
'SELECT cat, area FROM table WHERE area>10000;'
-
-
"""
#
Modified: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/table.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/table.py 2014-06-21 09:14:49 UTC (rev 60912)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/table.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -93,19 +93,32 @@
return self
def where(self, condition):
- """Create the where condition"""
+ """Create the where condition
+
+ :param condition: the condition of where statement, for example
+ `cat = 1`
+ :type condition: str
+ """
self._where = 'WHERE {condition}'.format(condition=condition)
return self
def order_by(self, orderby):
- """Create the order by condition"""
+ """Create the order by condition
+
+ :param orderby: the name of column/s to order the result
+ :type orderby: str
+ """
if not isinstance(orderby, unicode):
orderby = ', '.join(orderby)
self._orderby = 'ORDER BY {orderby}'.format(orderby=orderby)
return self
def limit(self, number):
- """Create the limit condition"""
+ """Create the limit condition
+
+ :param number: the number to limit the result
+ :type number: int
+ """
if not isinstance(number, int):
raise ValueError("Must be an integer.")
else:
@@ -113,7 +126,11 @@
return self
def group_by(self, groupby):
- """Create the group by condition"""
+ """Create the group by condition
+
+ :param groupby: the name of column/s to group the result
+ :type groupby: str, list
+ """
if not isinstance(groupby, unicode):
groupby = ', '.join(groupby)
self._groupby = 'GROUP BY {groupby}'.format(groupby=groupby)
@@ -347,8 +364,14 @@
return self.odict.items()
def add(self, col_name, col_type):
- """Add a new column to the table. ::
+ """Add a new column to the table.
+ :param col_name: the name of column to add
+ :type col_name: str
+ :param col_type: the tipe of column to add
+ :type col_type: str
+ ::
+
>>> import sqlite3
>>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
>>> from grass.pygrass.functions import copy, remove
@@ -369,6 +392,11 @@
..
"""
def check_col(col_type):
+ """Check the column type if it is supported by GRASS
+
+ :param col_type: the type of column
+ :type col_type: str
+ """
valid_type = ('DOUBLE PRECISION', 'DOUBLE', 'INT', 'INTEGER',
'DATE')
if 'VARCHAR' in col_type or col_type.upper() not in valid_type:
@@ -397,8 +425,14 @@
self.update_odict()
def rename(self, old_name, new_name):
- """Rename a column of the table. ::
+ """Rename a column of the table.
+ :param old_name: the name of existing column
+ :type old_name: str
+ :param new_name: the name of new column
+ :type new_name: str
+ ::
+
>>> import sqlite3
>>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
>>> from grass.pygrass.functions import copy, remove
@@ -447,8 +481,14 @@
self.drop(old_name)
def cast(self, col_name, new_type):
- """Change the column type. ::
+ """Change the column type.
+ :param col_name: the name of column
+ :type col_name: str
+ :param new_type: the new type of column
+ :type new_type: str
+ ::
+
>>> import sqlite3
>>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
>>> from grass.pygrass.functions import copy, remove
@@ -485,8 +525,12 @@
raise DBError('SQLite does not support to cast columns.')
def drop(self, col_name):
- """Drop a column from the table. ::
+ """Drop a column from the table.
+ :param col_name: the name of column to remove
+ :type col_name: str
+ ::
+
>>> import sqlite3
>>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
>>> from grass.pygrass.functions import copy, remove
@@ -582,7 +626,8 @@
raise TypeError("Number must be positive and greater than 0.")
self.c_fieldinfo.contents.number = number
- layer = property(fget=_get_layer, fset=_set_layer)
+ layer = property(fget=_get_layer, fset=_set_layer,
+ doc="Set and obtain layer number")
def _get_name(self):
return self.c_fieldinfo.contents.name
@@ -590,7 +635,8 @@
def _set_name(self, name):
self.c_fieldinfo.contents.name = name
- name = property(fget=_get_name, fset=_set_name)
+ name = property(fget=_get_name, fset=_set_name,
+ doc="Set and obtain name vale")
def _get_table(self):
return self.c_fieldinfo.contents.table
@@ -598,7 +644,8 @@
def _set_table(self, new_name):
self.c_fieldinfo.contents.table = new_name
- table_name = property(fget=_get_table, fset=_set_table)
+ table_name = property(fget=_get_table, fset=_set_table,
+ doc="Set and obtain table name value")
def _get_key(self):
return self.c_fieldinfo.contents.key
@@ -606,7 +653,8 @@
def _set_key(self, key):
self.c_fieldinfo.contents.key = key
- key = property(fget=_get_key, fset=_set_key)
+ key = property(fget=_get_key, fset=_set_key,
+ doc="Set and obtain cat value")
def _get_database(self):
return self.c_fieldinfo.contents.database
@@ -614,7 +662,8 @@
def _set_database(self, database):
self.c_fieldinfo.contents.database = database
- database = property(fget=_get_database, fset=_set_database)
+ database = property(fget=_get_database, fset=_set_database,
+ doc="Set and obtain database value")
def _get_driver(self):
return self.c_fieldinfo.contents.driver
@@ -625,7 +674,9 @@
raise TypeError(str_err)
self.c_fieldinfo.contents.driver = driver
- driver = property(fget=_get_driver, fset=_set_driver)
+ driver = property(fget=_get_driver, fset=_set_driver,
+ doc="Set and obtain driver value. The drivers supported \
+ by PyGRASS are: SQLite and PostgreSQL")
def __init__(self, layer=1, name=None, table=None, key='cat',
database='$GISDBASE/$LOCATION_NAME/'
@@ -777,7 +828,11 @@
return "DBlinks(%r)" % [link for link in self.__iter__()]
def by_index(self, indx):
- """Return a Link object by index"""
+ """Return a Link object by index
+
+ :param indx: the index where add new point
+ :type indx: int
+ """
nlinks = self.num_dblinks()
if nlinks == 0:
raise IndexError
@@ -789,33 +844,45 @@
return Link(c_fieldinfo=c_fieldinfo) if c_fieldinfo else None
def by_layer(self, layer):
+ """Return the choosen Link using the layer
+
+ :param layer: the number of layer
+ :type layer: int
+ """
c_fieldinfo = libvect.Vect_get_field(self.c_mapinfo, layer)
return Link(c_fieldinfo=c_fieldinfo) if c_fieldinfo else None
def by_name(self, name):
+ """Return the choosen Link using the name
+
+ :param name: the name of Link
+ :type name: str
+ """
c_fieldinfo = libvect.Vect_get_field_by_name(self.c_mapinfo, name)
return Link(c_fieldinfo=c_fieldinfo) if c_fieldinfo else None
def num_dblinks(self):
+ """Return the number of DBlinks"""
return libvect.Vect_get_num_dblinks(self.c_mapinfo)
def add(self, link):
- """Add a new link.
- Need to open vector map in write mode::
+ """Add a new link. Need to open vector map in write mode
- >>> from grass.pygrass.vector import VectorTopo
- >>> municip = VectorTopo('census')
- >>> municip.open()
- >>> dblinks = DBlinks(municip.c_mapinfo)
- >>> dblinks
- DBlinks([Link(1, census, sqlite)])
- >>> link = Link(2, 'pg_link', 'boundary_municp_pg', 'cat',
- ... 'host=localhost dbname=grassdb', 'pg') # doctest: +SKIP
- >>> dblinks.add(link) # doctest: +SKIP
- >>> dblinks # doctest: +SKIP
- DBlinks([Link(1, boundary_municp, sqlite)])
+ :param link: the Link to add to the DBlinks
+ :type link: a Link object
- ..
+ >>> from grass.pygrass.vector import VectorTopo
+ >>> municip = VectorTopo('census')
+ >>> municip.open()
+ >>> dblinks = DBlinks(municip.c_mapinfo)
+ >>> dblinks
+ DBlinks([Link(1, census, sqlite)])
+ >>> link = Link(2, 'pg_link', 'boundary_municp_pg', 'cat',
+ ... 'host=localhost dbname=grassdb', 'pg') # doctest: +SKIP
+ >>> dblinks.add(link) # doctest: +SKIP
+ >>> dblinks # doctest: +SKIP
+ DBlinks([Link(1, boundary_municp, sqlite)])
+
"""
#TODO: check if open in write mode or not.
libvect.Vect_map_add_dblink(self.c_mapinfo,
@@ -823,19 +890,25 @@
link.key, link.database, link.driver)
def remove(self, key, force=False):
- """Remove a link. If force set to true remove also the table ::
+ """Remove a link. If force set to true remove also the table
- >>> from grass.pygrass.vector import VectorTopo
- >>> municip = VectorTopo('census')
- >>> municip.open()
- >>> dblinks = DBlinks(municip.c_mapinfo)
- >>> dblinks
- DBlinks([Link(1, census, sqlite)])
- >>> dblinks.remove('pg_link') # doctest: +SKIP
- >>> dblinks # need to open vector map in write mode
- DBlinks([Link(1, census, sqlite)])
+ :param key: the key of Link
+ :type key: str
+ :param force: if True remove also the table from database otherwise
+ only the link between table and vector
+ :type force: boole
- ..
+ >>> from grass.pygrass.vector import VectorTopo
+ >>> municip = VectorTopo('census')
+ >>> municip.open()
+ >>> dblinks = DBlinks(municip.c_mapinfo)
+ >>> dblinks
+ DBlinks([Link(1, census, sqlite)])
+ >>> dblinks.remove('pg_link') # doctest: +SKIP
+ >>> dblinks # need to open vector map in write mode
+ DBlinks([Link(1, census, sqlite)])
+
+
"""
if force:
link = self.by_name(key)
@@ -875,7 +948,11 @@
return self._name
def _set_name(self, new_name):
- """Private method to set the name of table"""
+ """Private method to set the name of table
+
+ :param new_name: the new name of table
+ :type new_name: str
+ """
old_name = self._name
cur = self.conn.cursor()
cur.execute(sql.RENAME_TAB.format(old_name=old_name,
@@ -883,7 +960,8 @@
self.conn.commit()
cur.close()
- name = property(fget=_get_name, fset=_set_name)
+ name = property(fget=_get_name, fset=_set_name,
+ doc="Set and obtain table name")
def __init__(self, name, connection, key='cat'):
self._name = name
@@ -917,8 +995,16 @@
return self.n_rows()
def drop(self, cursor=None, force=False):
- """Private method to drop table from database"""
+ """Method to drop table from database
+ :param cursor: the cursor to connect, if None it use the cursor
+ of connection table object
+ :type cursor: Cursor object
+ :param force: True to remove the table, by default False to print
+ advice
+ :type force: bool
+ """
+
cur = cursor if cursor else self.conn.cursor()
if self.exist(cursor=cur):
used = db_table_in_vector(self.name)
@@ -950,19 +1036,29 @@
def execute(self, sql_code=None, cursor=None, many=False, values=None):
"""Execute SQL code from a given string or build with filters and
- return a cursor object. ::
+ return a cursor object.
- >>> import sqlite3
- >>> path = '$GISDBASE/$LOCATION_NAME/PERMANENT/sqlite/sqlite.db'
- >>> tab_sqlite = Table(name='census',
- ... connection=sqlite3.connect(get_path(path)))
- >>> tab_sqlite.filters.select('cat', 'TOTAL_POP').order_by('AREA')
- Filters(u'SELECT cat, TOTAL_POP FROM census ORDER BY AREA;')
- >>> cur = tab_sqlite.execute()
- >>> cur.fetchone()
- (1856, 0)
+ :param sql_code: the SQL code to execute, if not pass it use filters
+ variable
+ :type sql_code: str
+ :param cursor: the cursor to connect, if None it use the cursor
+ of connection table object
+ :type cursor: Cursor object
+ :param many: True to run executemany function
+ :type many: bool
+ :param values: The values to substitute into sql_code string
+ :type values: list of tuple
- ..
+ >>> import sqlite3
+ >>> path = '$GISDBASE/$LOCATION_NAME/PERMANENT/sqlite/sqlite.db'
+ >>> tab_sqlite = Table(name='census',
+ ... connection=sqlite3.connect(get_path(path)))
+ >>> tab_sqlite.filters.select('cat', 'TOTAL_POP').order_by('AREA')
+ Filters(u'SELECT cat, TOTAL_POP FROM census ORDER BY AREA;')
+ >>> cur = tab_sqlite.execute()
+ >>> cur.fetchone()
+ (1856, 0)
+
"""
try:
sqlc = sql_code if sql_code else self.filters.get_sql()
@@ -975,26 +1071,62 @@
raise ValueError("The SQL is not correct:\n%r" % sqlc)
def exist(self, cursor=None):
- """Return True if the table already exist in the DB, False otherwise"""
+ """Return True if the table already exist in the DB, False otherwise
+ :param cursor: the cursor to connect, if None it use the cursor
+ of connection table object
+ :type cursor: Cursor object
+ """
cur = cursor if cursor else self.conn.cursor()
return table_exist(cur, self.name)
def insert(self, values, cursor=None, many=False):
- """Insert a new row"""
+ """Insert a new row
+
+ :param values: a tuple of values to insert, it is possible to insert
+ more rows using a list of tuple and paramater `many`
+ :type values: tuple
+ :param cursor: the cursor to connect, if None it use the cursor
+ of connection table object
+ :type cursor: Cursor object
+ :param many: True to run executemany function
+ :type many: bool
+ """
cur = cursor if cursor else self.conn.cursor()
if many:
return cur.executemany(self.columns.insert_str, values)
return cur.execute(self.columns.insert_str, values)
def update(self, key, values, cursor=None, many=False):
- """Update a column for each row"""
+ """Update a column for each row
+
+ :param key: the name of column
+ :param values: the values to insert
+ :type values: str
+ :param cursor: the cursor to connect, if None it use the cursor
+ of connection table object
+ :type cursor: Cursor object
+ :param many: True to run executemany function
+ :type many: bool
+ """
cur = cursor if cursor else self.conn.cursor()
vals = list(values)
vals.append(key)
return cur.execute(self.columns.update_str, vals)
def create(self, cols, name=None, overwrite=False, cursor=None):
- """Create a new table"""
+ """Create a new table
+
+ :param cols:
+ :type cols:
+ :param name: the name of table to create, None for the name of Table object
+ :type name: str
+ :param overwrite: overwrite existing table
+ :type overwrite: bool
+ :param cursor: the cursor to connect, if None it use the cursor
+ of connection table object
+ :type cursor: Cursor object
+
+ """
cur = cursor if cursor else self.conn.cursor()
coldef = ',\n'.join(['%s %s' % col for col in cols])
if name:
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_geometry.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_geometry.py (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_geometry.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Thu Jun 19 14:13:53 2014
+
+ at author: pietro
+"""
+import sys
+import unittest
+import numpy as np
+
+import grass.lib.vector as libvect
+
+from grass.pygrass.vector.geometry import Point, Line
+
+
+class PointTestCase(unittest.TestCase):
+
+ def test_empty_init(self):
+ """Test Point()"""
+ point = Point()
+ self.assertEqual(point.gtype, libvect.GV_POINT)
+ self.assertEqual(point.x, 0)
+ self.assertEqual(point.y, 0)
+ self.assertIsNone(point.z)
+ self.assertTrue(point.is2D)
+
+ def test_init_3d(self):
+ """Test 3D Point(1, 2, 3)"""
+ point = Point(1, 2, 3)
+ self.assertEqual(point.x, 1)
+ self.assertEqual(point.y, 2)
+ self.assertEqual(point.z, 3)
+ self.assertFalse(point.is2D)
+
+ def test_switch_2D_3D_2D(self):
+ """Test switch between: 2D => 3D => 2D"""
+ point = Point()
+ self.assertIsNone(point.z)
+ self.assertTrue(point.is2D)
+ point.z = 1
+ self.assertFalse(point.is2D)
+ point.z = None
+ self.assertTrue(point.is2D, True)
+
+ def test_coords(self):
+ """Test coords method"""
+ self.assertEqual(Point(1, 2).coords(), (1, 2))
+ self.assertEqual(Point(1, 2, 3).coords(), (1, 2, 3))
+
+ def test_get_wkt(self):
+ """Test coords method"""
+ self.assertEqual(Point(1, 2).get_wkt(), 'POINT(1.000000 2.000000)')
+ self.assertEqual(Point(1, 2, 3).get_wkt(),
+ 'POINT(1.000000 2.000000 3.000000)')
+
+ def test_distance(self):
+ """Test distance method"""
+ point0 = Point(0, 0, 0)
+ point1 = Point(1, 0)
+ self.assertEqual(point0.distance(point1), 1.0)
+ point1.z = 1
+ self.assertAlmostEqual(point0.distance(point1), np.sqrt(2.))
+
+ def test_eq(self):
+ """Test __eq__"""
+ point0 = Point(0, 0)
+ point1 = Point(1, 0)
+ self.assertFalse(point0 == point1)
+ self.assertFalse(point0 == (1, 0))
+ self.assertTrue(point0 == point0)
+ self.assertTrue(point0 == (0, 0))
+
+ def test_repr(self):
+ """Test __eq__"""
+ self.assertEqual(repr(Point(1, 2)), 'Point(1.000000, 2.000000)')
+ self.assertEqual(repr(Point(1, 2, 3)),
+ 'Point(1.000000, 2.000000, 3.000000)')
+
+ @unittest.skip("Not implemented yet.")
+ def test_buffer(self):
+ """Test buffer method"""
+ # TODO: verify if the buffer depends from the mapset's projection
+ pass
+
+
+class LineTestCase(unittest.TestCase):
+
+ def test_len(self):
+ """Test __len__ magic method"""
+ self.assertEqual(len(Line()), 0)
+ self.assertEqual(len(Line([(0, 0), (1, 1)])), 2)
+
+ @unittest.skipIf(sys.version_info[:2] < (2, 7), "Require Python >= 2.7")
+ def test_getitem(self):
+ """Test __getitem__ magic method"""
+ line = Line([(0, 0), (1, 1), (2, 2), (3, 3), (4, 4)])
+ self.assertTupleEqual(line[0].coords(), (0, 0))
+ self.assertTupleEqual(line[1].coords(), (1, 1))
+ self.assertTupleEqual(line[-2].coords(), (3, 3))
+ self.assertTupleEqual(line[-1].coords(), (4, 4))
+ self.assertListEqual([p.coords() for p in line[:2]], [(0, 0), (1, 1)])
+ self.assertListEqual([p.coords() for p in line[::2]],
+ [(0, 0), (2, 2), (4, 4)])
+ with self.assertRaises(IndexError):
+ line[5]
+
+ @unittest.skipIf(sys.version_info[:2] < (2, 7), "Require Python >= 2.7")
+ def test_setitem(self):
+ """Test __setitem__ magic method"""
+ line = Line([(0, 0), (1, 1)])
+ self.assertTupleEqual(line[0].coords(), (0., 0.))
+ line[0] = (10, 10)
+ self.assertTupleEqual(line[0].coords(), (10., 10.))
+
+ @unittest.skipIf(sys.version_info[:2] < (2, 7), "Require Python >= 2.7")
+ def test_get_pnt(self):
+ """Test get_pnt method"""
+ line = Line([(0, 0), (1, 1)])
+ with self.assertRaises(ValueError):
+ line.get_pnt(5)
+ vals = (0.7071067811865475, 0.7071067811865475)
+ self.assertTupleEqual(line.get_pnt(1).coords(), vals)
+
+ def test_bbox(self):
+ line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
+ bbox = line.bbox()
+
+
+if __name__ == '__main__':
+ unittest.main()
Added: grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_vector3d.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_vector3d.py (rev 0)
+++ grass/branches/releasebranch_7_0/lib/python/pygrass/vector/testsuite/test_vector3d.py 2014-06-21 09:34:04 UTC (rev 60913)
@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Wed Jun 18 17:21:42 2014
+
+ at author: pietro
+"""
+import unittest
+import numpy as np
+
+from grass.script.core import run_command
+
+from grass.pygrass.vector import VectorTopo
+from grass.pygrass.vector.geometry import Point
+from grass.pygrass.gis.region import Region
+from grass.pygrass.functions import get_mapset_vector
+
+
+def generate_coordinates(number, bbox=None, with_z=False):
+ """Return 2 or 3 random arrays of coordinates"""
+ bbox = Region() if bbox is None else bbox
+ x = bbox.south + (bbox.north - bbox.south) * np.random.random(number)
+ y = bbox.west + (bbox.east - bbox.west) * np.random.random(number)
+ if with_z:
+ z = np.random.random(number) * 1000
+ return x, y, z
+ return x, y
+
+
+class VectorTopo3DTestCase(unittest.TestCase):
+
+ npoints = 10
+ tmpname = "tmp_vect3d"
+
+ @classmethod
+ def setUpClass(cls):
+ """Generate a number (NPOINTS) of random points"""
+ cls.x, cls.y, cls.z = generate_coordinates(cls.npoints, with_z=True)
+
+ def writing_points(self):
+ """Write the generated random points to a vector map"""
+ with VectorTopo(self.tmpname, mode="w", with_z=True) as vect:
+ for x, y, z in zip(self.x, self.y, self.z):
+ vect.write(Point(x, y, z))
+
+ def reading_points(self):
+ """Read the generated random points from a vector map"""
+ with VectorTopo(self.tmpname, mode="r") as vect:
+ # reading the generated vector points map
+ arr = np.array([(p.x, p.y, p.z) for p in vect])
+ # verify the correspondance
+ for i, coords in enumerate((self.x, self.y, self.z)):
+ np.testing.assert_almost_equal(arr.T[i], coords)
+
+ def test_writing_reading_points(self):
+ self.writing_points()
+ self.reading_points()
+
+ @classmethod
+ def tearDownClass(cls):
+ """Remove the generated vector map, if exist"""
+ mset = get_mapset_vector(cls.tmpname, mapset='')
+ if mset:
+ run_command("g.remove", vect="%s@%s" % (cls.tmpname, mset))
+
+
+if __name__ == '__main__':
+ unittest.main()
More information about the grass-commit
mailing list