Skip to content

Errors

Every error you would handle subclasses GrelmicroError, so one except catches any of them. A bad configuration value always raises SettingsValidationError, whichever pattern or component you built.

EventLoopDeadlockError is deliberately outside that tree. It is a BaseException, so except Exception, a Retry, and a Fallback all pass it through. It reports a wiring mistake, and no fallback value stands in for one.

grelmicro

grelmicro is a lightweight framework/toolkit which is ideal for building async microservices in Python.

GrelmicroError

Bases: Exception

Base grelmicro error.

SettingsValidationError

SettingsValidationError(error: ValidationError | str)

Bases: GrelmicroError, ValueError

Raised when a configuration value fails validation.

Every grelmicro class raises this one error, whichever pattern or component it is, so one except covers the whole library. A config class you build yourself, such as RetryConfig(...), raises pydantic's ValidationError like any pydantic model.

Subclasses ValueError, which pydantic.ValidationError also is, so an except ValueError catches either.

Pydantic ValidationError messages already describe the failure shape ("Input should be a valid string", "Input should be greater than 0", ...) so the raw input is intentionally omitted from the rendered error. Settings often originate from environment variables that may carry credentials (DSNs, tokens), and echoing the offending value into a log line would leak them.

Initialize the error.

AdmissionError

Bases: GrelmicroError

Raised when a gatekeeping primitive refuses a call.

The shared base for every "turned away" rejection: a rate limiter over budget (RateLimitExceededError), a full bulkhead (BulkheadFullError), an open circuit breaker (CircuitBreakerError), or a lock acquire that did not get in (WouldBlockError, and LockTimeoutError for the bounded form). Catch AdmissionError to handle any admission rejection with one except.

BackendScopeError

Bases: GrelmicroError, RuntimeError

Raised when a backend does not reach as far as its component requires.

A Lock on a memory backend excludes nothing once a second replica runs. So in staging and production, a component bound to a backend whose scope falls short of what it requires refuses to open, before the first connection is made. Wire a backend that reaches far enough, or pass requires= to declare the reach you meant.

micro.check_backends() raises the same error from a test, so the wiring is answered for before a pod answers for it.

Carries the backend-scope code, the same one BackendScopeWarning carries when no tier is declared.

code class-attribute

code: str = 'backend-scope'

DependencyNotFoundError

DependencyNotFoundError(*, module: str)

Bases: GrelmicroError, ImportError

Dependency Not Found Error.

Initialize the error.

DependencyVersionError

DependencyVersionError(
    *,
    module: str,
    version: str | None,
    floor: str,
    extra: str,
)

Bases: GrelmicroError, ImportError

Raised at import when a framework is older than its extra allows.

The message names the version found, the oldest version grelmicro runs on and the grelmicro extra that installs a matching one. A module whose version cannot be read is refused the same way.

Initialize the error.

MultipleActiveAppsError

MultipleActiveAppsError()

Bases: GrelmicroError, RuntimeError

Raised when a second Grelmicro app is opened while one is active.

Components such as Log and Trace configure process-global state (the stdlib root logger, the OpenTelemetry tracer provider) and restore it in reverse order on exit. Two overlapping app lifecycles in the same process would restore that state out of order and clobber each other, so a second concurrent app is blocked by default. Run apps one at a time, or pass Grelmicro(allow_multiple=True) if you are sure no two active apps configure the same global state.

Initialize the error.

OutOfContextError

OutOfContextError(
    cls: object, method_name: str | None = None
)

Bases: GrelmicroError, RuntimeError

Raised when something is used while it is not open.

The message names the object and the call that reached it, whether the object was never opened or already closed. It then names the fixes: registering it on the app so the app opens it, or making the call while it is open.

Initialize the error.

Pass a context object and a method name for the default message, or a single ready-made message string.

AdapterNotRegisteredError

AdapterNotRegisteredError(
    kind: str, short_name: str, available: list[str]
)

Bases: GrelmicroError, LookupError

Raised when no Adapter is registered under a short name for a kind.

Short names resolve against the grelmicro.{kind}.adapters entry-point group. A miss usually means the package that ships the Adapter is not installed, or the name is misspelled.

Initialize the error.

EventLoopDeadlockError

Bases: BaseException

Raised by a sync entry point reached from the loop that has to serve it.

lock.from_thread, rwlock.read.from_thread, rwlock.write.from_thread, task_lock.from_thread, breaker.from_thread, and the sync @cached wrapper hand their work to the event loop the backend runs on and block until it answers. Called from that loop, the answer never arrives: the call waits on the loop it is blocking. Each one raises this instead, so the deadlock is reported rather than reached.

Not a GrelmicroError, and not an Exception at all, so except Exception, a Retry, and a Fallback all pass it through to whoever ran the call.

Use the async API from async code, or reach the sync one through asyncio.to_thread(...). A caller on a different event loop, or on a thread with no loop at all, is served by the backend's own loop and is unaffected.

ProviderNotRegisteredError

ProviderNotRegisteredError(
    short_name: str, available: list[str]
)

Bases: GrelmicroError, LookupError

Raised when no Provider is registered under a requested short name.

Short names resolve against the grelmicro.providers entry-point group. A miss usually means the package that ships the Provider is not installed, or the name is misspelled.

Initialize the error.

AppNotInstalledError

AppNotInstalledError()

Bases: GrelmicroError, LookupError

Raised when route_template(scope) cannot read the route of a request.

route_template(scope) reads the route of a request to an app micro.install(app) wired, once that app runs. It raises on a request to any other app, and from a wrapper that calls it before the installed app runs.

Initialize the error.

GrelmicroConfigWarning

Bases: UserWarning

Warned when configuration is set in a way that will not take effect.

A category of its own so it can be filtered precisely, without silencing every UserWarning and without matching on the message text:

filterwarnings = ["error", "ignore::grelmicro.GrelmicroConfigWarning"]

Each diagnostic also has its own subclass, so one can be silenced without silencing the rest. The code attribute is the diagnostic's stable identifier, matching the section at /diagnostics/#{code}.

code class-attribute

code: str = ''

Stable diagnostic code, empty on the base category.

EnvLoadOffWarning

Bases: GrelmicroConfigWarning

A GREL_* variable is set but GREL_ENV_LOAD is off.

code class-attribute

code: str = 'env-load-off'

BackendScopeWarning

Bases: GrelmicroConfigWarning

A bound backend reaches less far than its component requires.

The same problem raises BackendScopeError in staging and production. Both carry the backend-scope code.

code class-attribute

code: str = 'backend-scope'

AmbientBindingWarning

Bases: GrelmicroConfigWarning

Ambient components are registered but the binding middleware is missing.

The same problem raises AmbientBindingError under Grelmicro(strict=True). Both carry the ambient-binding code.

code class-attribute

code: str = 'ambient-binding'

SentinelPasswordWarning

Bases: GrelmicroConfigWarning

A Sentinel password is set but the URL scheme cannot apply it.

code class-attribute

code: str = 'sentinel-password'

UnknownEnvironmentWarning

Bases: GrelmicroConfigWarning

GREL_ENVIRONMENT names no tier grelmicro knows.

code class-attribute

code: str = 'unknown-environment'

GrelmicroFutureWarning

Bases: FutureWarning

Warned when a default or a name changes in a coming minor release.

A behavior change warns only while the setting is left at its default. Choosing the value explicitly keeps the chosen behavior across the switch and emits nothing. A renamed or removed name warns on every use of the old name, which is removed in the release the message names.

A category of its own so it can be promoted or filtered precisely:

filterwarnings = ["error::grelmicro.GrelmicroFutureWarning"]

Each switching release also has its own subclass, such as Grelmicro045Warning for every change that lands in 0.45.0. The switch_in attribute is that release.

switch_in class-attribute

switch_in: str = ''

The release that brings the change, empty on the base category.

Grelmicro045Warning

Bases: GrelmicroFutureWarning

Warned for a change that lands in 0.45.0.

The change is a default, a read-back value, a check result, or a removed name or value.

A filter on it promotes or silences every change that lands in 0.45.0 and leaves the other releases alone:

filterwarnings = ["error::grelmicro.Grelmicro045Warning"]

switch_in class-attribute

switch_in: str = '0.45.0'