grass.script: add create_mapset function

[petrasovaa]

Add gs.create_mapset() to grass.script for creating mapsets programmatically in Python (e.g. in jupyter notebooks).
This has been a missing piece with Python jupyter workflows - you create new project, import data, then you want to do the analysis in a different mapset, but calling g.mapset does not match the API style and immediately switches to the new mapset which might not be desired.

The new gs.create_mapset() provides a user-facing API consistent with gs.create_project() — it can run outside of GRASS session, handles validation, overwrite, DB initialization, and supports multiple calling conventions.

There is an existing create_mapset in grass.grassdb.create, but it is a low-level function that only creates the directory and WIND file. The GUI (gui/wxpython/startup/guiutils.py) wraps it with initialize_mapset to also set up the database connection. The CLI (grass mapset create) doesn't initialize the DB at all.

import grass.script as gs                                                                  
                
# Full path
gs.create_mapset("/home/user/grassdata/project/new_mapset")
                                                                                           
# Project path + name
gs.create_mapset("/home/user/grassdata/project", name="new_mapset")                        
                                                                                           
# Name only (within an active session)
gs.create_mapset(name="new_mapset")                                                        
gs.create_mapset(name="new_mapset", env=session.env)                                       
                                                                                           
# Overwrite existing                                                                       
gs.create_mapset(project, name="analysis", overwrite=True)                                 
                
# Skip DB initialization
gs.create_mapset(project, name="tmp", initialize_db=False)
 

Features

• Validates project exists and has PERMANENT mapset
• Validates mapset name using legal_name()
• Rejects creating PERMANENT
• overwrite=True to replace existing mapset
• initialize_db=True (default) runs db.connect -c via Tools API
• env parameter for use with specific sessions, falls back to os.environ
• Raises ScriptError with clear messages for all error cases

[wenzeslaus]

Design:

1. path + triplet vs path + name: I think it is good not to both with the complexities of supporting triplet in a new function.
2. First parameter as always path (current) versus sometimes being a name (create in current project, not in a current directory): Current directory case could still be supported by explicit ./. What is more/less confusing?
3. What parameters are positional only and which are keyword only? (See the comment)
4. Should there be also ensure mapset? I kind of thought it makes the notebook workflows easier, but that's also before we added proper create_project. There is a dedicated function for that if needed. pathlib.Path has some exists_ok for dirs.

Feature parity should be improved: grass mapset create should behave the same as the new create_mapset (e.g. use it).

Parameter alignment: Compare the parameters against create_project, grass.jupter's session switch_mapset, and grass mapset create.

[petrasovaa]

Design:

4. Should there be also ensure mapset? I kind of thought it makes the notebook workflows easier, but that's also before we added proper create_project. There is a dedicated function for that if needed. pathlib.Path has some exists_ok for dirs.

Let's skip this now, create_project would need the same.

Feature parity should be improved: grass mapset create should behave the same as the new create_mapset (e.g. use it).

Done, also added overwrite flag.

Parameter alignment: Compare the parameters against create_project, grass.jupter's session switch_mapset, and grass mapset create.

Went stricter than create_project (positional-only path) since this is a new function with no existing callers; consciously diverging from the triplet style of switch_mapset since create doesn't need it.

create_project has the same all-caps warning in its overwrite docstring — leaving it for a follow-up since this PR is scoped to create_mapset.