[Docs] Enumerate valid values for time_attr in Tune scheduler docstrings (#32467)

[dstrodtman]

Description

The time_attr docstring across the Tune schedulers said only "you can pass in something non-temporal such as training_iteration", which left users guessing what other keys were actually valid. This PR expands the shared docstring across AsyncHyperBandScheduler, HyperBandScheduler, MedianStoppingRule, PopulationBasedTraining, and PB2 to enumerate the two always-available auto-filled keys (training_iteration and time_total_s) and to state the general rule: any monotonic numeric key reported by the trainable via tune.report({...}) is valid. The schedulers all look up time_attr in the reported result dict (see e.g. AsyncHyperBandScheduler.on_trial_result checking self._time_attr not in result), so the convention is "any reported key".

Documentation-only change; no behavior changes.

Related issues

Closes #32467

[DOC-986]

Additional information

Files touched:

• python/ray/tune/schedulers/async_hyperband.py
• python/ray/tune/schedulers/hyperband.py
• python/ray/tune/schedulers/median_stopping_rule.py
• python/ray/tune/schedulers/pbt.py
• python/ray/tune/schedulers/pb2.py

These five docstrings shared the same template, so the fix is applied to all of them in a single PR. The reporter's issue called out the async_hyperband case specifically, but the wording was identical across the family.

Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the documentation for several Ray Tune schedulers to clarify the usage of progress tracking attributes and the behavior when keys are missing. Feedback indicates that the HyperBandScheduler implementation needs to be updated to gracefully handle missing keys as described in the new docstring to avoid a KeyError. Additionally, suggestions were made to refine the documentation for PB2 and PopulationBasedTraining to accurately reflect that a RuntimeError is raised when require_attrs is enabled, rather than simply skipping the decision step.

[gemini-code-assist]

The docstring states that passing a key not present in the reported result causes the scheduler to skip its decision. However, HyperBandScheduler currently lacks the safety guards present in other schedulers (like AsyncHyperBandScheduler or MedianStoppingRule). Specifically, on_trial_result does not check if time_attr exists in the result dict before calling bracket.update_trial_stats, which leads to a KeyError in _Bracket._get_result_time. To align with this documentation, the implementation should be updated to handle missing keys gracefully.

[gemini-code-assist]

While the docstring states that the scheduler skips its decision if the key is missing, for PopulationBasedTraining this behavior is conditional on the require_attrs parameter. If require_attrs is set to True (the default), the scheduler will raise a RuntimeError if time_attr is missing. It would be more accurate to mention this interaction.

Suggested change

	Passing a key that is not present in the reported result causes
	the scheduler to skip its decision for that step.
	Passing a key that is not present in the reported result causes
	the scheduler to skip its decision for that step (or raise an
	error if ``require_attrs=True``).

[gemini-code-assist]

Similar to PopulationBasedTraining, PB2 uses the require_attrs parameter (defaulting to True). If the key is missing and require_attrs is True, the scheduler will raise a RuntimeError rather than simply skipping its decision. The docstring should reflect this dependency on the require_attrs setting.

Suggested change

	Passing a key that is not present in the reported result causes
	the scheduler to skip its decision for that step.
	Passing a key that is not present in the reported result causes
	the scheduler to skip its decision for that step (or raise an
	error if ``require_attrs=True``).

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