kdbxtool.parsing.context

Parsing and building context classes for binary data.

This module provides structured helpers for reading and writing binary data with good error messages and type safety.

Classes

BuildContext([_parts])	Stateful writer for building binary data.
ParseContext(data[, offset, _path])	Stateful reader for binary data with error context tracking.

class kdbxtool.parsing.context.ParseContext(data, offset=0, _path=<factory>)

Bases: object

Stateful reader for binary data with error context tracking.

Tracks the current offset and a path of nested scopes for error messages. When parsing fails, error messages include the full path to the failure point.

Example

ctx = ParseContext(data) with ctx.scope(“header”):

magic = ctx.read(8, “magic”) with ctx.scope(“version”):

major = ctx.read_u16(“major”)

# Error would show: “Unexpected EOF at header/version/major, offset 10”

Parameters:

• data (bytes)

• offset (int)

• _path (list[str])

data: bytes

offset: int = 0

read(n, name='')

Read n bytes from current position.

Parameters:

• n (int) – Number of bytes to read

• name (str) – Optional name for error messages

Returns:

The bytes read

Raises:

CorruptedDataError – If not enough bytes available

Return type:

bytes

read_u8(name='')

Read unsigned 8-bit integer.

Parameters:

name (str)

Return type:

int

read_u16(name='')

Read unsigned 16-bit little-endian integer.

Parameters:

name (str)

Return type:

int

read_u32(name='')

Read unsigned 32-bit little-endian integer.

Parameters:

name (str)

Return type:

int

read_u64(name='')

Read unsigned 64-bit little-endian integer.

Parameters:

name (str)

Return type:

int

read_bytes_prefixed(name='')

Read length-prefixed bytes (4-byte little-endian length prefix).

Parameters:

name (str) – Optional name for error messages

Returns:

The bytes read (not including the length prefix)

Return type:

bytes

peek(n)

Peek at next n bytes without advancing offset.

Parameters:

n (int) – Number of bytes to peek

Returns:

The bytes (may be shorter if near end of data)

Return type:

bytes

skip(n, name='')

Skip n bytes.

Parameters:

• n (int) – Number of bytes to skip

• name (str) – Optional name for error messages

Raises:

CorruptedDataError – If not enough bytes available

Return type:

None

scope(name)

Create a named scope for error context.

Parameters:

name (str) – Scope name to add to error path

Return type:

Iterator[None]

Example

with ctx.scope(“inner_header”):

field_type = ctx.read_u8(“type”)

property remaining: int

Number of bytes remaining to read.

property exhausted: bool

True if all bytes have been read.

property position: int

Current read position (alias for offset).

__init__(data, offset=0, _path=<factory>)

Parameters:

• data (bytes)

• offset (int)

• _path (list[str])

Return type:

None

class kdbxtool.parsing.context.BuildContext(_parts=<factory>)

Bases: object

Stateful writer for building binary data.

Accumulates bytes in a list and joins them efficiently at the end.

Example

ctx = BuildContext() ctx.write(MAGIC_BYTES) ctx.write_u32(version) ctx.write_tlv(FIELD_TYPE, field_data) result = ctx.build()

Parameters:

_parts (list[bytes])

write(data)

Write raw bytes.

Parameters:

data (bytes)

Return type:

None

write_u8(value)

Write unsigned 8-bit integer.

Parameters:

value (int)

Return type:

None

write_u16(value)

Write unsigned 16-bit little-endian integer.

Parameters:

value (int)

Return type:

None

write_u32(value)

Write unsigned 32-bit little-endian integer.

Parameters:

value (int)

Return type:

None

write_u64(value)

Write unsigned 64-bit little-endian integer.

Parameters:

value (int)

Return type:

None

write_bytes_prefixed(data)

Write length-prefixed bytes (4-byte little-endian length prefix).

Parameters:

data (bytes)

Return type:

None

write_tlv(type_id, data, type_size=1)

Write Type-Length-Value field.

Parameters:

• type_id (int) – Field type identifier

• data (bytes) – Field data

• type_size (int) – Size of type field in bytes (1 for KDBX4, can vary)

Return type:

None

build()

Join all accumulated bytes and return result.

Return type:

bytes

property size: int

Total size of accumulated bytes.

__init__(_parts=<factory>)

Parameters:

_parts (list[bytes])

Return type:

None