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

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