grass.experimental package — GRASS Python Library documentation

# grass.experimental package

Experimental code, all can change

## Submodules

## grass.experimental.create module

Likely going into grass.grassdb.create

grass.experimental.create.create_temporary_mapset(path, location=None) → MapsetPath

  Create temporary mapset

  The user of this function is responsible for deleting the contents of the temporary directory and the directory itself when done with it.

grass.experimental.create.require_create_ensure_mapset(path, location=None, mapset=None, *, create=False, overwrite=False, ensure=False)

  Checks that mapsets exists or creates it in a specified location

  By default, it checks that the mapset exists and raises a ValueError otherwise. If create is True and the mapset does not exists, it creates it. If it exists and overwrite is True, it deletes the existing mapset (with all the data in it). If ensure is True, existing mapset is used as is and when there is none, a new mapset is created.

  Where the mapset is specified by a full path or by location name and path to the directory where the location is.

  The path argument is positional-only. Location and mapset are recommend to be used as positional.

## grass.experimental.mapset module

Session or subsession for mapsets (subprojects)

class grass.experimental.mapset.MapsetSession(name, *, create=False, overwrite=False, ensure=False, env=None)

  Bases: `object`

  Session in another mapset in the same location

  By default, it assumes that the mapset exists and raises ValueError otherwise. Use create to create a new mapset and add overwrite to delete an existing one of the same name (with all the data in it) before the new one is created. To use an existing mapset if it exist and create it if it doesn’t exist, use ensure.

  Note that ensure will not create a new mapset if the current is invalid. Invalid mapset may mean corrupt data, so it is not clear what to do. Using create with overwrite will work on an invalid mapset because the existing mapset is always deleted with overwrite enabled.

  Standard use of the object is to use it as a context manager, i.e., create it using the `with` statement. Then use its env property to pass the environment variables for the session to subprocesses:

      >>> with MapsetSession(name, ensure=True) as session:
      ...     run_command("r.surf.fractal", output="surface", env=session.env)

  This session expects an existing GRASS runtime environment.

  The name argument is positional-only.

  Added in version 8.4.

  Starts the session and creates the mapset if requested

  property active

    True if session is active (i.e., not finished)

  property env

    Mapping object with environment variables

    This is suitable for subprocess which should run this mapset.

  finish()

    Finish the session.

    If not used as a context manager, call explicitly to clean and close the mapset and finish the session. No GRASS modules can be called afterwards with the environment obtained from this object.

  property name

    Mapset name

class grass.experimental.mapset.TemporaryMapsetSession(*, location=None, env=None)

  Bases: `object`

  Session in another mapset in the same location

  By default, it assumes that the mapset exists and raises ValueError otherwise. Use create to create a new mapset and add overwrite to delete an existing one of the same name (with all the data in it) before the new one is created. To use an existing mapset if it exist and create it if it doesn’t exist, use ensure.

  Note that ensure will not create a new mapset if the current is invalid. Invalid mapset may mean corrupt data, so it is not clear what to do. Using create with overwrite will work on an invalid mapset because the existing mapset is always deleted with overwrite enabled.

  Standard use of the object is to use it as a context manager, i.e., create it using the `with` statement. Then use its env property to pass the environment variables for the session to subprocesses:

      >>> with MapsetSession(name, ensure=True) as session:
      ...     run_command("r.surf.fractal", output="surface", env=session.env)

  The name argument is positional-only.

  Added in version 8.4.

  Starts the session and creates the mapset if requested

  property active

    True if session is active (i.e., not finished)

  property env

    Mapping object with environment variables

    This is suitable for subprocess which should run this mapset.

  finish()

    Finish the session.

    If not used as a context manager, call explicitly to clean and close the mapset and finish the session. No GRASS modules can be called afterwards with the environment obtained from this object.

  property mapset_path

    MapsetPath

  property name

    Mapset name

Help Index | Topics Index | Keywords Index | Full Index

© 2003-2026 GRASS Development Team, GRASS GIS 8.4.3dev Reference Manual