opentau.configs.parser

Command-line argument parsing and configuration loading utilities.

This module provides utilities for parsing command-line arguments, loading configuration files from local paths or the HuggingFace Hub, and handling plugin discovery and loading. It extends draccus functionality with support for path-based configuration loading and plugin system integration.

Functions

filter_arg(field_to_filter[, args])

Filter out arguments matching a specific field name.

filter_distributed_args([args])

Filter out distributed training arguments.

filter_path_args(fields_to_filter[, args])

Filter command-line arguments related to fields with specific path arguments.

get_cli_overrides(field_name[, args])

Parse arguments from CLI at a given nested attribute level.

get_path_arg(field_name[, args])

Get the path argument for a given field name.

get_type_arg(field_name[, args])

Get the type argument for a given field name.

load_plugin(plugin_path)

Load and initialize a plugin from a given Python package path.

parse_arg(arg_name[, args])

Parse a single command-line argument value.

parse_plugin_args(plugin_arg_suffix, args)

Parse plugin-related arguments from command-line arguments.

wrap([config_path])

Wrap a function to handle configuration parsing with enhanced features.

Exceptions

PluginLoadError

Raised when a plugin fails to load.
exception opentau.configs.parser.PluginLoadError[source]

Bases: Exception

Raised when a plugin fails to load.

opentau.configs.parser.filter_arg(field_to_filter: str, args: Sequence[str] | None = None) → list[str][source]

Filter out arguments matching a specific field name.

Parameters:

  • field_to_filter – The field name to filter out (without the ‘–’ prefix).

  • args – Sequence of command-line arguments to filter. If None, uses sys.argv[1:]. Defaults to None.

Returns:

List of arguments with the specified field filtered out.

Example

For [’–batch_size=32’, ‘–lr=0.001’, ‘–batch_size=64’]: filter_arg(‘batch_size’) returns [’–lr=0.001’].

opentau.configs.parser.filter_distributed_args(args: Sequence[str] | None = None) → list[str][source]

Filter out distributed training arguments.

This function removes arguments that are automatically injected by distributed training frameworks (e.g., DeepSpeed, torchrun) but not recognized by the custom argument parser.

Parameters:

args – The sequence of command-line arguments to be filtered. If None, uses sys.argv[1:]. Defaults to None.

Returns:

A filtered list of arguments with distributed training arguments removed.

Note

Filtered arguments include: local_rank, node_rank, master_addr, master_port, world_size, and rank.

opentau.configs.parser.filter_path_args(fields_to_filter: str | list[str], args: Sequence[str] | None = None) → list[str][source]

Filter command-line arguments related to fields with specific path arguments.

This function removes all arguments related to specified fields when a path argument is present for those fields. It also validates that path and type arguments are not both specified for the same field.

Parameters:

  • fields_to_filter – A single field name or a list of field names whose arguments need to be filtered.

  • args – The sequence of command-line arguments to be filtered. If None, uses sys.argv[1:]. Defaults to None.

Returns:

A filtered list of arguments, with arguments related to the specified fields removed.

Raises:

ArgumentError – If both a path argument (e.g., –field_name.path) and a type argument (e.g., –field_name.type) are specified for the same field.

opentau.configs.parser.get_cli_overrides(field_name: str, args: Sequence[str] | None = None) → list[str] | None[source]

Parse arguments from CLI at a given nested attribute level.

This function extracts command-line arguments that are nested under a specific field name and returns them with the field name prefix removed.

Parameters:

  • field_name – The field name to extract nested arguments for.

  • args – Sequence of command-line arguments to parse. If None, uses sys.argv[1:]. Defaults to None.

Returns:

List of denested arguments with the field name prefix removed, or None if no matching arguments are found.

Example

Supposing the main script was called with: ` python myscript.py --arg1=1 --arg2.subarg1=abc --arg2.subarg2=some/path `

If called during execution of myscript.py, get_cli_overrides(“arg2”) will return: ` ["--subarg1=abc", "--subarg2=some/path"] `

opentau.configs.parser.get_path_arg(field_name: str, args: Sequence[str] | None = None) → str | None[source]

Get the path argument for a given field name.

This function extracts the path argument for a field, which is typically specified as –field_name.path=some/path.

Parameters:

  • field_name – The field name to get the path argument for.

  • args – Sequence of command-line arguments to parse. If None, uses sys.argv[1:]. Defaults to None.

Returns:

The path value if found, or None if not found.

Example

For –policy.path=/path/to/config, get_path_arg(‘policy’) returns ‘/path/to/config’.

opentau.configs.parser.get_type_arg(field_name: str, args: Sequence[str] | None = None) → str | None[source]

Get the type argument for a given field name.

This function extracts the type argument for a field, which is typically specified as –field_name.type=SomeType.

Parameters:

  • field_name – The field name to get the type argument for.

  • args – Sequence of command-line arguments to parse. If None, uses sys.argv[1:]. Defaults to None.

Returns:

The type value if found, or None if not found.

Example

For –policy.type=Pi0Config, get_type_arg(‘policy’) returns ‘Pi0Config’.

opentau.configs.parser.load_plugin(plugin_path: str) → None[source]

Load and initialize a plugin from a given Python package path.

This function attempts to load a plugin by importing its package and any submodules. Plugin registration is expected to happen during package initialization, i.e. when the package is imported the gym environment should be registered and the config classes registered with their parents using the register_subclass decorator.

Parameters:

plugin_path (str) – The Python package path to the plugin (e.g. “mypackage.plugins.myplugin”)

Raises:

PluginLoadError – If the plugin cannot be loaded due to import errors or if the package path is invalid.

Examples

>>> load_plugin("external_plugin.core")       # Loads plugin from external package

Notes

  • The plugin package should handle its own registration during import

  • All submodules in the plugin package will be imported

  • Implementation follows the plugin discovery pattern from Python packaging guidelines

See also

https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/

opentau.configs.parser.parse_arg(arg_name: str, args: Sequence[str] | None = None) → str | None[source]

Parse a single command-line argument value.

Parameters:

  • arg_name – Name of the argument to parse (without the ‘–’ prefix).

  • args – Sequence of command-line arguments to parse. If None, uses sys.argv[1:]. Defaults to None.

Returns:

The value of the argument if found, or None if not found.

Example

For command-line arguments [’–batch_size=32’, ‘–lr=0.001’]: - parse_arg(‘batch_size’) returns ‘32’ - parse_arg(‘lr’) returns ‘0.001’ - parse_arg(‘missing’) returns None

opentau.configs.parser.parse_plugin_args(plugin_arg_suffix: str, args: Sequence[str]) → dict[source]

Parse plugin-related arguments from command-line arguments.

This function extracts arguments from command-line arguments that match a specified suffix pattern. It processes arguments in the format ‘–key=value’ and returns them as a dictionary.

Parameters:

  • plugin_arg_suffix (str) – The suffix to identify plugin-related arguments.

  • cli_args (Sequence[str]) – A sequence of command-line arguments to parse.

Returns:

A dictionary containing the parsed plugin arguments where:

  • Keys are the argument names (with ‘–’ prefix removed if present)

  • Values are the corresponding argument values

Return type:

dict

Example

>>> args = ['--env.discover_packages_path=my_package',
...         '--other_arg=value']
>>> parse_plugin_args('discover_packages_path', args)
{'env.discover_packages_path': 'my_package'}
opentau.configs.parser.wrap(config_path: Path | None = None)[source]

Wrap a function to handle configuration parsing with enhanced features.

This decorator is similar to draccus.wrap but provides three additional features:

  1. Removes ‘.path’ arguments from CLI to process them later

  2. If a ‘config_path’ is passed and the main config class has a ‘from_pretrained’ method, initializes it from there to allow fetching configs from the hub directly

  3. Loads plugins specified in CLI arguments. These plugins typically register their own subclasses of config classes, so that draccus can find the right class to instantiate from the CLI ‘.type’ arguments

Parameters:

config_path – Optional path to a configuration file. If provided and the config class supports from_pretrained, will load from this path. Defaults to None.

Returns:

A decorator function that wraps the target function with enhanced configuration parsing capabilities.

Note

This is a HACK wrapper around draccus.wrap to add custom functionality.