_codecs_array

data.drivers._pelt._codecs_array

module

E2 codec family: PostgreSQL arrays (1-D and N-D), parametric on element type.

PostgreSQL models every array type as a distinct OID (_int4 = 1007, _text= 1009, …) whose elements share…

E2 codec family: PostgreSQL arrays (1-D and N-D), parametric on element type.

PostgreSQL models every array type as a distinct OID (_int4 = 1007, _text= 1009, …) whose elements share one element OID. The binary wire layout is a fixed header followed by a row-major run of length-prefixed element payloads:

int32  ndim          -- number of dimensions (0 => empty array, header ends here)
int32  flags         -- bit 0 set => the array contains at least one SQL NULL
int32  element_oid   -- OID of the element type
ndim * (             -- one pair per dimension
    int32 dim_length     -- number of elements along this dimension
    int32 lower_bound )  -- starting subscript (PostgreSQL default is 1)
elements...          -- prod(dim_lengths) elements, row-major (last axis varies fastest)
    int32 length         -- byte length of this element (-1 => SQL NULL, no payload)
    byte  value[length]  -- the element payload, decoded by the element codec

Because element decoding resolves to a codec only at plan time (the element OID is known from the array OID, but the codec is looked up against a registry snapshot), arrays are a parametric family: this module exports puredecode_array / encode_arrayhelpers plus amake_array_codec() factory that closes over a concrete element codec, rather than ready-to-register leaf codecs.LEAF_CODECSis therefore empty.

This module touches no socket and no anyio — bytes in, nested Python lists out.

data.drivers._pelt._codecs_array

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function decode_array

Decode a binary array payload into nested Python lists.

decode_elemdecodes one element's raw bytes (typically the element codec's decode_binary); SQL NULL elements…

function encode_array

Encode a nested Python list into a binary array payload.

encode_elemencodes one non-NULL element to its raw bytes (typically the element codec'sencode_binary…

function make_array_codec

Build an arrayCodec that wraps element_codec's binary functions.

The returned codec decodes/encodes the binaryarray format only; the text path falls back…

decode_array

function

def decode_array(data: bytes, decode_elem: Callable[[bytes], Any]) -> list

Decode a binary array payload into nested Python lists.

decode_elemdecodes one element's raw bytes (typically the element codec's decode_binary); SQL NULL elements become None and never reach decode_elem. A truncated or self-inconsistent payload raisesProtocolError— arrays arrive from the framer, so a malformed body is a protocol fault, not caller misuse. The whole buffer must be consumed: a stray trailing byte (even after a complete array) raises ProtocolErrorrather than being silently dropped, since it signals an upstream framing desync — unrecoverable on that connection.

Parameters

Name	Type	Default	Description
`data`	`bytes`	—
`decode_elem`	`Callable[[bytes], Any]`	—

encode_array

function

def encode_array(value: list, *, element_oid: int, encode_elem: Callable[[Any], bytes], ndim_hint: int | None = None) -> bytes

Encode a nested Python list into a binary array payload.

encode_elemencodes one non-NULL element to its raw bytes (typically the element codec'sencode_binary); None elements are emitted as the -1NULL sentinel and set the has-nulls header flag.ndim_hintbounds dimension inference for the rare case of an array of lists (where the leaf type is itself a list); whenNonethe shape is inferred by walking the nesting until a non-list leaf.

Any array with zero total elements encodes as the canonical zero-dimension header, regardless of nesting depth — PostgreSQL flattens every empty array ([], [[]], [[], []]) to the same ndim=0 form, and decode_arrayof that header returns a bare[](so an empty nested input does not round-trip back to its original nesting). A nesting deeper than PostgreSQL'sMAXDIMis impossible on a real server and is rejected asValueError (caller misuse); a ragged (non-rectangular) valueis likewise aValueError.

Parameters

Name	Type	Default
`value`	`list`	—
`element_oid`	`int`	—
`encode_elem`	`Callable[[Any], bytes]`	—
`ndim_hint`	`int \| None`	`None`

make_array_codec

function

def make_array_codec(*, array_oid: int, name: str, element_oid: int, element_codec: Codec) -> Codec

Build an arrayCodec that wraps element_codec's binary functions.

The returned codec decodes/encodes the binary array format only; the text path falls back to the binary functions (PostgreSQL's text array syntax —{1,2,3}with quoting and escaping rules — is out of scope here, since pelt prefers binary for arrays). The factory is parametric: callers resolveelement_codecagainst a registry snapshot at plan time and pass it in, keeping this module free of any global registry coupling.

Parameters

Name	Type	Default
`array_oid`	`int`	—
`name`	`str`	—
`element_oid`	`int`	—
`element_codec`	`Codec`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/data/drivers/_pelt/_codecs_array.py:1