pre-alpha

Reference

Parsers and renderers

Updated November 20, 2026 3 min read

hinoki.parsers.Parser

Base class of body parsers.

hinoki.parsers.JSONParser

Bases: Parser

JSON, decoded by the Rust parser (strict: no NaN, no lone surrogates, depth limit). Customise by overriding prepare(data) to reshape the decoded value (for example rename keys) or media_type (application/vnd.api+json).

prepare

prepare(data: object) -> object

Hook: the value the action sees (default: as decoded).

hinoki.parsers.FormParser

FormParser(max_fields: int = DEFAULT_FIELDS)

Bases: Parser

application/x-www-form-urlencoded. data holds the last value of each field as text.

hinoki.parsers.MultiPartParser

MultiPartParser(
    max_parts: int = DEFAULT_PARTS,
    max_part_bytes: int = DEFAULT_PART_BYTES,
)

Bases: Parser

multipart/form-data with at most max_parts parts of at most max_part_bytes bytes each (the whole body is capped separately).

Selected automatically, with the default limits, for an action that binds an UploadedFile without choosing its parsers; pass it explicitly to change the limits.

hinoki.parsers.TextParser

Bases: Parser

text/plain bodies as a str (UTF-8, strict).

hinoki.parsers.BytesParser

Bases: Parser

application/octet-stream bodies as the raw bytes, unchanged.

hinoki.parsers.XMLParser

XMLParser(
    max_depth: int = DEFAULT_XML_DEPTH,
    max_elements: int = DEFAULT_XML_ELEMENTS,
)

Bases: Parser

application/xml. data is the tree under the root element: an element with children is a dict, a repeated child name a list, a text-only element a str and an empty one None. Attributes are not read. DTDs, custom entities, characters XML 1.0 forbids and an encoding other than UTF-8 are refused, and nesting (at most MAX_XML_DEPTH) and element count are capped.

hinoki.parsers.Parsed dataclass

Parsed(
    data: object,
    fields: Mapping[str, list[str]] = dict(),
    files: Mapping[str, list[UploadedFile]] = dict(),
)

What a parser produced: data for request.data plus form fields and files for request.POST / request.FILES.

hinoki.errors.InvalidBody

InvalidBody(code: str, message: str)

Bases: Exception

The request body cannot be used at all (wrong media type, bad JSON).

hinoki.UploadedFile dataclass

UploadedFile(
    name: str,
    filename: str,
    content_type: str,
    content: bytes,
)

A multipart file. filename is exactly what the client sent: never use it as a path.

hinoki.renderers.Renderer

Base class of response renderers.

hinoki.renderers.JSONRenderer

JSONRenderer(
    indent: int | None = None,
    sort_keys: bool = False,
    default: Callable[[Any], Any] | None = None,
)

Bases: Renderer

JSON, written by the Rust encoder. Customise without leaving Rust:

  • options: JSONRenderer(indent=2, sort_keys=True, default=fn) where default turns a value that is not JSON (a Decimal, a Path) into one that is;
  • a subclass overriding prepare(value, request) to reshape the result (envelopes, key renaming) before it is encoded, and/or media_type (for application/vnd.api+json).

prepare

prepare(value: object, request: Request) -> object

Hook: the value to encode (default: unchanged).

hinoki.renderers.HTMLRenderer

Bases: Renderer

A handler that returns str answers HTML (UTF-8). The string is sent as is: escape untrusted data before putting it in.

hinoki.renderers.TextRenderer

Bases: Renderer

A handler that returns str answers plain text (UTF-8).

hinoki.renderers.XMLRenderer

XMLRenderer(root: str = 'response', item: str = 'item')

Bases: Renderer

The JSON-compatible result as XML (UTF-8, with an XML declaration).

A mapping becomes child elements named by its keys, a list becomes repeated item elements, None an empty element, and true/false are written in lower case. Keys are spelled as JSON spells them (None as null, booleans true/false, integers in decimal) and any other key is refused, as JSON refuses it. A key that is not a valid XML name (it has a space, starts with a digit, begins with xml) is written as <item key="..."> instead of failing. Characters XML 1.0 cannot carry are replaced by U+FFFD. XMLRenderer(root="orders", item="order") renames the root element and the list item.