HParam Fields

yahp.field.auto(constructor: Callable, arg_name: str, doc: Optional[str] = None, ignore_docstring_errors: bool = False)[source]

A field automatically inferred from the docstring and signature.

This helper will automatically parse the docstring and signature of a class or function to determine the documentation entry and default value for a field.

For example:

import dataclasses
import yahp as hp

class Foo:
    '''Foo.

    Args:
        bar (str): Required parameter.
        baz (int, optional): Optional parameter.
    '''

    def __init__(self, bar: str, baz: int = 42):
        self.bar = bar
        self.baz = baz

@dataclasses.dataclass
class FooHparams(hp.Hparams):
    bar: str = hp.auto(Foo, 'bar')  # Equivalent to hp.required(doc='Required parameter.')
    baz: int = hp.auto(Foo, 'baz')  # Equivalent to hp.optional(doc='Optional parameter.', default=42)
Parameters
  • cls (Callable) – The class or function.

  • arg_name (str) – The argument name within the class or function signature and docstring.

  • doc (str, optional) – If provided, use this value for argparse documentation, instead of attempting to extract it from the docstring.

  • ignore_docstring_errors (bool, optional) – If False, ignore any errors from parsing the docstring. Useful if the constructor is in a third-party library.

Returns

A yahp field.

yahp.field.optional(doc: str, *, default: TObject) TObject[source]
yahp.field.optional(doc: str, *, default_factory: Callable[[], TObject]) TObject

An optional field for a yahp.hparams.Hparams.

Parameters
  • doc (str) – A description for the field. This description is printed when YAHP is invoked with the --help CLI flag, and it may be included in generated YAML templates.

  • default – Default value for the field. Cannot be specified with default_factory. Required if default_factory is omitted.

  • default_factory (optional) – A function that returns a default value for the field. Cannot be specified with default. Required if default is omitted.

yahp.field.required(doc: str) Any[source]
yahp.field.required(doc: str, *, template_default: Any) Any

A required field for a Hparams.

Parameters
  • doc (str) – A description for the field. This description is printed when yahp is invoked with the --help CLI flag, and it may be included in generated YAML templates.

  • template_default – Default to use when generating a YAML template. If not specified, no default value is included.