struct --- حزم وفك حزم أنواع البيانات البدائية

تجري هذه الوحدة تحويلات بين قيم Python وبُنى بأسلوب C ممثَّلة على شكل كائنات bytes في Python، باستخدام سلاسل التنسيق لوصف تخطيط البيانات.

تُدعم ترتيبات البايتات التالية:

الحرف	ترتيب البايتات	الحجم	المحاذاة
@	أصلي	أصلي	أصلي
<	صغير الترتيب (little-endian)	معياري	لا شيء
>	كبير الترتيب (big-endian)	معياري	لا شيء
!	الشبكة (= كبير الترتيب)	معياري	لا شيء

تُدعم أنواع البيانات التالية:

التنسيق	نوع C	نوع Python	الحجم المعياري
b	signed char	عدد صحيح	1
B	unsigned char	عدد صحيح	1
h	short	عدد صحيح	2
H	unsigned short	عدد صحيح	2
i	int	عدد صحيح (1)	4
I	unsigned int	عدد صحيح (1)	4
l	long	عدد صحيح (1)	4
L	unsigned long	عدد صحيح (1)	4
q	long long	عدد صحيح (1)	8
Q	unsigned long long	عدد صحيح (1)	8
e	غير متاح (نصف عائم)	float (2)	2
f	float	float (2)	4
d	double	float (2)	8
s	char[]	bytes
P	void *	عدد صحيح

1. يتطلب دعم long عند الاستخدام مع قيم أكبر من 30 بت.

2. يتطلب دعم الفاصلة العائمة.

الفرق عن CPython

لا تُدعم المسافات البيضاء في سلاسل التنسيق.

أمثلة

حزم وفك حزم قيم صغيرة الترتيب. تختار البادئة < ترتيب البايتات صغير الترتيب بأحجام معيارية ودون محاذاة:

import struct

# Pack an unsigned short (H, 2 bytes) then an unsigned int (I, 4 bytes).
data = struct.pack("<HI", 7, 1000)
# data == b'\x07\x00\xe8\x03\x00\x00'

# Unpack returns a tuple of the values, in order.
struct.unpack("<HI", data)
# (7, 1000)

# calcsize() reports how many bytes the format needs.
struct.calcsize("<HI")
# 6

الحزم في مخزن مؤقت موجود وفك الحزم منه عند إزاحة بايتية:

buf = bytearray(8)

# Write a little-endian signed int (i) at offset 2.
struct.pack_into("<i", buf, 2, -12345)
# buf == bytearray(b'\x00\x00\xc7\xcf\xff\xff\x00\x00')

# Read it back from the same offset.
struct.unpack_from("<i", buf, 2)
# (-12345,)

الدوال

struct.calcsize(fmt: str) → int

يُرجع عدد البايتات اللازمة لتخزين الـ fmt المعطى.

struct.pack(fmt: str, *values: Any) → bytes

يحزم الـ values وفقاً لسلسلة التنسيق fmt. القيمة المُرجَعة هي كائن bytes يرمّز القيم.

struct.pack_into(fmt: str, buffer: Any, offset: int, *values: Any) → None

يحزم الـ values وفقاً لسلسلة التنسيق fmt في buffer بدءاً من offset. يمكن أن يكون offset سالباً للعد من نهاية buffer.

struct.unpack(fmt: str, data: bytes) → Tuple

يفك الحزم من الـ data وفقاً لسلسلة التنسيق fmt. القيمة المُرجَعة هي مجموعة من القيم المفكوكة.

struct.unpack_from(fmt: str, data: bytes, offset: int = 0, /) → Tuple

يفك الحزم من الـ data بدءاً من offset وفقاً لسلسلة التنسيق fmt. يمكن أن يكون offset سالباً للعد من نهاية data. القيمة المُرجَعة هي مجموعة من القيم المفكوكة.