harnest.extensions

All Python modules · Import and compatibility guidance

Exports

Name	Kind
`ActivatedExtension`	Class
`Extension`	Class
`ExtensionContext`	Class
`ExtensionContextUnavailableError`	Class
`ExtensionImportError`	Class
`ExtensionNamespaceError`	Class
`ExtensionStartContext`	Class
`activate_extensions`	Function
`extension_mutation`	Function
`extension_namespaces`	Function
`release_extensions`	Function

ActivatedExtension

One validated namespace module and its authored singleton.

ActivatedExtension(
    descriptor: ExtensionDescriptor,
    module: ModuleType,
    extension: Extension[ExtensionContext],
) -> None

Fields (— means no declared default):

Field	Type	Default
`descriptor`	`ExtensionDescriptor`	`—`
`module`	`ModuleType`	`—`
`extension`	`Extension[ExtensionContext]`	`—`

Parameters and example

Parameter	Type	Default
`descriptor`	`ExtensionDescriptor`	Required
`module`	`ModuleType`	Required
`extension`	`Extension[ExtensionContext]`	Required

from harnest.extensions import ActivatedExtension

extension = ActivatedExtension(descriptor=..., module=..., extension=...)

Extension

Application-owned extension with task-local invocation context.

Extension(*args: object, **kwargs: object) -> 'Extension[ContextT]'

Parameters and example

Parameter	Type	Default
`*args`	`object`	Optional
`**kwargs`	`object`	Optional

from harnest.extensions import Extension

extension = Extension()

Extension.start

async Extension.start(context: 'ExtensionStartContext') -> None

Initialize application-scoped resources after dependencies start.

Parameters and example

Parameter	Type	Default
`context`	`'ExtensionStartContext'`	Required

from harnest.extensions import Extension

extension: Extension
await extension.start(context=...)

Extension.stop

async Extension.stop() -> None

Release application-scoped resources before dependencies stop.

Example

from harnest.extensions import Extension

extension: Extension
await extension.stop()

Extension.create_context

Extension.create_context(context: ExtensionContext) -> ContextT

Adapt the managed invocation base to an extension-specific context.

Parameters and example

Parameter	Type	Default
`context`	`ExtensionContext`	Required

from harnest.extensions import Extension

extension: Extension
result = extension.create_context(context=...)

Extension.context

Return the task-local extension context for the active invocation.

Example

from harnest.extensions import Extension

extension: Extension
value = extension.context

ExtensionContext

Revocable invocation base that extension-specific contexts may extend.

ExtensionContext(extension_name: str) -> None

Parameters and example

Parameter	Type	Default
`extension_name`	`str`	Required

from harnest.extensions import ExtensionContext

context = ExtensionContext(extension_name=...)

ExtensionContext.extension_name

Return the extension whose invocation authority this context carries.

Example

from harnest.extensions import ExtensionContext

context: ExtensionContext
value = context.extension_name

ExtensionContext.active

Report whether the owning managed invocation is still active.

Example

from harnest.extensions import ExtensionContext

context: ExtensionContext
value = context.active

ExtensionContext.continuations

Return provider-bound suspension authority for this invocation.

Example

from harnest.extensions import ExtensionContext

context: ExtensionContext
value = context.continuations

ExtensionContextUnavailableError

An extension context was used outside its managed invocation.

Example

from harnest.extensions import ExtensionContextUnavailableError

try:
    ...
except ExtensionContextUnavailableError as error:
    ...

ExtensionImportError

An authored extension module violates its export contract.

Example

from harnest.extensions import ExtensionImportError

try:
    ...
except ExtensionImportError as error:
    ...

ExtensionNamespaceError

An extension namespace cannot be activated or safely released.

Example

from harnest.extensions import ExtensionNamespaceError

try:
    ...
except ExtensionNamespaceError as error:
    ...

ExtensionStartContext

Application facts available while one same-process extension starts. The context deliberately excludes invocation credentials and framework storage authorities. Extensions may reuse only explicitly named application storage whose lifecycle Harnest has already started. Obtain this object from the owning Harnest API; its constructor includes runtime bindings. Fields (— means no declared default):

Field	Type	Default
`extension_name`	`str`	`—`
`framework`	`str`	`—`
`root_agent_name`	`str`	`—`

Example

from harnest.extensions import ExtensionStartContext

context: ExtensionStartContext  # returned by Harnest, not constructed directly

ExtensionStartContext.storage

ExtensionStartContext.storage(name: str, expected_type: type[Any] | None = None) -> Any

Return one named custom store without exposing the registry.

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`expected_type`	`type[Any] \| None`	`None`

from harnest.extensions import ExtensionStartContext

context: ExtensionStartContext
result = context.storage(name=...)

ExtensionStartContext.continuations

Return provider-bound completion authority when explicitly declared.

Example

from harnest.extensions import ExtensionStartContext

context: ExtensionStartContext
value = context.continuations

activate_extensions

Activate a dependency-ordered extension set as one namespace transaction.

activate_extensions(descriptors: Sequence[ExtensionDescriptor]) -> tuple[ActivatedExtension, ...]

Parameters and example

Parameter	Type	Default
`descriptors`	`Sequence[ExtensionDescriptor]`	Required

from harnest.extensions import activate_extensions

result = activate_extensions(descriptors=...)

extension_mutation

Audit one exact durable operation after commit or on correlated failure.

extension_mutation(extension_name: str, operation: str, *, trigger: Literal['agent', 'user']) -> AsyncIterator[None]

Parameters and example

Parameter	Type	Default
`extension_name`	`str`	Required
`operation`	`str`	Required
`trigger`	`Literal['agent', 'user']`	Required

from harnest.extensions import extension_mutation

async with extension_mutation(extension_name=..., operation=..., trigger=...):
    ...

extension_namespaces

Activate extensions for one bounded compiler or test operation.

extension_namespaces(descriptors: Sequence[ExtensionDescriptor]) -> Iterator[tuple[ActivatedExtension, ...]]

Parameters and example

Parameter	Type	Default
`descriptors`	`Sequence[ExtensionDescriptor]`	Required

from harnest.extensions import extension_namespaces

with extension_namespaces(descriptors=...):
    ...

release_extensions

Release one acquisition without disturbing a competing extension set.

release_extensions(descriptors: Sequence[ExtensionDescriptor]) -> None

Parameters and example

Parameter	Type	Default
`descriptors`	`Sequence[ExtensionDescriptor]`	Required

from harnest.extensions import release_extensions

release_extensions(descriptors=...)

Overview

Get started

Harnest Studio

Guides

API reference

harnest.extensions

Exports

ActivatedExtension

Extension

Extension.start

Extension.stop

Extension.create_context

Extension.context

ExtensionContext

ExtensionContext.extension_name

ExtensionContext.active

ExtensionContext.continuations

ExtensionContextUnavailableError

ExtensionImportError

ExtensionNamespaceError

ExtensionStartContext

ExtensionStartContext.storage

ExtensionStartContext.continuations

activate_extensions

extension_mutation

extension_namespaces

release_extensions

​Exports

​ActivatedExtension

​Extension

​Extension.start

​Extension.stop

​Extension.create_context

​Extension.context

​ExtensionContext

​ExtensionContext.extension_name

​ExtensionContext.active

​ExtensionContext.continuations

​ExtensionContextUnavailableError

​ExtensionImportError

​ExtensionNamespaceError

​ExtensionStartContext

​ExtensionStartContext.storage

​ExtensionStartContext.continuations

​activate_extensions

​extension_mutation

​extension_namespaces

​release_extensions

Exports

ActivatedExtension

Extension

Extension.start

Extension.stop

Extension.create_context

Extension.context

ExtensionContext

ExtensionContext.extension_name

ExtensionContext.active

ExtensionContext.continuations

ExtensionContextUnavailableError

ExtensionImportError

ExtensionNamespaceError

ExtensionStartContext

ExtensionStartContext.storage

ExtensionStartContext.continuations

activate_extensions

extension_mutation

extension_namespaces

release_extensions