asphalt.core.context

class asphalt.core.context.Resource(value, types, alias, context_attr, creator=None)

Contains the resource value or its creator callable, plus some metadata.

Variables:
  • alias (str) – alias of the resource
  • types (Sequence[str]) – type names the resource was registered with
  • context_attr (str) – the context attribute of the resource
  • creator (Callable[[Context], Any]) – callable to create the value (in case of a lazy resource)
class asphalt.core.context.ResourceEvent(source, topic, resource)

Dispatched when a resource has been published to or removed from a context.

Variables:
exception asphalt.core.context.ResourceConflict

Raised when a new resource that is being published conflicts with an existing resource or context variable.

exception asphalt.core.context.ResourceNotFound(type, alias)

Raised when a resource request cannot be fulfilled within the allotted time.

class asphalt.core.context.ContextFinishEvent(source, topic, exception)

Dispatched when a context has served its purpose and is being torn down.

Variables:exception (Optional[BaseException]) – the exception that caused the context to finish, if any
class asphalt.core.context.Context(parent=None, *, default_timeout=5)

Contexts give request handlers and callbacks access to resources.

Contexts are stacked in a way that accessing an attribute that is not present in the current context causes the attribute to be looked up in the parent instance and so on, until the attribute is found (or AttributeError is raised).

Requesting or publishing of resources MUST NOT be attempted during or after the dispatch of the finished event.

Parameters:
Variables:
  • finished (Signal) – a signal (ContextFinishEvent) dispatched when the context has served its purpose and is being discarded
  • resource_published (Signal) – a signal (ResourceEvent) dispatched when a resource has been published in this context
  • resource_removed (Signal) – a signal (ResourceEvent): dispatched when a resource has been removed from this context
get_resources(type=None, *, include_parents=True)

Return the currently published resources specific to one type or all types.

Parameters:
  • type (Union[str, type, None]) – type of the resources to return, or None to return all resources
  • include_parents (bool) – include the resources from parent contexts
Return type:

Sequence[Resource]
parent

Return the parent of this context or None if there is no parent context.

Return type:Optional[Context]
publish_lazy_resource(creator, types, alias='default', context_attr=None)

Publish a “lazy” or “contextual” resource and dispatch a resource_published event.

Instead of a concrete resource value, you supply a creator callable which is called with a context object as its argument when the resource is being requested either via request_resource() or by context attribute access. The return value of the creator callable will be cached so the creator will only be called once per context instance.

If the creator callable is a coroutine function or returns an awaitable, it is resolved before storing the resource value and returning it to the requester. Note that this will NOT work when a context attribute has been specified for the resource.

Parameters:
  • creator (Callable[[Context], Any]) – a callable taking a context instance as argument
  • types (Union[type, Iterable[Union[str, type]]]) – type(s) to register the resource as
  • alias (str) – name of this resource (unique among all its registered types)
  • context_attr (Optional[str]) – name of the context attribute this resource will be accessible as
Return type:

Resource
Returns:

the resource handle
Raises:

asphalt.core.context.ResourceConflict – if there is an existing resource creator for the given types or context variable
publish_resource(value, alias='default', context_attr=None, *, types=())

Publish a resource and dispatch a resource_published event.

Parameters:
  • value – the actual resource value
  • alias (str) – name of this resource (unique among all its registered types)
  • context_attr (Optional[str]) – name of the context attribute this resource will be accessible as
  • types (Union[type, Iterable[Union[str, type]]]) – type(s) to register the resource as (omit to use the type of value)
Return type:

Resource
Returns:

the resource handle
Raises:

asphalt.core.context.ResourceConflict – if the resource conflicts with an existing one in any way
remove_resource(resource)

Remove the given resource from the collection and dispatch a resource_removed event.

Parameters:resource (Resource) – the resource to be removed
Raises:LookupError – the given resource was not in the collection
coroutine request_resource(self, type, alias='default', *, timeout=None)

Request a resource matching the given type and alias.

If no such resource was found, this method will wait timeout seconds for it to become available. The timeout does not apply to resolving awaitables created by lazy resource creators.

Parameters:
  • type (Union[str, type]) – type of the requested resource
  • alias (str) – alias of the requested resource
  • timeout (Union[int, float, None]) – the timeout (in seconds; omit to use the context’s default timeout)
Returns:

the value contained by the requested resource (NOT a Resource instance)
Raises:

asphalt.core.context.ResourceNotFound – if the requested resource does not become available in the allotted time