Skip to content

Comments

grass.script: Add pack to create_project#6415

Merged
wenzeslaus merged 10 commits intoOSGeo:mainfrom
wenzeslaus:create-project-from-pack
Oct 1, 2025
Merged

grass.script: Add pack to create_project#6415
wenzeslaus merged 10 commits intoOSGeo:mainfrom
wenzeslaus:create-project-from-pack

Conversation

@wenzeslaus
Copy link
Member

@wenzeslaus wenzeslaus commented Sep 26, 2025

This adds another parameter to create_project called pack which allows for creating a project from raster pack files (requires the recent fix from #6408 for the complete CRS info including the computational region addition). Additionally, it refactors general CRS string handling from grass.py so that the pack code is available in the command line, but also that the general handling is available in the Python API.

Because grass/script/core.py can't take any more code, the underlying code is in grass.grassdb.create. This includes both the new functions and refactored code (the code reuses pieces of the XY project creation). Tests are included for the create_project level and separate tests for the underlying grass.grassdb.create level. The new functions include private functions (some of them used in create_project) and public functions (but somewhat internal in grass.grassdb).

The new add/create region function uses the general terms used now in g.region JSON API (#6407), so it is less dependent on the keys in the internal region format.

As part of the refactoring, this moves handling of a general CRS string (aka geostring) from the main executable (grass.py) script to the library, so that library function has the one, universal parameter feature and the CLI has the pack without adding CLI specific code to support pack in CLI.

A new translatable intro error message is now produced in the command line when project creation fails to. The text serves as an into to whatever comes afterwards from the exception (e.g. GDAL output).

Similarly to the main grass.py CLI, this adds the CRS string parameter to the experimental subcommand run. Since the create_function now supports this universal, CLI-friendly way, the addition is just about passing the parameter from command line to the function, so it is easy to add with benefits mostly for testing at this point.

This is adding a separate fixture for grass.app which is the same as the one added to grass.script, but having the fixture at the grass package level interfered with session setups in the grass.app tests. The grass.app fixture is using grass.tools while the grass.script one is written with run_command, so that also makes them different and aligns well with grass.script not using the grass.tools API.

For tests of the subcommands, this uses the standard pytest output capturing fixture, but it also runs the same tests with the subcommand package to capture stdout on Windows in a more reliable way because otherwise srid is not in the JSON from g.proj in the test. We skip rather than xfail the capdf tests on Windows since the issues don't seem to be in our code since subprocess way works just fine, but we use subprocess on all platform for simplicity.

This adds another parameter to create_project which allows for creating a project from raster pack files (requires the recenty fix for the complete CRS info including the computational region addition). The code layout may still change and documentation is needed. grass/script/core.py can't take any more code, but grass.grassdb seems like a good option, so the new functions and refactored code is now there (I needed to reuse pieces of XY project creation).

Tests are included for the create_project level.
@github-actions github-actions bot added Python Related code is in Python libraries tests Related to Test Suite labels Sep 26, 2025
…xecutable script to the library, so that library function has the one, universal parameter feature and the CLI has the pack without adding CLI specific code.
@wenzeslaus
Copy link
Member Author

This also now aligns create_project in Python with how CRS creation parameter is handled in CLI, so pack is available in Python:

import grass.script as gs
gs.create_project("project_1", pack="file.rpack")
import grass.script as gs
gs.create_project("project_1", crs="file.rpack")

...but also in CLI:

grass --tmp-project file.rpack --exec g.proj -p
grass -c file.rpack project_2

And because all that code is in the library now, you can also do (unrelated to pack):

gs.create_project("project_3", crs="EPSG:3358")

...in addition to epsg=3358, so aligned now with grass -c EPSG:3358.

…e the create_function now supports this universal, CLI-friendly way, the addition is just about passing the parameter from command line to the function. Most of the code is for testing. This is adding a separate fixture for grass.app which is the same as the one added to grass.script, but having the fixture at the grass package level interfered with session setups in the grass.app tests. The grass.app fixture is using grass.tools while the grass.script one is written with run_command.
…n't seem to be in our code since subprocess way works just fine.
@wenzeslaus wenzeslaus marked this pull request as ready for review October 1, 2025 03:10
@wenzeslaus
Copy link
Member Author

This is now ready for review.

Allowing:

gs.create_project("project_1", crs="file.grass_raster")

@wenzeslaus wenzeslaus merged commit 33967f9 into OSGeo:main Oct 1, 2025
27 checks passed
@wenzeslaus wenzeslaus deleted the create-project-from-pack branch October 1, 2025 19:55
@github-actions github-actions bot added this to the 8.5.0 milestone Oct 1, 2025
wenzeslaus added a commit to wenzeslaus/grass that referenced this pull request Oct 2, 2025
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.
wenzeslaus added a commit that referenced this pull request Oct 3, 2025
The create_project function is readily available for CLI use especially with the new crs parameter (added in #6415), so this is adding the functionality under as `project create` subcommand. All create_project parameters are exposed, so the user is not limited to what crs parameter can currently handle.

This will be useful in tests of the subcommand CLI itself if we want to use the other subcommands rather than the Python functions in the tests (of subcommands). It is used for lock and unlock tests in #6437.

A --project parameter is added to the run subcommand which now can use existing project instead of creating a new one. This makes subcommand `run --project project/path ...` roughly equivalent to `grass project/path --exec ...`. The functionality is used in the test to check the resulting project CRS.

Example subcomands:
project create --crs EPSG:3358 /tmp/project_1
run --project /tmp/project_1 g.mapset -p

Adds missing documentation for crs parameter of create_project. Also, this uses the description parameter from #6440 not desc.

Implementation of the subcommand now uses StackExit context manager to handle the only-sometimes-needed temporary directory.
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