hydra.coders module

Abstractions for paired transformations between languages.

class hydra.coders.Adapter(is_lossy: Annotated[bool, 'Whether information may be lost in the course of this adaptation'], source: Annotated[T1, 'The source type'], target: Annotated[T2, 'The target type'], coder: Annotated[Coder[V1, V2, E], 'The coder for transforming instances of the source type to instances of the target type'])

Bases: Generic[T1, T2, V1, V2, E]

A two-level bidirectional encoder which adapts types to types and terms to terms.

class Builder(_is_lossy: 'bool' = None, _source: 'T1' = None, _target: 'T2' = None, _coder: 'Coder[V1, V2, E]' = None)

Bases: Generic[T1, T2, V1, V2, E]

build()

coder(coder)

is_lossy(is_lossy)

source(source)

target(target)

CODER = Name(value='coder')

IS_LOSSY = Name(value='isLossy')

SOURCE = Name(value='source')

TARGET = Name(value='target')

TYPE_ = Name(value='hydra.coders.Adapter')

static builder()

coder: Annotated[Coder[V1, V2, E], 'The coder for transforming instances of the source type to instances of the target type']

is_lossy: Annotated[bool, 'Whether information may be lost in the course of this adaptation']

source: Annotated[T1, 'The source type']

target: Annotated[T2, 'The target type']

with_coder(coder)

with_is_lossy(is_lossy)

with_source(source)

with_target(target)

class hydra.coders.AdapterContext(graph: Annotated[Graph, 'The underlying graph of elements and primitives'], language: Annotated[Language, 'The language being encoded or decoded'], adapters: Annotated[Mapping[Name, Adapter[Type, Type, Term, Term, Error]], 'A map of type names to adapters for those types'])

Bases: object

An evaluation context together with a source language and a target language.

ADAPTERS = Name(value='adapters')

class Builder(_graph: 'hydra.graph.Graph' = None, _language: 'Language' = None, _adapters: 'Mapping[hydra.core.Name, Adapter[hydra.core.Type, hydra.core.Type, hydra.core.Term, hydra.core.Term, hydra.errors.Error]]' = None)

Bases: object

adapters(adapters)

build()

graph(graph)

language(language)

GRAPH = Name(value='graph')

LANGUAGE = Name(value='language')

TYPE_ = Name(value='hydra.coders.AdapterContext')

adapters: Annotated[Mapping[Name, Adapter[Type, Type, Term, Term, Error]], 'A map of type names to adapters for those types']

static builder()

graph: Annotated[Graph, 'The underlying graph of elements and primitives']

language: Annotated[Language, 'The language being encoded or decoded']

with_adapters(adapters)

with_graph(graph)

with_language(language)

class hydra.coders.Bicoder(encode: Annotated[Callable[[T1], Adapter[T1, T2, V1, V2, E]], 'A function from source types to adapters'], decode: Annotated[Callable[[T2], Adapter[T2, T1, V2, V1, E]], 'A function from target types to adapters'])

Bases: Generic[T1, T2, V1, V2, E]

A two-level encoder and decoder, operating both at a type level and an instance (data) level.

class Builder(_encode: 'Callable[[T1], Adapter[T1, T2, V1, V2, E]]' = None, _decode: 'Callable[[T2], Adapter[T2, T1, V2, V1, E]]' = None)

Bases: Generic[T1, T2, V1, V2, E]

build()

decode(decode)

encode(encode)

DECODE = Name(value='decode')

ENCODE = Name(value='encode')

TYPE_ = Name(value='hydra.coders.Bicoder')

static builder()

decode: Annotated[Callable[[T2], Adapter[T2, T1, V2, V1, E]], 'A function from target types to adapters']

encode: Annotated[Callable[[T1], Adapter[T1, T2, V1, V2, E]], 'A function from source types to adapters']

with_decode(decode)

with_encode(encode)

class hydra.coders.CaseConventions(constant: Annotated[CaseConvention, 'Convention for compile-time constant names'], directory: Annotated[CaseConvention, 'Convention for each directory level in the emitted source tree'], enum_value: Annotated[CaseConvention, 'Convention for enum-variant value names'], field: Annotated[CaseConvention, 'Convention for record field names'], file: Annotated[CaseConvention, 'Convention for the source-file basename'], module: Annotated[CaseConvention, 'Convention for a single segment of a module name'], term: Annotated[CaseConvention, 'Convention for top-level term definitions (functions, module-level values)'], term_variable: Annotated[CaseConvention, 'Convention for locally-bound term names (lambda parameters, let-bindings)'], type: Annotated[CaseConvention, 'Convention for type names'], type_variable: Annotated[CaseConvention, 'Convention for type-level variable names'])

Bases: object

Per-target case conventions for name forms that vary across emission targets.

class Builder(_constant: 'hydra.util.CaseConvention' = None, _directory: 'hydra.util.CaseConvention' = None, _enum_value: 'hydra.util.CaseConvention' = None, _field: 'hydra.util.CaseConvention' = None, _file: 'hydra.util.CaseConvention' = None, _module: 'hydra.util.CaseConvention' = None, _term: 'hydra.util.CaseConvention' = None, _term_variable: 'hydra.util.CaseConvention' = None, _type: 'hydra.util.CaseConvention' = None, _type_variable: 'hydra.util.CaseConvention' = None)

Bases: object

build()

constant(constant)

directory(directory)

enum_value(enum_value)

field(field)

file(file)

module(module)

term(term)

term_variable(term_variable)

type(type)

type_variable(type_variable)

CONSTANT = Name(value='constant')

DIRECTORY = Name(value='directory')

ENUM_VALUE = Name(value='enumValue')

FIELD = Name(value='field')

FILE = Name(value='file')

MODULE = Name(value='module')

TERM = Name(value='term')

TERM_VARIABLE = Name(value='termVariable')

TYPE = Name(value='type')

TYPE_ = Name(value='hydra.coders.CaseConventions')

TYPE_VARIABLE = Name(value='typeVariable')

static builder()

constant: Annotated[CaseConvention, 'Convention for compile-time constant names']

directory: Annotated[CaseConvention, 'Convention for each directory level in the emitted source tree']

enum_value: Annotated[CaseConvention, 'Convention for enum-variant value names']

field: Annotated[CaseConvention, 'Convention for record field names']

file: Annotated[CaseConvention, 'Convention for the source-file basename']

module: Annotated[CaseConvention, 'Convention for a single segment of a module name']

term: Annotated[CaseConvention, 'Convention for top-level term definitions (functions, module-level values)']

term_variable: Annotated[CaseConvention, 'Convention for locally-bound term names (lambda parameters, let-bindings)']

type: Annotated[CaseConvention, 'Convention for type names']

type_variable: Annotated[CaseConvention, 'Convention for type-level variable names']

with_constant(constant)

with_directory(directory)

with_enum_value(enum_value)

with_field(field)

with_file(file)

with_module(module)

with_term(term)

with_term_variable(term_variable)

with_type(type)

with_type_variable(type_variable)

class hydra.coders.Coder(encode: Annotated[Callable[[V1], object], 'A function which encodes a domain value to a codomain value, with the possibility of failure'], decode: Annotated[Callable[[V2], object], 'A function which decodes a codomain value to a domain value, with the possibility of failure'])

Bases: Generic[V1, V2, E]

An encoder and decoder; a pair of partial functions between two types.

class Builder(_encode: 'Callable[[V1], Either[E, V2]]' = None, _decode: 'Callable[[V2], Either[E, V1]]' = None)

Bases: Generic[V1, V2, E]

build()

decode(decode)

encode(encode)

DECODE = Name(value='decode')

ENCODE = Name(value='encode')

TYPE_ = Name(value='hydra.coders.Coder')

static builder()

decode: Annotated[Callable[[V2], object], 'A function which decodes a codomain value to a domain value, with the possibility of failure']

encode: Annotated[Callable[[V1], object], 'A function which encodes a domain value to a codomain value, with the possibility of failure']

with_decode(decode)

with_encode(encode)

class hydra.coders.CoderDirection(*values)

Bases: Enum

Indicates either the ‘out’ or the ‘in’ direction of a coder.

DECODE = Name(value='decode')

ENCODE = Name(value='encode')

TYPE_ = Name(value='hydra.coders.CoderDirection')

class hydra.coders.Language(name: Annotated[LanguageName, 'The unique name of the language'], constraints: Annotated[LanguageConstraints, "Constraints which characterize the language's type and term grammars"], supported_features: Annotated[Set[LanguageFeature], 'Target-language or target-runtime capabilities the emitter may assume are available'], case_conventions: Annotated[CaseConventions, 'Per-target case conventions for the various kinds of identifiers emitted by the coder'], default_file_extension: Annotated[FileExtension, 'Conventional file extension for emitted source files, without the leading dot (e.g. "scala", "py")'])

Bases: object

A named language together with its grammar constraints, capability profile, naming conventions, and conventional file extension.

class Builder(_name: 'LanguageName' = None, _constraints: 'LanguageConstraints' = None, _supported_features: 'Set[LanguageFeature]' = None, _case_conventions: 'CaseConventions' = None, _default_file_extension: 'hydra.file.FileExtension' = None)

Bases: object

build()

case_conventions(case_conventions)

constraints(constraints)

default_file_extension(default_file_extension)

name(name)

supported_features(supported_features)

CASE_CONVENTIONS = Name(value='caseConventions')

CONSTRAINTS = Name(value='constraints')

DEFAULT_FILE_EXTENSION = Name(value='defaultFileExtension')

NAME = Name(value='name')

SUPPORTED_FEATURES = Name(value='supportedFeatures')

TYPE_ = Name(value='hydra.coders.Language')

static builder()

case_conventions: Annotated[CaseConventions, 'Per-target case conventions for the various kinds of identifiers emitted by the coder']

constraints: Annotated[LanguageConstraints, "Constraints which characterize the language's type and term grammars"]

default_file_extension: Annotated[FileExtension, 'Conventional file extension for emitted source files, without the leading dot (e.g. "scala", "py")']

name: Annotated[LanguageName, 'The unique name of the language']

supported_features: Annotated[Set[LanguageFeature], 'Target-language or target-runtime capabilities the emitter may assume are available']

with_case_conventions(case_conventions)

with_constraints(constraints)

with_default_file_extension(default_file_extension)

with_name(name)

with_supported_features(supported_features)

class hydra.coders.LanguageConstraints(literal_variants: Annotated[Set[LiteralVariant], 'All supported literal variants'], float_types: Annotated[Set[FloatType], 'All supported float types'], integer_types: Annotated[Set[IntegerType], 'All supported integer types'], term_variants: Annotated[Set[TermVariant], 'All supported term variants'], type_variants: Annotated[Set[TypeVariant], 'All supported type variants'], types: Annotated[Callable[[Type], bool], 'A logical set of types, as a predicate which tests a type for inclusion'])

Bases: object

A set of constraints on valid type and term expressions, characterizing a language.

class Builder(_literal_variants: 'Set[hydra.variants.LiteralVariant]' = None, _float_types: 'Set[hydra.core.FloatType]' = None, _integer_types: 'Set[hydra.core.IntegerType]' = None, _term_variants: 'Set[hydra.variants.TermVariant]' = None, _type_variants: 'Set[hydra.variants.TypeVariant]' = None, _types: 'Callable[[hydra.core.Type], bool]' = None)

Bases: object

build()

float_types(float_types)

integer_types(integer_types)

literal_variants(literal_variants)

term_variants(term_variants)

type_variants(type_variants)

types(types)

FLOAT_TYPES = Name(value='floatTypes')

INTEGER_TYPES = Name(value='integerTypes')

LITERAL_VARIANTS = Name(value='literalVariants')

TERM_VARIANTS = Name(value='termVariants')

TYPES = Name(value='types')

TYPE_ = Name(value='hydra.coders.LanguageConstraints')

TYPE_VARIANTS = Name(value='typeVariants')

static builder()

float_types: Annotated[Set[FloatType], 'All supported float types']

integer_types: Annotated[Set[IntegerType], 'All supported integer types']

literal_variants: Annotated[Set[LiteralVariant], 'All supported literal variants']

term_variants: Annotated[Set[TermVariant], 'All supported term variants']

type_variants: Annotated[Set[TypeVariant], 'All supported type variants']

types: Annotated[Callable[[Type], bool], 'A logical set of types, as a predicate which tests a type for inclusion']

with_float_types(float_types)

with_integer_types(integer_types)

with_literal_variants(literal_variants)

with_term_variants(term_variants)

with_type_variants(type_variants)

with_types(types)

class hydra.coders.LanguageFeature(*values)

Bases: Enum

A target-language or target-runtime capability the coder may rely on. Absence from a Language’s supportedFeatures set means the emitter must work around the missing capability.

NESTED_CASE_STATEMENTS = Name(value='nestedCaseStatements')

The target runtime can handle deeply nested case statements without stack issues. When absent, the emitter hoists cases out into top-level helpers.

NESTED_POLYMORPHIC_LET_BINDINGS = Name(value='nestedPolymorphicLetBindings')

The target language permits polymorphic let-bindings in expression position. When absent, the emitter hoists polymorphic lets to top level.

PARTIAL_APPLICATION = Name(value='partialApplication')

The target runtime can invoke an n-ary function with fewer than n arguments without error. When absent, the emitter eta-expands partially-applied terms.

TYPE_ = Name(value='hydra.coders.LanguageFeature')

class hydra.coders.LanguageName(value: T)

Bases: Node[str]

The unique name of a language.

TYPE_ = Name(value='hydra.coders.LanguageName')

class hydra.coders.TraversalOrder(*values)

Bases: Enum

Specifies either a pre-order or post-order traversal.

POST = Name(value='post')

Post-order traversal

PRE = Name(value='pre')

Pre-order traversal

TYPE_ = Name(value='hydra.coders.TraversalOrder')