GitHub

API reference for Entity.

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

AttributeTypeDescription
typeEntityType
rpcsMapping[str, AnyRpc] = {}
annotationsContext[Any] = Context.empty()
protocolbuiltins.type[RpcGroup]

Functions

annotate

annotate[A, T](tag, value) -> builtins.type[Self]

This entity with value for tag in its annotations.

ParameterTypeDescription
tagTagLike[A, T]
valueA

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]
ParameterTypeDescription
annotationsContext[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.

ParameterTypeDescription
tagTagLike[A, T]
valueA

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]
ParameterTypeDescription
annotationsContext[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) -> str

The shard group of entity_id (ShardGroup, "default" unless annotated).

ParameterTypeDescription
entity_idEntityId

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]
ParameterTypeDescription
entity_idEntityId

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.

ParameterTypeDescription
buildEffect[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 make

to_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.

ParameterTypeDescription
handlersEntityHandlers[Self, R, Never]
max_idle_timeDurationInput | None = None
concurrencyConcurrency = 1
mailbox_capacityConcurrency | None = None
mailbox_metricsbool | None = None
disable_fatal_defectsbool = False
defect_retry_policySchedule[Any, Any, Any, Any] | None = None
span_attributesMapping[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.

ParameterTypeDescription
buildEffect[EntityHandlers[Self, RR, Never], Never, RX | _Activation]
max_idle_timeDurationInput | None = None
concurrencyConcurrency = 1
mailbox_capacityConcurrency | None = None
mailbox_metricsbool | None = None
disable_fatal_defectsbool = False
defect_retry_policySchedule[Any, Any, Any, Any] | None = None
span_attributesMapping[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.

ParameterTypeDescription
behaviourBehaviour[R]
max_idle_timeDurationInput | None = None
mailbox_capacityConcurrency | None = None
mailbox_metricsbool | None = None
disable_fatal_defectsbool = False
defect_retry_policySchedule[Any, Any, Any, Any] | None = None
span_attributesMapping[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.

ParameterTypeDescription
buildEffect[Behaviour[R], Never, RX | _Activation]
max_idle_timeDurationInput | None = None
mailbox_capacityConcurrency | None = None
mailbox_metricsbool | None = None
disable_fatal_defectsbool = False
defect_retry_policySchedule[Any, Any, Any, Any] | None = None
span_attributesMapping[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)