Edron symbol reference

The entries below are generated from the installed 1.0 source. Start with Edron API by task if you do not already know the symbol name.

Edron: a class-oriented authoring facade for Hedron.

__version__ = '1.1.3' module-attribute

HEDRON_BROWSER_FORWARD_TARGET = '1.0.0' module-attribute

HEDRON_BROWSER_REQUIREMENT = '>=0.67.0,<2.0' module-attribute

HEDRON_BROWSER_TRAIN = '0.67.0' module-attribute

ARTIFACT_SCHEMA = 'edron.artifact-manifest/1' module-attribute

PROFILE_NAMES = ('local', 'single-process', 'reverse-proxy', 'container', 'orchestrated', 'workbench', 'posit-connect') module-attribute

PROFILE_SCHEMA = 'edron.deployment-profile/1' module-attribute

BackendMode = Literal['process-local', 'shared', 'unknown'] module-attribute

DeploymentProfileName = Literal['local', 'single-process', 'reverse-proxy', 'container', 'orchestrated', 'workbench', 'posit-connect'] module-attribute

deployment_report = check_deployment module-attribute

profile_from_environment = resolve_deployment_profile module-attribute

DEPRECATED_HEDRON_067_PATHS = frozenset({'hedron-disclose', 'hedron-elements duplicate common-widget wrappers', 'hedron-dialog', 'hedron-field-text', 'hedron-field-choice', 'hedron-field-file', 'hedron-action-async', 'delegated common-widget controllers'}) module-attribute

expose = inherit module-attribute

LAYOUT_KINDS = ('stack', 'grid', 'plain', 'container') module-attribute

TEMPLATES = ('minimal', 'dashboard', 'form') module-attribute

__all__ = ['Action', 'App', 'AlpineAttrs', 'AlpineDirective', 'AlpineExpression', 'AlpineFeatureDemand', 'AlpineMaturity', 'ARTIFACT_SCHEMA', 'BackendMode', 'BindingError', 'BoundAction', 'BoundFragment', 'BrowserFeaturePlan', 'BrowserPlanClosure', 'CachedFunction', 'CapabilityError', 'CapabilityPromotion', 'Color', 'Column', 'Confirm', 'Container', 'Dependency', 'DeploymentError', 'DeploymentProfile', 'DeploymentProfileName', 'DeploymentReport', 'DeploymentResolution', 'Resource', 'DataExport', 'DataSelection', 'DataSource', 'DataWorkspace', 'DEPRECATED_HEDRON_067_PATHS', 'DiagnosticReport', 'DesignSystem', 'Download', 'EdronError', 'EdronDiagnostic', 'EditIntent', 'EditPolicy', 'FilterScope', 'FeaturePackage', 'Fragment', 'IncompatibleCapabilityError', 'JobBackend', 'JobFlow', 'JobScope', 'job_status_events', 'MissingCapabilityError', 'BrokenCapabilityError', 'Interaction', 'InteractionKind', 'Outcome', 'OutcomeKind', 'PackageConflictError', 'Page', 'PROFILE_NAMES', 'PROFILE_SCHEMA', 'PageRequest', 'LayoutSpec', 'NavigationError', 'NavigationTarget', 'LAYOUT_KINDS', 'PhaseError', 'RegistrationError', 'StyleContext', 'StyleRecipe', 'Theme', 'ThemeSpec', 'TEMPLATES', 'action', 'artifact_manifest', 'artifact_records', 'check_deployment', 'cache_data', 'create_scaffold', 'dependency', 'deployment_report', 'deprecated_hedron_paths', 'resource', 'browser_closure', 'browser_plan', 'feature_demand', 'HEDRON_BROWSER_FORWARD_TARGET', 'HEDRON_BROWSER_REQUIREMENT', 'HEDRON_BROWSER_TRAIN', 'profile_from_environment', 'resolve_deployment_profile', 'download', 'fragment', 'inherit', 'expose', 'refresh', 'success', 'theme', 'feature_package', 'layout', 'promoted_capability', 'promoted_capabilities', 'SourceLocation', 'WorkspacePage', 'AuditEvent', 'CellEdit'] module-attribute

App

Class-oriented facade over exactly one native :class:hedron.Hedron app.

native property

The exact native app (kept as a property for 0.1 compatibility).

resources property

The app-owned native resource registry.

native_surface(surface)

Resolve a registered Edron surface to its exact native projection.

simulation(*, fixtures=None)

Expose a bounded public callback boundary for simulation tooling.

The returned object invokes this app's actual registered pages, fragments, and actions. It is intended for deterministic documentation previews and tests; production traffic must continue through the ASGI application so middleware, security policy, and dependency injection remain authoritative.

interaction(value)

Register and return one native Hedron 1.0 interaction declaration.

browser_plan(*demands, assets=())

Build the native demand-driven browser plan for a page document.

resource(name, factory=None, *, kind='custom', scope='application', secret_refs=None, config=None, healthcheck=None, healthcheck_name=None)

Register a lazy native resource and return a typed dependency descriptor.

__call__(scope, receive, send) async

Expose the facade as an ordinary ASGI application.

function_page(path, *, title, name=None, show_title=True, dependencies=())

Register a function as a page with the same fresh-instance semantics.

This is intentionally explicit and limited to a single render function. A function page cannot grow inherited fragments/actions, which keeps the class facade as the composition path for related surfaces.

page_function(*args, **kwargs)

Alias for :meth:function_page with the noun-first spelling.

source_map()

Return a bounded, redacted map from Edron sources to native projections.

explain()

Explain registered Edron surfaces without executing application callbacks.

manifest()

Return a bounded deterministic Edron/native lowering manifest.

conformance()

Check bounded Edron/native metadata without invoking app callbacks.

operations()

Return bounded deployment facts without resolving resources or jobs.

deployment(profile=None, *, environ=None, cwd=None, overrides=None)

Return a bounded profile report for this app without serving it.

check()

Return a diagnostic report for registered metadata only.

include_feature(feature, *, capabilities=None)

Include a native feature through the exact Hedron transaction.

include_package(package, *, capabilities=None)

Atomically register a declarative package and its native assets.

package(package, *, capabilities=None)

Alias for :meth:include_package.

navigation_target(target)

Return an app-owned typed target for a registered page or native screen.

layout(kind='stack', **kwargs)

Return a shared, validated layout declaration.

promote_capability(name)

Promote one reviewed native capability after metadata validation.

chart_interaction(chart, *, event, payload, command, refreshes=(), max_items=100, name=None, experimental=False)

Register a typed chart event against a native action handle.

The native ChartInteraction contract validates the closed event set, payload, cardinality, and effect fan-out. Edron resolves its own action descriptors to the exact native handle before registration.

map_interaction(map, *, event, payload, command, refreshes=(), max_items=100, name=None)

Register a typed map event against a native action handle.

data_workspace(workspace, *, save_path=None, dependencies=())

Register an explicit native mutation route for an Edron workspace.

AlpineAttrs dataclass

Typed Alpine attributes accepted by Python components and html.*.

merge(other)

Compose typed attributes while rejecting duplicate writers.

AlpineDirective dataclass

One normalized long-form Alpine directive.

AlpineExpression dataclass

Small data-only expression AST accepted by the CSP authoring lane.

unary(operator, value) classmethod

Build a bounded unary expression without interpolating JavaScript.

not_(value) classmethod

Build a boolean negation expression.

AlpineFeatureDemand dataclass

One typed request for a browser-local Alpine capability.

AlpineMaturity

Bases: StrEnum

Maturity labels used by the 0.67 capability inventory.

BrowserFeaturePlan dataclass

Immutable feature/asset plan for one PAGE document.

with_fragment(name, plan)

Start a statically declared fragment closure from this plan.

BrowserPlanClosure dataclass

Immutable PAGE plan plus statically reachable fragment requirements.

The closure is compiled before a PAGE response is emitted. document_plan is the only plan allowed to reach asset injection; fragment(name) verifies that a later fragment is covered by that installed plan without registering response-time modules or plugins.

CachedFunction

Bases: Generic[P, R]

A callable lowered to Hedron's native cache_data decorator.

invalidate(*args, **kwargs)

Invalidate one invocation through the native cache backend.

invalidate_all()

Invalidate all invocations of this callable.

BrokenCapabilityError

Bases: CapabilityError

CapabilityError

Bases: EdronError

IncompatibleCapabilityError

Bases: CapabilityError

MissingCapabilityError

Bases: CapabilityError

FeaturePackage dataclass

A reusable, reviewable Edron package declaration.

bundle must be a native FeatureBundle (or provider). The package never accepts a registration callback: importing a package therefore cannot execute application code or create a hidden registry.

to_bundle()

Return the package's native bundle with package provenance applied.

PackageConflictError

Bases: ValueError

A package or one of its native-owned contributions conflicts.

Confirm dataclass

AuditEvent dataclass

CellEdit dataclass

One typed cell mutation with an optional optimistic row revision.

DataExport dataclass

A bounded export produced from an already-authorized page.

DataSelection dataclass

A bounded set of stable row identities.

DataSource

Bases: Generic[T]

Small adapter facade around one explicit native data source.

dataframe(frame, **kwargs) classmethod

Adapt a bounded pandas, Polars, or PyArrow value via native Narwhals.

DataWorkspace

Request-bounded read/filter/edit workspace over one native source.

request_from(values)

Parse ordinary query parameters using only workspace allowlists.

apply(intent, *, principal=None)

Authorize, validate, persist through the native source, then audit.

principal_from_request(request) staticmethod

Read the host-established principal without creating identity state.

native_feature(*, model, can_read, can_create=None, can_edit=None)

Compile common CRUD composition through native DataWorkspace.

EditIntent dataclass

Explicit application mutation intent; never persisted by Edron itself.

from_mapping(payload) classmethod

Validate the finite JSON shape emitted by the native editor host.

EditPolicy dataclass

Application-owned authorization, validation, and audit hooks.

Mutation is deny-by-default: authorize is required at execution time, writable fields must be named, and insert/delete operations must be enabled separately. The audit hook receives metadata only, never cell values.

PageRequest dataclass

A bounded, allowlisted request for one workspace page.

WorkspacePage dataclass

One native page plus safe facts useful to Edron application code.

Dependency dataclass

Bases: Generic[T]

Resource dataclass

App-owned named resource specification.

The factory is resolved lazily by Hedron's native ConnectionRegistry and disposed by the host lifespan. Secret values must be represented by opaque references in secret_refs; Edron never stores live credentials.

register(registry)

Register this resource in a native ConnectionRegistry.

DeploymentError

Bases: ValueError

Raised when an explicit deployment profile cannot be constructed.

DeploymentProfile dataclass

Validated, serializable deployment assumptions.

The profile describes a launch boundary. It does not start a server or grant trust to a proxy. state_backend and job_backend are claims supplied by the deployer and are intentionally not inferred.

for_name(name, **overrides) classmethod

Create one named profile with explicit overrides.

DeploymentReport dataclass

Bounded deployment profile and local artifact diagnostics.

DeploymentResolution dataclass

A profile plus non-throwing resolution findings.

Action dataclass

Bases: Generic[P, R]

BoundAction dataclass

Bases: Generic[P, R]

BoundFragment dataclass

Bases: Generic[P]

Fragment dataclass

Bases: Generic[P]

DiagnosticReport dataclass

A bounded collection of diagnostics with stable output projections.

EdronDiagnostic dataclass

An immutable Edron diagnostic suitable for text, JSON, or SARIF output.

to_dict()

Compatibility spelling for JSON-compatible consumers.

SourceLocation dataclass

A one-based source span attached to an Edron definition or finding.

Download dataclass

BindingError

Bases: EdronError

EdronError

Bases: Exception

Base class for errors raised by the Edron facade.

PhaseError

Bases: EdronError

RegistrationError

Bases: EdronError

Interaction dataclass

One closed local/request/combined interaction declaration.

to_attributes(*, tag=None)

Lower the interaction into inspectable and executable HTML facts.

The interaction algebra remains framework-neutral, so the request lane is resolved through the active core route registry rather than importing an adapter. When a route is available, HTMX receives the same method, target, swap, and event described by the interaction. The data-hedron-* facts remain useful for inspection and the native fallback path; they are never a substitute for server-side authorization.

to_lowering(*, tag=None)

Lower once into typed Alpine/HTMX lanes plus inspectable metadata.

InteractionKind

Bases: StrEnum

Outcome dataclass

Closed, role-indexed server outcome description.

refresh(*handles) classmethod

Refresh one or more registered view handles by logical id.

Callers may pass a handle object (anything exposing dom_id or logical_id) or an already-normalized logical-id string. The wire payload stays a redacted string so outcomes never serialize application objects; bound handles retain their exact instance identity.

OutcomeKind

Bases: StrEnum

JobBackend

Bases: Protocol

Durable job store used by status polling and inference admission.

Implementations must scope observation and cancel by auth_subject / tenant_id when those values are present. In-memory backends do not span processes — use Redis (or Celery/RQ bridges) for multi-worker deployments.

Implementations may set process_local = True when they cannot span processes. Production gates treat a missing attribute as durable.

Methods:

Name	Description
submit	Enqueue work and return a JobHandle.
get	Fetch status when authorized; return None when missing/denied.
request_cancel	Request cancellation; return whether the request was accepted.
cleanup_expired	Drop stale records; return the number removed.
mark	Update lifecycle state / result payload for an existing job.

submit(job_type, payload, *, idempotency_key=None, tenant_id=None, auth_subject=None)

Enqueue a job.

Parameters:

Name	Type	Description	Default
job_type	str	Application-defined job type string.	required
payload	Mapping[str, JsonValue]	JSON-compatible job payload.	required
idempotency_key	str | None	Optional deduplication key.	None
tenant_id	str | None	Optional tenant scope for authorization.	None
auth_subject	str | None	Optional subject scope for authorization.	None

Returns:

Type	Description
JobHandle	Handle containing the assigned job_id.

get(job_id, *, auth_subject=None, tenant_id=None)

Return job status when the caller is authorized to observe it.

Parameters:

Name	Type	Description	Default
job_id	str	Job identifier.	required
auth_subject	str | None	Optional subject scope; fail closed when mismatched.	None
tenant_id	str | None	Optional tenant scope; fail closed when mismatched.	None

Returns:

Type	Description
JobStatus | None	JobStatus or None when missing or unauthorized.

request_cancel(job_id, *, auth_subject=None, tenant_id=None)

Request cancellation for a job.

Parameters:

Name	Type	Description	Default
job_id	str	Job identifier.	required
auth_subject	str | None	Optional subject scope.	None
tenant_id	str | None	Optional tenant scope.	None

Returns:

Type	Description
bool	True when the cancel request was accepted.

cleanup_expired(*, older_than_seconds=86400)

Remove expired job records.

Parameters:

Name	Type	Description	Default
older_than_seconds	float	Age threshold for cleanup.	86400

Returns:

Type	Description
int	Number of records removed.

mark(job_id, state, *, result=None, error=None)

Update lifecycle state for an existing job.

Parameters:

Name	Type	Description	Default
job_id	str	Job identifier.	required
state	JobState	New JobState value.	required
result	object	Optional successful result payload.	None
error	str | None	Optional failure message.	None

Returns:

Type	Description
JobStatus | None	Updated JobStatus, or None when the job is missing.

JobFlow

Thin Edron constructor for native Hedron task flows.

JobScope dataclass

Immutable subject/tenant identity for durable job authorization.

LayoutSpec dataclass

Bounded composition metadata that lowers to one native layout node.

compose(nodes)

Create the corresponding native layout component.

NavigationError

Bases: ValueError

A navigation target is invalid or belongs to another app.

NavigationTarget dataclass

An app-owned, typed reference to a registered native route.

link(label=None, **kwargs)

Lower to the native NavLink with all safety checks intact.

Container dataclass

A request-local layout container.

FilterScope

Bases: Container

Page

Base class for Edron request-scoped page controllers.

data_workspace(workspace, *, request=None, editable=False, selection=None, caption=None, save_endpoint=None, save_mode='batch', _target=None)

Render one bounded Edron workspace page and return its safe page value.

When request is omitted, ordinary query parameters are parsed through the workspace allowlists. editable=True lowers to the native data editor; otherwise this lowers to its native accessible table.

data_editor(workspace, **kwargs)

Editable spelling of :meth:data_workspace.

chart(spec, *, alternative=None, _target=None)

Render a reviewed native hedron-charts specification.

Chart owns compilation, payload limits, sanitization, and its accessible static/table fallback. Edron only places the native node in the request-local output buffer.

image(src, *, alt, width=None, height=None, allow_external=False, _target=None)

Render a native safe image with required alternative text.

audio(src, *, tracks=(), controls=True, autoplay=False, loop=False, muted=False, preload=None, allow_external=False, _target=None)

Render native audio with validated caption/transcript tracks.

video(src, *, tracks=(), controls=True, autoplay=False, loop=False, muted=False, preload=None, poster=None, allow_external=False, _target=None)

Render native video with a safe poster and caption tracks.

layout(spec='stack', *, _target=None, **options)

Open a shared, bounded layout container for imperative composition.

job(flow, *, submit_label='Submit', show_cancel=False)

Render the submit surface for a flow already included in the app.

Including a feature mutates the router and must happen during startup. A page render is request-time work, so it only consumes the handles produced by the one-time materialization. show_cancel is exposed as a data hint for the generated status surface; a cancel command is only rendered once a job id is available on that surface.

CapabilityPromotion dataclass

A reviewed allowlist entry; module import is deferred until load.

inspect()

Check installed metadata without importing the promoted module.

load()

Import the native module after metadata compatibility succeeds.

Color dataclass

Safe immutable absolute CSS color.

Coordinates are normalized to the source space. Conversion is pure Python and the serialized fallback is always canonical sRGB hex. Relative colors, variables, URLs, gradients, and arbitrary CSS are not accepted because they cannot produce deterministic theme evidence.

rgb(red, green, blue, *, alpha=1.0) classmethod

Construct an sRGB color using the CSS-facing constructor name.

gamut_map()

Return the deterministic clipped sRGB representation of this color.

DesignSystem dataclass

Immutable portable design: Theme bridge plus named style recipes.

StyleContext dataclass

Serializable recipe context with explicit-component precedence.

resolve_presentation_values(slot)

Resolve the nearest mapped recipe into bounded presentation values.

StyleRecipe dataclass

Immutable named presentation defaults for one recipe family.

responsive_markers()

Return stable data markers for provider-neutral responsive adapters.

Theme dataclass

Python-native application design system.

tokens/modes/variants are the phase 0.9 semantic contract. palette, density, shape, nav_width, content_width, and elevation are the optional 0.54 design-system fields; each is emitted as CSS custom properties by :func:emit_theme_css. parent records the theme this one was derived from via :meth:extend.

extend(name, *, tokens=None, modes=None, variants=None, palette=None, density=None, shape=None, nav_width=None, content_width=None, typography_features=None, typography_role_features=None, elevation=None, accessibility_modes=None)

Return a new theme that inherits this theme's values by name.

Overrides are merged per mapping, so a derived theme only restates what it changes. The result records parent=self.name and is fully resolved, which keeps emit_theme_css and scoped data-hedron-theme subtrees independent of registration order.

ThemeSpec dataclass

Immutable canonical theme input for 0.60.

from_dict(data) classmethod

Rehydrate a package payload while checking its canonical fingerprint.

patch(name='inline', *, tokens=None, modes=None, accessibility_modes=None, aliases=None, groups=None, recipes=None, base_fingerprint=None, provenance=())

Apply one bounded immutable patch and return a new specification.

apply_patches(*patches)

Apply ordered patches without mutating the original specification.

to_theme()

Bridge to the compatible 0.59 Theme object.

browser_closure(initial=None, *, fragments=())

Build the native page/fragment browser closure before serving a page.

browser_plan(demands=(), *, assets=())

Build the native demand-driven plan; empty input remains feature-off.

feature_demand(feature, source='edron', *, maturity=AlpineMaturity.SUPPORTED)

Declare one browser-local feature for the native document planner.

cache_data(*, ttl=60, scope='private', max_entries=128, version='1', tags=(), vary_on=())

Decorate a recomputable function with native TTL/scope/cache policy.

feature_package(name, version, *, bundle=None, assets=(), description='', documentation=None)

Construct a :class:FeaturePackage with a beginner-friendly spelling.

dependency(provider=None, *, use_cache=True, scope=None)

resource(name, factory=None, *, kind='custom', scope='application', secret_refs=None, config=None, healthcheck=None, healthcheck_name=None)

Declare a reusable resource specification for App.resource.

artifact_manifest(paths, *, version, root=None, project='edron')

Build deterministic release metadata without writing or publishing it.

artifact_records(paths, *, root=None)

Return bounded SHA-256 records for already-built release artifacts.

check_deployment(name=None, *, profile=None, environ=None, cwd=None, overrides=None, application=None)

Check a profile, build manifest, trust boundary, and app metadata.

application is optional and is inspected only through inert metadata attributes. It is never imported, called, or probed over HTTP.

resolve_deployment_profile(name=None, *, profile=None, environ=None, cwd=None, overrides=None)

Resolve a deployment profile without importing or executing an app.

Explicit values win over environment values only after a conflict finding is recorded. This makes precedence observable instead of silently trusting a stale launcher or proxy setting.

deprecated_hedron_paths(text, *, paths=())

Return deprecated Hedron compatibility markers present in text.

action(fn=None, **kwargs)

action(fn: Callable[..., object]) -> Action[object, object]

action(*, method: str = 'post', path: str | None = None, name: str | None = None, fallback: str | None = None, idempotency: str = 'optional', updates: object = None, dependencies: tuple[object, ...] = ()) -> Callable[[Callable[..., object]], Action[object, object]]

fragment(fn=None, **kwargs)

fragment(fn: Callable[..., object]) -> Fragment[object]

fragment(*, path: str | None = None, name: str | None = None, fallback: str | None = None, dependencies: tuple[object, ...] = ()) -> Callable[[Callable[..., object]], Fragment[object]]

inherit(surface, *, name=None, path=None)

Opt in to exposing one descriptor on a subclass.

Decorated surfaces are never inherited implicitly. Assigning inherit(Base.view) creates a fresh descriptor owned by the subclass, so routes and native handles remain app-scoped and a base class cannot accidentally expose a surface.

download(identifier)

job_status_events(status, *, message_html, event_id=None)

Project an authorized native job status into bounded SSE events.

Authorization remains the responsibility of the native status route; this helper only formats an already-authorized status and never looks up a job.

layout(kind='stack', **kwargs)

Return a validated shared layout declaration.

refresh(*targets)

Return a native refresh outcome for registered Edron views.

success(message=None, *, status_code=200)

Return the closed native success outcome.

promoted_capabilities()

promoted_capability(name)

Return one reviewed capability entry without importing its module.

create_scaffold(name, destination, *, template='minimal', overwrite=False)

Create a deterministic Edron project without importing the generated app.

theme(name, *, accent, base=None, density='comfortable', geometry='soft', typography='system-sans', elevation='subtle', motion='standard', navigation='default', recipes=())