Optimize data retrieval by using return_path projection

[izkgao]

Description

Companion PRs:
CARTAvis/carta-frontend#2924 (should be merged first)
CARTAvis/carta-backend#1624

This PR reduces redundant frontend state traversal by using return_path projections and a type-specific frontend helper, preserving wrapper behavior while minimizing response payloads and Python-side iteration.

What is implemented:

• Extend return_path documentation and handling descriptions to cover string, list, and mapping projections.
• Refactor image, color-blending, active-view, region-export, and layer-image lookups to request only the fields they need; use the frontend type helper for color blendings.

Examples:

session.get_value("frames", return_path="frameInfo.fileId")
# [0, 1, 2, 3]

session.get_value("frameMap", return_path=["frameInfo.fileId", "center"])
# {'0': {'center': {'x': 5999.5, 'y': 5999.5}, 'frameInfo.fileId': 0},
#  '1': {'center': {'x': 5999.5, 'y': 5999.5}, 'frameInfo.fileId': 1},
#  '2': {'center': {'x': 5999.5, 'y': 5999.5}, 'frameInfo.fileId': 2},
#  '3': {'center': {'x': 215.5, 'y': 215.5}, 'frameInfo.fileId': 3}}

session.get_value("frameMap", return_path={"fileId": "frameInfo.fileId", "center": "center"})
# {'0': {'center': {'x': 5999.5, 'y': 5999.5}, 'fileId': 0},
#  '1': {'center': {'x': 5999.5, 'y': 5999.5}, 'fileId': 1},
#  '2': {'center': {'x': 5999.5, 'y': 5999.5}, 'fileId': 2},
#  '3': {'center': {'x': 215.5, 'y': 215.5}, 'fileId': 3}}

session.call_action("imageViewConfigStore.getImageIdsByType", ImageType.COLOR_BLENDING, response_expected=True)
# [0]

Frontend now provides improved error handling and descriptive error messages:

session.get_value("frames[0]", return_path=42)
# CartaActionFailed: CARTA scripting action .fetchParameter called with parameters (Macro('', 'frameMap[0]'),) failed: Response path not found: 42

session.get_value("frames", return_path=["frameInfo.fileId", "a_non_existing_path"])
# CartaActionFailed: CARTA scripting action .fetchParameter called with parameters (Macro('', 'frameMap'),) failed: Response path not found: a_non_existing_path

session.get_value("frames", return_path=["frameInfo.fileId", False])
# CartaActionFailed: CARTA scripting action .fetchParameter called with parameters (Macro('', 'frameMap'),) failed: Invalid return path at index 1: expected a string, got false

session.get_value("frames")
# CartaActionFailed: CARTA scripting action .fetchParameter called with parameters (Macro('', 'frameMap'),) failed: Response cannot be serialized to JSON because it contains a circular reference or unsupported value. Use return_path to select JSON-serializable fields.

Checklist

For linked issues (if any):

• assignee and labels added
• GitHub Project estimate added

For the pull request:

• reviewers and assignee added
• GitHub Project estimate added
• tests added or updated / no tests needed
• documentation updated / no documentation update needed

For dependencies and compatibility:

• companion frontend or backend PRs linked / no companion PRs needed
• pyproject.toml and uv.lock updated / no dependency changes
• CARTA compatibility table updated when the minimum CARTA series changes
  or dev starts a new carta-python major/minor series / no compatibility
  change

For pull requests targeting main:

• VERSION.txt finalized for the release
• final compatibility entry matches the release major/minor version and
  minimum supported CARTA series

[confluence]

Looks good. This will eliminate a lot of annoyances! :)

[izkgao]

@confluence Now the frontend PR has been merged. The corresponding backend and python PRs could be merged as well when ready.