Skip to content

Read mask

rn_forge.web.read_mask

The readMask query parameter: partial responses (AIP-157).

READ_MASK_PARAM = 'readMask' module-attribute

The name of the query parameter that carries the mask.

FieldTree = Mapping[str, FieldTree | None]

The declared shape of a representation, by wire field name.

A declared object, or a list of declared objects, maps to a subtree. Every other field maps to None, including a free-form JSON value.

ReadMask(tree) dataclass

A validated, merged set of field paths.

tree maps each selected wire field name to a subtree of selected sub-fields, or to None when the whole value is selected.

apply(body)

Return a copy of body holding only the selected fields.

A path through a list applies to every element. A selected field that body lacks is not added.

parse_read_mask(raw, *, fields)

Parse a readMask value against the declared fields of a representation.

Paths are comma-separated and joined by .; whitespace around a path is ignored. Overlapping paths merge, so address and address.city select the whole address.

Parameters:

Name Type Description Default
raw str | None

The raw query value.

required
fields FieldTree

The declared shape of the representation.

required

Returns:

Type Description
ReadMask | None

None when raw is absent, blank or *: the whole representation.

Raises:

Type Description
InvalidReadMask

* is combined with other paths, or a path is empty or names no declared field, including one that goes inside a scalar or free-form field.