hydra.overlay.python.dsl.meta.phantoms module

Term-level DSL which makes use of phantom types.

Use this DSL for defining programs as opposed to data type definitions. The phantom types provide static type checking in Python prior to Hydra’s runtime type checking.

hydra.overlay.python.dsl.meta.phantoms.annot(key: Name, mvalue: object, term: TypedTerm[A]) → TypedTerm[A]

Add an annotation to a term.

hydra.overlay.python.dsl.meta.phantoms.apply(fun: TypedTerm[A], arg: TypedTerm[B]) → TypedTerm[C]

Apply a function to an argument.

hydra.overlay.python.dsl.meta.phantoms.binary_function(f) → TypedTerm[A]

Extract a binary function from a function application.

hydra.overlay.python.dsl.meta.phantoms.bindings(*pairs) → list[Field]

Sugar for building a list of bindings from (name, value) tuples or Field objects.

Examples

bindings((“x”, val1), (“y”, val2)) → [Field(“x”, val1.value), Field(“y”, val2.value)] bindings(field(“x”, val1), (“y”, val2)) → works with mixed forms

hydra.overlay.python.dsl.meta.phantoms.cases(name, dflt: object = None, fields: Sequence[Field] = ()) → TypedTerm[A]

Create a pattern match on a union term. Accepts str or Name.

hydra.overlay.python.dsl.meta.phantoms.compose(f: TypedTerm[B], g: TypedTerm[A]) → TypedTerm[C]

Compose two functions (g then f).

hydra.overlay.python.dsl.meta.phantoms.constant(term: TypedTerm[A]) → TypedTerm[B]

Create a constant function that always returns the same value.

hydra.overlay.python.dsl.meta.phantoms.definition_in_module(mod: Module, lname: str, term: TypedTerm[A]) → TypedBinding[A]

Create a definition in a module.

hydra.overlay.python.dsl.meta.phantoms.definition_in_namespace(ns: ModuleName, lname: str, term: TypedTerm[A]) → TypedBinding[A]

Create a definition in a namespace, returning a TypedBinding.

hydra.overlay.python.dsl.meta.phantoms.derive_primitive_name() → Name

Automatically derive the primitive name from the calling function’s context.

Uses introspection to get: - Function name from the call stack - Module name to extract the library name

Returns:

The fully qualified primitive name (e.g., “hydra.lib.strings.fromList”)

hydra.overlay.python.dsl.meta.phantoms.doc(s: str, term: TypedTerm[A]) → TypedTerm[A]

Add documentation to a term, returning the annotated TypedTerm.

hydra.overlay.python.dsl.meta.phantoms.doc_wrapped(length: int, s: str, term: TypedTerm[A]) → TypedTerm[A]

Add documentation with line wrapping at the specified width.

hydra.overlay.python.dsl.meta.phantoms.el(binding: TypedBinding[A]) → Binding

Convert a typed element to an untyped element.

hydra.overlay.python.dsl.meta.phantoms.field(fname, val: TypedTerm[A]) → Field

Create a field with the given name and value. Accepts str or Name.

hydra.overlay.python.dsl.meta.phantoms.field_name_op(fname, d: TypedTerm[A]) → Field

Field definition operator with pre-constructed name: fname>>: value.

hydra.overlay.python.dsl.meta.phantoms.field_op(name: str, term: TypedTerm[A]) → Field

Field definition operator: name>: value.

hydra.overlay.python.dsl.meta.phantoms.first(pair: TypedTerm[tuple[A, B]]) → TypedTerm[A]

First element projection function for pairs.

hydra.overlay.python.dsl.meta.phantoms.first_class_type(typ: TypedTerm[Type]) → TypedTerm[Type]

Mark a type as first-class.

hydra.overlay.python.dsl.meta.phantoms.fold(f: TypedTerm[A]) → TypedTerm[B]

Create a fold function to process lists.

hydra.overlay.python.dsl.meta.phantoms.identity() → TypedTerm[A]

Identity function that returns its argument unchanged.

hydra.overlay.python.dsl.meta.phantoms.inject(name, fname, term: TypedTerm[A]) → TypedTerm[B]

Create a union injection. Accepts str or Name for type/field names.

hydra.overlay.python.dsl.meta.phantoms.inject_lambda(name, fname) → TypedTerm[A]

Create a function that injects its argument into a union variant.

hydra.overlay.python.dsl.meta.phantoms.inject_unit(name, fname) → TypedTerm[A]

Create a unit injection of a union. Accepts str or Name.

hydra.overlay.python.dsl.meta.phantoms.just(term: TypedTerm[A]) → TypedTerm[object]

Create a ‘Given’ optional value.

hydra.overlay.python.dsl.meta.phantoms.just_() → TypedTerm[A]

Function that wraps a value in ‘Given’.

hydra.overlay.python.dsl.meta.phantoms.lam(v: str, body: TypedTerm[X]) → TypedTerm[A]

Create a lambda function with one parameter.

hydra.overlay.python.dsl.meta.phantoms.lambdas(params: Sequence[str], body: TypedTerm[X]) → TypedTerm[A]

Create a multi-parameter lambda function.

hydra.overlay.python.dsl.meta.phantoms.left(term: TypedTerm[A]) → TypedTerm[A]

Create a ‘Left’ either value.

hydra.overlay.python.dsl.meta.phantoms.left_() → TypedTerm[A]

Function that wraps a value in ‘Left’.

hydra.overlay.python.dsl.meta.phantoms.let(name: str, value: TypedTerm[A], env: TypedTerm[B]) → TypedTerm[B]

Create a let expression with a single binding.

hydra.overlay.python.dsl.meta.phantoms.let1(name: str, value: TypedTerm[A], env: TypedTerm[B]) → TypedTerm[B]

Create a let expression with a single binding (alias for let with explicit args).

hydra.overlay.python.dsl.meta.phantoms.let_chain(pairs, body: TypedTerm[A]) → TypedTerm[A]

Emit nested singleton lets (matches Haskell’s <~ chaining).

Each pair is (name, value). Reverses the list to build inside-out so the first pair is the outermost binding (in scope for all subsequent ones).

hydra.overlay.python.dsl.meta.phantoms.lets(fields: Sequence[Field], env: TypedTerm[A]) → TypedTerm[A]

Create a let expression with multiple bindings.

hydra.overlay.python.dsl.meta.phantoms.lib_primitive() → TypedTerm

Automatically derive and apply a library primitive with no arguments.

The primitive name is derived from the calling function’s name and module.

hydra.overlay.python.dsl.meta.phantoms.lib_primitive1(a: TypedTerm) → TypedTerm

Automatically derive and apply a library primitive with one argument.

The primitive name is derived from the calling function’s name and module.

hydra.overlay.python.dsl.meta.phantoms.lib_primitive2(a: TypedTerm, b: TypedTerm) → TypedTerm

Automatically derive and apply a library primitive with two arguments.

The primitive name is derived from the calling function’s name and module.

hydra.overlay.python.dsl.meta.phantoms.lib_primitive3(a: TypedTerm, b: TypedTerm, c: TypedTerm) → TypedTerm

Automatically derive and apply a library primitive with three arguments.

The primitive name is derived from the calling function’s name and module.

hydra.overlay.python.dsl.meta.phantoms.list_(els: Sequence[TypedTerm[A]]) → TypedTerm[list[A]]

Create a list of terms.

hydra.overlay.python.dsl.meta.phantoms.make_local(ns: ModuleName)

Create a local reference function for a namespace.

Returns a function that takes a local name and produces a TypedTerm variable reference with the full qualified name. Use this for recursive or forward references within a module.

Usage:

local = make_local(ns) … .to(local(“rewriteTerm”) @ var(“rewrite”) @ var(“term”))

hydra.overlay.python.dsl.meta.phantoms.map_(m: Mapping[TypedTerm[A], TypedTerm[B]]) → TypedTerm[dict[A, B]]

Create a map/dictionary term.

hydra.overlay.python.dsl.meta.phantoms.match(name, arg: TypedTerm[A], dflt: object = None, fields: Sequence[Field] = ()) → TypedTerm[B]

Apply a named case match to an argument.

Accepts a str or Name. Without a default, pass dflt=None (treated as None_()). With a default, pass dflt=Given(default_tterm) or use match_with_default(…).

hydra.overlay.python.dsl.meta.phantoms.match_with_default(name, arg: TypedTerm[A], default: TypedTerm[B], *fields: Field) → TypedTerm[B]

Apply a named case match with a default branch.

Java-style alternative to match(name, arg, Given(default), [f1, f2, …]). Accepts variadic field args for ergonomics.

hydra.overlay.python.dsl.meta.phantoms.module_name(mod: Module) → ModuleName

Get the namespace from a module.

hydra.overlay.python.dsl.meta.phantoms.nothing() → TypedTerm[object]

Create a ‘None_’ optional value.

hydra.overlay.python.dsl.meta.phantoms.opt(mc: object) → TypedTerm[object]

Create an optional value from an optional.

hydra.overlay.python.dsl.meta.phantoms.opt_cases(arg: TypedTerm[object], if_nothing: TypedTerm[B], if_just: TypedTerm[A]) → TypedTerm[B]

Pattern match on an optional value.

hydra.overlay.python.dsl.meta.phantoms.pair(l: TypedTerm[A], r: TypedTerm[B]) → TypedTerm[tuple[A, B]]

Create a pair (2-tuple).

hydra.overlay.python.dsl.meta.phantoms.primitive(prim_name: Name) → TypedTerm[A]

Primitive function by name.

hydra.overlay.python.dsl.meta.phantoms.primitive1(prim_name: Name, a: TypedTerm[A]) → TypedTerm[B]

Apply a primitive function to one argument.

hydra.overlay.python.dsl.meta.phantoms.primitive2(prim_name: Name, a: TypedTerm[A], b: TypedTerm[B]) → TypedTerm[C]

Apply a primitive function to two arguments.

hydra.overlay.python.dsl.meta.phantoms.primitive3(prim_name: Name, a: TypedTerm[A], b: TypedTerm[B], c: TypedTerm[C]) → TypedTerm[X]

Apply a primitive function to three arguments.

hydra.overlay.python.dsl.meta.phantoms.project(name, fname) → TypedTerm[A]

Extract a field from a record. Accepts str or Name.

hydra.overlay.python.dsl.meta.phantoms.record(name, fields: Sequence[Field]) → TypedTerm[A]

Create a record with named fields. Accepts str or Name.

hydra.overlay.python.dsl.meta.phantoms.ref(binding: TypedBinding[A]) → TypedTerm[A]

Reference a defined element.

hydra.overlay.python.dsl.meta.phantoms.right(term: TypedTerm[A]) → TypedTerm[A]

Create a ‘Right’ either value.

hydra.overlay.python.dsl.meta.phantoms.right_() → TypedTerm[A]

Function that wraps a value in ‘Right’.

hydra.overlay.python.dsl.meta.phantoms.second(pair: TypedTerm[tuple[A, B]]) → TypedTerm[B]

Second element projection function for pairs.

hydra.overlay.python.dsl.meta.phantoms.set_(els: Sequence[TypedTerm[A]]) → TypedTerm[set[A]]

Create a set of terms.

hydra.overlay.python.dsl.meta.phantoms.to_binding(tb: TypedBinding[A]) → Binding

Convert a TypedBinding to an untyped Binding for use in module element lists.

This mirrors Haskell’s toBinding and Java’s Phantoms.toBinding().

hydra.overlay.python.dsl.meta.phantoms.to_definition(tb: TypedBinding[A])

Convert a TypedBinding to a term Definition for use in Module.definitions.

Mirrors Haskell’s Hydra.Dsl.Meta.Phantoms.toDefinition.

hydra.overlay.python.dsl.meta.phantoms.to_term_definition(tb: TypedBinding[A])

Convert a TypedBinding to a term Definition (alias for to_definition).

hydra.overlay.python.dsl.meta.phantoms.triple(a: TypedTerm[A], b: TypedTerm[B], c: TypedTerm[C]) → TypedTerm[tuple[A, B, C]]

Create a triple.

hydra.overlay.python.dsl.meta.phantoms.tuple4(a: TypedTerm[A], b: TypedTerm[B], c: TypedTerm[C], d: TypedTerm[X]) → TypedTerm[tuple[A, B, C, X]]

Create a 4-tuple.

hydra.overlay.python.dsl.meta.phantoms.tuple5(a: TypedTerm[A], b: TypedTerm[B], c: TypedTerm[C], d: TypedTerm[X], e: TypedTerm[X]) → TypedTerm[tuple[A, B, C, X, X]]

Create a 5-tuple.

hydra.overlay.python.dsl.meta.phantoms.un_tterm(t: TypedTerm[A]) → Term

Extract the underlying Term from a TypedTerm.

hydra.overlay.python.dsl.meta.phantoms.unary_function(f) → TypedTerm[A]

Extract a unary function from a function application.

hydra.overlay.python.dsl.meta.phantoms.unit() → TypedTerm[A]

Unit value (empty record).

hydra.overlay.python.dsl.meta.phantoms.unqualify_name(qname: QualifiedName) → Name

Convert a QualifiedName to a Name.

hydra.overlay.python.dsl.meta.phantoms.unsafe_cast(t: TypedTerm[A]) → TypedTerm[B]

Cast a TypedTerm to a different phantom type. Used to bridge type inference gaps.

hydra.overlay.python.dsl.meta.phantoms.unwrap(name) → TypedTerm[A]

Create an unwrap function for a wrapped type. Accepts str or Name.

hydra.overlay.python.dsl.meta.phantoms.var(v: str) → TypedTerm[A]

Create a variable reference.

hydra.overlay.python.dsl.meta.phantoms.with_eq(v: str, term: TypedTerm[A]) → TypedTerm[A]

Associate the Eq type class with the inferred type of a term.

hydra.overlay.python.dsl.meta.phantoms.with_ord(v: str, term: TypedTerm[A]) → TypedTerm[A]

Associate the Ord type class with the inferred type of a term.

hydra.overlay.python.dsl.meta.phantoms.with_type_classes(classes: FrozenDict[Name, frozenset], term: TypedTerm[A]) → TypedTerm[A]

Associate type classes with the inferred type of a term.

hydra.overlay.python.dsl.meta.phantoms.wrap(name, term: TypedTerm[A]) → TypedTerm[B]

Create a wrapped term (instance of a newtype). Accepts str or Name.