eformer.aparser._aparser

eformer.aparser._aparser#

eformer.aparser._aparser.Argu(*, aliases: str | list[str] | None = None, help: str | None = None, default: ~typing.Any = <dataclasses._MISSING_TYPE object>, default_factory: ~typing.Callable[[], ~typing.Any] = <dataclasses._MISSING_TYPE object>, metadata: dict | None = None, **kwargs) → Field[source]#

Create a dataclass field with argument parsing metadata.

A convenience wrapper around dataclasses.field() that adds metadata for command-line argument generation. Use this to specify help text, aliases, and other argparse options for dataclass fields.

Parameters

  • aliases – Alternative command-line names for this argument. Can be a single string or list of strings. Example: aliases=[“-lr”, “–rate”]

  • help – Help text displayed in –help output.

  • default – Default value for the field.

  • default_factory – Factory function for mutable default values.

  • metadata – Additional metadata dictionary to extend.

  • **kwargs – Additional arguments passed to dataclasses.field().

Returns

A dataclass Field object with argument metadata.

Example

>>> from dataclasses import dataclass
>>> from eformer.aparser import Argu, DataClassArgumentParser
>>>
>>> @dataclass
>>> class Config:
...     learning_rate: float = Argu(
...         default=1e-4,
...         aliases=["-lr"],
...         help="Learning rate for optimizer"
...     )
...     output_dir: str = Argu(
...         default="./output",
...         help="Directory for saving outputs"
...     )
>>>
>>> parser = DataClassArgumentParser(Config)
>>> # Can use: --learning-rate 0.01 OR -lr 0.01
class eformer.aparser._aparser.DataClassArgumentParser(dataclass_types: Union[DataClassType, Iterable[DataClassType]], **kwargs: Any)[source]#

Bases: ArgumentParser

ArgumentParser that generates arguments from dataclass type hints.

This class extends argparse.ArgumentParser to automatically create command-line arguments from dataclass field definitions. It supports multiple dataclasses, various field types, and configuration loading from files.

Supported field types:

  • Basic types: str, int, float, bool

  • Optional types: Optional[T] / T | None

  • Literal types: Literal[“a”, “b”, “c”]

  • Enum types: MyEnum with automatic choices

  • List types: list[T] with nargs=”+”

Special handling:

  • Boolean fields get –no-{field} variants when default is True

  • Fields with underscores also accept hyphenated names

  • Aliases can be specified via Argu() metadata

dataclass_types#

List of dataclass types to generate arguments for.

Type

Iterable[eformer.aparser._aparser.DataClassType]

Example

>>> from dataclasses import dataclass
>>> from typing import Literal
>>>
>>> @dataclass
>>> class TrainConfig:
...     batch_size: int = 32
...     learning_rate: float = 1e-4
...     optimizer: Literal["adam", "sgd"] = "adam"
...     use_amp: bool = True
>>>
>>> parser = DataClassArgumentParser(TrainConfig)
>>> config, = parser.parse_args_into_dataclasses(["--batch-size", "64"])
>>> print(config.batch_size)
64
Multiple dataclasses:
>>> parser = DataClassArgumentParser([TrainConfig, ModelConfig])
>>> train_cfg, model_cfg = parser.parse_args_into_dataclasses()
dataclass_types: Iterable[DataClassType]#
parse_args_into_dataclasses(args: list[str] | None = None, return_remaining_strings: bool = False, look_for_args_file: bool = True, args_filename: str | None = None, args_file_flag: str | None = None) → tuple[Any, ...][source]#

Parse command-line arguments into dataclass instances.

Parses arguments and constructs instances of all registered dataclass types. Supports loading additional arguments from files.

Parameters

  • args – List of argument strings. If None, uses sys.argv[1:].

  • return_remaining_strings – If True, include unparsed arguments in output.

  • look_for_args_file – If True, look for a .args file matching the script name.

  • args_filename – Explicit path to an args file to load.

  • args_file_flag – Command-line flag for specifying args file(s).

Returns

Tuple of dataclass instances, one per registered dataclass type. If return_remaining_strings is True, the last element is a list of unparsed argument strings.

Raises

ValueError – If there are unknown arguments and return_remaining_strings is False.

Example

>>> parser = DataClassArgumentParser([TrainConfig, ModelConfig])
>>> train, model = parser.parse_args_into_dataclasses()
>>>
>>> # With remaining args
>>> train, model, remaining = parser.parse_args_into_dataclasses(
...     return_remaining_strings=True
... )
parse_dict(args: dict[str, Any], allow_extra_keys: bool = False) → tuple[Any, ...][source]#

Parse a dictionary of configuration values into dataclass instances.

Useful for programmatic configuration or loading from config files.

Parameters

  • args – Dictionary with keys matching dataclass field names.

  • allow_extra_keys – If True, ignore keys that don’t match any field. If False, raise ValueError for unknown keys.

Returns

Tuple of dataclass instances, one per registered dataclass type.

Raises

ValueError – If allow_extra_keys is False and unknown keys are present.

Example

>>> parser = DataClassArgumentParser(TrainConfig)
>>> config, = parser.parse_dict({
...     "learning_rate": 0.001,
...     "batch_size": 64
... })
parse_json_file(json_file: str | os.PathLike, allow_extra_keys: bool = False) → tuple[Any, ...][source]#

Load a JSON file and parse it into dataclass instances.

Parameters

  • json_file – Path to the JSON configuration file. Supports both local paths and GCS paths (gs://).

  • allow_extra_keys – If True, ignore keys that don’t match any field.

Returns

Tuple of dataclass instances, one per registered dataclass type.

Raises

  • FileNotFoundError – If the JSON file doesn’t exist.

  • json.JSONDecodeError – If the file contains invalid JSON.

  • ValueError – If allow_extra_keys is False and unknown keys are present.

Example

>>> parser = DataClassArgumentParser(TrainConfig)
>>> config, = parser.parse_json_file("config.json")
parse_yaml_file(yaml_file: str | os.PathLike, allow_extra_keys: bool = False) → tuple[Any, ...][source]#

Load a YAML file and parse it into dataclass instances.

Parameters

  • yaml_file – Path to the YAML configuration file.

  • allow_extra_keys – If True, ignore keys that don’t match any field.

Returns

Tuple of dataclass instances, one per registered dataclass type.

Raises

  • FileNotFoundError – If the YAML file doesn’t exist.

  • yaml.YAMLError – If the file contains invalid YAML.

  • ValueError – If allow_extra_keys is False and unknown keys are present.

Example

>>> parser = DataClassArgumentParser(TrainConfig)
>>> config, = parser.parse_yaml_file("config.yaml")
eformer.aparser._aparser.make_choice_type_function(choices: list[Any]) → Callable[[str], Any][source]#

Create a type converter function for argparse choices.

Creates a function that maps string representations back to their original values from a list of choices. This is useful for Literal and Enum types where argparse receives strings but the original values may be different types.

Parameters

choices – List of valid choice values.

Returns

A function that converts a string argument to its corresponding choice value, or returns the original string if no match is found.

Example

>>> converter = make_choice_type_function([1, 2, 3])
>>> converter("2")
2
>>> converter = make_choice_type_function(["small", "large"])
>>> converter("small")
'small'
eformer.aparser._aparser.string_to_bool(v: str | bool) → bool[source]#

Convert a string to a boolean.

Accepts various string representations for truthy and falsy values. Case-insensitive matching is used.

Parameters

v – Value to convert. Can be a string or already a boolean.

Returns

Boolean value corresponding to the input.

Raises

ArgumentTypeError – If the string cannot be interpreted as boolean.

Example

>>> string_to_bool("yes")
True
>>> string_to_bool("false")
False
>>> string_to_bool("1")
True

Accepted truthy values: “yes”, “true”, “t”, “y”, “1” Accepted falsy values: “no”, “false”, “f”, “n”, “0”

Contents