entoscope.script

Experiment scripts.

experiment is importable from entoscope.script and from entoscope.

entoscope.script.experiment.experiment(func: Callable | None = None, *, description: str | None = None) → Callable[source]

Turn main(config: Config) into a command-line entry point.

The config dataclass is taken from the first parameter’s annotation and its fields become --field-name options (see entoscope.script.argument.build_parser). When the decorated function lives in the __main__ module it runs immediately at decoration time, so the config class and DESCRIPTION must be defined above it in the script.

Usable bare, @experiment, or with arguments, @experiment(description=...).

Parameters:

  • func – The experiment function, when used bare.

  • description – The parser’s description. Defaults to a module-level DESCRIPTION, else the function’s docstring.

Returns:

The wrapped function, or a decorator when called with arguments only. The wrapper parses the command line into a config and calls the function with it. It stays callable with an explicit config, main(Config(...)), which bypasses the parser, or with main(argv=[...]), which feeds it.

Raises:

TypeError – If the function’s first parameter is not a config dataclass, or it has another required parameter.

class entoscope.script.argument.DictAction(option_strings, dest, key_type=str, value_type=str, **kwargs)[source]

Bases: Action

Collects key:value tokens into a dict, converting each side with its own type.

Tokens split on the first : only, so values may contain colons. Each occurrence of the option builds a fresh dict (the last one wins), leaving any default dict untouched.

Parameters:

  • option_strings – The option’s flags, as argparse passes them.

  • dest – The attribute to store the dict in.

  • key_type – Converts each key.

  • value_type – Converts each value.

  • **kwargs – The remaining add_argument arguments.

class entoscope.script.argument.TupleAction(option_strings, dest, element_types=(str, ...), **kwargs)[source]

Bases: Action

Collects values into a tuple, converting each position with its own type.

Parameters:

  • option_strings – The option’s flags, as argparse passes them.

  • dest – The attribute to store the tuple in.

  • element_types – typing.get_args of a tuple annotation: (int, str) converts exactly two values positionally, and (int, Ellipsis) converts any number of values with int.

  • **kwargs – The remaining add_argument arguments.

entoscope.script.argument.build_parser(config_cls: type, description: str | None = None) → ArgumentParser[source]

Build an ArgumentParser with one --field-name option per dataclass field.

Type, default and required-ness are derived from the field itself, and anything argparse-specific that cannot be derived (help, choices, …) is read from field.metadata and overrides the derived arguments. list[X] fields become nargs="*" options whose values are converted with X, dict[K, V] fields nargs="*" options taking key:value tokens (see DictAction), tuple[X, Y] fields take exactly that many values converted per position, and tuple[X, ...] any number (see TupleAction). Fields with a default get (default: ...) appended to their help text. Put %(default)s in the metadata help to control its placement instead.

Parameters:

  • config_cls – The config dataclass.

  • description – The parser’s description.

Returns:

The parser.

entoscope.script.argument.parse_config(config_cls: type, argv: Sequence[str] | None = None, description: str | None = None)[source]

Parse a command line into a config.

Parameters:

  • config_cls – The config dataclass.

  • argv – The arguments, sys.argv[1:] when None.

  • description – The parser’s description, shown by --help.

Returns:

An instance of config_cls.