Selectors¶

Protocols (lenient)¶

Selector ¶

Bases: Protocol

Any callable returning a queryset, list, or single object.

Used as a structural type for documentation purposes; the views accept any plain callable, so satisfying this protocol is optional.

AsyncSelector ¶

Bases: Protocol

Async sibling of :class:Selector.

ListSelector ¶

Bases: Protocol[ResultT]

Structural shape for a list-action selector callable.

The framework calls this from get_queryset(); the returned iterable flows through DRF's filter backends, pagination, and output_serializer.

Lenient by design: **kwargs: Any lets the framework deliver URL kwargs and extras from SelectorSpec.kwargs / get_selector_kwargs without forcing the selector to declare them.

RetrieveSelector ¶

Bases: Protocol[ResultT]

Structural shape for a retrieve-action selector callable.

The framework calls this from get_object(). Returning None (or raising Model.DoesNotExist) results in a 404. The URL lookup field (typically pk) is delivered via **kwargs.

Lenient by design — see :class:ListSelector for rationale.

OutputSelector ¶

Bases: Protocol[InT, OutT]

Structural shape for a ServiceSpec.output_selector callable.

Invoked after the service returns. Receives the service's return value as result and may transform it (e.g. attach computed fields, swap to a different shape) before serialization.

Lenient by design — see :class:~rest_framework_services.services.CreateService for rationale.

Protocols (strict)¶

StrictListSelector ¶

Bases: Protocol[ResultT, ExtraT]

Strict shape for a list-action selector.

See :class:~rest_framework_services.services.StrictCreateService for rationale. ExtraT should declare both URL kwargs and any extras supplied by SelectorSpec.kwargs.

StrictRetrieveSelector ¶

Bases: Protocol[ResultT, ExtraT]

Strict shape for a retrieve-action selector.

See :class:~rest_framework_services.services.StrictCreateService for rationale. ExtraT typically contains the URL lookup field (pk, slug) plus any extras from SelectorSpec.kwargs.

StrictOutputSelector ¶

Bases: Protocol[InT, OutT, ExtraT]

Strict shape for a ServiceSpec.output_selector.

See :class:~rest_framework_services.services.StrictCreateService for rationale.

Dispatch¶

utils ¶

Internal selector dispatch helpers (sync + async).

run_selector ¶

run_selector(fn: Callable[..., Any], kwargs: dict[str, Any]) -> Any

Call a selector from sync code, transparently bridging async ones.

arun_selector `async` ¶

arun_selector(
    fn: Callable[..., Any] | Callable[..., Awaitable[Any]], kwargs: dict[str, Any]
) -> Any

Call a selector from async code; sync ones run inline.

dispatch_selector_for_spec ¶

dispatch_selector_for_spec(
    view: Any,
    spec: SelectorSpec[Any, Any],
    *,
    extra_url_kwargs: dict[str, Any] | None = None,
) -> Any

End-to-end dispatch for one SelectorSpec call.

Runs the kwargs-resolution chain (spec.kwargs → get_<action>_selector_kwargs → get_selector_kwargs), filters the resulting pool against the selector's signature, and invokes it sync-or-async. Used by both selector viewset mixins and the standalone selector views so the call shape lives in one place.

The caller must check spec.selector is not None before calling and fall back to vanilla DRF otherwise.

dispatch_retrieve_selector ¶

dispatch_retrieve_selector(
    view: Any,
    spec: SelectorSpec[Any, Any],
    *,
    extra_url_kwargs: dict[str, Any] | None = None,
) -> Any

Like :func:dispatch_selector_for_spec, with retrieve-flavoured 404s.

Wraps :exc:~django.core.exceptions.ObjectDoesNotExist and a None return as :exc:~rest_framework.exceptions.NotFound. Used by both the standalone retrieve view and the retrieve viewset mixin.