C-style structs for Python
Project description
Python-CStruct
C-style structs for Python
Convert C struct/union definitions into Python classes with methods for serializing/deserializing.
The usage is very simple: create a class subclassing
cstruct.MemCStruct
and add a C struct/union definition as a string in the __def__
field.
The C struct/union definition is parsed at runtime and the struct format string
is generated. The class offers the method unpack
for deserializing
an array of bytes into a Python object and the method pack
for
serializing the values into an array of bytes.
Install
pip install cstruct
Examples
- Read the DOS-type (MBR) partition table
- Print information about logged uses
- Flexible Array Member (FAM)
- libc integration (using ctypes)
Features
Structs
Struct definition subclassing cstruct.MemCStruct
. Methods can access stuct values as instance variables.
class Position(cstruct.MemCStruct):
__def__ = """
struct {
unsigned char head;
unsigned char sector;
unsigned char cyl;
}
"""
@property
def lba(self):
return (self.cyl * 16 + self.head) * 63 + (self.sector - 1)
pos = Position(cyl=15, head=15, sector=63)
print(f"head: {pos.head} sector: {pos.sector} cyl: {pos.cyl} lba: {pos.lba}")
Struct definition using cstruct.parse
.
Partition = cstruct.parse("""
#define ACTIVE_FLAG 0x80
struct Partition {
unsigned char status; /* 0x80 - active */
struct Position start;
unsigned char partition_type;
struct Position end;
unsigned int start_sect; /* starting sector counting from 0 */
unsigned int sectors; /* nr of sectors in partition */
}
""")
part = Partition()
part.status = cstruct.getdef('ACTIVE_FLAG')
Unions
Union definition subclassing cstruct.MemCStruct
.
class Data(cstruct.MemCStruct):
__def__ = """
union {
int integer;
float real;
}
"""
data = Data()
data.integer = 2
data.real = 3
assert data.integer != 2
Enums
Enum definition subclassing cstruct.CEnum
.
class HtmlFont(cstruct.CEnum):
__size__ = 2
__def__ = """
#define NONE 0
enum htmlfont {
HTMLFONT_NONE = NONE,
HTMLFONT_BOLD,
HTMLFONT_ITALIC
}
"""
assert HtmlFont.HTMLFONT_NONE == 0
assert HtmlFont.HTMLFONT_BOLD == 1
assert HtmlFont.HTMLFONT_ITALIC == 2
Different enum styles are supported in struct/union definitions.
enum Type_A a; // externally defined using CEnum
enum Type_B {A, B, C} b;
enum {A, B, C} c;
enum Type_D : short {A, B, C} d; // specify the underlying type
enum Direction { left = 'l', right = 'r' };
Nested structs/unions
Nested stucts and unions are supported, both named and anonymous.
class Packet(cstruct.MemCStruct):
__def__ = """
struct Packet {
uint8_t packetLength;
union {
struct {
uint16_t field1;
uint16_t field2;
uint16_t field3;
} format1;
struct {
double value1;
double value2;
} format2;
};
};
"""
Byte Order, Size, and Padding
Suported byte orders:
cstruct.LITTLE_ENDIAN
- Little endian byte order, standard size, no paddingcstruct.BIG_ENDIAN
- Big endian byte order, standard size, no paddingcstruct.NATIVE_ORDER
- Native byte order, native size, padding
class Native(cstruct.MemCStruct):
__byte_order__ = cstruct.NATIVE_ORDER
__def__ = """
struct {
long p;
char c;
long x;
}
"""
Flexible Array Member
class Pkg(cstruct.MemCStruct):
__byte_order__ = cstruct.LITTLE_ENDIAN
__def__ = """
struct {
uint16_t cmd;
uint16_t length;
uint8_t data[];
}
"""
pkg = Pkg()
pkg.length = 4
pkg.data = [10, 20, 30, 40]
Pack and Unpack
A code example illustrating how to use
pack
to pack a structure into binary form.
class Position(cstruct.MemCStruct):
__byte_order__ = cstruct.LITTLE_ENDIAN
__def__ = """
struct {
unsigned char head;
unsigned char sector;
unsigned char cyl;
}
"""
pos = Position(head=10, sector=20, cyl=3)
packed = pos.pack()
Binary representation can be converted into structure using
unpack
.
pos1 = Position()
pos1.unpack(packed)
assert pos1.head == 10
assert pos1.sector == 20
assert pos1.cyl == 3
Define, Sizeof, and Eval
Definitions in Struct declaration:
class Packet(cstruct.MemCStruct):
__byte_order__ = cstruct.LITTLE_ENDIAN
__def__ = """
#define MaxPacket 20
struct Packet {
uint8_t bytes[MaxPacket];
}
"""
Parse C definitions:
cstruct.parse("""
#define A1 10
#define A2 10 + A1
#define A3 30
""")
assert cstruct.getdef("A1") == 10
assert cstruct.getdef('A2') == 20
Get structure size:
cstruct.sizeof(Partition)
Evaluate C expression using c_eval
:
cstruct.c_eval("A1 / 10")
cstruct.c_eval("((A10 < 6) || (A10>10))")
C expressions are automatically evaluated during structure definitions:
class MBR(cstruct.MemCStruct):
__byte_order__ = cstruct.LITTLE_ENDIAN
__def__ = """
#define MBR_SIZE 512
#define MBR_DISK_SIGNATURE_SIZE 4
#define MBR_USUALY_NULLS_SIZE 2
#define MBR_SIGNATURE_SIZE 2
#define MBR_BOOT_SIGNATURE 0xaa55
#define MBR_PARTITIONS_NUM 4
#define MBR_PARTITIONS_SIZE (sizeof(Partition) * MBR_PARTITIONS_NUM)
#define MBR_UNUSED_SIZE (MBR_SIZE - MBR_DISK_SIGNATURE_SIZE - MBR_USUALY_NULLS_SIZE - MBR_PARTITIONS_SIZE - MBR_SIGNATURE_SIZE)
struct {
char unused[MBR_UNUSED_SIZE];
unsigned char disk_signature[MBR_DISK_SIGNATURE_SIZE];
unsigned char usualy_nulls[MBR_USUALY_NULLS_SIZE];
struct Partition partitions[MBR_PARTITIONS_NUM];
uint16 signature;
}
"""
Ispect memory
The inspect
methods displays memory contents in hexadecimal.
print(mbr.inspect())
Output example:
00000000 eb 48 90 00 00 00 00 00 00 00 00 00 00 00 00 00 |.H..............|
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 03 02 |................|
00000040 ff 00 00 80 61 cb 04 00 00 08 fa 80 ca 80 ea 53 |....a..........S|
00000050 7c 00 00 31 c0 8e d8 8e d0 bc 00 20 fb a0 40 7c ||..1....... ..@||
00000060 3c ff 74 02 88 c2 52 be 79 7d e8 34 01 f6 c2 80 |<.t...R.y}.4....|
00000070 74 54 b4 41 bb aa 55 cd 13 5a 52 72 49 81 fb 55 |tT.A..U..ZRrI..U|
00000080 aa 75 43 a0 41 7c 84 c0 75 05 83 e1 01 74 37 66 |.uC.A|..u....t7f|
00000090 8b 4c 10 be 05 7c c6 44 ff 01 66 8b 1e 44 7c c7 |.L...|.D..f..D|.|
000000a0 04 10 00 c7 44 02 01 00 66 89 5c 08 c7 44 06 00 |....D...f.\..D..|
000000b0 70 66 31 c0 89 44 04 66 89 44 0c b4 42 cd 13 72 |pf1..D.f.D..B..r|
000000c0 05 bb 00 70 eb 7d b4 08 cd 13 73 0a f6 c2 80 0f |...p.}....s.....|
000000d0 84 f0 00 e9 8d 00 be 05 7c c6 44 ff 00 66 31 c0 |........|.D..f1.|
000000e0 88 f0 40 66 89 44 04 31 d2 88 ca c1 e2 02 88 e8 |..@f.D.1........|
000000f0 88 f4 40 89 44 08 31 c0 88 d0 c0 e8 02 66 89 04 |..@.D.1......f..|
00000100 66 a1 44 7c 66 31 d2 66 f7 34 88 54 0a 66 31 d2 |f.D|f1.f.4.T.f1.|
00000110 66 f7 74 04 88 54 0b 89 44 0c 3b 44 08 7d 3c 8a |f.t..T..D.;D.}<.|
00000120 54 0d c0 e2 06 8a 4c 0a fe c1 08 d1 8a 6c 0c 5a |T.....L......l.Z|
00000130 8a 74 0b bb 00 70 8e c3 31 db b8 01 02 cd 13 72 |.t...p..1......r|
00000140 2a 8c c3 8e 06 48 7c 60 1e b9 00 01 8e db 31 f6 |*....H|`......1.|
00000150 31 ff fc f3 a5 1f 61 ff 26 42 7c be 7f 7d e8 40 |1.....a.&B|..}.@|
00000160 00 eb 0e be 84 7d e8 38 00 eb 06 be 8e 7d e8 30 |.....}.8.....}.0|
00000170 00 be 93 7d e8 2a 00 eb fe 47 52 55 42 20 00 47 |...}.*...GRUB .G|
00000180 65 6f 6d 00 48 61 72 64 20 44 69 73 6b 00 52 65 |eom.Hard Disk.Re|
00000190 61 64 00 20 45 72 72 6f 72 00 bb 01 00 b4 0e cd |ad. Error.......|
000001a0 10 ac 3c 00 75 f4 c3 00 00 00 00 00 00 00 00 00 |..<.u...........|
000001b0 00 00 00 00 00 00 00 00 40 e2 01 00 00 00 80 00 |........@.......|
000001c0 02 00 83 fe 3f 86 01 00 00 00 c6 17 21 00 00 00 |....?.......!...|
000001d0 01 87 8e fe ff ff c7 17 21 00 4d d3 de 00 00 00 |........!.M.....|
000001e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 55 aa |..............U.|
Links
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file cstruct-5.3.tar.gz
.
File metadata
- Download URL: cstruct-5.3.tar.gz
- Upload date:
- Size: 33.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.9.6 requests/2.31.0 setuptools/69.0.3 requests-toolbelt/1.0.0 tqdm/4.66.1 CPython/3.12.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | dc7f1e7eb1e9b5cd1dbd5052e06f58b00343685c662dbb892c5071fef6bcf4c7 |
|
MD5 | 733f282c0f206ccbc6bf2fb881c65d92 |
|
BLAKE2b-256 | 85bc34af58152d3b7d794fdd9266cd14f4187f00b3a10ad4efe790996417ed47 |
File details
Details for the file cstruct-5.3-py2.py3-none-any.whl
.
File metadata
- Download URL: cstruct-5.3-py2.py3-none-any.whl
- Upload date:
- Size: 30.6 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.9.6 requests/2.31.0 setuptools/69.0.3 requests-toolbelt/1.0.0 tqdm/4.66.1 CPython/3.12.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5cdc27f78f725d7cc49e24b1d8c91644ec385deb9a15bdd8b2089f5b9d38ecc9 |
|
MD5 | 3270e1e03c79fd01e2e732b0119cf46f |
|
BLAKE2b-256 | 545af5c0df80dade81156ef92fd620abcef4be98ae3540326f207b7b7456cd01 |