[core] Split task option helpers from _raylet.pyx

[chichic21039]

Why are these changes needed?

This PR addresses #63082, which is a scoped sub-issue related to #51080 after the discussion with @edoakes.

python/ray/_raylet.pyx is a large Cython file that contains multiple groups of helper functions. Some helper functions related to task option preparation, including labels, resource preparation, fallback strategy, function descriptors, and actor concurrency groups, were previously defined directly inside _raylet.pyx.

This PR moves those task option helper functions into a focused Cython include file:

python/ray/includes/task_options_utils.pxi

This is a behavior-preserving refactor. It does not aim to change runtime behavior or improve performance directly. The main goal is to improve maintainability by reducing the size of _raylet.pyx, grouping related task option helper logic in one place, and making future changes easier to review and extend.

What changed?

This PR:

• Adds python/ray/includes/task_options_utils.pxi
• Moves task option/resource/label-related helper functions out of python/ray/_raylet.pyx
• Updates _raylet.pyx to include the new .pxi file
• Keeps existing call sites unchanged
• Preserves the existing helper logic and behavior

The moved helper functions include task option preparation logic such as label handling, resource preparation, fallback strategy handling, function descriptor preparation, and actor concurrency group preparation.

Design rationale

The change keeps the refactor small and focused. Instead of changing task submission behavior or modifying call sites, this PR only relocates a coherent group of helper functions into a dedicated include file.

Although this only extracts a small portion of _raylet.pyx, the extracted code forms a related helper group for task option preparation. Keeping the PR scoped makes it easier to review, lowers the risk of behavioral regressions, and provides a clear pattern for future extractions from the large Cython file.

Related issue number

Closes #63082
Related to #51080

Checks

• git diff --check
• Verified the final diff only changes python/ray/_raylet.pyx and python/ray/includes/task_options_utils.pxi
• Verified _raylet.pyx includes task_options_utils.pxi exactly once
• pip install -e . --verbose from python/

Docs and tests

No user-facing documentation was added because this is an internal behavior-preserving refactor.

No new tests were added because the PR does not introduce new functionality or change existing behavior. The local editable build/install completed successfully with pip install -e . --verbose.

Team contribution note

This PR was prepared as a team contribution for the scoped task option helper refactor.

The work was discussed and split by helper-function groups among team members. The final clean PR branch contains the combined implementation in two signed-off commits:

• ec32208: split task option helper logic into task_options_utils.pxi
• 5d44e1f: move resource and fallback task option helpers into task_options_utils.pxi

Some intermediate work was done on separate team branches before being consolidated into this final PR branch to keep the upstream PR small, clean, and reviewable.

Notes for reviewers

This PR was prepared after the scoped discussion in #51080 and tracked through #63082.

The work was merged into the final PR branch:

split-task-options-utils-pr

[gemini-code-assist]

Code Review

This pull request refactors task option utility functions by moving them from python/ray/_raylet.pyx to a new include file python/ray/includes/task_options_utils.pxi. The review identified several issues in the moved code: a vague error message in prepare_actor_concurrency_groups, a missing except -1 clause for proper exception propagation in Cython, and efficiency and correctness problems in prepare_resources related to redundant list construction and malformed ValueError arguments.

[gemini-code-assist]

The error message "Must provide it..." is vague and not helpful for debugging. It should clearly state that the actor concurrency groups dictionary is missing.

        raise ValueError("Must provide actor concurrency groups dictionary.")

[gemini-code-assist]

The function prepare_actor_concurrency_groups is missing an except clause. In Cython, cdef functions that return a primitive type and can raise Python exceptions should be marked with except -1 (or similar) to ensure proper exception propagation to the caller. Without it, exceptions might be swallowed or only print a warning to stderr.

cdef int prepare_actor_concurrency_groups(
        dict concurrency_groups_dict,
        c_vector[CConcurrencyGroup] *concurrency_groups) except -1:

[gemini-code-assist]

There are two issues in prepare_resources that should be addressed:

1. Efficiency: The unit_resources list is reconstructed in every iteration of the loop (lines 134-139). Since these configuration values are constant for the duration of the call, the list should be moved outside the loop to avoid redundant calculations and string operations.
2. Correctness: The ValueError at lines 143-145 is called with two separate string arguments due to the trailing comma on line 144. This results in the exception message being a tuple of strings (e.g., ('msg1', 'msg2')) instead of a single concatenated string.

cdef int prepare_resources(
        dict resource_dict,
        unordered_map[c_string, double] *resource_map) except -1:
    cdef:
        list unit_resources

    if resource_dict is None:
        raise ValueError("Must provide resource map.")

    unit_resources = (
        f"{RayConfig.instance().predefined_unit_instance_resources().decode('utf-8')},"
        f"{RayConfig.instance().custom_unit_instance_resources().decode('utf-8')}"
    ).split(",")

    resource_map[0].reserve(len(resource_dict))
    for key, value in resource_dict.items():
        if not (isinstance(value, int) or isinstance(value, float)):
            raise ValueError("Resource quantities may only be ints or floats.")
        if value < 0:
            raise ValueError("Resource quantities may not be negative.")
        if value > 0:
            if (value >= 1 and isinstance(value, float)
                    and not value.is_integer() and str(key) in unit_resources):
                raise ValueError(
                    f"{key} resource quantities >1 must "
                    f"be whole numbers. The specified quantity {value} is invalid.")
            resource_map[0][key.encode("ascii")] = float(value)
    return 0

[edoakes]

I've triggered the premerge CI build: https://buildkite.com/ray-project/premerge/builds/65856

[edoakes]

please add docstring comments to the functions as you move them

[chichic21039]

Thanks for the review, I added docstring-style comments for the moved task option helper functions

[chichic21039]

Small follow-up: I also addressed the bot feedback by restoring the original ValueError arguments, so the latest commit should preserve the original behavior. Most checks look good now, but the Buildkite premerge still seems to need maintainer input/approval. Could you please trigger/rerun it for the latest commit when you get a chance? 🙏

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit ec8331d. Configure here.}

[github-actions]

This pull request has been automatically marked as stale because it has not had
any activity for 14 days. It will be closed in another 14 days if no further activity occurs.
Thank you for your contributions.

You can always ask for help on our discussion forum or Ray's public slack channel.

If you'd like to keep this open, just leave any comment, and the stale label will be removed.