diff --git a/.gitignore b/.gitignore index 29446d15507..fd8c521b7c6 100644 --- a/.gitignore +++ b/.gitignore @@ -193,15 +193,7 @@ CMakeUserPresets.json # Auto-generated sphinx source files for python library docs python/grass/docs/_templates/layout.html -python/grass/docs/src/exceptions.rst -python/grass/docs/src/ctypes*.rst python/grass/docs/src/grass.*rst -python/grass/docs/src/gunittest.rst -python/grass/docs/src/imaging.rst -python/grass/docs/src/pydispatch.rst -python/grass/docs/src/pygrass.*rst -python/grass/docs/src/script.rst -python/grass/docs/src/temporal.rst # Test result files *junit.xml diff --git a/doc/examples/notebooks/parallelization_tutorial.ipynb b/doc/examples/notebooks/parallelization_tutorial.ipynb index 88f2b7638f4..c289dca3044 100644 --- a/doc/examples/notebooks/parallelization_tutorial.ipynb +++ b/doc/examples/notebooks/parallelization_tutorial.ipynb @@ -109,7 +109,7 @@ "source": [ "### Data-based parallelization\n", "Data-based parallelism involves spatial domain decomposition, a process of splitting data into smaller datasets that can be processed in parallel.\n", - "As part of [GRASS Python API](https://grass.osgeo.org/grass-stable/manuals/libpython/index.html), [GridModule](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.modules.grid.html) decomposes input data into rectangular tiles, executes a given tool for each tile in parallel, and merges the results. Effectively, tiling is applied virtually (using computational region), determining the spatial extent of analysis for each parallel process. In some cases such as moving window analysis, tiles need to overlap to get correct results. Note that GridModule can be fairly inefficient due to the overhead from merging results back and is therefore best suited for computationally-itensive tasks such as interpolation." + "As part of [GRASS Python API](https://grass.osgeo.org/grass-stable/manuals/libpython/index.html), [GridModule](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.modules.grid.html) decomposes input data into rectangular tiles, executes a given tool for each tile in parallel, and merges the results. Effectively, tiling is applied virtually (using computational region), determining the spatial extent of analysis for each parallel process. In some cases such as moving window analysis, tiles need to overlap to get correct results. Note that GridModule can be fairly inefficient due to the overhead from merging results back and is therefore best suited for computationally-itensive tasks such as interpolation." ] }, { diff --git a/doc/grass_projects.md b/doc/grass_projects.md index b3c0d86eedd..253e9deac17 100644 --- a/doc/grass_projects.md +++ b/doc/grass_projects.md @@ -97,7 +97,7 @@ data file are often the most practical and convenient options. Projects can be created in various ways depending on the environment: - GRASS Python API: Allows creating a project programmatically with the function - [`create_project`](https://grass.osgeo.org/grass-stable/manuals/libpython/script.html#script.core.create_project). + [`create_project`](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.create_project). This example creates a project named *my_project* with a specific EPSG code: ```python diff --git a/doc/python_intro.md b/doc/python_intro.md index 75872c47731..cf0ee6c277a 100644 --- a/doc/python_intro.md +++ b/doc/python_intro.md @@ -292,11 +292,11 @@ The [grass.pygrass.gis](https://grass.osgeo.org/grass-stable/manuals/libpython/p module provides access to the project and region management of GRASS. The [grass.pygrass.gis](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_gis.html) module provides functions to create, manage, and delete GRASS projects and -mapsets. The core classes include [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Gisdbase), -[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Location), -and [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/pygrass.gis.html#pygrass.gis.Mapset). +mapsets. The core classes include [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Gisdbase), +[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Location), +and [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Mapset). -The [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Gisdbase) +The [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Gisdbase) class provides access to the GRASS database and where you can manage GRASS projects and mapsets. @@ -311,14 +311,14 @@ print(projects) ``` This will return a list of all projects in the GRASS database directory as -[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Location) +[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Location) objects. ```text ['nc_spm_08_grass7', 'my_project'] ``` -The [Location](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Location) +The [Location](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Location) object provides access to the specific project and its mapsets. @@ -334,7 +334,7 @@ print(location.name) mapsets = location.mapsets() ``` -The [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/pygrass.gis.html#pygrass.gis.Mapset) +The [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Mapset) object provides access to the specific mapset and its layers. ```python @@ -352,7 +352,7 @@ For more details about the `gis` module, see the Full Documentation: ### Region -The [grass.pygrass.gis.region](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.region.Region) +The [grass.pygrass.gis.region](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.region.Region) module gives access to read and modify computational regions. For example, to get the current extent and resolution of the active mapset: @@ -416,7 +416,7 @@ Resolution: [10.0, 10.0] For more details about the `region` module, see the Full Documentation: -[Full Documentation :material-arrow-right-bold:](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#module-pygrass.gis){ .md-button } +[Full Documentation :material-arrow-right-bold:](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#module-grass.pygrass.gis){ .md-button } ### Data Management @@ -495,15 +495,15 @@ For more details about the `raster` module, see the Full Documentation: The [grass.pygrass.vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vector) module provides direct read and write access to vector data in GRASS. -The core classes include [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector) +The core classes include [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector) and [VectorTopo](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vectortopo-label). | Class | Description | | ----- | ----------- | -| [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector) | Provides basic information about vector data. | +| [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector) | Provides basic information about vector data. | | [VectorTopo](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vectortopo-label) | Read and write access to vector data. | -Here is a simple example with [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector) +Here is a simple example with [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector) to check if a vector map exists and print the mapset it is in. ```python @@ -520,7 +520,7 @@ if roads.exist(): With the [VectorTopo](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vectortopo-label) class you can get the same basic information about the -vector map returned by the [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector) +vector map returned by the [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector) class in addition to read and write access. ```python @@ -544,17 +544,17 @@ and attributes are treated separately. This means that the attributes of a vector are not automatically read when the geometry is read. To build a geometry object, you can use the geometry class in the -[grass.pygrass.vector.geometry](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#module-pygrass.vector.geometry) +[grass.pygrass.vector.geometry](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#module-grass.pygrass.vector.geometry) module. | Geometry Class | Description | | -------------- | ----------- | -| [Area](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Area) | Represents the topological composition of a closed ring of boundaries and a centroid. | -| [Boundary](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Boundary) | Represents the border line to describe an area. | -| [Centroid](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Centroid) | Represents a centroid feature in a vector map. | -| [Isle](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Isle) | Represents an isle feature in a vector map. | -| [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line) | Represents a line feature in a vector map. | -| [Point](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Point) | Represents a point feature in a vector map. | +| [Area](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Area) | Represents the topological composition of a closed ring of boundaries and a centroid. | +| [Boundary](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Boundary) | Represents the border line to describe an area. | +| [Centroid](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Centroid) | Represents a centroid feature in a vector map. | +| [Isle](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Isle) | Represents an isle feature in a vector map. | +| [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line) | Represents a line feature in a vector map. | +| [Point](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Point) | Represents a point feature in a vector map. | Each geometry class has its own set of methods to help extract useful information. For example, let's build a `Boundary` object from a list of points @@ -625,7 +625,7 @@ with VectorTopo('roadsmajor', mode='rw') as roads: roads.build() ``` -Features can also be updated by using the [rewrite](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.VectorTopo.rewrite) +Features can also be updated by using the [rewrite](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.VectorTopo.rewrite) method instead of the `write`. If the geometry of the feature has not changed, you can save the attributes to the database table without rebuilding the topology using `table.conn.commit`. @@ -653,10 +653,10 @@ You can also use many of `Geometry` and `Attribute` methods to filter features in a more concise way. For example, to test if a random point is within 5000 meters of a road segment -you can use the [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line.distance) -method of the [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line) -geometry object. The [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line.distance) -method returns a [LineDist](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.LineDist) +you can use the [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line.distance) +method of the [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line) +geometry object. The [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line.distance) +method returns a [LineDist](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.LineDist) object that contains the distance and the closest point on the line. ```python @@ -686,8 +686,8 @@ with VectorTopo('roadsmajor') as roads: ``` Or to simply filter a table using `SQL` you can use the `where` method with -[table_to_dict](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.VectorTopo.table_to_dict) -to get a dictionary of the features that match the query, the [table.Filter](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.table.Filters) +[table_to_dict](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.VectorTopo.table_to_dict) +to get a dictionary of the features that match the query, the [table.Filter](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.table.Filters) class for more advanced operations. ```python @@ -743,12 +743,12 @@ The *grass.script* package provides a set of tool-calling functions which follow text input and output handling use cases from a command-line shell perspective. Four main functions are: -*[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.run_command)*, -*[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.parse_command)*, -*[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.read_command)*, -and *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.write_command)*. +*[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.run_command)*, +*[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.parse_command)*, +*[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.read_command)*, +and *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.write_command)*. -The *[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.run_command)* +The *[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.run_command)* function is used to run a GRASS tool when you require no return value. For example, when computing raster slope with [r.slope.aspect](r.slope.aspect.md): @@ -757,7 +757,7 @@ no return value. For example, when computing raster slope with gs.run_command("r.slope.aspect", elevation="elevation", slope="slope") ``` -The *[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.parse_command)* +The *[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.parse_command)* function is useful when the tool returns machine-readable text output on the standard output. For example, use it to parse the output of [v.db.select](v.db.select.md#json) @@ -767,7 +767,7 @@ to represent attribute data in a Python dictionary: data = gs.parse_command("v.db.select", map="hospitals", format="json") ``` -The *[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.read_command)* +The *[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.read_command)* function returns the text output of a GRASS tool. This can be useful when you want to print human-readable output of a tool. For example, when reading the output of [g.region](g.region.md): @@ -776,7 +776,7 @@ For example, when reading the output of [g.region](g.region.md): print(gs.read_command("g.region", flags="p")) ``` -The *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.write_command)* +The *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.write_command)* function is used to send data to a GRASS tool through the standard input. For example, when writing a custom color scheme to a raster map with [r.colors](r.colors.md): diff --git a/python/grass/docs/Makefile b/python/grass/docs/Makefile index ffeb15f9ba3..631fd7be000 100644 --- a/python/grass/docs/Makefile +++ b/python/grass/docs/Makefile @@ -48,25 +48,10 @@ libpythonhelp: libpythonclean: -rm -rf $(BUILDDIR)/* -rm -f _templates/layout.html - -rm -f src/ctypes*.rst - -rm -f src/exceptions.rst - -rm -f src/gunittest.*rst - -rm -f src/imaging.rst - -rm -f src/pydispatch.rst - -rm -f src/pygrass.*rst - -rm -f src/script.rst - -rm -f src/temporal.rst -rm -f src/grass*.rst libpythonapidoc: @echo "SPHINXBUILD: Using <$(SPHINXBUILD)>" - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../imaging/) - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../exceptions/) - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../gunittest/ ../gunittest/multireport.py ../gunittest/multirunner.py ../gunittest/main.py) - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../pydispatch/) - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../pygrass/) - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../script/) - $(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../temporal/) $(call run_grass,$(SPHINXAPIDOC) --module-first -T -f -t _templates/sphinx/apidoc/ -o src/ ../../grass) libpythonhtml: checksphinx diff --git a/python/grass/docs/conf.py b/python/grass/docs/conf.py index 01c46232f08..7402a0e0d83 100644 --- a/python/grass/docs/conf.py +++ b/python/grass/docs/conf.py @@ -16,62 +16,9 @@ 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 -# documentation root, use os.path.abspath to make it absolute, like shown here. +# The grass package is imported from GISBASE, which the build puts on PYTHONPATH. if not os.getenv("GISBASE"): sys.exit("GISBASE not defined") -sys.path.insert( - 0, os.path.abspath(os.path.join(os.environ["GISBASE"], "etc", "python", "grass")) -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "ctypes") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "exceptions") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "gunittest") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "imaging") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "pydispatch") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "pygrass") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "script") - ), -) -sys.path.insert( - 0, - os.path.abspath( - os.path.join(os.environ["GISBASE"], "etc", "python", "grass", "temporal") - ), -) from grass.script import core # noqa: E402 @@ -116,17 +63,13 @@ # Skip temporal lexer rule methods because their regex docstrings are not intended -# for reStructuredText parsing and only serve PLY token definitions. The modules -# are checked under both names because the sys.path entries above make them -# importable both as grass.temporal.* and as temporal.*. +# for reStructuredText parsing and only serve PLY token definitions. def skip_member(app, what, name, obj, skip, options): if name.startswith("t_"): mod = getattr(obj, "__module__", None) if mod in { "grass.temporal.temporal_algebra", "grass.temporal.temporal_operator", - "temporal.temporal_algebra", - "temporal.temporal_operator", }: return True return None @@ -257,7 +200,7 @@ def setup(app): "internal": True, }, { - "href": "exceptions", + "href": "grass.exceptions", "title": "Exceptions", "internal": True, }, diff --git a/python/grass/docs/src/gunittest_testing.rst b/python/grass/docs/src/gunittest_testing.rst index 0fa9b74d144..23b09a9eea3 100644 --- a/python/grass/docs/src/gunittest_testing.rst +++ b/python/grass/docs/src/gunittest_testing.rst @@ -8,7 +8,7 @@ of GRASS testing framework, you might want to skip to one of: * :ref:`test-c` section * :ref:`test-python` section * :ref:`test-doctest` section -* :class:`~gunittest.case.TestCase` class +* :class:`~grass.gunittest.case.TestCase` class * :ref:`running-tests-report` section @@ -93,7 +93,7 @@ it must be placed into a directory named ``testsuite``. In the example we have used only two assert methods, one to check that module runs and end successfully and the other to test that map values are within an expect interval. There is a much larger selection of assert methods -in :class:`~gunittest.case.TestCase` class documentation +in :class:`~grass.gunittest.case.TestCase` class documentation and also in Python `unittest`_ package documentation. To run the test, run GRASS, use NC SPM sample location and create @@ -141,7 +141,7 @@ test case In other words, a *test case* class contains all tests which are using the same *test fixture*. - There is also a general :class:`~gunittest.case.TestCase` class which + There is also a general :class:`~grass.gunittest.case.TestCase` class which all concrete test case classes should inherit from to get all GRASS-specific testing functionality and also to be found by the testing framework. @@ -299,7 +299,7 @@ it is much better then relying on given data but it is not at all required and all approaches are encouraged. Whenever possible it is advantageous to use available assert methods. -GRASS-specific assert methods are in :class:`gunittest.case.TestCase` class. +GRASS-specific assert methods are in :class:`grass.gunittest.case.TestCase` class. For general assert methods refer to Python `unittest`_ package documentation. Both are used in the same way; they are methods of a given test case class. In cases (which should be rare) when no assert methods fits the purpose, @@ -711,7 +711,7 @@ Further reading .. toctree:: :maxdepth: 2 - gunittest + grass.gunittest gunittest_running_tests diff --git a/python/grass/docs/src/index.rst b/python/grass/docs/src/index.rst index 5ae76b82258..aa4ada5ccfa 100644 --- a/python/grass/docs/src/index.rst +++ b/python/grass/docs/src/index.rst @@ -23,9 +23,9 @@ at various levels: * `grass.jupyter package `_ offers classes and setup functions for running GRASS in Jupyter Notebooks * `Testing GRASS source code and modules `_ using gunittest package -* `exceptions package `_ contains exceptions used by other packages -* `imaging package `_ is a library to create animated images and films -* `pydispatch package `_ is a library for signal-dispatching +* `grass.exceptions package `_ contains exceptions used by other packages +* `grass.imaging package `_ is a library to create animated images and films +* `grass.pydispatch package `_ is a library for signal-dispatching -------------------- Additional Resources @@ -47,8 +47,8 @@ Modules and Packages script_intro pygrass_index grass.jupyter - exceptions - imaging - pydispatch + grass.exceptions + grass.imaging + grass.pydispatch temporal_framework gunittest_testing diff --git a/python/grass/docs/src/pygrass_gis.rst b/python/grass/docs/src/pygrass_gis.rst index 23891aab291..0829a8cf1bc 100644 --- a/python/grass/docs/src/pygrass_gis.rst +++ b/python/grass/docs/src/pygrass_gis.rst @@ -5,10 +5,10 @@ GRASS database management PyGRASS implements the classes described below: -* :class:`~pygrass.gis.Gisdbase` -* :class:`~pygrass.gis.Location` -* :class:`~pygrass.gis.Mapset` -* :class:`~pygrass.gis.VisibleMapset` +* :class:`~grass.pygrass.gis.Gisdbase` +* :class:`~grass.pygrass.gis.Location` +* :class:`~grass.pygrass.gis.Mapset` +* :class:`~grass.pygrass.gis.VisibleMapset` These classes are used to manage the infrastructure of GRASS database: GIS data directory, Location and Mapset. Details about the GRASS @@ -21,10 +21,10 @@ User's Manual: GRASS Quickstart Region management ================= -The :class:`~pygrass.gis.region.Region` class it is useful to obtain +The :class:`~grass.pygrass.gis.region.Region` class it is useful to obtain information about the computational region and to change it. Details about the GRASS computational region management can be found in the `GRASS Wiki: Computational region `_. -The classes are part of the :mod:`~pygrass.gis` module. +The classes are part of the :mod:`~grass.pygrass.gis` module. diff --git a/python/grass/docs/src/pygrass_index.rst b/python/grass/docs/src/pygrass_index.rst index bea68afe468..1c0158e350f 100644 --- a/python/grass/docs/src/pygrass_index.rst +++ b/python/grass/docs/src/pygrass_index.rst @@ -35,7 +35,7 @@ Read more about how to work with *PyGRASS* in this documentation. pygrass_vector pygrass_modules pygrass_messages - pygrass + grass.pygrass References diff --git a/python/grass/docs/src/pygrass_messages.rst b/python/grass/docs/src/pygrass_messages.rst index 9f5ec2cf8c7..ecb41b14afa 100644 --- a/python/grass/docs/src/pygrass_messages.rst +++ b/python/grass/docs/src/pygrass_messages.rst @@ -5,7 +5,7 @@ The PyGRASS message interface is a fast and exit-safe interface to the `GRASS C-library message functions `_. -The :class:`~pygrass.messages.Messenger` class implements a fast and +The :class:`~grass.pygrass.messages.Messenger` class implements a fast and exit-safe interface to the GRASS C-library message functions like: ``G_message()``, ``G_warning()``, ``G_important_message()``, ``G_verbose_message()``, ``G_percent()`` and ``G_debug()``. diff --git a/python/grass/docs/src/pygrass_modules.rst b/python/grass/docs/src/pygrass_modules.rst index a262012ba8a..0c02ab2f369 100644 --- a/python/grass/docs/src/pygrass_modules.rst +++ b/python/grass/docs/src/pygrass_modules.rst @@ -1,8 +1,8 @@ Interface to GRASS modules ============================== -In :mod:`~pygrass.modules` module, GRASS modules are represented -by :class:`~pygrass.modules.interface.module.Module` class +In :mod:`~grass.pygrass.modules` module, GRASS modules are represented +by :class:`~grass.pygrass.modules.interface.module.Module` class objects. These objects are generated based on the XML module description that is used also for the generation of the graphical user interface (GUI). :: @@ -193,11 +193,11 @@ Launching GRASS modules in parallel PyGRASS implements simple mechanism for launching GRASS modules in parallel. See -:class:`~pygrass.modules.interface.module.ParallelModuleQueue` class +:class:`~grass.pygrass.modules.interface.module.ParallelModuleQueue` class for details. Multiple GRASS modules can be joined into one object by -:class:`~pygrass.modules.interface.module.MultiModule`. +:class:`~grass.pygrass.modules.interface.module.MultiModule`. .. _Popen: https://docs.python.org/library/subprocess.html#Popen diff --git a/python/grass/docs/src/pygrass_raster.rst b/python/grass/docs/src/pygrass_raster.rst index d473ba48952..2733daf6a04 100644 --- a/python/grass/docs/src/pygrass_raster.rst +++ b/python/grass/docs/src/pygrass_raster.rst @@ -16,7 +16,7 @@ RowIO is row cached, :ref:`RasterSegment-label` is tile cached for reading and writing; therefore, random access is possible. Hence RasterRow and RasterRowIO should be used for fast (cached) row read access and RasterRow for fast sequential writing. RasterSegment should be used -for random access. The classes are part of the :mod:`~pygrass.raster` +for random access. The classes are part of the :mod:`~grass.pygrass.raster` module. @@ -66,7 +66,7 @@ We can rename the map: :: RasterRow --------- -The PyGRASS :class:`~pygrass.raster.RasterRow` class allow user to open maps row +The PyGRASS :class:`~grass.pygrass.raster.RasterRow` class allow user to open maps row by row in either read or write mode using the `Raster library`_. Reading and writing to the same map at the same time is not supported. For this functionality, please see the :ref:`RasterSegment-label` class. @@ -136,7 +136,7 @@ added to the file as the last row. :: RasterRowIO ----------- -The :class:`~pygrass.raster.RasterRowIO` class uses the GRASS `RowIO library`_, and implements a row +The :class:`~grass.pygrass.raster.RasterRowIO` class uses the GRASS `RowIO library`_, and implements a row cache. The RasterRowIO class only supports reading rasters; because raster rows can only be written in sequential order, writing by row id is not supported by design. Hence, the RowIO lib can only be used to cache rows @@ -159,7 +159,7 @@ for reading, and any write access should use the :ref:`RasterRow-label` class. : RasterSegment ------------- -The :class:`~pygrass.raster.RasterSegment` class uses the GRASS `Segmentation library`_. The class divides +The :class:`~grass.pygrass.raster.RasterSegment` class uses the GRASS `Segmentation library`_. The class divides a raster map into small tiles stored on disk. Initialization of this class is therefore intensive. However, this class has lower memory requirements, as GRASS loads only currently-accessed tiles into memory. The segment library allow diff --git a/python/grass/docs/src/pygrass_vector.rst b/python/grass/docs/src/pygrass_vector.rst index faa1dd098dc..b7de76bc2f0 100644 --- a/python/grass/docs/src/pygrass_vector.rst +++ b/python/grass/docs/src/pygrass_vector.rst @@ -11,15 +11,15 @@ for vector maps, while VectorTopo opens vector maps with `GRASS topology `_. VectorTopo is an extension of the Vector class, so supports all the Vector class methods, with additions. The classes are part of the -:mod:`~pygrass.vector` module. +:mod:`~grass.pygrass.vector` module. .. _Vector-label: Vector ------ -The :class:`~pygrass.vector.Vector` class is based on the -:class:`~pygrass.vector.abstract.Info` class, which provides methods +The :class:`~grass.pygrass.vector.Vector` class is based on the +:class:`~grass.pygrass.vector.abstract.Info` class, which provides methods for accessing basic information about the vector map: :: >>> from grass.pygrass.vector import Vector @@ -40,7 +40,7 @@ for accessing basic information about the vector map: :: VectorTopo ---------- -The :class:`~pygrass.vector.VectorTopo` class allows vector maps to be loaded +The :class:`~grass.pygrass.vector.VectorTopo` class allows vector maps to be loaded along with an accompanying topology. The VectorTopo class interface has all the same methods as the basic Vector class, but includes many more methods dependent on the topology rules. Consult each class's documentation for a list of the @@ -72,7 +72,7 @@ To begin using a vector map, it must first be opened: :: >>> municip.open(mode='r') The ``open()`` method supports a number of option arguments (see the -:class:`~pygrass.vector.abstract.Info` documentation for a complete +:class:`~grass.pygrass.vector.abstract.Info` documentation for a complete list). In particular, the mode argument can take a value of: * 'r': read-only mode, vector features are read-only (attribute table @@ -215,23 +215,23 @@ requesting the table from each of the returned links: :: Link(1, census, sqlite) >>> table = link.table() -Here, :class:`~pygrass.vector.table.DBlinks` is a class that contains +Here, :class:`~grass.pygrass.vector.table.DBlinks` is a class that contains all the links of a vector map. Each link is also a class -(:class:`~pygrass.vector.table.Link`) that contains a specific link's +(:class:`~grass.pygrass.vector.table.Link`) that contains a specific link's parameters. The ``table()`` method of the link class return the linked -table as a table object (:class:`~pygrass.vector.table.Table`). +table as a table object (:class:`~grass.pygrass.vector.table.Table`). Geometry Classes ---------------- The vector package also includes a number of geometry classes, -including :class:`~pygrass.vector.geometry.Area`, -:class:`~pygrass.vector.geometry.Boundary`, -:class:`~pygrass.vector.geometry.Centroid`, -:class:`~pygrass.vector.geometry.Isle`, -:class:`~pygrass.vector.geometry.Line`, and -:class:`~pygrass.vector.geometry.Point` classes. Please consult the -:mod:`~pygrass.vector.geometry` module for a complete list of methods +including :class:`~grass.pygrass.vector.geometry.Area`, +:class:`~grass.pygrass.vector.geometry.Boundary`, +:class:`~grass.pygrass.vector.geometry.Centroid`, +:class:`~grass.pygrass.vector.geometry.Isle`, +:class:`~grass.pygrass.vector.geometry.Line`, and +:class:`~grass.pygrass.vector.geometry.Point` classes. Please consult the +:mod:`~grass.pygrass.vector.geometry` module for a complete list of methods for these classes, as there are many. Some basic examples are given below. diff --git a/python/grass/docs/src/script_intro.rst b/python/grass/docs/src/script_intro.rst index e8dee5533c7..a3a069617ca 100644 --- a/python/grass/docs/src/script_intro.rst +++ b/python/grass/docs/src/script_intro.rst @@ -7,7 +7,7 @@ Parts of the grass.script API .. toctree:: :maxdepth: 2 - script + grass.script Syntax diff --git a/python/grass/docs/src/temporal_framework.rst b/python/grass/docs/src/temporal_framework.rst index f97dce8f1f6..95bbe080f0f 100644 --- a/python/grass/docs/src/temporal_framework.rst +++ b/python/grass/docs/src/temporal_framework.rst @@ -36,94 +36,94 @@ for example the database interface, the temporal database creation and initializ the SQL object serialization, all classes that represent table entries, datetime mathematics and many more. -:mod:`~temporal.core` -""""""""""""""""""""" +:mod:`~grass.temporal.core` +""""""""""""""""""""""""""" The core functionality of the temporal framework: - - Initialization function :func:`~temporal.core.init()` + - Initialization function :func:`~grass.temporal.core.init()` - Definition of global variables - Several global functions to access TGIS specific variables - Interfaces to the TGIS C-library and PyGRASS messenger objects - - Database interface connection class :class:`~temporal.core.SQLDatabaseInterfaceConnection` + - Database interface connection class :class:`~grass.temporal.core.SQLDatabaseInterfaceConnection` to sqlite3 and postgresql database backends - Functions to create the temporal database -:mod:`~temporal.base` -""""""""""""""""""""" +:mod:`~grass.temporal.base` +""""""""""""""""""""""""""" Implements of basic dataset information and SQL conversion of such information: - - Definition of the SQL serialize class :class:`~temporal.base.DictSQLSerializer` + - Definition of the SQL serialize class :class:`~grass.temporal.base.DictSQLSerializer` that converts the content of temporal classes into SQL SELECT, INSERT or UPDATE statements - - Definition of :class:`~temporal.base.SQLDatabaseInterface` + - Definition of :class:`~grass.temporal.base.SQLDatabaseInterface` that is the base class for all temporal datatype subclasses - Contains classes for all datasets [#allds]_ that contain basic information (id, name, mapset, creator, ...) -:mod:`~temporal.spatial_extent` -""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.spatial_extent` +""""""""""""""""""""""""""""""""""""" Implements of 2d and 3d spatial extents of all datasets: - - Implements class :class:`~temporal.spatial_extent.SpatialExtent` + - Implements class :class:`~grass.temporal.spatial_extent.SpatialExtent` that is the base class for all dataset specific spatial extent classes It provides spatial topological logic and operations for 2D and 3D extents - Implements spatial extent classes for all datasets [#allds]_ -:mod:`~temporal.temporal_extent` -"""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.temporal_extent` +"""""""""""""""""""""""""""""""""""""" Implements of the temporal extent of all datasets for relative and absolute time: - - Implements class :class:`~temporal.temporal_extent.TemporalExtent` + - Implements class :class:`~grass.temporal.temporal_extent.TemporalExtent` that is the base class for all dataset specific temporal extent classes It provides temporal topological logic and operations - Implements temporal extent classes for relative time and absolute time for all datasets [#allds]_ -:mod:`~temporal.metadata` -""""""""""""""""""""""""" +:mod:`~grass.temporal.metadata` +""""""""""""""""""""""""""""""" Implements the metadata base classes and datatype specific derivatives for all datasets [#allds]_. -:mod:`~temporal.spatial_topology_dataset_connector` -""""""""""""""""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.spatial_topology_dataset_connector` +""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Implements the interface to link datasets by spatial topological relations -:mod:`~temporal.temporal_topology_dataset_connector` -"""""""""""""""""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.temporal_topology_dataset_connector` +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Implements the interface to link datasets by temporal topological relations -:mod:`~temporal.c_libraries_interface` -"""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.c_libraries_interface` +"""""""""""""""""""""""""""""""""""""""""""" The RPC C-library interface for exit safe and fast access to raster, vector and 3D raster information. -:mod:`~temporal.temporal_granularity` -""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.temporal_granularity` +""""""""""""""""""""""""""""""""""""""""""" The computation of the temporal granularity for a list - of :class:`~temporal.abstract_dataset.AbstractDataset` + of :class:`~grass.temporal.abstract_dataset.AbstractDataset` objects for absolute and relative is implemented here. -:mod:`~temporal.datetime_math` -"""""""""""""""""""""""""""""" +:mod:`~grass.temporal.datetime_math` +"""""""""""""""""""""""""""""""""""" This module contains function to parse, convert and process datetime objects in the temporal framework. Spatio-temporal algebra classes for space time raster and vector datasets are defined in: -- :mod:`~temporal.temporal_algebra` -- :mod:`~temporal.temporal_operator` -- :mod:`~temporal.temporal_raster_base_algebra` -- :mod:`~temporal.temporal_raster_algebra` -- :mod:`~temporal.temporal_raster3d_algebra` -- :mod:`~temporal.temporal_vector_algebra` +- :mod:`~grass.temporal.temporal_algebra` +- :mod:`~grass.temporal.temporal_operator` +- :mod:`~grass.temporal.temporal_raster_base_algebra` +- :mod:`~grass.temporal.temporal_raster_algebra` +- :mod:`~grass.temporal.temporal_raster3d_algebra` +- :mod:`~grass.temporal.temporal_vector_algebra` High level API ^^^^^^^^^^^^^^ @@ -131,46 +131,46 @@ High level API The high level API utilizes the low level API. Its classes and functions are usually used to implement temporal processing algorithms and temporal GRASS modules. -:mod:`~temporal.abstract_dataset` -""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.abstract_dataset` +""""""""""""""""""""""""""""""""""""""" - - Implements the base class for all datasets [#allds]_ :class:`~temporal.abstract_dataset.AbstractDataset`. + - Implements the base class for all datasets [#allds]_ :class:`~grass.temporal.abstract_dataset.AbstractDataset`. - Implements the select, insert and update functionality as well as convenient functions to access the base, extent and metadata information -:mod:`~temporal.abstract_map_dataset` -""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.abstract_map_dataset` +""""""""""""""""""""""""""""""""""""""""""" - - Implements the base class :class:`~temporal.abstract_map_dataset.AbstractMapDataset` + - Implements the base class :class:`~grass.temporal.abstract_map_dataset.AbstractMapDataset` for all map layer specific classes - Provides the interface to all map layer specific information in the temporal database -:mod:`~temporal.abstract_space_time_dataset` -"""""""""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.abstract_space_time_dataset` +"""""""""""""""""""""""""""""""""""""""""""""""""" - - Implements the base class :class:`~temporal.abstract_space_time_dataset.AbstractSpaceTimeDataset` + - Implements the base class :class:`~grass.temporal.abstract_space_time_dataset.AbstractSpaceTimeDataset` for all Space Time Datasets classes - Contains the creation and deletion functionality, the map registration and un-registration, access methods to map layer objects and so on - Provides the interface to all Space Time Dataset specific information in the temporal database -:mod:`~temporal.space_time_datasets` -"""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.space_time_datasets` +"""""""""""""""""""""""""""""""""""""""""" This module contains all classes that represent specific datasets [#allds]_. A module developer uses these map layer and Space Time Dataset object representations to perform spatio-temporal tasks. -:mod:`~temporal.spatio_temporal_relationships` -"""""""""""""""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.spatio_temporal_relationships` +"""""""""""""""""""""""""""""""""""""""""""""""""""" - The logic to compute spatio-temporal topology for a single list or two lists of :class:`~temporal.abstract_dataset.AbstractDataset` objects + The logic to compute spatio-temporal topology for a single list or two lists of :class:`~grass.temporal.abstract_dataset.AbstractDataset` objects is implemented in this module. - The class :class:`~temporal.spatio_temporal_relationships.SpatioTemporalTopologyBuilder` + The class :class:`~grass.temporal.spatio_temporal_relationships.SpatioTemporalTopologyBuilder` provides a convenient interface for topology computation. -:mod:`~temporal.gui_support` -"""""""""""""""""""""""""""" +:mod:`~grass.temporal.gui_support` +"""""""""""""""""""""""""""""""""" Helper functions to support the listing of space time datasets in the automatically generated GUI. @@ -183,65 +183,65 @@ map listing, space time dataset creation, map registration and un-registration, aggregation, extraction, map calculation, statistics as well as import and export of space time datasets. -:mod:`~temporal.aggregation` -"""""""""""""""""""""""""""" +:mod:`~grass.temporal.aggregation` +"""""""""""""""""""""""""""""""""" Aggregation of Space Time Raster Datasets based on topological relations. Used in *t.rast.aggregate* and *t.rast.aggregate.ds* -:mod:`~temporal.extract` -"""""""""""""""""""""""" +:mod:`~grass.temporal.extract` +"""""""""""""""""""""""""""""" Extraction of subsets from Space Time Datasets including map algebra and vector selection statements. Used in *t.rast.extract*, *t.rast3d.extract* and *t.vect.extract*. -:mod:`~temporal.factory` -"""""""""""""""""""""""" +:mod:`~grass.temporal.factory` +"""""""""""""""""""""""""""""" Factory functions to create datasets of all types [#allds]_. -:mod:`~temporal.open_stds` -"""""""""""""""""""""""""" +:mod:`~grass.temporal.open_stds` +"""""""""""""""""""""""""""""""" Convenient functions to open existing Space Time Datasets or to create new ones. Used in almost all temporal modules. -:mod:`~temporal.list_stds` -"""""""""""""""""""""""""" +:mod:`~grass.temporal.list_stds` +"""""""""""""""""""""""""""""""" Convenient functions to list datasets of all types [#allds]_ registered in the temporal database. -:mod:`~temporal.mapcalc` -"""""""""""""""""""""""" +:mod:`~grass.temporal.mapcalc` +"""""""""""""""""""""""""""""" Simple temporal algebra for Space Time Raster and 3d Raster datasets. Used in *t.rast.mapcalc* and *t.rast3d.mapcalc* -:mod:`~temporal.register` -""""""""""""""""""""""""" +:mod:`~grass.temporal.register` +""""""""""""""""""""""""""""""" Convenient functions to register a single or multiple map layer in the temporal database and SpaceTime Datasets. Used in several modules, most important *t.register*. -:mod:`~temporal.sampling` -""""""""""""""""""""""""" +:mod:`~grass.temporal.sampling` +""""""""""""""""""""""""""""""" Sampling functions used in several modules. -:mod:`~temporal.stds_export` -"""""""""""""""""""""""""""" +:mod:`~grass.temporal.stds_export` +"""""""""""""""""""""""""""""""""" Functions to export of Space Time Datasets, used in *t.rast.export*, *t.rast3d.export* and *t.vect.export*. -:mod:`~temporal.stds_import` -"""""""""""""""""""""""""""" +:mod:`~grass.temporal.stds_import` +"""""""""""""""""""""""""""""""""" Functions to import Space Time Datasets, used in *t.rast.import*, *t.rast3d.import* and *t.vect.import*. -:mod:`~temporal.univar_statistics` -"""""""""""""""""""""""""""""""""" +:mod:`~grass.temporal.univar_statistics` +"""""""""""""""""""""""""""""""""""""""" Simple statistical analysis functions for Space Time Datasets, used in *t.rast.univar*, *t.rast3d.univar* and *t.vect.univar*. @@ -256,7 +256,7 @@ Here the full list of all temporal modules: .. toctree:: :maxdepth: 2 - temporal + grass.temporal Examples