GitHub

API reference for Problem.

A typed RFC 9457 problem (Effect's HttpApiError.Problem), declared by subclassing with its type URI, status and title::

class OutOfCredit(
    Problem,
    type="https://example.com/probs/out-of-credit",
    status=403,
    title="You do not have enough credit.",
):
    balance: float

The class is a yieldable schema error whose _tag is tag (default: the class name), so catch_tag works without a _tag on the wire. An endpoint declaring it answers with status and an application/problem+json body, documents it so and decodes it back. type tells apart problems that share a status: a body of another type is rejected; status and title decode to the declared values whatever the body says. detail and instance are optional (a field of the subclass may replace them); the subclass's fields are its extensions, and unknown ones are dropped. type, status and title cannot be fields of the subclass (TypeError). Errors below 500 are not reported, and an undeclared instance still renders as its problem. message is detail, else title.

Attributes

AttributeTypeDescription
detailstr | None = S.field(_optional_string(), default=None)
instancestr | None = S.field(_optional_string(), default=None)
typestr = S.field(S.String, default=(problem_details.BLANK_TYPE))
statusint = S.field(S.Int, default=500)
titlestr = S.field(S.String, default='')
messagestr

Functions

fields

fields() -> Mapping[str, Bottom[object, object, Never, Never]]

Each field's schema, the tag's first in a tagged class.

Returns Mapping[str, Bottom[object, object, Never, Never]]

@classmethod
def fields(cls) -> Mapping[str, Bottom[object, object, Never, Never]]:
    """Each field's schema, the tag's first in a tagged class."""
    shape = _shape_of(cls)
    schemas = shape.schemas
    if shape.tag is None:
        return dict(schemas)
    tag: Bottom[object, object, Never, Never] = Bottom(ast.Literal(shape.tag))
    return {"_tag": tag, **schemas}

make

make(input, **options) -> Self

input checked against the class's schema (its checks included); raises SchemaError. Construct with cls(...); an instance is kept as it is.

ParameterTypeDescription
inputSelf
optionsUnpack[ParseOptions] = {}

Returns Self

@classmethod
def make(cls, input: Self, /, **options: Unpack[ParseOptions]) -> Self:
    """``input`` checked against the class's schema (its checks
    included); raises ``SchemaError``. Construct with ``cls(...)``; an
    instance is kept as it is."""
    shape = _shape_of(cls)
    return make_class_sync(
        cls.ast.to_type(),
        input,
        options,
        lambda fields: cast("Self", shape.construct(dict(fields))),
    )

make_option

make_option(input, **options) -> Option[Self]
ParameterTypeDescription
inputSelf
optionsUnpack[ParseOptions] = {}

Returns Option[Self]

@classmethod
def make_option(cls, input: Self, /, **options: Unpack[ParseOptions]) -> Option[Self]:
    return cls.__codec__().make_option(input, **options)

make_effect

make_effect(input, **options) -> Effect[Self, Issue]
ParameterTypeDescription
inputSelf
optionsUnpack[ParseOptions] = {}

Returns Effect[Self, Issue]

@classmethod
def make_effect(cls, input: Self, /, **options: Unpack[ParseOptions]) -> Effect[Self, Issue]:
    return cls.__codec__().make_effect(input, **options)

annotate

annotate(**annotations) -> Bottom[Self, Mapping[str, object]]

The class's schema with annotations (a new schema, not a class).

ParameterTypeDescription
annotationsobject = {}

Returns Bottom[Self, Mapping[str, object]]

@classmethod
def annotate(cls, /, **annotations: object) -> Bottom[Self, Mapping[str, object]]:
    """The class's schema with annotations (a new schema, not a class)."""
    return cls.__codec__().annotate(**annotations)

check

check(first, *rest) -> Bottom[Self, Mapping[str, object]]

The class's schema with checks (a new schema, not a class).

ParameterTypeDescription
firstCheck[Self]
restCheck[Self] = ()

Returns Bottom[Self, Mapping[str, object]]

@classmethod
def check(cls, first: Check[Self], /, *rest: Check[Self]) -> Bottom[Self, Mapping[str, object]]:
    """The class's schema with checks (a new schema, not a class)."""
    return cls.__codec__().check(first, *rest)

pipe

pipe[B](f) -> B
ParameterTypeDescription
fCallable[[type[Self]], B]

Returns B

@classmethod
def pipe[B](cls, f: Callable[[type[Self]], B], /) -> B:
    return f(cls)