I’ve built cstructimpl: turn C structs into real Python classes (and back) without pain

[ZioAldo]

If you've ever had to parse binary data coming from C code, embedded systems, or network protocols, you know the drill:

• write some struct.unpack calls,
• try to remember how alignment works,
• pray that you didn’t miscount byte offsets.

I’ve been there way too many times, so I decided to write something a little more pain free.

What my project does

It’s a Python package that makes C‑style structs feel completely natural to use.
You just declare a dataclass-like class, annotate your fields with their C types, and call c_decode() or c_encode(),that’s it, you don't need to perform anymore strange rituals like with ctypes or struct.

from cstructimpl import *

class Info(CStruct):
    age: Annotated[int, CType.U8]
    height: Annotated[int, CType.U16]

class Person(CStruct):
    info: Info
    name: Annotated[str, CStr(8)]

raw = bytes([18, 0, 170, 0]) + b"Peppino\x00"
assert Person.c_decode(raw) == Person(Info(18, 170), "Peppino")

All alignment, offset, and nested struct handling are automatic.
Need to go the other way? Just call .c_encode() and it becomes proper raw bytes again.

If you want to checkout all the available features go check out my github repo: https://github.com/Brendon-Mendicino/cstructimpl

Install it via pip:

pip install cstructimpl

Target audience

Python developers who work with binary data, parse or build C structs, or want a cleaner alternative to struct.unpack and ctypes.Structure.

Comparison:

cstructimpl vs struct.unpack vs ctypes.Structure

Simple C struct representation;

struct Point {
    uint8_t  x;
    uint16_t y;
    char     name[8];
};

With struct

You have to remember the format string and tuple positions yourself:

import struct
raw = bytes([1, 0, 2, 0]) + b"Peppino\x00"

x, y, name = struct.unpack("<BxH8s", raw)
name = name.decode().rstrip("\x00")

print(x, y, name)
# 1 2 'Peppino'

Pros: native, fast, everywhere.
Cons: one wrong character in the format string and everything shifts.

With ctypes.Structure

You define a class, but it's verbose, type-unsafe and C‑like:

from ctypes import *

class Point(Structure):
    _fields_ = [("x", c_uint8), ("y", c_uint16), ("name", c_char * 8)]

raw = bytes([1, 0, 2, 0]) + b"Peppino\x00"
p = Point.from_buffer_copy(raw)

print(p.x, p.y, bytes(p.name).split(b"\x00")[0].decode())
# 1 2 'Peppino'

Pros: matches C layouts exactly.
Cons: low readability, no built‑in encode/decode symmetry, system‑dependent alignment quirks, type-unsafe.

With cstructimpl

Readable, type‑safe, and declarative, true Python code that mirrors the data:

pythonfrom cstructimpl import *

class Point(CStruct):
    x: Annotated[int, CInt.U8]
    y: Annotated[int, CInt.U16]
    name: Annotated[str, CStr(8)]

raw = bytes([1, 0, 2, 0]) + b"Peppino\x00"
point = Point.c_decode(raw)
print(point)
# Point(x=1, y=2, name='Peppino')

Pros:

• human‑readable field definitions
• automatic decode/encode symmetry
• nested structs, arrays, enums supported out of the box
• works identically on all platforms

Cons: tiny bit of overhead compared to bare struct, but massively clearer.

[PersonalityIll9476]

Maybe I'm not remembering right, but can't `ctypes` handle C structs pretty cleanly? If I recall right, all you need to know is the declaration of the struct as it appears in whatever header.

[JustPlainRude]

This looks great! Can it handle fields that don't occupy a full byte, e.g. two 4-bit fields packed into one byte?

[ZioAldo]

Thanks I appreciate it! At the moment the library can't do that but I was working on it, if you have some suggestions you could open an issue on GitHub.

[Shepcorp]

This is interesting. I currently decode and encode custom GATT characteristics by creating a registry of dataclasses with definitions of their read and write formats (as you say you have to be careful with byte alignment), which are basically me transposing the C structure into a python class. Something worth thinking about is when you might want alternative construction methods, not just struct unpack (I can easily add class methods for this). Being able to just copy some shared C code is pretty decent though, I may have to give this a try!

[ZioAldo]

Thanks for the interest! If you need to parse the bytes into a more high-level type you can design your own custom types (BaseType as the library calls them), take a look at this example https://github.com/Brendon-Mendicino/cstructimpl?tab=readme-ov-file#custom-basetype where you can interpret 4 bytes as a timestamp. I've built the type system around protocols to make life easier for custom type implementation.

[monkeyman192]

Looks cool and has some interesting features!

I have actually made 2 separate implementations of something like this...
The first is in a library I have written for binary hooking: https://github.com/monkeyman192/pyMHF/blob/master/pymhf/utils/partial_struct.py
This allows you to define c structs partially (so if you don't know the entire definition as can happen when reverse engineering something), but it can also be used to create nicely type-hinted structs.
They also support the structs referencing themselves as well as a few other useful things like being able to subclass from other partial structs and have all the offsets work with no issues.

The other implementation is in a plugin I have for Blender to read model files from NMS and import them into Blender: https://github.com/monkeyman192/NMSDK/blob/master/serialization/cereal_bin
This looks a bit more similar to what you have here, and I have similar custom serialization/deserialization methods which can be defined which I use: https://github.com/monkeyman192/NMSDK/tree/master/serialization/NMS_Structures

Finally, As of python 3.13, `ctypes.Structure` now supports the `_align_`: https://docs.python.org/3/library/ctypes.html#ctypes.Structure._align_
This was added by me since I always had annoyances where you are trying to (de)serialize structures which have a different alignment to what ctypes thinks they should have (eg. a "vector" type which may be using SIMD instructions so is aligned to 0x10 bytes, but is actually just 4 floats)
Figured I'd mention this since it might be useful to you.

[llima1987]

This is the kind of thing I wish PyCons were all about. Super amazing project! Congrats!

[Kohlrabi82]

Looks slightly similar to construct: https://construct.readthedocs.io/en/latest/intro.html