grass.tools: Return None with no stdout#6278
Merged
wenzeslaus merged 4 commits intoOSGeo:mainfrom Sep 3, 2025
Merged
Conversation
When there is no standard output (stdout), return None, instead of returning the ToolResult object. This creates expected result in interactive console and similar cases (notebooks and doctest-tested documentation), i.e., no result for tools which produce no text output (all tools which create spatial data such as r.slope.aspect or r.grow). Closes OSGeo#6272. This also adds description of the returned value to the generated documentation of each tool. We don't have a 'returns' section which would apply to all interfaces, so I went with imperfect soltion of adding 'Returns:' block at the end of Parameters section. This mimics how the block looks like in other Python doc, copying the 'Parameters:' block, but our block does completely fit with our Parameters section and breaks the hiearchy as it is nested under Parameters (but it is not a section heading, so not visible as heading or in toc). It also leave out the indent for the description because we can do this indent only for the first line, so a multiline paragraph would not create a consistent look. It also fixes couple spelling and syntax issues in the doc and adds missing tests related to no stdout. While this makes even more sense with OSGeo#5878 (returning NumPy arrays), it would make sense even without it.
github-actions
bot
added
Python
…tent_result and include examples when it is useful.
petrasovaa
approved these changes
Sep 3, 2025
wenzeslaus
added a commit
that referenced
this pull request
Sep 5, 2025
This is adding NumPy array as input and output to tools when called through the Tools object. My focus with this PR was to create a good API which can be used in various contexts and is useful as is. However, the specifics of the implementation, especially low performance comparing to native data, are secondary issues for me in this addition as long as there is no performance hit for the cases when NumPy arrays are not used which is the case. Even with the performance hits, it works great as a replacement of explicit grass.script.array conversions (same code, just in the background) and in tests (replacing custom tests asserts, and data conversions). While the interface for inputs is clear (the array with data), the interface for outputs was a pick among many choices (type used as a flag over strings, booleans, empty objects, flags). Strict adherence to NumPy universal function was left out as well as control over the actual output array type (a generic array is documented; grass.script.array.array is used now). The NumPy import dependency is optional so that the imports and Tools objects work without NumPy installed. While the tests would fail, GRASS build should work without NumPy as of now. This combines well with the dynamic return value with control over consistency implemented in #6278 as the arrays are one of the possible return types, but can be also made as part of a consistent return type. This lends itself to single array, tuple of arrays, or object with named arrays as possible return types. Overall, this is building on top of Tools class addition in #2923. The big picture is also discussed in #5830.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
When there is no standard output (stdout), return None, instead of returning the ToolResult object.
This creates expected result in interactive console and similar cases (notebooks and doctest-tested documentation),
i.e., no result for tools which produce no text output (all tools which create spatial data such as r.slope.aspect or r.grow).
Closes #6272.
This also adds description of the returned value to the generated documentation of each tool. We don't have a 'returns' section which would apply to all interfaces, so I went with imperfect soltion of adding 'Returns:' block at the end of Parameters section. This mimics how the block looks like in other Python doc, copying the 'Parameters:' block, but our block does completely fit with our Parameters section and breaks the hiearchy as it is nested under Parameters (but it is not a section heading, so not visible as heading or in toc). It also leave out the indent for the description because we can do this indent only for the first line, so a multiline paragraph would not create a consistent look.
It also fixes couple spelling and syntax issues in the doc and adds missing tests related to no stdout.
While this makes even more sense with #5878 (returning NumPy arrays), it would make sense even without it.