grass.app package¶
- grass.app.create_database_directory()[source]¶
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 [source]¶
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()[source]¶
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()[source]¶
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)[source]¶
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.data module¶
Provides functions for the main GRASS executable
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.
- grass.app.data.acquire_mapset_lock(mapset_path, *, process_id=None, timeout=30, initial_sleep=1, message_callback=None, env=None)[source]¶
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()[source]¶
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 [source]¶
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()[source]¶
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()[source]¶
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)[source]¶
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.resource_paths module¶
Paths to resources and and other GRASS properties, configured during build
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
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)[source]¶
Bases:
object
Get runtime paths to resources and basic GRASS build properties
The resource paths are also set as environmental variables.
- 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_main_executable_paths(paths, install_path)[source]¶
Add executables to PATH
- grass.app.runtime.get_grass_config_dir(major_version, minor_version, env)[source]¶
Get configuration directory
Determines path of GRASS user configuration directory.
- grass.app.runtime.set_defaults(config_projshare_path)[source]¶
Set paths or commands for dependencies and auxiliary utilities
- grass.app.runtime.set_dynamic_library_path(variable_name, install_path, env)[source]¶
Define path to dynamic libraries (LD_LIBRARY_PATH on Linux)
- grass.app.runtime.set_executable_paths(install_path, grass_config_dir, env)[source]¶
Add paths with executables to PATH in _env_
- grass.app.runtime.set_isis()[source]¶
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)[source]¶
Set path for the GRASS man pages