Skip to content

base

Public base classes for defining C-compatible Pydantic models.

Classes:

  • CCountedBy –

    Pydantic annotated metadata defining the element count in a variable length array.

  • CEncoded –

    Pydantic annotated metadata declaring how to pack/unpack a value from a C encoded buffer.

  • CFormat –

    Pydantic annotated metadata declaring the C format for to pack/unpack a value.

  • CModel –

    Base class for models that can be packed to and unpacked from C-compatible bytes.

CCountedBy dataclass 

CCountedBy(
    *,
    get_count_field_name: Callable[[CBuildContext], str],
    count_field_value_as_int: (
        Callable[[Any], int] | None
    ) = None
)

Pydantic annotated metadata defining the element count in a variable length array.

This should be used to annotate a variadic tuple (tuple[T, ...]) when the number of elements is stored in another field. For example:

from typing import Annotated as An

from cmodel import CCountedBy
from cmodel import CModel


class MyModel(CModel):
    values_count: int
    values: An[tuple[int, ...], CCountedBy.name("values_count")]

By contrast, a bare tuple[T, ...] with no CCountedBy is treated as an unbounded trailing array that reads until the end of the buffer.

Methods:

  • name –

    Create a CCountedBy with the given count field name.

  • template –

    Create a CCountedBy with a template string for the count field name.

Attributes:

count_field_value_as_int class-attribute instance-attribute 

count_field_value_as_int: Callable[[Any], int] | None = None

Cast the value of the count field to an int.

get_count_field_name instance-attribute 

get_count_field_name: Callable[[CBuildContext], str]

Return the field name containing the count of elements, given the name of the array field.

name classmethod 

name(
    count_field_name: str,
    as_int: Callable[[Any], int] | None = None,
) -> Self

Create a CCountedBy with the given count field name.

template classmethod 

template(
    template_str: str,
    as_int: Callable[[Any], int] | None = None,
) -> Self

Create a CCountedBy with a template string for the count field name.

Parameters:

  • template_str

    (str) –

    The template string should contain one {} placeholder, which will be replaced with the name of the array field to get the name of the count field. For example, CCountedByField. template("{}_count") will create a CCountedByField that looks for a count field named <array_field_name>_count for an array field named <array_field_name>.

  • as_int

    (Callable[[Any], int] | None, default: None ) –

    An optional function to cast the value of the count field to an int. For example, you might have a bitmask field where the count is stored as the number of set bits, and you could pass lambda x: x.bit_count() to get the count.

CEncoded dataclass 

CEncoded(
    get_encoder: Callable[
        [CBuildContext], CEncoderSchema[CEncoded[T]]
    ],
)

Pydantic annotated metadata declaring how to pack/unpack a value from a C encoded buffer.

Attributes:

  • get_encoder (Callable[[CBuildContext], CEncoderSchema[CEncoded[T]]]) –

    A function returning a CEncoderSchema for this value given an endianness and size type.

get_encoder instance-attribute 

get_encoder: Callable[
    [CBuildContext], CEncoderSchema[CEncoded[T]]
]

A function returning a CEncoderSchema for this value given an endianness and size type.

CFormat dataclass 

CFormat(
    format: str,
    validate: Callable[
        [tuple[Any, ...]], CFormat[T]
    ] = lambda x: x,
    dump: Callable[
        [CFormat[T]], tuple[Any, ...]
    ] = lambda x: x,
)

Pydantic annotated metadata declaring the C format for to pack/unpack a value.

CModel

Bases: BaseModel

Base class for models that can be packed to and unpacked from C-compatible bytes.

Subclasses behave like normal Pydantic models, but also carry a derived binary schema that c_pack() and c_unpack() use to read and write struct data.

Methods:

  • c_pack –

    Write this model instance to the current position of a binary buffer.

  • c_unpack –

    Read one model instance from the current position of a binary buffer.

Attributes:

  • c_alignment (int) –

    Override the alignment of this struct. Native by default (0).

  • c_endian_type (EndianType) –

    Override the endianness of this struct. Native by default.

  • c_schema (CStructSchema) –

    The C struct schema for this model, derived from the Pydantic schema of the model

  • c_size_type (SizeType) –

    Override the size type of this struct. Native by default.

c_alignment class-attribute 

c_alignment: int = 0

Override the alignment of this struct. Native by default (0).

c_endian_type class-attribute 

c_endian_type: EndianType = 'native'

Override the endianness of this struct. Native by default.

c_schema class-attribute 

c_schema: CStructSchema

The C struct schema for this model, derived from the Pydantic schema of the model

c_size_type class-attribute 

c_size_type: SizeType = 'native'

Override the size type of this struct. Native by default.

c_pack 

c_pack(buffer: BytesIO) -> None

Write this model instance to the current position of a binary buffer.

c_unpack classmethod 

c_unpack(buffer: BytesIO) -> Self

Read one model instance from the current position of a binary buffer.