[GRASS-git] [OSGeo/grass] de4f00: grass.tools: Return None with no stdout (#6278)

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: de4f00df2769f7ea79d3a7b22779edfc4364b2cc
      https://github.com/OSGeo/grass/commit/de4f00df2769f7ea79d3a7b22779edfc4364b2cc
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-09-03 (Wed, 03 Sep 2025)

  Changed paths:
    M lib/gis/parser_md_python.c
    M python/grass/app/cli.py
    M python/grass/tools/session_tools.py
    M python/grass/tools/support.py
    M python/grass/tools/tests/grass_tools_session_tools_test.py
    M vector/v.colors/tests/test_v_colors.py

  Log Message:
  -----------
  grass.tools: Return None with no stdout (#6278)

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

While this makes even more sense with #5878 (returning NumPy arrays), it would make sense even without it.

Closes #6272.

Provides consistent_return_value parameter to signal that a result should not switch to None, but always be an object. Using long, but very explicit consistent_return_value as a name.

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. Also improves the generated tool documentation: Parameters have space on both sides of colon.



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications