Skip to content

Conversation

wenzeslaus
Copy link
Member

For symmetry with project create, this adds a new mapset create subcommand. The mapset subcommand can be used, similarly to project, to group operations related to mapsets.

Locking will be moved under mapset in #6437, so besides the availability of the subcommand for testing of other subcommands, the move of locking is the main motivation for adding the mapset create subcommand now.

The mapset creation uses the semi-internal function grass.grassdb.create.create_mapset. The function parameters were adjusted to allow for a single path being provided (which was already supported through path resolution function, but not supported though the parameters).

There are no parameters yet, and only basic creation and creation failure are handled (no computational region, overwrite, or search path). Tests cover creation and basic expectations of the new mapset, that is being separate from the default mapset, but part of the project.

Example

python -m grass.app project create data/project --crs EPSG:3358
python -m grass.app mapset create data/project/task_1
python -m grass.app run --project data/project/task_1 g.region res=0.1

Assuming #6442:

grass project create data/project --crs EPSG:3358
grass mapset create data/project/task_1
grass run --project data/project/task_1 g.region res=0.1

Comparison with the classic CLI:

grass -c EPSG:3358 data/project -e
grass -c data/project/task_1 -e
grass data/project/task_1 --exec g.region res=0.1

Similarly to the project create subcommand, mapset create makes the create operation more clear, rather than driven by a flag (-c) as additional operation to whatever is the main thing happening, it makes distinction between project and mapset creation explicit (not relying on the combination of path and CRS), and no -e is required to avoid the interactive start. On the other hand, the three commands are always required for the above example (while the classic interface can do it in two, combining the mapset creation with the first tool run).

This enables access to the subcommands from the main command. It keeps the commands not documeneted at the top level, so they remain hidden and experimental.

The lock and unlock, now under 'grass mapset lock' and 'grass mapset unlock', are accessible from outside of GRASS through CLI (no Python API or GRASS tools), providing a way of other applications (such as QGIS) to use GRASS locking when accessing GRASS mapsets.

Given that lock and unlock are under mapset (they are too low level to be at subcommand top level), it is clear there should be also project. The create_project function is readily available for CLI use (espetially after OSGeo#6415), so it is now under 'grass project create' and the subcommand is utilized in tests.

For symmetry, this adds also 'grass mapset create' which uses the semi-internal function grass.grassdb.create.create_mapset. The function parameters were adjusted to allow for a single path being provided (which was already supported through path resolution function).

The create_project function was also improved by adding description parameter as full word replacing (but keeping) desc parameter. The behavior was sligtly changes so that MYNAME is only created when description is provided which is what the documenetation suggests ('desc...creates MYNAME file'), but it was implemented that MYNAME was always created even if empty. Finally, missing documentation for the CRS parameter was added.

The new structure in the cli file is that project and mapset subcommand parser definitions have their own functions. This minimizes name conflicts and keeps the main function short.

Finally, 'grass run' subcommad now has --project to use an existing project (defaulting to PERMANENT mapset) or a mapset within that project. This is needed now for testing the created project using the subcommand interface.
@github-actions github-actions bot added Python Related code is in Python libraries tests Related to Test Suite labels Oct 6, 2025
@wenzeslaus wenzeslaus changed the title Add mapset create subcommand grass.app: Add mapset create subcommand Oct 6, 2025
@wenzeslaus wenzeslaus merged commit 14923ee into OSGeo:main Oct 6, 2025
27 of 28 checks passed
@wenzeslaus wenzeslaus deleted the add-mapset-create-subcommand branch October 6, 2025 14:20
@github-actions github-actions bot added this to the 8.5.0 milestone Oct 6, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
libraries Python Related code is in Python tests Related to Test Suite
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants