YadOpt Documentation

API Reference

yadopt.parse

def parse(source: str | None,
          argv: list[str] | None = None,
          exit_on_help: bool = True,
          verbose: bool = False) -> YadOptArgs:

def parse(source: type[T],
          argv: list[str] | None = None,
          exit_on_help: bool = True,
          verbose: bool = False) -> T:

Parse an input source and return an appropriate object. This function is overloaded: the former definition assumes a help-message-driven style, while the latter assumes a dataclass-driven style. The source must be either a string or a dataclass type. The return value is either a YadOptArgs instance or an instance of the dataclass type specified by source, which also inherits from YadOptArgs.

yadopt.wrap

def wrap(*pargs: Any,
         **kwargs: Any) -> Callable

The yadopt.wrap decorator enables decorator-based command-line parsing. It wraps a function so that command-line arguments are automatically parsed and passed to the function when it is invoked. This function accepts the same arguments as yadopt.parse. The decorated function must take a YadOptArgs instance as its first parameter. When the decorated function is called, YadOpt parses the command-line arguments and injects the parsed values into the function parameters.

yadopt.save

def save(path: str | Path,
         args: YadOptArgs,
         metadata: bool = True,
         indent: int = 4) -> None

The yadopt.save function serializes a parsed YadOptArgs instance args and writes it to a file on path. Supported file formats include TOML (.toml) and JSON (.json), as well as their compressed variants (.toml.gz and .json.gz). The saved file contains the parsed argument values along with their type information, organized into groups. By default, the output file includes execution metadata such as hostname, username, platform information, Python version, Git commit hash, and a timestamp. To suppress most of this metadata, set metadata=False when calling this function. In that case, only the timestamp is preserved. The indent controls the indent depth of the output files.

yadopt.load

def load(path: str | Path) -> YadOptArgs

The yadopt.load function deserializes a file path that is made by yadopt.save and reconstructs the corresponding YadOptArgs instance. The function supports all formats produced by yadopt.save, including TOML, JSON, and their compressed variants. The loaded object contains the parsed argument values and associated type information. Any additional metadata stored in the file does not affect the reconstruction of the arguments.

yadopt.to_dict

def to_dict(args: YadOptArgs) -> dict[str, Any]

The yadopt.to_dict function converts a YadOptArgs instance into a standard Python dictionary. The returned dictionary contains all parsed arguments and their values. Note that once a YadOptArgs instance is converted to a dictionary, it cannot be restored, since group information is not preserved in the dictionary representation.

yadopt.to_namedtuple

def to_namedtuple(args: YadOptArgs) -> tuple[Any, ...]

The yadopt.to_namedtuple function converts a YadOptArgs instance into an immutable named tuple. The returned named tuple contains all parsed arguments and their values. Note that once a YadOptArgs instance is converted to a named tuple, it cannot be restored, since group information is not preserved in the named tuple representation.

yadopt.get_group

def get_group(args: YadOptArgs,
              group: str) -> YadOptArgs

The yadopt.get_group function extracts a specified section (group) from a parsed YadOptArgs instance and returns it as a new YadOptArgs object. The target group group is identified by its section name (e.g., “Arguments” or “Options”). The returned object retains the same structure and type information as the original YadOptArgs, but only includes the arguments belonging to the specified group.