grass.grassdb package — GRASS Python Library documentation

# grass.grassdb package

## Submodules

## grass.grassdb.checks module

Checking objects in a GRASS GIS Spatial Database

(C) 2020 by 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.

grass.grassdb.checks.can_start_in_mapset(mapset_path, ignore_lock=False)

  Check if a mapset from a gisrc file is usable for new session

grass.grassdb.checks.dir_contains_location(path)

  Return True if directory path contains a valid location

grass.grassdb.checks.get_list_of_locations(dbase)

  Get list of GRASS locations in given dbase

  Parameters:

    dbase – GRASS database path

  Returns:

    list of locations (sorted)

grass.grassdb.checks.get_location_invalid_reason(database, location, none_for_no_reason=False)

  Returns a message describing what is wrong with the Location

  The goal is to provide the most suitable error message (rather than to do a quick check).

  By default, when no reason is found, a message about unknown reason is returned. This applies also to the case when this function is called on a valid location (e.g. as a part of larger investigation). `none_for_no_reason=True` allows the function to be used as part of other diagnostic. When this function fails to find reason for invalidity, other the caller can continue the investigation in their context.

  Parameters:

    - database – Path to GRASS GIS database directory

    - location – name of a Location

    - none_for_no_reason – When True, return None when reason is unknown

  Returns:

    translated message or None

grass.grassdb.checks.get_location_invalid_suggestion(database, location)

  Return suggestion what to do when specified location is not valid

  It gives suggestion when:

    - A mapset was specified instead of a location.

    - A GRASS database was specified instead of a location.

grass.grassdb.checks.get_location_name_invalid_reason(grassdb, location_name)

  Get reasons why location name is not valid.

  It gets reasons when:

    - Name is not valid.

    - Location in the same path already exists.

  Returns message as string if there was a reason, otherwise None.

grass.grassdb.checks.get_lockfile_if_present(database, location, mapset)

  Return path to lock if present, None otherwise

  Returns the path as a string or None if nothing was found, so the return value can be used to test if the lock is present.

grass.grassdb.checks.get_mapset_invalid_reason(database, location, mapset, none_for_no_reason=False)

  Returns a message describing what is wrong with the Mapset

  The goal is to provide the most suitable error message (rather than to do a quick check).

  Parameters:

    - database – Path to GRASS GIS database directory

    - location – name of a Location

    - mapset – name of a Mapset

  Returns:

    translated message

grass.grassdb.checks.get_mapset_lock_info(mapset_path)

  Get information about .gislock file. Assumes lock file exists, use is_mapset_locked to find out. Returns information as a dictionary with keys ‘owner’ (None if unknown), ‘lockpath’, and ‘timestamp’.

grass.grassdb.checks.get_mapset_name_invalid_reason(database, location, mapset_name)

  Get reasons why mapset name is not valid.

  It gets reasons when:

    - Name is not valid.

    - Name is reserved for OGR layers.

    - Mapset in the same path already exists.

  Returns message as string if there was a reason, otherwise None.

grass.grassdb.checks.get_mapset_owner(mapset_path)

  Returns mapset owner name or None if owner name unknown. On Windows it always returns None.

grass.grassdb.checks.get_reason_id_mapset_not_usable(mapset_path)

  It finds a reason why mapset is not usable.

  Returns a reason id as a string. If mapset path is None or no reason found, returns None.

grass.grassdb.checks.get_reason_mapset_not_removable(grassdb, location, mapset, check_permanent)

  Get reason why one mapset cannot be removed.

  Parameter check_permanent is True of False. It depends on whether we want to check for permanent mapset or not.

  Returns message as string if there was failed check, otherwise None.

grass.grassdb.checks.get_reasons_grassdb_not_removable(grassdb)

  Get reasons why one grassdb cannot be removed.

  Returns messages as list if there were any failed checks, otherwise empty list.

grass.grassdb.checks.get_reasons_location_not_removable(grassdb, location)

  Get reasons why one location cannot be removed.

  Returns messages as list if there were any failed checks, otherwise empty list.

grass.grassdb.checks.get_reasons_locations_not_removable(locations)

  Get reasons why locations cannot be removed.

  Parameter locations is a list of tuples (database, location).

  Returns messages as list if there were any failed checks, otherwise empty list.

grass.grassdb.checks.get_reasons_mapsets_not_removable(mapsets, check_permanent)

  Get reasons why mapsets cannot be removed.

  Parameter mapsets is a list of tuples (database, location, mapset). Parameter check_permanent is True of False. It depends on whether we want to check for permanent mapset or not.

  Returns messages as list if there were any failed checks, otherwise empty list.

grass.grassdb.checks.is_current_user_mapset_owner(mapset_path)

  Returns True if mapset owner is the current user. On Windows it always returns True.

grass.grassdb.checks.is_different_mapset_owner(mapset_path)

  Returns True if mapset owner is different from the current user

grass.grassdb.checks.is_fallback_session()

  Checks if a user encounters a fallback GRASS session.

  Returns True if a user encounters a fallback session. It occurs when a last mapset is not usable and at the same time a user is in a temporary location.

grass.grassdb.checks.is_first_time_user()

  Check if a user is a first-time user.

  Returns True if a user is a first-time user. It occurs when a gisrc file has initial settings either in last used mapset or in current mapset settings.

grass.grassdb.checks.is_location_current(database, location)

  Return True if the given GRASS Location is the current location

grass.grassdb.checks.is_location_name_valid(database, location_name)

  Check if location name is valid.

  Returns True if location name is valid, otherwise False.

grass.grassdb.checks.is_location_valid(path, location=None)

  Return True if GRASS Location is valid

  Parameters:

    - path – Path to a Location or to a GRASS GIS database directory

    - location – name of a Location if not part of path

grass.grassdb.checks.is_mapset_current(database, location, mapset)

  Return True if the given GRASS Mapset is the current mapset

grass.grassdb.checks.is_mapset_locked(mapset_path)

  Check if the mapset is locked

grass.grassdb.checks.is_mapset_name_valid(database, location, mapset_name)

  Check if mapset name is valid.

  Returns True if mapset name is valid, otherwise False.

grass.grassdb.checks.is_mapset_valid(path, location=None, mapset=None)

  Return True if GRASS Mapset is valid

  Either only path is provided or all three parameters need to be provided.

  Parameters:

    - path – Path to a Mapset or to a GRASS GIS database directory

    - location – name of a Location if not part of path

    - mapset – name of a Mapset if not part of path

grass.grassdb.checks.location_exists(path, location=None)

  Returns True whether location path exists.

  Parameters:

    - path – Path to a Location or to a GRASS GIS database directory

    - location – name of a Location if not part of path

grass.grassdb.checks.mapset_exists(path, location=None, mapset=None)

  Returns True whether mapset path exists.

  Either only path is provided or all three parameters need to be provided.

  Parameters:

    - path – Path to a Mapset or to a GRASS GIS database directory

    - location – name of a Location if not part of path

    - mapset – name of a Mapset if not part of path

## grass.grassdb.config module

Set global variables for objects in a GRASS GIS Spatial Database

(C) 2020 by 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.

## grass.grassdb.create module

Create objects in GRASS GIS Spatial Database

(C) 2020 by 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.

grass.grassdb.create.create_mapset(database, location, mapset)

  Creates a mapset in a specified location

grass.grassdb.create.get_default_mapset_name()

  Returns default name for mapset.

## grass.grassdb.data module

Manipulate data in mapsets in GRASS GIS Spatial Database

(C) 2020 by 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.

grass.grassdb.data.map_exists(name, element, mapset=None, env=None)

  Check is map is present in the mapset given in the environment

  Parameters:

    - name – Name of the map

    - element – Data type (‘raster’, ‘raster_3d’, and ‘vector’)

    - env – Environment created by function grass.script.create_environment

    - mapset – Mapset name, “.” for current mapset only, None for all mapsets in the search path

## grass.grassdb.history module

Managing existing history files included within mapset

(C) 2023 by 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.

class grass.grassdb.history.Status(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `Enum`

  Enum representing a set of status constants that are used to represent various states or command outcomes.

  ABORTED = 'aborted'
  FAILED = 'failed'
  RUNNING = 'running'
  SUCCESS = 'success'
  UNKNOWN = 'unknown'

grass.grassdb.history.add_entry(history_path, entry)

  Add entry to history file.

  Parameters:

    - history_path (str) – path to the history log file

    - entry (dict) – entry consisting of ‘command’ and ‘command_info’ keys

grass.grassdb.history.convert_plain_text_to_JSON(history_path)

  Convert plain text history log to JSON format.

  Parameters:

    history_path (str) – path to the history log file

grass.grassdb.history.copy(history_path, target_path)

  Copy history file to the target location.

  Parameters:

    - history_path (str) – path to the history log file

    - target_path (str) – target location for history log file

  Return boolean:

    True if file is successfully copied

grass.grassdb.history.ensure_history_file(history_path)

  Set up a new GUI history file if it doesn’t exist.

  Parameters:

    history_path (str) – path to the history file

grass.grassdb.history.filter(json_data, command, timestamp)

  Filter JSON history file based on provided command and the time of command launch.

  Parameters:

    - json_data – List of dictionaries representing JSON entries

    - command – First filtering argument representing command as string

    - timestamp – Second filtering argument representing the time of command launch

  Returns:

    Index of entry matching the filter criteria.

grass.grassdb.history.get_current_mapset_gui_history_path()

  Return path to the current mapset history file. This function does not ensure that the file exists.

grass.grassdb.history.get_history_file_extension(history_path)

  Get extension of the history file. The standard long-term format is plain text. Newly it is stored as JSON-formatted.

  Parameters:

    history_path (str) – path to the history log file

  Return str extension:

    None (plain text) or .json

grass.grassdb.history.get_initial_command_info(env_run)

  Get information about the launched command.

  Parameters:

    env_run – environment needed for processing grass command

  Return cmd_info dict:

    initial information about the launched command

grass.grassdb.history.read(history_path)

  Read the content of the history file.

  Parameters:

    history_path (str) – path to the history log file

  Return content_list:

    list of dictionaries

  with ‘command’ and ‘command_info’ keys

grass.grassdb.history.remove_entry(history_path, index)

  Remove entry from history file.

  Parameters:

    - history_path (str) – path to the history log file

    - index (int) – index of the command to be removed

grass.grassdb.history.update_entry(history_path, command_info, index=None)

  Update entry in history file. If index is None it updates a last entry.

  Parameters:

    - history_path (str) – path to the history log file

    - command_info (dict) – command info entry for update

    - index (int|None) – index of the command to be updated

## grass.grassdb.manage module

Managing existing objects in a GRASS GIS Spatial Database

(C) 2020 by 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.

class grass.grassdb.manage.MapsetPath(path, directory, location, mapset)

  Bases: `object`

  This is a representation of a path to mapset.

  Individual components are accessible through read-only properties and objects have an os.PathLike interface.

  Paths are currently stored as is (not resolved, not expanded), but that may change in the future.

  property directory

    Location name

  property location

    Location name

  property mapset

    Mapset name

  property path

    Full path to the mapset as a pathlib.Path object

grass.grassdb.manage.delete_grassdb(database)

  Deletes a specified GRASS database

grass.grassdb.manage.delete_location(database, location)

  Deletes a specified location

grass.grassdb.manage.delete_mapset(database, location, mapset)

  Deletes a specified mapset

grass.grassdb.manage.rename_location(database, old_name, new_name)

  Rename location from old_name to new_name

grass.grassdb.manage.rename_mapset(database, location, old_name, new_name)

  Rename mapset from old_name to new_name

grass.grassdb.manage.resolve_mapset_path(path, location=None, mapset=None) → MapsetPath

  Resolve full path to mapset from given combination of parameters.

  Full or relative path to mapset can be provided as path. If the path points to a valid location instead of a valid mapset, the mapset defaults to PERMANENT.

  Alternatively, location and mapset can be provided separately. In that case, location and mapset are added to the path. If location is provided and mapset is not, mapset defaults to PERMANENT.

  Home represented by `~` (tilde) and relative paths are resolved and the result contains absolute paths.

  The function does not enforce the existence of the directory or that it is a mapset. It only manipulates the paths except for internal checks which help to determine the result in some cases. On Windows, if the path does not exist and `..` is present in the path, it will be not be resolved due to path resolution limitation in the Python pathlib package.

  Returns a MapsetPath object.

grass.grassdb.manage.split_mapset_path(mapset_path)

  Split mapset path to three parts - grassdb, location, mapset

Help Index | Topics Index | Keywords Index | Full Index

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