hydra.packaging module

A model for Hydra module names, modules, and packages.

class hydra.packaging.Definition

Bases: object

DefinitionPrimitive | DefinitionTerm | DefinitionType

PRIMITIVE = Name(value='primitive')

TERM = Name(value='term')

TYPE = Name(value='type')

TYPE_ = Name(value='hydra.packaging.Definition')

class hydra.packaging.DefinitionPrimitive(value: T)

Bases: Node[PrimitiveDefinition]

A primitive definition

class hydra.packaging.DefinitionReference

Bases: object

DefinitionReferencePrimitive | DefinitionReferenceTerm | DefinitionReferenceType

PRIMITIVE = Name(value='primitive')

TERM = Name(value='term')

TYPE = Name(value='type')

TYPE_ = Name(value='hydra.packaging.DefinitionReference')

class hydra.packaging.DefinitionReferencePrimitive(value: T)

Bases: Node[hydra.core.Name]

A reference to a primitive definition, by name

class hydra.packaging.DefinitionReferenceTerm(value: T)

Bases: Node[hydra.core.Name]

A reference to a term definition, by name

class hydra.packaging.DefinitionReferenceType(value: T)

Bases: Node[hydra.core.Name]

A reference to a type definition, by name

class hydra.packaging.DefinitionTerm(value: T)

Bases: Node[TermDefinition]

A term definition

class hydra.packaging.DefinitionType(value: T)

Bases: Node[TypeDefinition]

A type definition

class hydra.packaging.DependencyScope(*values)

Bases: Enum

The scope in which a package dependency is required. Relevant mainly to dependencies on third-party (non-Hydra) artifacts, where build systems distinguish compile-time, runtime, test-only, and build-tool-only dependencies. Hydra inter-package dependencies normally leave the scope unspecified.

API = Name(value='api')

present at both compile time and runtime, and visible downstream

Type:

A dependency exported transitively to consumers of this package (e.g. Gradle api, Cabal build-depends)

RUNTIME = Name(value='runtime')

A dependency required at runtime but not at compile time

TEST = Name(value='test')

A dependency required only to compile and run the package’s tests

TOOL = Name(value='tool')

A build-tool-only dependency, used to generate or process sources at build time but not present in the compiled artifact (e.g. an ANTLR tool jar or an annotation processor)

TYPE_ = Name(value='hydra.packaging.DependencyScope')

class hydra.packaging.EntityMetadata(description: Annotated[object, 'An optional, concise one-line human-readable summary of the entity.'], comments: Annotated[Sequence[str], "Zero or more long-form prose paragraphs: cross-cutting semantic conventions, caveats, and references that would otherwise be repeated across the entity's constituents."], see_also: Annotated[Sequence[EntityReference], 'Typed cross-references to related entities, for navigation and documentation.'], lifecycle: Annotated[object, 'Optional version-lifecycle milestones for the entity.'])

Bases: object

Documentation and lifecycle metadata attachable to a packaging entity (package, module, or definition). Bundling these fields in one type lets future metadata be added without changing the field shape of the entities that carry it.

class Builder(_description: 'Optional[str]' = None, _comments: 'Sequence[str]' = None, _see_also: 'Sequence[EntityReference]' = None, _lifecycle: 'Optional[LifecycleInfo]' = None)

Bases: object

build()

comments(comments)

description(description)

lifecycle(lifecycle)

see_also(see_also)

COMMENTS = Name(value='comments')

DESCRIPTION = Name(value='description')

LIFECYCLE = Name(value='lifecycle')

SEE_ALSO = Name(value='seeAlso')

TYPE_ = Name(value='hydra.packaging.EntityMetadata')

static builder()

comments: Annotated[Sequence[str], "Zero or more long-form prose paragraphs: cross-cutting semantic conventions, caveats, and references that would otherwise be repeated across the entity's constituents."]

description: Annotated[object, 'An optional, concise one-line human-readable summary of the entity.']

lifecycle: Annotated[object, 'Optional version-lifecycle milestones for the entity.']

see_also: Annotated[Sequence[EntityReference], 'Typed cross-references to related entities, for navigation and documentation.']

with_comments(comments)

with_description(description)

with_lifecycle(lifecycle)

with_see_also(see_also)

class hydra.packaging.EntityReference

Bases: object

EntityReferenceDefinition | EntityReferenceModule | EntityReferencePackage | EntityReferenceTermExpr | EntityReferenceTypeExpr

DEFINITION = Name(value='definition')

MODULE = Name(value='module')

PACKAGE = Name(value='package')

TERM_EXPR = Name(value='termExpr')

TYPE_ = Name(value='hydra.packaging.EntityReference')

TYPE_EXPR = Name(value='typeExpr')

class hydra.packaging.EntityReferenceDefinition(value: T)

Bases: Node[DefinitionReference]

A reference to a definition (type, term, or primitive), by name

class hydra.packaging.EntityReferenceModule(value: T)

Bases: Node[ModuleName]

A reference to a module, by name

class hydra.packaging.EntityReferencePackage(value: T)

Bases: Node[PackageName]

A reference to a package, by name

class hydra.packaging.EntityReferenceTermExpr(value: T)

Bases: Node[str]

An inline term expression in Hydra textual syntax

class hydra.packaging.EntityReferenceTypeExpr(value: T)

Bases: Node[str]

An inline type expression in Hydra textual syntax

class hydra.packaging.LifecycleInfo(available_since: Annotated[object, 'The version in which the entity was introduced, if known.'], deprecated_since: Annotated[object, 'The version in which the entity was deprecated, if applicable.'])

Bases: object

Version-lifecycle milestones for a packaging entity. Each milestone is independently optional; further milestones (e.g. stableSince, removedSince) may be added without changing dependent types.

AVAILABLE_SINCE = Name(value='availableSince')

class Builder(_available_since: 'Optional[Version]' = None, _deprecated_since: 'Optional[Version]' = None)

Bases: object

available_since(available_since)

build()

deprecated_since(deprecated_since)

DEPRECATED_SINCE = Name(value='deprecatedSince')

TYPE_ = Name(value='hydra.packaging.LifecycleInfo')

available_since: Annotated[object, 'The version in which the entity was introduced, if known.']

static builder()

deprecated_since: Annotated[object, 'The version in which the entity was deprecated, if applicable.']

with_available_since(available_since)

with_deprecated_since(deprecated_since)

class hydra.packaging.Module(name: Annotated[ModuleName, 'The name of the module, which is also the common prefix for all element names in the module'], metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the module'], dependencies: Annotated[Sequence[ModuleDependency], 'Any modules which this module directly depends on'], definitions: Annotated[Sequence[Definition], 'The definitions in this module'])

Bases: object

A logical collection of elements sharing a common module name, having dependencies on zero or more other modules.

class Builder(_name: 'ModuleName' = None, _metadata: 'Optional[EntityMetadata]' = None, _dependencies: 'Sequence[ModuleDependency]' = None, _definitions: 'Sequence[Definition]' = None)

Bases: object

build()

definitions(definitions)

dependencies(dependencies)

metadata(metadata)

name(name)

DEFINITIONS = Name(value='definitions')

DEPENDENCIES = Name(value='dependencies')

METADATA = Name(value='metadata')

NAME = Name(value='name')

TYPE_ = Name(value='hydra.packaging.Module')

static builder()

definitions: Annotated[Sequence[Definition], 'The definitions in this module']

dependencies: Annotated[Sequence[ModuleDependency], 'Any modules which this module directly depends on']

metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the module']

name: Annotated[ModuleName, 'The name of the module, which is also the common prefix for all element names in the module']

with_definitions(definitions)

with_dependencies(dependencies)

with_metadata(metadata)

with_name(name)

class hydra.packaging.ModuleDependency(module: Annotated[ModuleName, 'The name of the depended-on module'], package: Annotated[object, 'The package providing the depended-on module, if disambiguation is required'])

Bases: object

A dependency on another module, identified by its name and (optionally) the package which provides it. When the package is omitted, the resolver searches all packages in scope; a duplicate module name across packages is a resolution error which can be disambiguated by naming the intended package explicitly.

class Builder(_module: 'ModuleName' = None, _package: 'Optional[PackageName]' = None)

Bases: object

build()

module(module)

package(package)

MODULE = Name(value='module')

PACKAGE = Name(value='package')

TYPE_ = Name(value='hydra.packaging.ModuleDependency')

static builder()

module: Annotated[ModuleName, 'The name of the depended-on module']

package: Annotated[object, 'The package providing the depended-on module, if disambiguation is required']

with_module(module)

with_package(package)

class hydra.packaging.ModuleName(value: T)

Bases: Node[str]

The unique name of a module; a prefix for the names of elements defined in the module.

TYPE_ = Name(value='hydra.packaging.ModuleName')

class hydra.packaging.Package(name: Annotated[PackageName, 'The name of the package'], metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the package'], dependencies: Annotated[Sequence[PackageDependency], 'The packages which this package depends on'], modules: Annotated[Sequence[Module], 'The modules in this package'])

Bases: object

A package, which is a named collection of modules with metadata and dependencies.

class Builder(_name: 'PackageName' = None, _metadata: 'Optional[EntityMetadata]' = None, _dependencies: 'Sequence[PackageDependency]' = None, _modules: 'Sequence[Module]' = None)

Bases: object

build()

dependencies(dependencies)

metadata(metadata)

modules(modules)

name(name)

DEPENDENCIES = Name(value='dependencies')

METADATA = Name(value='metadata')

MODULES = Name(value='modules')

NAME = Name(value='name')

TYPE_ = Name(value='hydra.packaging.Package')

static builder()

dependencies: Annotated[Sequence[PackageDependency], 'The packages which this package depends on']

metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the package']

modules: Annotated[Sequence[Module], 'The modules in this package']

name: Annotated[PackageName, 'The name of the package']

with_dependencies(dependencies)

with_metadata(metadata)

with_modules(modules)

with_name(name)

class hydra.packaging.PackageDependency(name: Annotated[PackageName, 'The name of the depended-on package'], version: Annotated[VersionSpecifier, 'The version-range constraint on the depended-on package'], scope: Annotated[object, 'The scope in which the dependency is required, if specified. Normally absent for Hydra inter-package dependencies; specified for third-party dependencies whose build scope (compile/runtime/test/tool) is significant.'])

Bases: object

A dependency on another package, identified by name and constrained by an optional version specifier.

class Builder(_name: 'PackageName' = None, _version: 'VersionSpecifier' = None, _scope: 'Optional[DependencyScope]' = None)

Bases: object

build()

name(name)

scope(scope)

version(version)

NAME = Name(value='name')

SCOPE = Name(value='scope')

TYPE_ = Name(value='hydra.packaging.PackageDependency')

VERSION = Name(value='version')

static builder()

name: Annotated[PackageName, 'The name of the depended-on package']

scope: Annotated[object, 'The scope in which the dependency is required, if specified. Normally absent for Hydra inter-package dependencies; specified for third-party dependencies whose build scope (compile/runtime/test/tool) is significant.']

version: Annotated[VersionSpecifier, 'The version-range constraint on the depended-on package']

with_name(name)

with_scope(scope)

with_version(version)

class hydra.packaging.PackageName(value: T)

Bases: Node[str]

The unique name of a package, e.g. “hydra-kernel” or “hydra-python”. For dependencies on third-party artifacts in ecosystems with a group/namespace component (notably Maven), the group and artifact are carried in a single name separated by a colon, e.g. “org.eclipse.rdf4j:rdf4j-rio-ntriples”; the consuming host splits on the colon to recover the group when emitting build configuration. Hydra package names contain no colon.

TYPE_ = Name(value='hydra.packaging.PackageName')

class hydra.packaging.PrimitiveDefinition(name: Annotated[Name, 'The name of the primitive'], metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the primitive.'], signature: Annotated[TermSignature, 'The signature of the primitive. Always explicit, never inferred.'], is_pure: Annotated[bool, 'Whether the primitive is pure (referentially transparent, no observable side effects). Normally true.'], is_total: Annotated[bool, 'Whether the primitive is total (terminates on every input of its declared type). Normally true.'], default_implementation: Annotated[object, 'An optional cross-compilable reference implementation of the primitive, expressed as a Hydra term. Used by interpreters lacking a native implementation and as a proof-friendly reference. Distinct from the per-host Primitive.implementation.'])

Bases: object

A primitive definition: the universal, host-independent declarative metadata for a primitive, including name, signature, documentation and lifecycle metadata, totality and purity flags, and an optional default implementation expressed as a Hydra term.

class Builder(_name: 'hydra.core.Name' = None, _metadata: 'Optional[EntityMetadata]' = None, _signature: 'hydra.typing.TermSignature' = None, _is_pure: 'bool' = None, _is_total: 'bool' = None, _default_implementation: 'Optional[hydra.core.Term]' = None)

Bases: object

build()

default_implementation(default_implementation)

is_pure(is_pure)

is_total(is_total)

metadata(metadata)

name(name)

signature(signature)

DEFAULT_IMPLEMENTATION = Name(value='defaultImplementation')

IS_PURE = Name(value='isPure')

IS_TOTAL = Name(value='isTotal')

METADATA = Name(value='metadata')

NAME = Name(value='name')

SIGNATURE = Name(value='signature')

TYPE_ = Name(value='hydra.packaging.PrimitiveDefinition')

static builder()

default_implementation: Annotated[object, 'An optional cross-compilable reference implementation of the primitive, expressed as a Hydra term. Used by interpreters lacking a native implementation and as a proof-friendly reference. Distinct from the per-host Primitive.implementation.']

is_pure: Annotated[bool, 'Whether the primitive is pure (referentially transparent, no observable side effects). Normally true.']

is_total: Annotated[bool, 'Whether the primitive is total (terminates on every input of its declared type). Normally true.']

metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the primitive.']

name: Annotated[Name, 'The name of the primitive']

signature: Annotated[TermSignature, 'The signature of the primitive. Always explicit, never inferred.']

with_default_implementation(default_implementation)

with_is_pure(is_pure)

with_is_total(is_total)

with_metadata(metadata)

with_name(name)

with_signature(signature)

class hydra.packaging.TermDefinition(name: Annotated[Name, 'The name of the term'], metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the term definition'], signature: Annotated[object, 'The optional signature of the term. When absent, the signature has yet to be inferred.'], body: Annotated[Term, 'The term being defined'])

Bases: object

A term-level definition, including a name, an optional signature, and a term.

BODY = Name(value='body')

class Builder(_name: 'hydra.core.Name' = None, _metadata: 'Optional[EntityMetadata]' = None, _signature: 'Optional[hydra.typing.TermSignature]' = None, _body: 'hydra.core.Term' = None)

Bases: object

body(body)

build()

metadata(metadata)

name(name)

signature(signature)

METADATA = Name(value='metadata')

NAME = Name(value='name')

SIGNATURE = Name(value='signature')

TYPE_ = Name(value='hydra.packaging.TermDefinition')

body: Annotated[Term, 'The term being defined']

static builder()

metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the term definition']

name: Annotated[Name, 'The name of the term']

signature: Annotated[object, 'The optional signature of the term. When absent, the signature has yet to be inferred.']

with_body(body)

with_metadata(metadata)

with_name(name)

with_signature(signature)

class hydra.packaging.TypeDefinition(name: Annotated[Name, 'The name of the type'], metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the type definition'], body: Annotated[TypeScheme, 'The type scheme being defined'])

Bases: object

A type-level definition, including a name and the type scheme.

BODY = Name(value='body')

class Builder(_name: 'hydra.core.Name' = None, _metadata: 'Optional[EntityMetadata]' = None, _body: 'hydra.core.TypeScheme' = None)

Bases: object

body(body)

build()

metadata(metadata)

name(name)

METADATA = Name(value='metadata')

NAME = Name(value='name')

TYPE_ = Name(value='hydra.packaging.TypeDefinition')

body: Annotated[TypeScheme, 'The type scheme being defined']

static builder()

metadata: Annotated[object, 'Optional documentation and lifecycle metadata for the type definition']

name: Annotated[Name, 'The name of the type']

with_body(body)

with_metadata(metadata)

with_name(name)

class hydra.packaging.Version(value: T)

Bases: Node[str]

A version string, e.g. “0.15” or “1.0.0”.

TYPE_ = Name(value='hydra.packaging.Version')

class hydra.packaging.VersionRange(lower_inclusive: Annotated[object, 'The inclusive lower bound, if any (the minimum acceptable version).'], upper_exclusive: Annotated[object, 'The exclusive upper bound, if any (versions strictly below this are acceptable).'])

Bases: object

A version range with an optional inclusive lower bound and an optional exclusive upper bound.

class Builder(_lower_inclusive: 'Optional[Version]' = None, _upper_exclusive: 'Optional[Version]' = None)

Bases: object

build()

lower_inclusive(lower_inclusive)

upper_exclusive(upper_exclusive)

LOWER_INCLUSIVE = Name(value='lowerInclusive')

TYPE_ = Name(value='hydra.packaging.VersionRange')

UPPER_EXCLUSIVE = Name(value='upperExclusive')

static builder()

lower_inclusive: Annotated[object, 'The inclusive lower bound, if any (the minimum acceptable version).']

upper_exclusive: Annotated[object, 'The exclusive upper bound, if any (versions strictly below this are acceptable).']

with_lower_inclusive(lower_inclusive)

with_upper_exclusive(upper_exclusive)

class hydra.packaging.VersionSpecifier

Bases: object

VersionSpecifierAny | VersionSpecifierExact | VersionSpecifierAtLeast | VersionSpecifierRange

ANY = Name(value='any')

AT_LEAST = Name(value='atLeast')

EXACT = Name(value='exact')

RANGE = Name(value='range')

TYPE_ = Name(value='hydra.packaging.VersionSpecifier')

class hydra.packaging.VersionSpecifierAny

Bases: object

Any version satisfies the dependency

class hydra.packaging.VersionSpecifierAtLeast(value: T)

Bases: Node[Version]

Any version greater than or equal to the given version (e.g. PyPI “>=7.0”)

class hydra.packaging.VersionSpecifierExact(value: T)

Bases: Node[Version]

Exactly the given version satisfies the dependency; used to pin a specific release

class hydra.packaging.VersionSpecifierRange(value: T)

Bases: Node[VersionRange]

A version range with an optional inclusive lower bound and optional exclusive upper bound (e.g. “>=3.7,<4.0”)