# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
"""Typed-preset selection via Hydra-style CLI tokens.
Recognizes three ``key=value`` tokens (no leading dashes) on ``sys.argv``:
* ``physics=NAME`` -- typed selector for ``PhysicsCfg`` variants.
* ``renderer=NAME`` -- typed selector for ``RendererCfg`` variants.
* ``presets=NAME[,NAME,...]`` -- broadcast applied to every matching ``PresetCfg``.
:func:`setup_preset_cli` registers the preset-selection help description on the
parser and runs ``parse_known_args``, returning the verbatim remainder. The
tokens above are passed through unchanged; hydra's
:func:`~isaaclab_tasks.utils.hydra.register_task` parses them directly (applying
the names as presets and enforcing that ``physics=``/``renderer=`` resolve
against a config of that type). Callers simply assign the remainder to
``sys.argv``; no rewriting step is needed.
No argparse arguments are registered for the typed selectors -- discoverability
lives in the ``argument_group`` description, so the parsed Namespace gains no
preset attributes and cannot shadow :class:`~isaaclab.app.AppLauncher`
SimulationApp config keys (``renderer`` notably).
Typical script setup::
parser = argparse.ArgumentParser(...)
# ... script-specific args ...
add_launcher_args(parser)
args_cli, remaining = setup_preset_cli(parser)
sys.argv = [sys.argv[0]] + remaining
Scripts that intersect the remainder with external-callback output (e.g.
``rsl_rl`` scripts' ``--external_callback`` hook) do the intersection on the
remainder before assigning ``sys.argv`` -- both sides share the same token
vocabulary::
args_cli, remaining = setup_preset_cli(parser)
if args_cli.external_callback:
remaining = list_intersection(remaining, external_callback_function())
sys.argv = [sys.argv[0]] + remaining
``setup_preset_cli`` does NOT add AppLauncher flags itself -- callers add them
explicitly via :func:`isaaclab_tasks.utils.add_launcher_args` before calling.
"""
from __future__ import annotations
import argparse
import sys
from .preset_target import PresetTarget
# ============================================================================
# Public entry point
# ============================================================================
[docs]
def setup_preset_cli(
parser: argparse.ArgumentParser, argv: list[str] | None = None
) -> tuple[argparse.Namespace, list[str]]:
"""Register the preset-selection help description and parse argv.
Must be called *after* AppLauncher flags and script-specific arguments are
registered on ``parser`` -- otherwise those unknown tokens land in
``parse_known_args``'s remainder.
The returned remainder contains the user-typed ``physics=`` / ``renderer=``
/ ``presets=`` tokens verbatim, alongside any Hydra path overrides and any
unknown argparse flags, ready to assign to ``sys.argv`` for hydra to parse.
Does not mutate ``sys.argv``; the caller assigns
``sys.argv = [sys.argv[0]] + remaining`` when ready, so any argv-aware logic
that re-reads ``sys.argv`` (e.g. an external callback) runs against the
user's original command line first.
Args:
parser: Caller's argument parser. An ``argument_group`` is attached
for help-time variant discovery; no ``add_argument`` calls are
made, so the Namespace gains no preset attributes.
argv: Optional argument list to parse. When ``None`` (default),
``parse_known_args`` reads from ``sys.argv``. Provided primarily
for in-process test paths that drive the parser with a synthetic
argv. Help-time variant enumeration always reads ``sys.argv`` --
the user's interactive command line is the only argv that
triggers ``--help`` rendering.
Returns:
``(args, remaining)`` where ``remaining`` is the verbatim output of
``parser.parse_known_args(argv)``, ready to hand to Hydra via
``sys.argv``.
"""
# --help short-circuits parsing, so help text that depends on --task has to
# find it before argparse runs. Gate the env_cfg load on --help to keep
# normal training runs cheap.
argv_helper = _ArgvHelper(sys.argv)
actual_variants = (
_enumerate_variants(argv_helper.task_name) if (argv_helper.task_name and argv_helper.help_requested) else None
)
# Argparse's default HelpFormatter reflows description text into one wrapped
# paragraph, which would collapse the per-variant bullets we emit. Use a
# formatter that wraps each blank-line-separated paragraph independently
# while preserving explicit newlines. Respect a caller-set custom formatter.
if parser.formatter_class is argparse.HelpFormatter:
parser.formatter_class = _PresetHelpFormatter
# Help-only group: no add_argument() calls means no preset attributes on
# the Namespace, so AppLauncher can't accidentally forward one (notably
# ``renderer``) into SimulationApp config.
parser.add_argument_group("preset selection", description=_DescriptionBuilder.build(actual_variants))
return parser.parse_known_args(argv)
# ============================================================================
# Public preset enumeration (for tooling, e.g. list_envs)
# ============================================================================
def enumerate_task_presets(task_name: str) -> dict[PresetTarget, list[str]] | None:
"""Return the available preset names for *task_name*, bucketed by selector type.
Loads the env config registered under *task_name* and walks its preset tree
using the same logic that the CLI help-text renderer uses, so the returned
view matches what ``--task=<name> --help`` shows at the command line.
This function is safe to call after :class:`~isaaclab.app.AppLauncher` has
booted (i.e. inside a running Isaac Sim session).
Args:
task_name: Gymnasium task ID (e.g. ``"Isaac-Cartpole-v0"``).
Returns:
A mapping ``{PresetTarget: sorted list of preset names}`` on success.
Returns ``None`` if the env config cannot be loaded (import error,
missing registration, etc.). The ``"default"`` fallback is excluded
from every list because it is implicit, not a user-selectable name.
"""
try:
result = _enumerate_variants(task_name)
return {target: sorted(names) for target, names in result.items()}
except Exception:
return None
# ============================================================================
# Help-text rendering
# ============================================================================
class _PresetHelpFormatter(argparse.HelpFormatter):
"""Argparse help formatter that wraps each paragraph separately.
Default :class:`argparse.HelpFormatter` reflows the entire description into
one paragraph, merging the variant listing into the surrounding prose, and
collapses ``\\n``-separated bullets onto one line.
:class:`~argparse.RawDescriptionHelpFormatter` preserves description
newlines but drops wrapping entirely. The ``_fill_text`` override below
splits the description on blank lines and wraps each paragraph indep-
endently, giving both readable paragraphs and per-line bullets.
"""
def _fill_text(self, text: str, width: int, indent: str) -> str:
import textwrap
paragraphs = text.split("\n\n")
rendered: list[str] = []
for paragraph in paragraphs:
# A paragraph that already contains hard newlines (the bulleted
# variant listing) is rendered verbatim; otherwise word-wrap.
if "\n" in paragraph:
rendered.append("\n".join(f"{indent}{line}" for line in paragraph.splitlines()))
else:
rendered.append(textwrap.fill(paragraph, width, initial_indent=indent, subsequent_indent=indent))
return "\n\n".join(rendered)
class _DescriptionBuilder:
"""Renders the preset-selection ``argument_group`` description.
Groups the column constants and per-row formatting that build the
selector table. Iterates :class:`PresetTarget` to produce one row per
selector; each row's syntax and description come from the enum, so
adding a new typed target needs no changes here.
"""
# Column widths. ``SELECTOR_COL`` = width of the longest selector syntax
# (``presets=NAME[,NAME,...]`` = 23 chars); shorter selectors right-pad
# to this width. ``DESC_GAP`` is the gap between syntax and description.
SELECTOR_COL = 23
DESC_GAP = 3
ROW_PREFIX = " "
INTRO = "Select named PresetCfg alternatives via Hydra-style overrides (key=value, no leading dashes):"
EPILOG = "Hydra also accepts path-targeted overrides like env.sim.physics=NAME."
HINT = "Pass `--task=X` along with `--help` to see preset variants available for that task."
@classmethod
def build(cls, actual_variants: dict[PresetTarget, set[str]] | None) -> str:
"""Build the description text.
Args:
actual_variants: ``None`` when no ``--task=X --help`` is in argv;
otherwise a ``{target: set[name]}`` bucketed view from
:func:`_enumerate_variants`.
"""
with_available = actual_variants is not None
rows = [
cls._row(t, with_available=with_available, variants=sorted((actual_variants or {}).get(t, set())))
for t in PresetTarget
]
middle = f"{cls.HINT}\n\n" if not with_available else ""
return f"{cls.INTRO}\n" + "\n".join(rows) + f"\n\n{middle}{cls.EPILOG}"
@classmethod
def _row(cls, target: PresetTarget, *, with_available: bool, variants: list[str]) -> str:
syntax = cls._syntax(target).ljust(cls.SELECTOR_COL)
desc = cls._description(target)
suffix = ". Available:" if with_available else ""
header = f"{cls.ROW_PREFIX}{syntax}{' ' * cls.DESC_GAP}{desc}{suffix}"
if not with_available:
return header
# Bullet indent aligns with the description column once argparse
# prepends its 2-space group-description indent.
bullet_indent = " " * (len(cls.ROW_PREFIX) + cls.SELECTOR_COL + cls.DESC_GAP)
body = "\n".join(f"{bullet_indent}- {n}" for n in variants) if variants else f"{bullet_indent}(none)"
return f"{header}\n{body}"
@staticmethod
def _syntax(target: PresetTarget) -> str:
"""User-facing selector form: ``physics=NAME`` vs ``presets=NAME[,NAME,...]``."""
if target.base_classes: # typed: single name
return f"{target.value}=NAME"
return f"{target.value}=NAME[,NAME,...]" # DOMAIN: comma-separated broadcast
@staticmethod
def _description(target: PresetTarget) -> str:
"""One-line description; for typed targets includes the cfg base class name."""
if target.base_classes:
return f"(typed) selects a {target.base_classes[0].__name__} variant"
return "broadcast: applied to every matching PresetCfg"
# ============================================================================
# argv inspection (pre-argparse peek for help-text rendering)
# ============================================================================
class _ArgvHelper:
"""Single-pass argv scan that exposes ``task_name`` and ``help_requested``.
Needed because argparse's ``--help`` short-circuits parsing, so help text
that depends on ``--task`` has to find it before argparse runs.
Attributes:
task_name: Last ``--task`` value (matching argparse's last-wins
semantics), or ``None`` if absent.
help_requested: ``True`` if ``--help`` or ``-h`` is present.
"""
def __init__(self, argv: list[str]):
self.task_name: str | None = None
self.help_requested: bool = False
for i in range(1, len(argv)):
token = argv[i]
if token in ("--help", "-h"):
self.help_requested = True
elif token == "--task" and i + 1 < len(argv):
self.task_name = argv[i + 1]
elif token.startswith("--task="):
self.task_name = token[len("--task=") :]
# ============================================================================
# Help-time variant enumeration (load env_cfg, walk, bucket by target)
# ============================================================================
def _enumerate_variants(task_name: str) -> dict[PresetTarget, set[str]]:
"""Load env_cfg for *task_name* and bucket its variants by target.
Uses the same walker hydra's resolver runs so help and resolve see one
view of the cfg tree. The env_cfg load is safe before AppLauncher boots
because ``test_env_cfg_no_forbidden_imports`` blocks Kit-only imports at
the top level of cfg modules. Exceptions from the loader propagate
verbatim -- they surface as the natural error, not a buried help string.
"""
from isaaclab_tasks.utils.hydra import collect_presets
from isaaclab_tasks.utils.parse_cfg import load_cfg_from_registry
env_cfg = load_cfg_from_registry(task_name, "env_cfg_entry_point")
return _bucket_variants_by_target(collect_presets(env_cfg))
def _bucket_variants_by_target(walked: dict) -> dict[PresetTarget, set[str]]:
"""Convert :func:`collect_presets` output into ``{target: set[name]}``.
Routes each ``(name, cfg)`` by ``isinstance(cfg, target.base_classes)``;
cfgs matching no typed target fall into ``DOMAIN``. The implicit
``default`` field is filtered -- it's the fallback, not a selectable name.
Routing by class hierarchy means new backends subclassing
:class:`~isaaclab.physics.PhysicsCfg` /
:class:`~isaaclab.renderers.renderer_cfg.RendererCfg` bucket automatically
regardless of what name the env_cfg gives the field.
"""
typed_targets = [t for t in PresetTarget if t.base_classes]
result: dict[PresetTarget, set[str]] = {target: set() for target in PresetTarget}
for path_dict in walked.values():
for name, cfg in path_dict.items():
if name == "default":
continue
matched = next(
(t for t in typed_targets if isinstance(cfg, t.base_classes)),
PresetTarget.DOMAIN,
)
result[matched].add(name)
return result
