[GRASS-git] [OSGeo/grass] 59ce61: grass.script: Add MapsetSession for runs in other ...

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 59ce612d2a396d6ca2bb6340e6d198543de16571
      https://github.com/OSGeo/grass/commit/59ce612d2a396d6ca2bb6340e6d198543de16571
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2024-02-08 (Thu, 08 Feb 2024)

  Changed paths:
    M python/grass/Makefile
    A python/grass/experimental/Makefile
    A python/grass/experimental/__init__.py
    A python/grass/experimental/create.py
    A python/grass/experimental/mapset.py
    A python/grass/experimental/tests/conftest.py
    A python/grass/experimental/tests/grass_script_mapset_session_module_fixture_test.py
    A python/grass/experimental/tests/grass_script_mapset_session_test.py
    A python/grass/experimental/tests/grass_script_tmp_mapset_session_test.py
    M python/grass/grassdb/create.py
    M python/grass/grassdb/manage.py
    M python/grass/script/core.py
    M python/grass/script/setup.py

  Log Message:
  -----------
  grass.script: Add MapsetSession for runs in other mapsets (#2367)

The new MapsetSession object uses the current db/location (project) and changes mapset (subproject) in a new separate environment. A new mapset is created if requested. MapsetSession can be used as a context manager. The original use case is bulk imports.

This combines existing create_mapset and create_environment and adds the require/create/ensure logic, one interface, and resource handling. The underlying functionality is general enough and available as a new require_create_ensure_mapset function.

The MapsetSession interface is the same as the session handle returned from grass.script.setup.init which now gets a new env property to keep the interface unified and to allow for session-object-agnostic code in the tests.

A separate TemporaryMapsetSession adds a temporary mapset handling which shares most of the API, but the implementation is very different since the mapset never exists and is always created. There the context manager creates and deletes the temporary mapset within the with-statement. The expected usage is one-off computations which are part of a larger process in GRASS GIS or outside of it.

Other names considered were MapsetSubSession and SubMapsetSession.

The session classes are under a new subpackage grass.experimental. This allows use and testing by advanced users without creating high expectations or committing to a specific API or behavior.