An entity type: subclass it with the RPCs as attributes and
type= its name (the class name when left out). An entity listing
its RPCs' tags, class Counter(Entity[Literal["Increment"]]), has its
handlers checked by pyright: to_layer rejects them while an RPC has
none (Effect's toLayer). The class is checked against the list when
it is defined.
Attributes#
| Attribute | Type | Description |
|---|---|---|
type | EntityType | |
rpcs | Mapping[str, AnyRpc] = {} | |
annotations | Context[Any] = Context.empty() | |
protocol | builtins.type[RpcGroup] |
Functions#
annotate#
annotate[A, T](tag, value) -> builtins.type[Self]This entity with value for tag in its annotations.
| Parameter | Type | Description |
|---|---|---|
tag | TagLike[A, T] | |
value | A |
Returns builtins.type[Self]
@classmethod
def annotate[A, T](cls, tag: TagLike[A, T], value: A) -> builtins.type[Self]:
"""This entity with ``value`` for ``tag`` in its annotations."""
return cls._derive(annotations=Context.make(tag, value))annotate_merge#
annotate_merge(annotations) -> builtins.type[Self]| Parameter | Type | Description |
|---|---|---|
annotations | Context[Any] |
Returns builtins.type[Self]
@classmethod
def annotate_merge(cls, annotations: Context[Any]) -> builtins.type[Self]:
return cls._derive(annotations=annotations)annotate_rpcs#
annotate_rpcs[A, T](tag, value) -> builtins.type[Self]This entity with value for tag on each RPC that has no
value of its own.
| Parameter | Type | Description |
|---|---|---|
tag | TagLike[A, T] | |
value | A |
Returns builtins.type[Self]
@classmethod
def annotate_rpcs[A, T](cls, tag: TagLike[A, T], value: A) -> builtins.type[Self]:
"""This entity with ``value`` for ``tag`` on each RPC that has no
value of its own."""
return cls._derive(rpc_annotations=Context.make(tag, value))annotate_rpcs_merge#
annotate_rpcs_merge(annotations) -> builtins.type[Self]| Parameter | Type | Description |
|---|---|---|
annotations | Context[Any] |
Returns builtins.type[Self]
@classmethod
def annotate_rpcs_merge(cls, annotations: Context[Any]) -> builtins.type[Self]:
return cls._derive(rpc_annotations=annotations)get_shard_group#
get_shard_group(entity_id) -> strThe shard group of entity_id (ShardGroup, "default"
unless annotated).
| Parameter | Type | Description |
|---|---|---|
entity_id | EntityId |
Returns str
@classmethod
def get_shard_group(cls, entity_id: EntityId) -> str:
"""The shard group of ``entity_id`` (``ShardGroup``, ``"default"``
unless annotated)."""
return cls.annotations.get(ShardGroup)(entity_id)get_shard_id#
get_shard_id(entity_id) -> Effect[ShardId, Never, Sharding]| Parameter | Type | Description |
|---|---|---|
entity_id | EntityId |
Returns Effect[ShardId, Never, Sharding]
@classmethod
def get_shard_id(cls, entity_id: EntityId) -> Effect[ShardId, Never, Sharding]:
return Sharding().map(
lambda sharding: sharding.get_shard_id(entity_id, cls.get_shard_group(entity_id))
)client#
client() -> Effect[Callable[[str], Self], Never, Sharding]A function giving the client of an entity id.
Returns Effect[Callable[[str], Self], Never, Sharding]
@classmethod
def client(cls) -> Effect[Callable[[str], Self], Never, Sharding]:
"""A function giving the client of an entity id."""
return Sharding().flat_map(lambda sharding: sharding.make_client(cls))handlers#
handlers() -> EntityHandlers[Self, Never, Tags_contra]No handlers yet: add one per RPC with handle.
Returns EntityHandlers[Self, Never, Tags_contra]
@classmethod
def handlers(cls) -> EntityHandlers[Self, Never, Tags_contra]:
"""No handlers yet: add one per RPC with ``handle``."""
return EntityHandlers(cls, {})to_handlers#
to_handlers(build) -> Effect[Context[Any], Never, Any]The handler services of the entity's protocol (Effect's
RpcGroup.toHandlers): each handler gets the entity Request
(the RPC request's payload) and runs with the services of the
caller of this effect.
| Parameter | Type | Description |
|---|---|---|
build | Effect[EntityHandlers[Any, Any], Never, Any] |
Returns Effect[Context[Any], Never, Any]
@classmethod
def to_handlers(
cls, build: Effect[EntityHandlers[Any, Any], Never, Any]
) -> Effect[Context[Any], Never, Any]:
"""The handler services of the entity's ``protocol`` (Effect's
``RpcGroup.toHandlers``): each handler gets the entity ``Request``
(the RPC request's payload) and runs with the services of the
caller of this effect."""
require_effect(build, "build")
@gen
def make():
services = yield from context()
handlers = yield from build
message = cls._missing_message(handlers)
if message is not None:
return (yield from die(ValueError(message)))
kept = Context({t: s for t, s in services.map_unsafe.items() if t is not Scope})
entries: dict[Any, Any] = {}
for tag, rpc in cls.rpcs.items():
handler = handlers.by_tag[tag]
entries[handler_tag(rpc)] = HandlerEntry(tag, _payload_handler(handler), kept)
return Context(entries)
return maketo_layer#
to_layer[R](handlers, /, *, max_idle_time=None, concurrency=1, mailbox_capacity=None, mailbox_metrics=None, disable_fatal_defects=False, defect_retry_policy=None, span_attributes=None) -> Layer[Never, Never, R | Sharding]Register the entity's handlers with Sharding (Effect's
toLayer). An RPC without a handler is a pyright error when the
entity lists its tags (Entity[Literal[...]]), and a
ValueError here either way.
| Parameter | Type | Description |
|---|---|---|
handlers | EntityHandlers[Self, R, Never] | |
max_idle_time | DurationInput | None = None | |
concurrency | Concurrency = 1 | |
mailbox_capacity | Concurrency | None = None | |
mailbox_metrics | bool | None = None | |
disable_fatal_defects | bool = False | |
defect_retry_policy | Schedule[Any, Any, Any, Any] | None = None | |
span_attributes | Mapping[str, str] | None = None |
Returns Layer[Never, Never, R | Sharding]
@classmethod
def to_layer[R](
cls,
handlers: EntityHandlers[Self, R, Never],
/,
*,
max_idle_time: DurationInput | None = None,
concurrency: Concurrency = 1,
mailbox_capacity: Concurrency | None = None,
mailbox_metrics: bool | None = None,
disable_fatal_defects: bool = False,
defect_retry_policy: Schedule[Any, Any, Any, Any] | None = None,
span_attributes: Mapping[str, str] | None = None,
) -> Layer[Never, Never, R | Sharding]:
"""Register the entity's ``handlers`` with ``Sharding`` (Effect's
``toLayer``). An RPC without a handler is a pyright error when the
entity lists its tags (``Entity[Literal[...]]``), and a
``ValueError`` here either way."""
message = cls._missing_message(handlers)
if message is not None:
raise ValueError(message)
options = parse_options(
max_idle_time=max_idle_time,
concurrency=concurrency,
mailbox_capacity=mailbox_capacity,
mailbox_metrics=mailbox_metrics,
disable_fatal_defects=disable_fatal_defects,
defect_retry_policy=defect_retry_policy,
span_attributes=span_attributes,
)
return cls._register(succeed(handlers), options)to_layer_effect#
to_layer_effect[RR, RX](build, /, *, max_idle_time=None, concurrency=1, mailbox_capacity=None, mailbox_metrics=None, disable_fatal_defects=False, defect_retry_policy=None, span_attributes=None) -> Layer[Never, Never, RR | RX | Sharding]to_layer with the handlers made by build, which runs each
time an entity starts, with its CurrentAddress,
CurrentRunnerAddress and activation Scope.
| Parameter | Type | Description |
|---|---|---|
build | Effect[EntityHandlers[Self, RR, Never], Never, RX | _Activation] | |
max_idle_time | DurationInput | None = None | |
concurrency | Concurrency = 1 | |
mailbox_capacity | Concurrency | None = None | |
mailbox_metrics | bool | None = None | |
disable_fatal_defects | bool = False | |
defect_retry_policy | Schedule[Any, Any, Any, Any] | None = None | |
span_attributes | Mapping[str, str] | None = None |
Returns Layer[Never, Never, RR | RX | Sharding]
@classmethod
def to_layer_effect[RR, RX](
cls,
build: Effect[EntityHandlers[Self, RR, Never], Never, RX | _Activation],
/,
*,
max_idle_time: DurationInput | None = None,
concurrency: Concurrency = 1,
mailbox_capacity: Concurrency | None = None,
mailbox_metrics: bool | None = None,
disable_fatal_defects: bool = False,
defect_retry_policy: Schedule[Any, Any, Any, Any] | None = None,
span_attributes: Mapping[str, str] | None = None,
) -> Layer[Never, Never, RR | RX | Sharding]:
"""``to_layer`` with the handlers made by ``build``, which runs each
time an entity starts, with its ``CurrentAddress``,
``CurrentRunnerAddress`` and activation ``Scope``."""
require_effect(build, "build")
options = parse_options(
max_idle_time=max_idle_time,
concurrency=concurrency,
mailbox_capacity=mailbox_capacity,
mailbox_metrics=mailbox_metrics,
disable_fatal_defects=disable_fatal_defects,
defect_retry_policy=defect_retry_policy,
span_attributes=span_attributes,
)
return cls._register(cast("Effect[EntityHandlers[Any, Any], Never, Any]", build), options)to_layer_queue#
to_layer_queue[R](behaviour, /, *, max_idle_time=None, mailbox_capacity=None, mailbox_metrics=None, disable_fatal_defects=False, defect_retry_policy=None, span_attributes=None) -> Layer[Never, Never, R | Sharding]Register the entity served by behaviour, which takes each
request from a mailbox queue and answers it with a Replier
(Effect's toLayerQueue). It is forked when an entity starts,
and requests run concurrently.
| Parameter | Type | Description |
|---|---|---|
behaviour | Behaviour[R] | |
max_idle_time | DurationInput | None = None | |
mailbox_capacity | Concurrency | None = None | |
mailbox_metrics | bool | None = None | |
disable_fatal_defects | bool = False | |
defect_retry_policy | Schedule[Any, Any, Any, Any] | None = None | |
span_attributes | Mapping[str, str] | None = None |
Returns Layer[Never, Never, R | Sharding]
@classmethod
def to_layer_queue[R](
cls,
behaviour: Behaviour[R],
/,
*,
max_idle_time: DurationInput | None = None,
mailbox_capacity: Concurrency | None = None,
mailbox_metrics: bool | None = None,
disable_fatal_defects: bool = False,
defect_retry_policy: Schedule[Any, Any, Any, Any] | None = None,
span_attributes: Mapping[str, str] | None = None,
) -> Layer[Never, Never, R | Sharding]:
"""Register the entity served by ``behaviour``, which takes each
request from a mailbox queue and answers it with a ``Replier``
(Effect's ``toLayerQueue``). It is forked when an entity starts,
and requests run concurrently."""
options = parse_options(
max_idle_time=max_idle_time,
concurrency="unbounded",
mailbox_capacity=mailbox_capacity,
mailbox_metrics=mailbox_metrics,
disable_fatal_defects=disable_fatal_defects,
defect_retry_policy=defect_retry_policy,
span_attributes=span_attributes,
)
return cls._register(queue_handlers(cls, behaviour), options)to_layer_queue_effect#
to_layer_queue_effect[R, RX](build, /, *, max_idle_time=None, mailbox_capacity=None, mailbox_metrics=None, disable_fatal_defects=False, defect_retry_policy=None, span_attributes=None) -> Layer[Never, Never, R | RX | Sharding]to_layer_queue with the behaviour made by build when an
entity starts.
| Parameter | Type | Description |
|---|---|---|
build | Effect[Behaviour[R], Never, RX | _Activation] | |
max_idle_time | DurationInput | None = None | |
mailbox_capacity | Concurrency | None = None | |
mailbox_metrics | bool | None = None | |
disable_fatal_defects | bool = False | |
defect_retry_policy | Schedule[Any, Any, Any, Any] | None = None | |
span_attributes | Mapping[str, str] | None = None |
Returns Layer[Never, Never, R | RX | Sharding]
@classmethod
def to_layer_queue_effect[R, RX](
cls,
build: Effect[Behaviour[R], Never, RX | _Activation],
/,
*,
max_idle_time: DurationInput | None = None,
mailbox_capacity: Concurrency | None = None,
mailbox_metrics: bool | None = None,
disable_fatal_defects: bool = False,
defect_retry_policy: Schedule[Any, Any, Any, Any] | None = None,
span_attributes: Mapping[str, str] | None = None,
) -> Layer[Never, Never, R | RX | Sharding]:
"""``to_layer_queue`` with the behaviour made by ``build`` when an
entity starts."""
require_effect(build, "build")
options = parse_options(
max_idle_time=max_idle_time,
concurrency="unbounded",
mailbox_capacity=mailbox_capacity,
mailbox_metrics=mailbox_metrics,
disable_fatal_defects=disable_fatal_defects,
defect_retry_policy=defect_retry_policy,
span_attributes=span_attributes,
)
handlers = build.flat_map(lambda behaviour: queue_handlers(cls, behaviour))
return cls._register(handlers, options)