Move grass package content to directory named grass (#1356)

Before this change, the code of the Python package called grass which comes
with GRASS GIS is hidden among C libraries in lib/python.
This may look like it is a C library to use or to communicate with Python,
not a Python package.

For Python packages, the standard naming is a directory which matches the name of the package.
This allows, for example, to import files directly from the source code.

This PR moves content of lib/python to python/grass so that the name of the directory
matches the name of the resulting package (currently placed in etc/python).

This does not change Sphinx which continues to ignore the top-level grass package
(this is future work).

Fixes #1100.

.github/workflows/flake8.yml

@@ -13,7 +13,7 @@ jobs:
       matrix:
         directory:
         - gui/wxpython
-        - lib/python
+        - python/grass
         - lib/init
         - scripts
         - temporal

.gitignore

@@ -24,8 +24,8 @@ lib/db/sqlp/sqlp.output
 lib/db/sqlp/sqlp.tab.c
 lib/db/sqlp/sqlp.tab.h
 lib/db/sqlp/sqlp.yy.c
-lib/python/ctypes/ctypesgencore/parser/lextab.py
-lib/python/script/setup.py.tmp
+python/grass/ctypes/ctypesgencore/parser/lextab.py
+python/grass/script/setup.py.tmp
 raster/r.mapcalc/mapcalc.output
 raster/r.mapcalc/mapcalc.tab.c
 raster/r.mapcalc/mapcalc.tab.h

Makefile

@@ -29,6 +29,7 @@ DIRS = \
 	utils \
 	include \
 	lib \
+	python \
 	db \
 	display \
 	general \
@@ -97,7 +98,7 @@ LIBDIRS = \
 	lib/db \
 	lib/vector \
 	db/drivers \
-	lib/python
+	python
 
 # Compile libraries only
 libs:

doc/howto_release.md

@@ -84,7 +84,7 @@ find . -name '*.o'    | xargs rm
 find . -name '*.pyc'  | xargs rm
 find . -name 'OBJ.*'  | xargs rm -r
 find . -name '__pycache__' | xargs rm -r
-rm -f lib/python/ctypes/ctypesgencore/parser/lextab.py
+rm -f python/grass/ctypes/ctypesgencore/parser/lextab.py
 rm -f gui/wxpython/menustrings.py gui/wxpython/build_ext.pyc \
   gui/wxpython/xml/menudata.xml gui/wxpython/xml/module_tree_menudata.xml
 chmod -R a+r *

doc/infrastructure.md

@@ -284,9 +284,9 @@ Maintainer: Vaclav Petras
 * CI workflow with:
     * A build job which is not parallelized and is meant for clear & relatively fast check of compilation and building in general. (Duplicating what is running on Travis)
     * A test job which of course needs to build, but the main focus is to run tests, so the compilation is parallelized (depending on nproc) and thus potentially less readable. This runs the whole test suite. (You need to run it locally to see the actual error, but you can see which tests are failing.)
-* Static code analysis/Code quality check using Flake8 with separate tests for lib/python, gui/wxpython, scripts and temporal directories.
-    * lib/python uses configuration which ignores code in testsuite directories and ignores a lot of errors.
-    * The other directories use the default settings and the failure is ignored. (Neither is an ideal solution, but we can see and change it based on whatever is more advantageous for getting it fixed.)
+* Static code analysis/Code quality check using Flake8 with separate checks for python/grass, gui/wxpython, scripts and temporal directories.
+    * Configurations ignore different lists of Flake8 errors. The idea is to reduce that to minimum.
+    * Code in testsuite directories is also ignored for now, but should not be in the future.
 
 Helper files placed to .github/workflows
 

include/Make/Doxyfile_arch_html.in

@@ -692,9 +692,9 @@ EXCLUDE                = bin.@ARCH@ \
                          lib/gpde/test \
                          lib/linkm/test \
                          lib/raster3d/test \
-                         lib/python \
                          lib/vector/dglib/examples \
                          lib/vector/rtree/docs \
+                         python \
                          locale \
                          macosx \
                          man \

include/Make/Doxyfile_arch_latex.in

@@ -692,9 +692,9 @@ EXCLUDE                = bin.@ARCH@ \
                          lib/gpde/test \
                          lib/linkm/test \
                          lib/raster3d/test \
-                         lib/python \
                          lib/vector/dglib/examples \
                          lib/vector/rtree/docs \
+                         python \
                          locale \
                          macosx \
                          man \

include/Make/Sphinx.make

@@ -24,30 +24,31 @@ checksphinx:
 	@(type $(SPHINXBUILD) > /dev/null || (echo "ERROR: Install 'sphinx-build' software first (get from http://sphinx-doc.org)" && exit 1))
 	@(type $(SPHINXAPIDOC) > /dev/null || (echo "ERROR: Install 'sphinx-apidoc' software first (get from http://sphinx-doc.org)" && exit 1))
 
+DOCSDIR = $(MODULE_TOPDIR)/python/grass/docs/
+
 cleansphinx:
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiclean
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs libpythonclean
+	$(MAKE) -C $(DOCSDIR) libpythonclean
 
 sphinxdoc: checksphinx cleansphinx
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguihtml
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonhtml
+	$(MAKE) -C $(DOCSDIR) libpythonapidoc
+	$(MAKE) -C $(DOCSDIR) libpythonhtml
 
 sphinxman:checksphinx cleansphinx
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiman
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonman
+	$(MAKE) -C $(DOCSDIR) libpythonapidoc
+	$(MAKE) -C $(DOCSDIR) libpythonman
 
 cleansphinxlib:
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs libpythonclean
+	$(MAKE) -C $(DOCSDIR) libpythonclean
 
 sphinxdoclib: checksphinx cleansphinxlib
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonhtml
+	$(MAKE) -C $(DOCSDIR) libpythonapidoc
+	$(MAKE) -C $(DOCSDIR) libpythonhtml
 
 sphinxmanlib:checksphinx cleansphinxlib
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
-	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonman
-
+	$(MAKE) -C $(DOCSDIR) libpythonapidoc
+	$(MAKE) -C $(DOCSDIR) libpythonman

lib/Makefile

@@ -41,7 +41,6 @@ SUBDIRS = \
 	ogsf \
 	nviz \
 	temporal \
-	python \
 	iostream \
 	manage \
 	calc

lib/init/grass.py

@@ -102,7 +102,7 @@ MACOSX = "darwin" in sys.platform
 
 def decode(bytes_, encoding=ENCODING):
     """Decode bytes with default locale and return (unicode) string
-    Adapted from lib/python/core/utils.py
+    Adapted from grass.script.core.utils.
 
     No-op if parameter is not bytes (assumed unicode string).
 
@@ -123,7 +123,7 @@ def decode(bytes_, encoding=ENCODING):
 
 def encode(string, encoding=ENCODING):
     """Encode string with default locale and return bytes with that encoding
-    Adapted from lib/python/core/utils.py
+    Adapted from grass.script.core.utils.
 
     No-op if parameter is bytes (assumed already encoded).
     This ensures garbage in, garbage out.
@@ -695,7 +695,7 @@ def set_paths(grass_config_dir):
         # the env var PYTHONPATH is only evaluated when python is started,
         # thus:
         sys.path.append(pythonpath)
-        # now we can import stuff from GRASS lib/python
+        # now we can import stuff from grass package
 
     # set path for the GRASS man pages
     grass_man_path = gpath("docs", "man")

python/Makefile

@@ -0,0 +1,10 @@
+MODULE_TOPDIR = ..
+
+include $(MODULE_TOPDIR)/include/Make/Vars.make
+
+SUBDIRS = \
+	grass
+
+include $(MODULE_TOPDIR)/include/Make/Dir.make
+
+default: subdirs

lib/python/docs/src/gunittest_running_tests.rst

@@ -110,8 +110,8 @@ Example Bash script to run be used as a cron job
     
     # necessary hardcoded GRASS paths
     GRASSDIST_PYTHON="$GRASSDIST/etc/python"
-    GRASS_MULTI_RUNNER="$GRASSSRC/lib/python/gunittest/multirunner.py"
-    GRASS_MULTI_REPORTER="$GRASSSRC/lib/python/gunittest/multireport.py"
+    GRASS_MULTI_RUNNER="$GRASSSRC/python/grass/gunittest/multirunner.py"
+    GRASS_MULTI_REPORTER="$GRASSSRC/python/grass/gunittest/multireport.py"
 
     DATE_FLAGS="--utc +%Y-%m-%d-%H-%M"
     NOW=$(date $DATE_FLAGS)

lib/python/gunittest/multirunner.py

@@ -153,7 +153,7 @@ def main():
 
     if main_report:
         # TODO: solve the path to source code (work now only for grass source code)
-        arguments = [sys.executable, grasssrc + '/lib/python/guittest/' + 'multireport.py', '--timestapms']
+        arguments = [sys.executable, grasssrc + '/python/grass/gunittest/' + 'multireport.py', '--timestapms']
         arguments.extend(reports)
         p = subprocess.Popen(arguments)
         returncode = p.wait()