firstclass 0.0.1__py3-none-any.whl

firstclass/__init__.py

@@ -0,0 +1,26 @@
+from ._core import firstclass
+from ._specs import (
+    array_t,
+    bool_t,
+    bytes_t,
+    char_array,
+    char_t,
+    float32_t,
+    float64_t,
+    int8_t,
+    int16_t,
+    int32_t,
+    int64_t,
+    uint8_t,
+    uint16_t,
+    uint32_t,
+    uint64_t,
+)
+
+__all__ = [
+    "firstclass",
+    "uint8_t", "uint16_t", "uint32_t", "uint64_t",
+    "int8_t", "int16_t", "int32_t", "int64_t",
+    "float32_t", "float64_t", "bool_t", "char_t",
+    "char_array", "bytes_t", "array_t",
+]

firstclass/_core.py

@@ -0,0 +1,251 @@
+"""The @firstclass decorator and the per-class Schema it attaches."""
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+import json
+import sys
+import typing
+import xml.etree.ElementTree as ET
+
+from ._specs import ArrayOf, Nested, Spec, resolve_spec
+
+_METHODS = (
+    "to_bytes", "from_bytes", "to_dict", "from_dict", "to_json", "from_json",
+    "to_xml", "from_xml", "to_ctypes", "from_ctypes", "ctypes_type", "c_header", "sizeof",
+)
+
+
+def _round_up(n: int, a: int) -> int:
+    return -(-n // a) * a
+
+
+class Schema:
+    def __init__(self, cls, byteorder: str, align: bool):
+        if byteorder not in ("little", "big"):
+            raise ValueError(f"byteorder must be 'little' or 'big', got {byteorder!r}")
+        self.cls = cls
+        self.bo = "<" if byteorder == "little" else ">"
+        self.byteorder = byteorder
+        self.aligned = align
+        self._fields: list[tuple[dataclasses.Field, Spec]] | None = None
+        self._layout = None
+        self._ctype = None
+
+    # -- structure -----------------------------------------------------------
+
+    @property
+    def fields(self):
+        if self._fields is None:
+            hints = typing.get_type_hints(self.cls, include_extras=True)
+            self._fields = [(f, resolve_spec(hints[f.name])) for f in dataclasses.fields(self.cls)]
+        return self._fields
+
+    def require_binary(self):
+        for f, spec in self.fields:
+            if not spec.binary:
+                raise TypeError(
+                    f"{self.cls.__name__}.{f.name}: type {spec.tp!r} has no binary form; "
+                    "annotate it with uint8_t, char_array[N], ... or a firstclass class"
+                )
+
+    def layout(self):
+        if self._layout is None:
+            self.require_binary()
+            off, widest, offsets = 0, 1, []
+            for _, spec in self.fields:
+                a = spec.align() if self.aligned else 1
+                off = _round_up(off, a)
+                offsets.append(off)
+                off += spec.size()
+                widest = max(widest, a)
+            self._layout = (offsets, _round_up(off, widest), widest)
+        return self._layout
+
+    def size(self) -> int:
+        return self.layout()[1]
+
+    def align(self) -> int:
+        return self.layout()[2]
+
+    def _build(self, kw: dict):
+        init = {k: v for k, v in kw.items() if self._by_name[k].init}
+        obj = self.cls(**init)
+        for k, v in kw.items():
+            if not self._by_name[k].init:
+                object.__setattr__(obj, k, v)
+        return obj
+
+    @property
+    def _by_name(self):
+        return {f.name: f for f, _ in self.fields}  # small; fields are cached
+
+    def _ctx(self, f, exc):
+        return type(exc)(f"{self.cls.__name__}.{f.name}: {exc}")
+
+    # -- bytes ---------------------------------------------------------------
+
+    def pack(self, obj) -> bytes:
+        offsets, total, _ = self.layout()
+        buf = bytearray(total)
+        for (f, spec), off in zip(self.fields, offsets):
+            try:
+                raw = spec.pack(getattr(obj, f.name), self.bo)
+            except (TypeError, ValueError) as e:
+                raise self._ctx(f, e) from e
+            buf[off:off + len(raw)] = raw
+        return bytes(buf)
+
+    def unpack(self, buf, off: int = 0):
+        offsets, total, _ = self.layout()
+        if len(buf) - off < total:
+            raise ValueError(f"{self.cls.__name__} needs {total} bytes, got {len(buf) - off}")
+        kw = {}
+        for (f, spec), o in zip(self.fields, offsets):
+            try:
+                kw[f.name] = spec.unpack(buf, off + o, self.bo)
+            except (TypeError, ValueError) as e:
+                raise self._ctx(f, e) from e
+        return self._build(kw)
+
+    def from_bytes(self, data):
+        data = memoryview(data).cast("B") if not isinstance(data, (bytes, bytearray)) else data
+        if len(data) != self.size():
+            raise ValueError(f"{self.cls.__name__} needs exactly {self.size()} bytes, got {len(data)}")
+        return self.unpack(data, 0)
+
+    # -- dict / json / xml ---------------------------------------------------
+
+    def to_dict(self, obj) -> dict:
+        return {f.name: spec.to_json(getattr(obj, f.name)) for f, spec in self.fields}
+
+    def from_dict(self, d):
+        if not isinstance(d, dict):
+            raise TypeError(f"{self.cls.__name__}.from_dict needs a dict, got {type(d).__name__}")
+        unknown = set(d) - set(self._by_name)
+        if unknown:
+            raise ValueError(f"{self.cls.__name__}: unknown keys {sorted(unknown)}")
+        kw = {}
+        for f, spec in self.fields:
+            if f.name in d:
+                try:
+                    kw[f.name] = spec.from_json(d[f.name])
+                except (TypeError, ValueError) as e:
+                    raise self._ctx(f, e) from e
+        return self._build(kw)
+
+    def fill_xml(self, obj, elem: ET.Element) -> None:
+        for f, spec in self.fields:
+            spec.to_xml(getattr(obj, f.name), ET.SubElement(elem, f.name))
+
+    def read_xml(self, elem: ET.Element):
+        known = self._by_name
+        specs = {f.name: s for f, s in self.fields}
+        kw = {}
+        for child in elem:
+            if child.tag not in known:
+                raise ValueError(f"{self.cls.__name__}: unknown element <{child.tag}>")
+            if child.tag in kw:
+                raise ValueError(f"{self.cls.__name__}: duplicate element <{child.tag}>")
+            spec = specs[child.tag]
+            try:
+                kw[child.tag] = spec.from_xml(child)
+            except (TypeError, ValueError) as e:
+                raise self._ctx(known[child.tag], e) from e
+        return self._build(kw)
+
+    # -- ctypes / C ----------------------------------------------------------
+
+    def ctypes_type(self):
+        if self._ctype is None:
+            self.require_binary()
+            base = ctypes.LittleEndianStructure if self.bo == "<" else ctypes.BigEndianStructure
+            ns = {"_fields_": [(f.name, spec.ctype(self.bo)) for f, spec in self.fields]}
+            if not self.aligned:
+                ns["_pack_"] = 1
+                if sys.version_info >= (3, 14):
+                    ns["_layout_"] = "ms"
+            self._ctype = type(self.cls.__name__ + "_c", (base,), ns)
+        return self._ctype
+
+    def to_ctypes(self, obj):
+        c = self.ctypes_type()()
+        for f, spec in self.fields:
+            try:
+                setattr(c, f.name, spec.to_c(getattr(obj, f.name)))
+            except (TypeError, ValueError) as e:
+                raise self._ctx(f, e) from e
+        return c
+
+    def from_ctypes(self, c):
+        return self._build({f.name: spec.from_c(getattr(c, f.name)) for f, spec in self.fields})
+
+    def _nested_schemas(self):
+        for _, spec in self.fields:
+            while isinstance(spec, ArrayOf):
+                spec = spec.elem
+            if isinstance(spec, Nested):
+                yield spec.schema
+
+    def c_header(self) -> str:
+        self.require_binary()
+        out, seen = [], set()
+
+        def emit(schema):
+            if schema.cls in seen:
+                return
+            seen.add(schema.cls)
+            for dep in schema._nested_schemas():
+                emit(dep)
+            lines = [f"/* byteorder: {schema.byteorder} */"]
+            if not schema.aligned:
+                lines.append("#pragma pack(push, 1)")
+            lines.append(f"struct {schema.cls.__name__} {{")
+            lines += [f"    {spec.c_decl(f.name)};" for f, spec in schema.fields]
+            lines.append("};")
+            if not schema.aligned:
+                lines.append("#pragma pack(pop)")
+            out.append("\n".join(lines))
+
+        emit(self)
+        return "#include <stdint.h>\n#include <stdbool.h>\n\n" + "\n\n".join(out) + "\n"
+
+
+def firstclass(cls=None, /, *, byteorder: str = "little", align: bool = False, **dataclass_kwargs):
+    """Like `@dataclass` (same keyword args), plus binary/JSON/XML/ctypes/C codecs.
+
+    byteorder: 'little' (default) or 'big'.
+    align: False (default) = packed layout, no padding; True = natural C alignment padding.
+    """
+
+    def wrap(cls):
+        dc = dataclasses.dataclass(cls, **dataclass_kwargs)
+        clash = [f.name for f in dataclasses.fields(dc) if f.name in _METHODS or f.name == "__firstclass__"]
+        if clash:
+            raise TypeError(f"{dc.__name__}: field names clash with firstclass methods: {clash}")
+        s = Schema(dc, byteorder, align)
+        dc.__firstclass__ = s
+        dc.to_bytes = lambda self: s.pack(self)
+        dc.from_bytes = staticmethod(s.from_bytes)
+        dc.to_dict = lambda self: s.to_dict(self)
+        dc.from_dict = staticmethod(s.from_dict)
+        dc.to_json = lambda self, **kw: json.dumps(s.to_dict(self), **kw)
+        dc.from_json = staticmethod(lambda text: s.from_dict(json.loads(text)))
+        dc.to_xml = lambda self, indent=None: _to_xml(s, self, indent)
+        dc.from_xml = staticmethod(lambda text: s.read_xml(ET.fromstring(text)))
+        dc.to_ctypes = lambda self: s.to_ctypes(self)
+        dc.from_ctypes = staticmethod(s.from_ctypes)
+        dc.ctypes_type = staticmethod(s.ctypes_type)
+        dc.c_header = staticmethod(s.c_header)
+        dc.sizeof = staticmethod(s.size)
+        return dc
+
+    return wrap if cls is None else wrap(cls)
+
+
+def _to_xml(schema: Schema, obj, indent) -> str:
+    root = ET.Element(schema.cls.__name__)
+    schema.fill_xml(obj, root)
+    if indent is not None:
+        ET.indent(root, space=" " * indent if isinstance(indent, int) else indent)
+    return ET.tostring(root, encoding="unicode")

firstclass/_specs.py

@@ -0,0 +1,526 @@
+"""Field specs: how one annotated field maps to bytes, JSON, XML and ctypes."""
+from __future__ import annotations
+
+import binascii
+import ctypes
+import struct
+import sys
+from typing import Annotated, Any, get_origin
+import xml.etree.ElementTree as ET
+
+
+class Spec:
+    """Base class. `bo` is a struct byte-order prefix: '<' or '>'."""
+
+    binary = True
+
+    def align(self) -> int:
+        raise NotImplementedError
+
+    def size(self) -> int:
+        raise NotImplementedError
+
+    def check(self, value: Any) -> Any:
+        """Validate (and normalise) a python value; raises TypeError/ValueError."""
+        raise NotImplementedError
+
+    def pack(self, value: Any, bo: str) -> bytes:
+        raise NotImplementedError
+
+    def unpack(self, buf, off: int, bo: str) -> Any:
+        raise NotImplementedError
+
+    def to_json(self, value: Any) -> Any:
+        raise NotImplementedError
+
+    def from_json(self, obj: Any) -> Any:
+        raise NotImplementedError
+
+    def to_xml(self, value: Any, elem: ET.Element) -> None:
+        raise NotImplementedError
+
+    def from_xml(self, elem: ET.Element) -> Any:
+        raise NotImplementedError
+
+    def ctype(self, bo: str):
+        raise NotImplementedError
+
+    def to_c(self, value: Any) -> Any:
+        raise NotImplementedError
+
+    def from_c(self, cvalue: Any) -> Any:
+        raise NotImplementedError
+
+    def c_decl(self, name: str) -> str:
+        raise NotImplementedError
+
+
+def _xml_text(elem: ET.Element) -> str:
+    return elem.text or ""
+
+
+class Scalar(Spec):
+    def __init__(self, name: str, fmt: str, ctype, c_name: str, kind: str):
+        self.name, self.fmt, self._ctype, self.c_name, self.kind = name, fmt, ctype, c_name, kind
+        self._size = struct.calcsize("<" + fmt)
+        if kind == "int":
+            bits = self._size * 8
+            signed = fmt.islower()
+            self.lo, self.hi = (-(1 << (bits - 1)), (1 << (bits - 1)) - 1) if signed else (0, (1 << bits) - 1)
+
+    def align(self):
+        return self._size
+
+    def size(self):
+        return self._size
+
+    def check(self, value):
+        if self.kind == "bool":
+            if not isinstance(value, bool):
+                raise TypeError(f"{self.name} needs bool, got {type(value).__name__}")
+        elif self.kind == "int":
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise TypeError(f"{self.name} needs int, got {type(value).__name__}")
+            if not self.lo <= value <= self.hi:
+                raise ValueError(f"{value} out of range for {self.name} [{self.lo}, {self.hi}]")
+        else:
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise TypeError(f"{self.name} needs float, got {type(value).__name__}")
+        return value
+
+    def pack(self, value, bo):
+        value = self.check(value)
+        try:
+            return struct.pack(bo + self.fmt, value)
+        except (OverflowError, struct.error) as e:
+            raise ValueError(f"{value!r} does not fit {self.name}: {e}") from e
+
+    def unpack(self, buf, off, bo):
+        return struct.unpack_from(bo + self.fmt, buf, off)[0]
+
+    def to_json(self, value):
+        return value
+
+    def from_json(self, obj):
+        return self.check(obj)
+
+    def to_xml(self, value, elem):
+        elem.text = ("true" if value else "false") if self.kind == "bool" else repr(value)
+
+    def from_xml(self, elem):
+        text = _xml_text(elem).strip()
+        if self.kind == "bool":
+            if text not in ("true", "false"):
+                raise ValueError(f"bad bool text {text!r}")
+            return text == "true"
+        return self.check(int(text) if self.kind == "int" else float(text))
+
+    def ctype(self, bo):
+        return self._ctype
+
+    def to_c(self, value):
+        return self.check(value)
+
+    def from_c(self, cvalue):
+        return cvalue
+
+    def c_decl(self, name):
+        return f"{self.c_name} {name}"
+
+
+class CharArray(Spec):
+    """Fixed-size, NUL-padded UTF-8 string, like `char name[N]`."""
+
+    def __init__(self, n: int):
+        self.n = n
+
+    def align(self):
+        return 1
+
+    def size(self):
+        return self.n
+
+    def _encode(self, value) -> bytes:
+        if not isinstance(value, str):
+            raise TypeError(f"char_array needs str, got {type(value).__name__}")
+        if "\0" in value:
+            raise ValueError("char_array value must not contain NUL")
+        raw = value.encode("utf-8")
+        if len(raw) > self.n:
+            raise ValueError(f"{value!r} is {len(raw)} bytes, char_array[{self.n}] holds {self.n}")
+        return raw
+
+    def check(self, value):
+        self._encode(value)
+        return value
+
+    def pack(self, value, bo):
+        return self._encode(value).ljust(self.n, b"\0")
+
+    def unpack(self, buf, off, bo):
+        return bytes(buf[off:off + self.n]).split(b"\0", 1)[0].decode("utf-8")
+
+    def to_json(self, value):
+        return value
+
+    def from_json(self, obj):
+        return self.check(obj)
+
+    def to_xml(self, value, elem):
+        elem.text = value
+
+    def from_xml(self, elem):
+        return self.check(_xml_text(elem))
+
+    def ctype(self, bo):
+        return ctypes.c_char * self.n
+
+    def to_c(self, value):
+        return self._encode(value)
+
+    def from_c(self, cvalue):
+        return bytes(cvalue).split(b"\0", 1)[0].decode("utf-8")
+
+    def c_decl(self, name):
+        return f"char {name}[{self.n}]"
+
+
+class ByteArray(Spec):
+    """Fixed-size raw bytes, exactly N long."""
+
+    def __init__(self, n: int):
+        self.n = n
+
+    def align(self):
+        return 1
+
+    def size(self):
+        return self.n
+
+    def check(self, value):
+        if not isinstance(value, (bytes, bytearray, memoryview)):
+            raise TypeError(f"bytes_t needs bytes, got {type(value).__name__}")
+        value = bytes(value)
+        if len(value) != self.n:
+            raise ValueError(f"bytes_t[{self.n}] needs exactly {self.n} bytes, got {len(value)}")
+        return value
+
+    def pack(self, value, bo):
+        return self.check(value)
+
+    def unpack(self, buf, off, bo):
+        return bytes(buf[off:off + self.n])
+
+    def to_json(self, value):
+        return value.hex()
+
+    def from_json(self, obj):
+        if not isinstance(obj, str):
+            raise TypeError("bytes_t JSON value must be a hex string")
+        try:
+            return self.check(binascii.unhexlify(obj))
+        except binascii.Error as e:
+            raise ValueError(f"bad hex string: {e}") from e
+
+    def to_xml(self, value, elem):
+        elem.text = value.hex()
+
+    def from_xml(self, elem):
+        return self.from_json(_xml_text(elem).strip())
+
+    def ctype(self, bo):
+        return ctypes.c_ubyte * self.n
+
+    def to_c(self, value):
+        return (ctypes.c_ubyte * self.n).from_buffer_copy(self.check(value))
+
+    def from_c(self, cvalue):
+        return bytes(cvalue)
+
+    def c_decl(self, name):
+        return f"uint8_t {name}[{self.n}]"
+
+
+class ArrayOf(Spec):
+    """Fixed-length array of any other spec, exactly N elements."""
+
+    def __init__(self, elem: Spec, n: int):
+        self.elem, self.n = elem, n
+        self.binary = elem.binary
+
+    def align(self):
+        return self.elem.align()
+
+    def size(self):
+        return self.elem.size() * self.n
+
+    def check(self, value):
+        if not isinstance(value, (list, tuple)):
+            raise TypeError(f"array_t needs list, got {type(value).__name__}")
+        if len(value) != self.n:
+            raise ValueError(f"array_t[..., {self.n}] needs {self.n} items, got {len(value)}")
+        return [self.elem.check(v) for v in value]
+
+    def pack(self, value, bo):
+        return b"".join(self.elem.pack(v, bo) for v in self.check(value))
+
+    def unpack(self, buf, off, bo):
+        step = self.elem.size()
+        return [self.elem.unpack(buf, off + i * step, bo) for i in range(self.n)]
+
+    def to_json(self, value):
+        return [self.elem.to_json(v) for v in value]
+
+    def from_json(self, obj):
+        if not isinstance(obj, (list, tuple)):
+            raise TypeError("array_t JSON value must be a list")
+        return self.check([self.elem.from_json(v) for v in obj])
+
+    def to_xml(self, value, elem):
+        for v in value:
+            self.elem.to_xml(v, ET.SubElement(elem, "item"))
+
+    def from_xml(self, elem):
+        kids = list(elem)
+        if any(k.tag != "item" for k in kids):
+            raise ValueError("array children must be <item>")
+        return self.check([self.elem.from_xml(k) for k in kids])
+
+    def ctype(self, bo):
+        return self.elem.ctype(bo) * self.n
+
+    def to_c(self, value):
+        arr = self.ctype(None)()
+        for i, v in enumerate(self.check(value)):
+            c = self.elem.to_c(v)
+            if isinstance(self.elem, CharArray):  # array items need an instance, not bytes
+                c = self.elem.ctype(None).from_buffer_copy(c.ljust(self.elem.n, b"\0"))
+            arr[i] = c
+        return arr
+
+    def from_c(self, cvalue):
+        return [self.elem.from_c(cvalue[i]) for i in range(self.n)]
+
+    def c_decl(self, name):
+        return self.elem.c_decl(f"{name}[{self.n}]")
+
+
+class Nested(Spec):
+    """A field whose type is itself a firstclass class."""
+
+    def __init__(self, schema):
+        self.schema = schema
+
+    def align(self):
+        return self.schema.align()
+
+    def size(self):
+        return self.schema.size()
+
+    def check(self, value):
+        if not isinstance(value, self.schema.cls):
+            raise TypeError(f"expected {self.schema.cls.__name__}, got {type(value).__name__}")
+        return value
+
+    def pack(self, value, bo):
+        return self.schema.pack(self.check(value))
+
+    def unpack(self, buf, off, bo):
+        return self.schema.unpack(buf, off)
+
+    def to_json(self, value):
+        return self.schema.to_dict(value)
+
+    def from_json(self, obj):
+        return self.schema.from_dict(obj)
+
+    def to_xml(self, value, elem):
+        self.schema.fill_xml(value, elem)
+
+    def from_xml(self, elem):
+        return self.schema.read_xml(elem)
+
+    def ctype(self, bo):
+        return self.schema.ctypes_type()
+
+    def to_c(self, value):
+        return self.schema.to_ctypes(self.check(value))
+
+    def from_c(self, cvalue):
+        return self.schema.from_ctypes(cvalue)
+
+    def c_decl(self, name):
+        return f"struct {self.schema.cls.__name__} {name}"
+
+
+class Plain(Spec):
+    """Un-annotated field: JSON/XML only, no binary form."""
+
+    binary = False
+
+    def __init__(self, tp):
+        self.tp = tp
+
+    def check(self, value):
+        return value
+
+    def to_json(self, value):
+        return value
+
+    def from_json(self, obj):
+        return obj
+
+    def to_xml(self, value, elem):
+        if self.tp is bool:
+            elem.text = "true" if value else "false"
+        elif self.tp in (int, float, str):
+            elem.text = str(value) if self.tp is not float else repr(value)
+        else:
+            raise TypeError(f"XML needs a firstclass type for {self.tp!r}")
+
+    def from_xml(self, elem):
+        text = _xml_text(elem)
+        if self.tp is bool:
+            if text.strip() not in ("true", "false"):
+                raise ValueError(f"bad bool text {text!r}")
+            return text.strip() == "true"
+        if self.tp in (int, float):
+            return self.tp(text.strip())
+        if self.tp is str:
+            return text
+        raise TypeError(f"XML needs a firstclass type for {self.tp!r}")
+
+
+_NATIVE_BO = "<" if sys.byteorder == "little" else ">"
+_PTR_SIZE = ctypes.sizeof(ctypes.c_void_p)
+
+
+class Pointer(Scalar):
+    """A ctypes pointer field. The python value is the address as an int (0 = NULL).
+
+    The bytes are the raw address, so it only round-trips inside one process/ABI.
+    """
+
+    def __init__(self, tp):
+        code = "Q" if _PTR_SIZE == 8 else "I"
+        super().__init__("pointer", code, ctypes.c_void_p, "void *", "int")
+        self.tp = tp
+
+    def ctype(self, bo):
+        if bo != _NATIVE_BO:
+            raise TypeError("ctypes pointers need the platform's native byteorder")
+        return self.tp
+
+    def to_c(self, value):
+        value = self.check(value)
+        if self.tp is ctypes.c_void_p:
+            return value
+        return ctypes.cast(ctypes.c_void_p(value), self.tp)
+
+    def from_c(self, cvalue):
+        if isinstance(cvalue, int) or cvalue is None:
+            return cvalue or 0
+        return ctypes.cast(cvalue, ctypes.c_void_p).value or 0
+
+    def c_decl(self, name):
+        return f"void *{name}"
+
+
+_SIGNED = {1: ctypes.c_int8, 2: ctypes.c_int16, 4: ctypes.c_int32, 8: ctypes.c_int64}
+_UNSIGNED = {1: ctypes.c_uint8, 2: ctypes.c_uint16, 4: ctypes.c_uint32, 8: ctypes.c_uint64}
+_INT_CODES = "bBhHiIlLqQ"
+
+
+def _ctypes_spec(tp):
+    """Spec for a raw ctypes type used as an annotation, or None."""
+    if not isinstance(tp, type):
+        return None
+    if issubclass(tp, ctypes.Array):
+        elem = tp._type_
+        if elem is ctypes.c_char:
+            return CharArray(tp._length_)
+        sub = resolve_spec(elem)
+        return None if not sub.binary else ArrayOf(sub, tp._length_)
+    if issubclass(tp, ctypes._Pointer):
+        return Pointer(tp)
+    if issubclass(tp, ctypes.Structure) or issubclass(tp, ctypes.Union):
+        return None
+    if not issubclass(tp, ctypes._SimpleCData):
+        return None
+    code = tp._type_
+    if code in "PzZ":
+        return Pointer(ctypes.c_void_p)
+    if code == "?":
+        return Scalar("c_bool", "?", ctypes.c_bool, "bool", "bool")
+    if code == "c":
+        return CharArray(1)
+    if code == "f":
+        return Scalar("c_float", "f", ctypes.c_float, "float", "float")
+    if code == "d":
+        return Scalar("c_double", "d", ctypes.c_double, "double", "float")
+    if code in _INT_CODES:
+        size = ctypes.sizeof(tp)
+        unsigned = code.isupper()
+        canon = (_UNSIGNED if unsigned else _SIGNED)[size]
+        fmt = {1: "b", 2: "h", 4: "i", 8: "q"}[size]
+        name = f"{'u' if unsigned else ''}int{size * 8}_t"
+        return Scalar(tp.__name__, fmt.upper() if unsigned else fmt, canon, name, "int")
+    return None
+
+
+def resolve_spec(tp) -> Spec:
+    if get_origin(tp) is Annotated:
+        for meta in tp.__metadata__:
+            if isinstance(meta, Spec):
+                return meta
+    schema = getattr(tp, "__firstclass__", None) if isinstance(tp, type) else None
+    if schema is not None:
+        return Nested(schema)
+    return _ctypes_spec(tp) or Plain(tp)
+
+
+def _positive(n) -> int:
+    if isinstance(n, bool) or not isinstance(n, int) or n <= 0:
+        raise TypeError(f"size must be a positive int, got {n!r}")
+    return n
+
+
+# --- public type markers -----------------------------------------------------
+
+uint8_t = Annotated[int, Scalar("uint8_t", "B", ctypes.c_uint8, "uint8_t", "int")]
+uint16_t = Annotated[int, Scalar("uint16_t", "H", ctypes.c_uint16, "uint16_t", "int")]
+uint32_t = Annotated[int, Scalar("uint32_t", "I", ctypes.c_uint32, "uint32_t", "int")]
+uint64_t = Annotated[int, Scalar("uint64_t", "Q", ctypes.c_uint64, "uint64_t", "int")]
+int8_t = Annotated[int, Scalar("int8_t", "b", ctypes.c_int8, "int8_t", "int")]
+int16_t = Annotated[int, Scalar("int16_t", "h", ctypes.c_int16, "int16_t", "int")]
+int32_t = Annotated[int, Scalar("int32_t", "i", ctypes.c_int32, "int32_t", "int")]
+int64_t = Annotated[int, Scalar("int64_t", "q", ctypes.c_int64, "int64_t", "int")]
+float32_t = Annotated[float, Scalar("float32_t", "f", ctypes.c_float, "float", "float")]
+float64_t = Annotated[float, Scalar("float64_t", "d", ctypes.c_double, "double", "float")]
+bool_t = Annotated[bool, Scalar("bool_t", "?", ctypes.c_bool, "bool", "bool")]
+char_t = Annotated[str, CharArray(1)]
+
+
+class char_array:
+    """`char_array[N]`: NUL-padded UTF-8 string in N bytes."""
+
+    def __class_getitem__(cls, n):
+        return Annotated[str, CharArray(_positive(n))]
+
+
+class bytes_t:
+    """`bytes_t[N]`: exactly N raw bytes."""
+
+    def __class_getitem__(cls, n):
+        return Annotated[bytes, ByteArray(_positive(n))]
+
+
+class array_t:
+    """`array_t[T, N]`: exactly N items of T (scalar, char_array, or firstclass class)."""
+
+    def __class_getitem__(cls, params):
+        try:
+            elem, n = params
+        except (TypeError, ValueError):
+            raise TypeError("array_t needs two params: array_t[element_type, length]") from None
+        return Annotated[list, ArrayOf(resolve_spec(elem), _positive(n))]

firstclass-0.0.1.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: firstclass
+Version: 0.0.1
+Summary: dataclass with bytes, ctypes, C struct, JSON and XML serialization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# firstclass
+
+`@firstclass` works like `@dataclass` (same keyword args) and adds conversion to and from
+packed bytes, `ctypes`, a C struct header, JSON and XML. Pure Python 3.10+, no dependencies.
+
+```python
+from firstclass import firstclass, uint8_t, uint16_t, int32_t, float32_t, bool_t, char_array, bytes_t, array_t
+
+@firstclass
+class Point:
+    x: int32_t
+    y: int32_t
+
+@firstclass
+class Packet:
+    kind: uint8_t
+    ok: bool_t
+    temp: float32_t
+    name: char_array[8]        # NUL-padded UTF-8
+    mac: bytes_t[6]            # exactly 6 bytes
+    samples: array_t[uint16_t, 4]
+    origin: Point              # nested
+
+p = Packet(1, True, 21.5, "sensor", b"\x00\x11\x22\x33\x44\x55", [1, 2, 3, 4], Point(10, -20))
+
+raw = p.to_bytes()                 # packed, little-endian
+assert Packet.from_bytes(raw) == p
+Packet.sizeof()                    # 36
+```
+
+## Types
+
+| Marker | C | Bytes |
+|---|---|---|
+| `uint8_t` `uint16_t` `uint32_t` `uint64_t` | `uintN_t` | 1/2/4/8 |
+| `int8_t` `int16_t` `int32_t` `int64_t` | `intN_t` | 1/2/4/8 |
+| `float32_t` / `float64_t` | `float` / `double` | 4 / 8 |
+| `bool_t` | `bool` | 1 |
+| `char_t` | `char` | 1 |
+| `char_array[N]` | `char x[N]` | N (UTF-8, NUL-padded) |
+| `bytes_t[N]` | `uint8_t x[N]` | N |
+| `array_t[T, N]` | `T x[N]` | N * size(T) |
+| another `@firstclass` class | `struct Name` | its size |
+
+Values are checked: out of range ints, over-long strings and wrong lengths raise
+`ValueError`; wrong Python types raise `TypeError`. Nothing is truncated or coerced silently.
+
+Raw `ctypes` types work as annotations too (packed, same layout as a `_pack_ = 1` Structure):
+`ctypes.c_int`, `c_uint64`, `c_size_t`, `c_bool`, `c_float`, `c_double`, `c_char`, `c_uint16 * 4`,
+`c_char * 8`. Pointers (`c_void_p`, `POINTER(T)`, `c_char_p`) are stored as the address (an `int`,
+0 = NULL) at pointer size; `to_ctypes()` gives a real pointer field you can dereference. The
+address only means something inside the same process. Sizes follow the platform
+(`c_long` is 4 bytes on Windows, 8 on Linux).
+
+## Methods added to every class
+
+| Method | |
+|---|---|
+| `obj.to_bytes()` / `Cls.from_bytes(data)` | binary; `from_bytes` needs exactly `sizeof()` bytes |
+| `Cls.sizeof()` | size in bytes |
+| `obj.to_dict()` / `Cls.from_dict(d)` | JSON-compatible dict (bytes as hex) |
+| `obj.to_json(**kw)` / `Cls.from_json(s)` | `kw` goes to `json.dumps` |
+| `obj.to_xml(indent=None)` / `Cls.from_xml(s)` | `<Packet><kind>1</kind>...</Packet>`, arrays as `<item>` |
+| `obj.to_ctypes()` / `Cls.from_ctypes(c)` / `Cls.ctypes_type()` | `ctypes.Structure` with matching layout |
+| `Cls.c_header()` | C source for the struct(s), nested ones first |
+
+## Layout options
+
+```python
+@firstclass(byteorder="big")   # default "little"
+@firstclass(align=True)        # default False = packed, no padding (like __attribute__((packed)))
+@firstclass(frozen=True, slots=True)   # any dataclass option
+```
+
+`align=True` inserts natural-alignment padding like a normal C struct (assumes the x86-64 style
+rule: alignment equals size). Padding bytes are written as zero and ignored on read.
+C headers describe the struct only; C compilers use native byte order, so `byteorder` is noted
+in a comment.
+
+## Notes
+
+- Fields with plain types (`str`, `int`) work for JSON/XML only; `to_bytes()` raises
+  `TypeError` naming the field.
+- Use `from __future__ import annotations` freely; annotations are resolved lazily. Classes
+  defined inside functions that refer to local names are not resolvable.
+- Don't parse untrusted XML with `from_xml` without extra care (stdlib `xml.etree`).
+- Field names that collide with the generated methods (`to_bytes`, ...) raise `TypeError`.
+
+## Example
+
+`python examples/example.py` shows bytes, JSON, XML, ctypes and the C header from one class.
+
+## Develop
+
+```
+python -m unittest discover -s tests
+```

firstclass-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+firstclass/__init__.py,sha256=ZpxYPlIPoVFGN1ouH9a-Zqnx68s1x6U2tQxTeVI3u0o,477
+firstclass/_core.py,sha256=25F5VoaJI6rPUcCQKMr7wK9Jdb8Edqg4TdU5WN__1_o,9852
+firstclass/_specs.py,sha256=naIM81qiAoyKY5GJVEiHA2zduJjtA5Y0IE0jWN2saQA,16398
+firstclass-0.0.1.dist-info/METADATA,sha256=KJ0uORJ26VH5mzyb2P9ACrwg-dpg8jS6KXv1HG2EnG8,4142
+firstclass-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+firstclass-0.0.1.dist-info/top_level.txt,sha256=97bGTourIpqo_FxCQEDC1ZrU6r220PBcE2XqKahU4nM,11
+firstclass-0.0.1.dist-info/RECORD,,

firstclass-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

firstclass-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+firstclass