hydra.overlay.python.dsl.terms module

A DSL for constructing Hydra terms in Python.

hydra.overlay.python.dsl.terms.annot(ann, t: Term) → Term

Attach an annotation to a term.

The ann argument may be either a Mapping[str, Term] (wrapped via annotation_map_as_term per Hydra’s map convention) or an arbitrary Term if the application wants a non-map annotation shape.

Example: annot({“comment”: string(“A User ID”)}, var(“userId”))

hydra.overlay.python.dsl.terms.annotated(t: Term, ann) → Term

Attach an annotation to a term (alternative argument order).

Example: annotated(var(“userId”), {“comment”: string(“A User ID”)})

hydra.overlay.python.dsl.terms.annotation_map_as_term(ann: Mapping[str, Term]) → Term

Wrap a {str -> Term} mapping as a TermMap annotation, the conventional annotation shape (#386 — annotation is now a Term, not a Map<Name, Term>). Each str key becomes a TermVariable with that Name.

hydra.overlay.python.dsl.terms.apply(func: Term, arg: Term) → Term

Apply a function term to an argument.

Example: apply(var(“capitalize”), string(“arthur”))

hydra.overlay.python.dsl.terms.apply_all(func: Term, args: Sequence[Term]) → Term

Apply a function to multiple arguments (curried application).

Example: apply_all(var(“add”), [int32(1), int32(2)])

hydra.overlay.python.dsl.terms.bigint(value: int) → Term

Create a bigint literal.

Example: bigint(9223372036854775808)

hydra.overlay.python.dsl.terms.binary(value: bytes) → Term

Create a binary data literal from bytes.

Example: binary(b’x48x65x00xffx20x7ax1bx80’)

hydra.overlay.python.dsl.terms.boolean(value: bool) → Term

Create a boolean literal.

Example: boolean(True)

hydra.overlay.python.dsl.terms.char(value: str) → Term

Create a character term (represented as int32 code point).

Example: char(‘A’) # Creates int32(65)

hydra.overlay.python.dsl.terms.comparison(comp: Comparison) → Term

Create a comparison result term (lessThan, equalTo, or greaterThan).

hydra.overlay.python.dsl.terms.compose(f: Term, g: Term) → Term

Compose two functions (apply g then f) to create a new function.

Example: compose(var(“stringLength”), var(“toString”)) This creates a function equivalent to: lambda x: stringLength(toString(x)) Function composition applies right-to-left: (f . g)(x) = f(g(x))

hydra.overlay.python.dsl.terms.constant(term: Term) → Term

Create a constant function that always returns the same value.

Example: constant(true()) # A function that always returns True

hydra.overlay.python.dsl.terms.decimal(value: Decimal) → Term

Create a decimal literal (arbitrary-precision exact decimal).

Example: decimal(Decimal(‘1.23’))

hydra.overlay.python.dsl.terms.false() → Term

Boolean false literal.

hydra.overlay.python.dsl.terms.field(n: str, t: Term) → Field

Create a field with the given name and value.

Example: field(“age”, int32(30))

hydra.overlay.python.dsl.terms.fields_to_map(fields: Sequence[Field]) → FrozenDict[Name, Term]

Convert a sequence of fields to a map from names to terms.

hydra.overlay.python.dsl.terms.first() → Term

First element projection function for pairs.

hydra.overlay.python.dsl.terms.float32(value: float) → Term

Create a float32 literal.

Example: float32(3.14)

hydra.overlay.python.dsl.terms.float64(value: float) → Term

Create a float64 literal.

Example: float64(3.14159265359)

hydra.overlay.python.dsl.terms.float_(value: FloatValue) → Term

Create a floating-point literal with specified precision.

Example: float_(FloatValueFloat32(3.14))

hydra.overlay.python.dsl.terms.identity() → Term

Identity function that returns its argument unchanged.

hydra.overlay.python.dsl.terms.inject(tname: Name, fname: Name, term: Term) → Term

Create a union value by injecting a value into a specific variant.

Example: inject(Name(“Result”), Name(“success”), int32(42)) This creates a “Result” union with the “success” variant containing value 42. Use this to construct values of union types at runtime.

hydra.overlay.python.dsl.terms.inject_unit(tname: Name, fname: Name) → Term

Create a unit variant of a union (convenience function).

Example: inject_unit(Name(“Result”), Name(“success”)) Equivalent to inject but automatically uses unit as the value.

hydra.overlay.python.dsl.terms.int16(value: int) → Term

Create an int16 literal.

Example: int16(32767)

hydra.overlay.python.dsl.terms.int32(value: int) → Term

Create an int32 literal.

Example: int32(42)

hydra.overlay.python.dsl.terms.int64(value: int) → Term

Create an int64 literal.

Example: int64(9223372036854775807)

hydra.overlay.python.dsl.terms.int8(value: int) → Term

Create an int8 literal.

Example: int8(127)

hydra.overlay.python.dsl.terms.integer(value: IntegerValue) → Term

Create an integer literal with specified bit width.

Example: integer(IntegerValueInt32(42))

hydra.overlay.python.dsl.terms.just(term: Term) → Term

Create a ‘Given’ optional value.

Example: just(string(“found”))

hydra.overlay.python.dsl.terms.lambda_(param: str, body: Term) → Term

Create a lambda function with one parameter.

Example: lambda_(“x”, apply(var(“x”), int32(1)))

hydra.overlay.python.dsl.terms.lambda_typed(param: str, dom: Type, body: Term) → Term

Create a lambda function with an explicit domain type.

Example: lambda_typed(“x”, Types.int32, list_([var(“x”)]))

hydra.overlay.python.dsl.terms.lambdas(params: Sequence[str], body: Term) → Term

Create a multi-parameter lambda function (curried).

Example: lambdas([“x”, “y”], apply_all(var(“add”), [var(“x”), var(“y”)])) This creates the function: lambda x: lambda y: add(x, y)

hydra.overlay.python.dsl.terms.left(term: Term) → Term

Create a ‘Left’ either value.

Example: left(string(“error”))

hydra.overlay.python.dsl.terms.let_multi(bindings: Sequence[tuple[str, Term]], body: Term) → Term

Create a let expression with multiple bindings.

Example: let_multi([(“x”, int32(1)), (“y”, int32(2))], apply_all(var(“add”), [var(“x”), var(“y”)]))

hydra.overlay.python.dsl.terms.let_term(v: Name, t1: Term, t2: Term) → Term

Create a let expression with a single binding.

hydra.overlay.python.dsl.terms.lets(bindings: Sequence[Field], env: Term) → Term

Create a let term with any number of bindings.

Example: lets([field(“x”, int32(1)), field(“y”, int32(2))], pair(var(“x”), var(“y”)))

hydra.overlay.python.dsl.terms.lets_typed(bindings: Sequence[tuple[str, Term, TypeScheme]], env: Term) → Term

Create a let expression with typed bindings.

hydra.overlay.python.dsl.terms.list_(terms: Sequence[Term]) → Term

Create a list of terms.

Example: list_([int32(1), int32(2), int32(3)])

hydra.overlay.python.dsl.terms.literal(value: Literal) → Term

Create a term from a literal value.

Example: literal(LiteralString(“hello”))

hydra.overlay.python.dsl.terms.map_(terms: Mapping[Term, Term]) → Term

Create a map/dictionary term.

Example: map_({string(“January”): int32(31), string(“February”): int32(28)})

hydra.overlay.python.dsl.terms.map_term(terms: Mapping[Term, Term]) → Term

Create a map/dictionary term (alias for map_).

hydra.overlay.python.dsl.terms.match(tname: Name, def_: object, fields: Sequence[Field]) → Term

Create a pattern match on a union type.

Example: match(Name(“Result”), Given(string(“unknown”)),

[field(“success”, lambda_(“s”, apply(var(“processSuccess”), var(“s”)))),

field(“error”, lambda_(“e”, apply(var(“handleError”), var(“e”))))])

This allows handling different cases of a union type with specific logic for each variant. The optional second parameter provides a default case for any unmatched variants.

Callers pass case branches as Field values (name + handler term); this funnel converts each to a CaseAlternative, so the many field(...) call sites are untouched. Mirrors the Haskell/Java match helpers.

hydra.overlay.python.dsl.terms.match_with_variants(tname: Name, def_: object, pairs: Sequence[tuple[Name, Name]]) → Term

Create a match term that maps variant names to other variants.

hydra.overlay.python.dsl.terms.nothing() → Term

Create a ‘None_’ optional value.

hydra.overlay.python.dsl.terms.optional(term: object) → Term

Create an optional (nullable) term.

Example: optional(Given(string(“found”)))

hydra.overlay.python.dsl.terms.pair(a: Term, b: Term) → Term

Create a pair.

Example: pair(string(“name”), int32(42))

hydra.overlay.python.dsl.terms.primitive(name: Name) → Term

Create a primitive function reference.

Example: primitive(Name(“hydra.lib.strings.length”))

hydra.overlay.python.dsl.terms.project(tname: Name, fname: Name) → Term

Create a field projection function.

Example: project(Name(“Person”), Name(“firstName”))

hydra.overlay.python.dsl.terms.record(tname: Name, fields: Sequence[Field]) → Term

Create a record with named fields of the specified type.

Example: record(Name(“Person”), [

field(“name”, string(“John”)), field(“age”, int32(30)), field(“email”, string(”john@example.com”))])

Records are products of named fields with values that can be accessed by field name.

hydra.overlay.python.dsl.terms.right(term: Term) → Term

Create a ‘Right’ either value.

Example: right(int32(42))

hydra.overlay.python.dsl.terms.second() → Term

Second element projection function for pairs.

hydra.overlay.python.dsl.terms.set_(s: set[Term]) → Term

Create a set of terms.

Example: set_({string(“a”), string(“b”), string(“c”)})

hydra.overlay.python.dsl.terms.string(value: str) → Term

Create a string literal.

Example: string(“hello world”)

hydra.overlay.python.dsl.terms.triple(a: Term, b: Term, c: Term) → Term

Create a triple using nested pairs.

hydra.overlay.python.dsl.terms.true() → Term

Boolean true literal.

hydra.overlay.python.dsl.terms.tuple2(a: Term, b: Term) → Term

Create a 2-tuple (same as pair).

hydra.overlay.python.dsl.terms.tuple3(a: Term, b: Term, c: Term) → Term

Create a 3-tuple using nested pairs.

hydra.overlay.python.dsl.terms.tuple4(a: Term, b: Term, c: Term, d: Term) → Term

Create a 4-tuple using nested pairs.

hydra.overlay.python.dsl.terms.tuple5(a: Term, b: Term, c: Term, d: Term, e: Term) → Term

Create a 5-tuple using nested pairs.

hydra.overlay.python.dsl.terms.tuple_(terms: Sequence[Term]) → Term

Create a tuple using nested pairs.

Example: tuple_([a, b, c]) creates pair(a, pair(b, c))

hydra.overlay.python.dsl.terms.tyapp(term: Term, typ: Type) → Term

Apply a single type argument to a polymorphic term.

hydra.overlay.python.dsl.terms.tyapps(term: Term, types: Sequence[Type]) → Term

Apply type arguments to a polymorphic term (alias for type_application).

hydra.overlay.python.dsl.terms.tylam(var: str, body: Term) → Term

Create a type abstraction with a single type variable.

hydra.overlay.python.dsl.terms.tylams(vars: Sequence[str], body: Term) → Term

Create a type abstraction with multiple type variables.

hydra.overlay.python.dsl.terms.type_application(term: Term, types: Sequence[Type]) → Term

Apply type arguments to a polymorphic term.

Example: type_application(var(“map”), [Types.int32, Types.string]) This instantiates a polymorphic function with concrete types. For instance, if ‘map’ has type ‘forall a b. (a -> b) -> list a -> list b’, the example would instantiate it to ‘(int32 -> string) -> list int32 -> list string’.

hydra.overlay.python.dsl.terms.type_lambda(vars: Sequence[Name], body: Term) → Term

Create a type abstraction (universal quantification).

Example: type_lambda([Name(“a”), Name(“b”)],

lambda_typed(“f”, Types.function(Types.var(“a”), Types.var(“b”)),

lambda_typed(“x”, Types.var(“a”), apply(var(“f”), var(“x”)))))

This creates a polymorphic term with type variables. The example creates a higher-order function with type ‘forall a b. (a -> b) -> a -> b’.

hydra.overlay.python.dsl.terms.uint16(value: int) → Term

Create a uint16 literal.

Example: uint16(65535)

hydra.overlay.python.dsl.terms.uint32(value: int) → Term

Create a uint32 literal.

Example: uint32(4294967295)

hydra.overlay.python.dsl.terms.uint64(value: int) → Term

Create a uint64 literal.

Example: uint64(18446744073709551615)

hydra.overlay.python.dsl.terms.uint8(value: int) → Term

Create a uint8 literal.

Example: uint8(255)

hydra.overlay.python.dsl.terms.unit() → Term

Unit value (empty record).

hydra.overlay.python.dsl.terms.unwrap(name: Name) → Term

Create an unwrap function for a wrapped type.

Example: unwrap(Name(“Email”))

hydra.overlay.python.dsl.terms.var(name: str) → Term

Create a variable reference.

Example: var(“x”)

hydra.overlay.python.dsl.terms.with_variant(tname: Name, fname: Name) → Term

Create a constant function that produces a unit variant.

hydra.overlay.python.dsl.terms.wrap(name: Name, term: Term) → Term

Create a wrapped term (instance of a newtype).

Example: wrap(Name(“Email”), string(”user@example.com”))