grass.app package

exception grass.app.MapsetLockingException

Bases: Exception

grass.app.create_database_directory()

Creates the standard GRASS directory. Creates database directory named grassdata in the standard location according to the platform.

Returns the new path as a string or None if nothing was found or created.

grass.app.create_startup_location_in_grassdb(grassdatabase, startup_location_name) → bool

Create a new startup location in the given GRASS database.

Returns True if a new startup location successfully created in the given GRASS database. Returns False if there is no location to copy in the installation or copying failed.

grass.app.ensure_default_data_hierarchy()

Ensure that default gisdbase, location and mapset exist. Creates database directory based on the default path determined according to OS if needed. Creates location if needed.

Returns the db, loc, mapset, mapset_path

grass.app.get_possible_database_path()

Looks for directory ‘grassdata’ (case-insensitive) in standard locations to detect existing GRASS Database.

Returns the path as a string or None if nothing was found.

grass.app.lock_mapset(mapset_path, *, force_lock_removal, timeout, message_callback, process_id=None, env=None)

Acquire a lock for a mapset and return name of new lock file

Raises MapsetLockingException when it is not possible to acquire a lock for the given mapset either because of existing lock or due to insufficient permissions. A corresponding localized message is given in the exception.

The timeout, process_id, and env parameters are the same as for the acquire_mapset_lock() function. force_lock_removal implies zero timeout.

A message_callback is a function which will be called to report messages about certain states. Specifically, the function is called when forcibly unlocking the mapset.

Assumes that the runtime is set up (specifically that GISBASE is in the environment). Environment can be provided as env.

Raises:

MapsetLockingException – Raised when it is not possible to acquire a lock for the given mapset either because of existing lock or due to insufficient permissions. A corresponding localized message is given in the exception.

Submodules

grass.app.cli module

Experimental low-level CLI interface for the main GRASS executable functionality

This is not a stable part of the API. Contact developers before using it.

grass.app.cli.call_g_manual(**kwargs)

grass.app.cli.main(args=None, program=None)

grass.app.cli.subcommand_lock_mapset(args)

grass.app.cli.subcommand_run_tool(args, tool_args: list, print_help: bool)

grass.app.cli.subcommand_show_help(args)

grass.app.cli.subcommand_show_man(args)

grass.app.cli.subcommand_unlock_mapset(args)

grass.app.data module

Provides functions for the main GRASS executable

3. 2020-2025 by Vaclav Petras and the GRASS Development Team

This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

This is not a stable part of the API. Use at your own risk.

exception grass.app.data.MapsetLockingException

Bases: Exception

grass.app.data.acquire_mapset_lock(mapset_path, *, process_id=None, timeout=30, initial_sleep=1, message_callback=None, env=None)

Lock a mapset and return lock process return code and name of new lock file

Acquires a lock for a mapset by calling the lock program. Returns lock process return code and name of new lock file.

When locking fails, it will re-attempt locking again until it succeeds or it times out. The initial sleep time is used the first time and then it is doubled after each failed attempt. However, the sleep time is limited to thousand times the initial sleep time, so for longer timeouts, the attempts will start happening in equal intervals.

A timeout is the maximum time to wait for the lock to be released in seconds.

A process_id is the process ID of the process locking the mapset. If not given, the current process ID is used.

Parameters:

• mapset_path – full path to the mapset

• process_id – process id to use for locking

• timeout – give up in timeout in seconds

• initial_sleep – initial sleep time in seconds

• message_callback – callback to show messages when locked

• env – system environment variables

The function assumes the GISBASE variable is in the environment. The variable is used to find the lock program. If env is not provided, os.environ is used.

grass.app.data.create_database_directory()

Creates the standard GRASS directory. Creates database directory named grassdata in the standard location according to the platform.

Returns the new path as a string or None if nothing was found or created.

grass.app.data.create_startup_location_in_grassdb(grassdatabase, startup_location_name) → bool

Create a new startup location in the given GRASS database.

Returns True if a new startup location successfully created in the given GRASS database. Returns False if there is no location to copy in the installation or copying failed.

grass.app.data.ensure_default_data_hierarchy()

Ensure that default gisdbase, location and mapset exist. Creates database directory based on the default path determined according to OS if needed. Creates location if needed.

Returns the db, loc, mapset, mapset_path

grass.app.data.get_possible_database_path()

Looks for directory ‘grassdata’ (case-insensitive) in standard locations to detect existing GRASS Database.

Returns the path as a string or None if nothing was found.

grass.app.data.lock_mapset(mapset_path, *, force_lock_removal, timeout, message_callback, process_id=None, env=None)

Acquire a lock for a mapset and return name of new lock file

Raises MapsetLockingException when it is not possible to acquire a lock for the given mapset either because of existing lock or due to insufficient permissions. A corresponding localized message is given in the exception.

The timeout, process_id, and env parameters are the same as for the acquire_mapset_lock() function. force_lock_removal implies zero timeout.

A message_callback is a function which will be called to report messages about certain states. Specifically, the function is called when forcibly unlocking the mapset.

Assumes that the runtime is set up (specifically that GISBASE is in the environment). Environment can be provided as env.

Raises:

MapsetLockingException – Raised when it is not possible to acquire a lock for the given mapset either because of existing lock or due to insufficient permissions. A corresponding localized message is given in the exception.

grass.app.data.unlock_mapset(mapset_path)

Unlock a mapset

grass.app.resource_paths module

Paths to resources and and other GRASS properties, configured during build

3. 2025 by Nicklas Larsson and the GRASS Development Team

SPDX-License-Identifier: GPL-2.0-or-later

This is not a stable part of the API. Use at your own risk.

The “@…@” variables are being substituted during build process

grass.app.runtime module

Provides functions for the main GRASS executable

3. 2024-2025 by Vaclav Petras and the GRASS Development Team

This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

This is not a stable part of the API. Use at your own risk.

class grass.app.runtime.RuntimePaths(env=None)

Bases: object

Get runtime paths to resources and basic GRASS build properties

The resource paths are also set as environmental variables.

property config_projshare

property gisbase

property grass_exe_name

property grass_version_git

property ld_library_path_var

property prefix

property version

property version_major

property version_minor

grass.app.runtime.append_left_addon_paths(paths, config_dir, env)

Add addons to path

grass.app.runtime.append_left_main_executable_paths(paths, install_path)

Add executables to PATH

grass.app.runtime.ensure_home()

Set HOME if not set on MS Windows

grass.app.runtime.get_grass_config_dir(*, env)

Get configuration directory path

Determines path of GRASS user configuration directory for the current platform using the build-time version information.

grass.app.runtime.get_grass_config_dir_for_version(major_version, minor_version, *, env)

Get configuration directory path for specific version

Determines path of GRASS user configuration directory for the current platform and for the provided version.

grass.app.runtime.set_browser(install_path)

Set path to HTML browser

grass.app.runtime.set_defaults(config_projshare_path)

Set paths or commands for dependencies and auxiliary utilities

grass.app.runtime.set_display_defaults()

Predefine monitor size for certain architectures

grass.app.runtime.set_dynamic_library_path(variable_name, install_path, env)

Define path to dynamic libraries (LD_LIBRARY_PATH on Linux)

grass.app.runtime.set_executable_paths(install_path, grass_config_dir, env)

Add paths with executables to PATH in _env_

grass.app.runtime.set_isis()

Enable a mixed ISIS-GRASS environment

ISIS is Integrated Software for Imagers and Spectrometers by USGS.

grass.app.runtime.set_man_path(install_path, addon_base, env)

Set path for the GRASS man pages

grass.app.runtime.set_path_to_python_executable(env)

Set GRASS_PYTHON environment variable

grass.app.runtime.set_paths(install_path, grass_config_dir)

Set variables with executable paths, library paths, and other paths

grass.app.runtime.set_python_path_variable(install_path, env)

Set PYTHONPATH to find GRASS Python package in subprocesses