Add weighted_choice helper for weighted random selection in TPV configs

[davelopez]

Adds a new helpers.weighted_choice(items) function to the TPV evaluation context, enabling weighted random selection of string values from a pool of {value, weight} dictionaries.

Problem

Users with multiple storage paths (e.g., job working directory roots) need a way to distribute jobs across them with configurable weights — steering most jobs to a particular path while keeping a fallback available, or draining a path by setting its weight to 0.

Changes

Core (tpv/core/helpers.py)

• weighted_choice(items) — selects a single value from a weighted pool of dicts. Falls back to unweighted random selection if no non-default weights are defined or all weights are zero.
• _resolve_weights() and _has_weighted_selection() — shared helpers for weight resolution and detection.
• weighted_random_sampling() — refactored to reuse the shared weight helpers, reducing duplication.

Documentation

• docs/topics/tpv_by_example.rst — new recipe: "Selecting a job working directory from a weighted pool" with a full YAML example.
• docs/topics/advanced_topics.rst — new Helper functions reference table documenting all exposed helpers (weighted_choice, weighted_random_sampling, job_args_match, input_size, etc.).

Tests

• tests/test_helpers.py — 8 unit tests covering unweighted fallback, weighted selection, default weights, zero/negative weights, empty list, and return type.
• tests/test_mapper_weighted_choice.py — 2 integration tests verifying weighted_choice works inside a params f-string and sets job_working_directory on the destination.
• tests/fixtures/mapping-weighted-choice.yml — mapping fixture with a jwd_pool context variable.

Usage

global:
  context:
    jwd_pool:
      - value: /fast/jobs
        weight: 3
      - value: /slow/jobs
        weight: 1

tools:
  default:
    params:
      job_working_directory: "{helpers.weighted_choice(jwd_pool)}"

/fast/jobs is selected ~75% of the time. Set weight: 0 to drain a path.

Related

• Galaxy PR implementing job_working_directory job-concern support: galaxyproject/galaxy#23133
• Discussion on job working directory configuration: galaxyproject/galaxy#23107

Notes

• This recipe requires Galaxy's job_working_directory job-concern support (PR #23133). Without it, the param is set by TPV but Galaxy will use the object-store derived path instead.
• The helper is generic over the meaning of value — any string-valued pool (cache paths, runner URLs, etc.) works the same way.