Exceptions

Every exception subclasses a builtin, so existing except clauses keep working.

NoProviderError

exception nodrill.NoProviderError

Bases: LookupError

Raised by use() when no provider is active for the requested key and no fallback is available.

key

The key that was looked up, the string or the class passed to use().

active_keys

A tuple of the keys that were active at the time, in registration order.

diagnosis

Why the key was not visible from here, as a string, or None. Set only when debug() was on for the lookup, and rendered below the message when it is.

The message names the requested key, lists the active ones, and states the fix. For a string key it also offers the nearest match, found with difflib, and for a class key it mentions set_default().

NoProviderError: use('datbase'): no active provider for 'datbase'.
Active providers: 'cache', 'database'. Did you mean 'database'?
Hint: did you forget `with provider('datbase')`?

Because it subclasses LookupError, except LookupError catches it alongside KeyError and IndexError.

KeyResolutionError

exception nodrill.KeyResolutionError

Bases: LookupError

Raised when a key built with ref() cannot be resolved to what its path names.

path

The import path the ref was created with, exactly as written.

Resolution happens the first time the ref is used as a key, so this is raised out of use(), provider(), set_default() or resolve_refs() rather than out of ref() itself. The underlying ImportError, where there is one, is the exception’s __cause__.

Three things go wrong, and each says which.

KeyResolutionError: ref('myapp.contxt:RequestScope'): cannot import 'myapp.contxt':
No module named 'myapp.contxt'

KeyResolutionError: ref('myapp.context:RequestScope'): 'myapp.context' has no
attribute 'RequestScope'

KeyResolutionError: ref('myapp.context:RequestScope'): 'myapp.context' is still
executing its own import, so 'RequestScope' does not exist yet. The lookup ran
during that import, so move it inside a function and it will run once the module
is loaded

The third is the one worth recognising. The lookup ran at module scope inside an import cycle, which is the one place a ref cannot help, because the name genuinely does not exist yet. See Refer to a key you cannot import.

A failure is not cached, so the same ref resolves normally once the import that was in flight completes.

It subclasses LookupError alongside NoProviderError, so except LookupError still catches everything a lookup can raise.

FrozenContextError

exception nodrill.FrozenContextError

Bases: AttributeError

Raised when setting or deleting an attribute on a value that was provided with frozen=True.

The object the with block yields stays writable, and only the view reached through use() refuses writes.

It subclasses AttributeError so that getattr-style guards and duck-typing checks behave as they would on any other object.

UnusedProviderWarning

exception nodrill.UnusedProviderWarning

Bases: UserWarning

Warned by debug() with unused=True when a provider block exits and nothing read what it provided.

A category of its own, so the warning can be silenced by kind rather than by matching the text of its message.

warnings.filterwarnings("ignore", category=nodrill.UnusedProviderWarning)

It subclasses UserWarning, which is what an unfiltered warning is reported as anyway, so nothing that already catches those stops seeing it.