grass.experimental package

Experimental code, all can change

class grass.experimental.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.

New 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.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.

New 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

grass.experimental.create_temporary_mapset(path, location=None) → grass.grassdb.manage.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.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.

Submodules

grass.experimental.create module

Likely going into grass.grassdb.create

grass.experimental.create.create_temporary_mapset(path, location=None) → grass.grassdb.manage.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.

New 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.

New 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