struct — Interpret bytes as packed binary data

Πηγαίος κώδικας: Lib/struct.py

---

This module performs conversions between Python values and C structs represented as Python bytes objects. This can be used in handling binary data stored in files or from network connections, among other sources. It uses Συμβολοσειρές μορφοποίησης as compact descriptions of the layout of the C structs and the intended conversion to/from Python values.

Σημείωση

By default, the result of packing a given C struct includes pad bytes in order to maintain proper alignment for the C types involved; similarly, alignment is taken into account when unpacking. This behavior is chosen so that the bytes of a packed struct correspond exactly to the layout in memory of the corresponding C struct. To handle platform-independent data formats or omit implicit pad bytes, use standard size and alignment instead of native size and alignment: see Διάταξη Byte, Μέγεθος και Στοίχιση for details.

Αρκετές συναρτήσεις του struct (και μέθοδοι της κλάσης Struct) δέχονται μια παράμετρο buffer. Αυτή αναφέρεται σε αντικείμενα που υλοποιούν τα Buffer Protocol και παρέχουν είτε ένα αναγνώσιμο είτε έναν αναγνώσιμο-εγγράψιμο buffer. Οι πιο συνηθισμένοι τύποι που χρησιμοποιούνται για αυτόν τον σκοπό είναι οι bytes και bytearray, αλλά πολλοί άλλοι τύποι που μπορούν να θεωρηθούν ως πίνακες bytes υλοποιούν το πρωτόκολλο buffer, επιτρέποντας την ανάγνωση/τροφοδότηση χωρίς επιπλέον αντιγραφή από ένα αντικείμενο bytes.

Συναρτήσεις και εξαιρέσεις

Το module ορίζει την ακόλουθη εξαίρεση και συναρτήσεις:

exception struct.error

Εξαίρεση που γίνεται raise σε διάφορες περιπτώσεις· το όρισμα είναι μια συμβολοσειρά που περιγράφει το σφάλμα.

struct.pack(format, v1, v2, ...)

Επιστρέφει ένα αντικείμενο τύπου bytes που περιέχει τις τιμές v1, v2, … πακεταρισμένες σύμφωνα με τη συμβολοσειρά μορφοποίησης format. Τα ορίσματα πρέπει να ταιριάζουν ακριβώς με τις απαιτούμενες τιμές της μορφοποίησης.

struct.pack_into(format, buffer, offset, v1, v2, ...)

Πακετάρει τις τιμές v1, v2, … σύμφωνα με τη συμβολοσειρά μορφοποίησης format και γράφει τα πακεταρισμένα bytes στον εγγράψιμο buffer buffer ξεκινώντας από τη θέση offset. Σημειώστε ότι το offset είναι υποχρεωτικό όρισμα.

struct.unpack(format, buffer)

Αποσυμπιέζει από τον buffer buffer (ο οποίος υποτίθεται έχει πακεταριστεί με τη μέθοδο pack(format, ...)) σύμφωνα με την συμβολοσειρά μορφοποίησης format. Το αποτέλεσμα είναι μια πλειάδα, ακόμα κι αν περιέχει μόνο ένα στοιχείο. Το μέγεθος του buffer σε bytes πρέπει να ταιριάζει με το απαιτούμενο μέγεθος σύμφωνα με τη μορφή, όπως καθορίζεται από τη συνάρτηση calcsize().

struct.unpack_from(format, /, buffer, offset=0)

Αποσυμπιέζει από τον buffer ξεκινώντας από τη θέση offset, σύμφωνα με τη συμβολοσειρά μορφοποίησης format. Το αποτέλεσμα είναι μια πλειάδα, ακόμα κι αν περιέχει μόνο ένα στοιχείο. Το μέγεθος του buffer σε bytes, ξεκινώντας από τη θέση offset, πρέπει να είναι τουλάχιστον το μέγεθος που απαιτείται από τη μορφή, όπως καθορίζεται από τη συνάρτηση calcsize().

struct.iter_unpack(format, buffer)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally-sized chunks from the buffer until all its contents have been consumed. The buffer’s size in bytes must be a multiple of the size required by the format, as reflected by calcsize().

Κάθε επανάληψη επιστρέφει μια πλειάδα σύμφωνα με τη συμβολοσειρά μορφοποίησης.

Νέο στην έκδοση 3.4.

struct.calcsize(format)

Επιστρέφει το μέγεθος της δομής (και κατά συνέπεια του αντικειμένου bytes που παράγεται από το pack(format, ...)) που αντιστοιχεί στη συμβολοσειρά μορφοποίησης format.

Συμβολοσειρές μορφοποίησης

Format strings are the mechanism used to specify the expected layout when packing and unpacking data. They are built up from Χαρακτήρες μορφής, which specify the type of data being packed/unpacked. In addition, there are special characters for controlling the Διάταξη Byte, Μέγεθος και Στοίχιση.

Διάταξη Byte, Μέγεθος και Στοίχιση

By default, C types are represented in the machine’s native format and byte order, and properly aligned by skipping pad bytes if necessary (according to the rules used by the C compiler).

Εναλλακτικά, ο πρώτος χαρακτήρας της συμβολοσειράς μορφοποίησης μπορεί να χρησιμοποιηθεί για να υποδείξει τη σειρά byte, το μέγεθος και την ευθυγράμμιση των συσκευασμένων δεδομένων, σύμφωνα με το παρακάτω πίνακα:

Χαρακτήρας	Σειρά bytes	Μέγεθος	Στοίχιση
@	native	native	native
=	native	τυπικό	κανένα
<	little-endian	τυπικό	κανένα
>	big-endian	τυπικό	κανένα
!	δίκτυο (= big-endian)	τυπικό	κανένα

Αν ο πρώτος χαρακτήρας δεν είναι ένας από αυτούς, υποτίθεται '@'.

Native byte order is big-endian or little-endian, depending on the host system. For example, Intel x86 and AMD64 (x86-64) are little-endian; Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature switchable endianness (bi-endian). Use sys.byteorder to check the endianness of your system.

Το native μέγεθος και η στοίχιση καθορίζονται χρησιμοποιώντας την έκφραση sizeof του μεταγλωττιστή C. Αυτό συνδυάζεται πάντα με την native σειρά byte.

Το τυπικό μέγεθος εξαρτάται μόνο από τον χαρακτήρα μορφοποίησης· δείτε τον πίνακα στην ενότητα Χαρακτήρες μορφής.

Σημειώστε τη διαφορά μεταξύ του '@' και '=': και τα δύο χρησιμοποιούν τη native σειρά byte, αλλά το μέγεθος και η στοίχιση του τελευταίου είναι τυποποιημένα.

Η μορφή '!' αντιπροσωπεύει τη σειρά byte του δικτύου, η οποία είναι πάντα big-endian όπως ορίζεται στο IETF RFC 1700.

Δεν υπάρχει τρόπος να δηλωθεί non-native σειρά byte (να επιβληθεί εναλλαγή byte). Χρησιμοποιήστε την κατάλληλη επιλογή '<' ή '>'.

Σημειώσεις:

1. Το συμπλήρωμα (padding) προστίθεται αυτόματα μόνο μεταξύ διαδοχικών μελών της δομής. Δεν προστίθεται συμπλήρωμα στην αρχή ή στο τέλος της κωδικοποιημένης δομής.

2. Δεν προστίθεται συμπλήρωμα όταν χρησιμοποιείται non-native μέγεθος και στοίχιση, π.χ. με “<”,”>”, “=”, και “!”.

3. Για να ευθυγραμμίσετε το τέλος μιας δομής με την απαίτηση στοίχισης ενός συγκεκριμένου τύπου, τελειώστε τη μορφή με τον κωδικό για αυτό τον τύπο με πλήθος επαναλήψεων μηδέν. Δείτε Παραδείγματα.

Χαρακτήρες μορφής

Οι χαρακτήρες μορφής έχουν την ακόλουθη σημασία· η μετατροπή μεταξύ τιμών C και Python είναι προφανής, δεδομένων των τύπων τους. Η στήλη “Τυπικό μέγεθος” αναφέρεται στο μέγεθος της συμπιεσμένης τιμής σε byte όταν χρησιμοποιείται τυπικό μέγεθος· δηλαδή, όταν η συμβολοσειρά μορφής ξεκινά με ένα από τα '<', '>', '!' or '='. Όταν χρησιμοποιείται το native μέγεθος, το μέγεθος της συμπιεσμένης τιμής εξαρτάται από την πλατφόρμα.

Μορφή	Τύπος C	Τύπος Python	Τυπικό μέγεθος	Σημειώσεις
x	συμπληρωματικό byte	καμία τιμή
c	char	bytes μήκους 1	1
b	signed char	integer	1	(1), (2)
B	unsigned char	integer	1	(2)
?	_Bool	bool	1	(1)
h	short	integer	2	(2)
H	unsigned short	integer	2	(2)
i	int	integer	4	(2)
I	unsigned int	integer	4	(2)
l	long	integer	4	(2)
L	unsigned long	integer	4	(2)
q	long long	integer	8	(2)
Q	unsigned long long	integer	8	(2)
n	ssize_t	integer		(3)
N	size_t	integer		(3)
e	(6)	float	2	(4)
f	float	float	4	(4)
d	double	float	8	(4)
s	char[]	bytes
p	char[]	bytes
P	void *	integer		(5)

Άλλαξε στην έκδοση 3.3: Προστέθηκε υποστήριξη για τις μορφές 'n' και 'N'.

Άλλαξε στην έκδοση 3.6: Προστέθηκε υποστήριξη για τη μορφή 'e'.

Σημειώσεις:

1. The '?' conversion code corresponds to the _Bool type defined by C99. If this type is not available, it is simulated using a char. In standard mode, it is always represented by one byte.

2. When attempting to pack a non-integer using any of the integer conversion codes, if the non-integer has a __index__() method then that method is called to convert the argument to an integer before packing.

   Άλλαξε στην έκδοση 3.2: Added use of the __index__() method for non-integers.

3. Οι κωδικοί μετατροπής 'n' και 'N' είναι διαθέσιμοι μόνο για το native μέγεθος (επιλεγμένο ως προεπιλογή ή με τον χαρακτήρα διάταξης byte '@'). Για το τυπικό μέγεθος, μπορείτε να χρησιμοποιήσετε οποιαδήποτε από τις άλλες μορφές ακέραιων που ταιριάζουν στην εφαρμογή σας.

4. Για τους κωδικούς μετατροπής 'f', 'd' και 'e', η συσκευασμένη αναπαράσταση χρησιμοποιεί τη μορφή IEEE 754 binary32, binary64 ή binary16 (αντίστοιχα για 'f', 'd' ή 'e'), ανεξάρτητα από τη μορφή κινητής υποδιαστολής που χρησιμοποιεί η πλατφόρμα.

5. Ο χαρακτήρας μορφοποίησης 'P' είναι διαθέσιμος μόνο για τη φυσική σειρά byte (επιλεγμένη ως προεπιλογή ή με τον χαρακτήρα σειράς byte '@'). Ο χαρακτήρας σειράς byte '=' επιλέγει τη χρήση little- ή big-endian σειράς με βάση το σύστημα. Το module struct δεν ερμηνεύει αυτό ως native σειρά, επομένως η μορφή 'P' δεν είναι διαθέσιμη.

6. Ο τύπος IEEE 754 binary16 «half precision» εισήχθη στην αναθεώρηση του 2008 του προτύπου IEEE 754 standard. Διαθέτει ένα bit προσήμου, έναν εκθέτη 5-bit και ακρίβεια 11-bit (με 10 bit αποθηκευμένα ρητά) και μπορεί να αναπαραστήσει αριθμούς μεταξύ περίπου 6.1e-05 και 6.5e+04 με πλήρη ακρίβεια. Αυτός ο τύπος δεν υποστηρίζεται ευρέως από τους μεταγλωττιστές της C: σε μια τυπική μηχανή, ένας μη προσημασμένος short μπορεί να χρησιμοποιηθεί για αποθήκευση, αλλά όχι για αριθμητικές πράξεις. Δείτε τη σελίδα της Wikipedia για τη half-precision floating-point format για περισσότερες πληροφορίες.

Ένας χαρακτήρας μορφοποίησης μπορεί να προηγείται από έναν ακέραιο αριθμό επαναλήψεων. Για παράδειγμα, η συμβολοσειρά μορφοποίησης '4h' σημαίνει ακριβώς το ίδιο με 'hhhh'.

Οι χαρακτήρες κενού μεταξύ των μορφοποιήσεων αγνοούνται· ωστόσο, ένας αριθμός και η μορφή του δεν πρέπει να περιέχουν κενά.

For the 's' format character, the count is interpreted as the length of the bytes, not a repeat count like for the other format characters; for example, '10s' means a single 10-byte string, while '10c' means 10 characters. If a count is not given, it defaults to 1. For packing, the string is truncated or padded with null bytes as appropriate to make it fit. For unpacking, the resulting bytes object always has exactly the specified number of bytes. As a special case, '0s' means a single, empty string (while '0c' means 0 characters).

Κατά το πακετάρισμα μιας τιμής x χρησιμοποιώντας μια από τις μορφές ακεραίων ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q'), εάν το x είναι εκτός του έγκυρου εύρους για αυτήν τη μορφή, γίνεται raise μια εξαίρεση struct.error.

Άλλαξε στην έκδοση 3.1: Προηγουμένως, ορισμένες από τις μορφές ακεραίων περιτύλιγαν τιμές εκτός εύρους και εμφάνιζαν DeprecationWarning αντί για struct.error.

Ο χαρακτήρας μορφοποίησης 'p' κωδικοποιεί ένα «Pascal string», δηλαδή μια μικρή συμβολοσειρά μεταβλητού μήκους αποθηκευμένη σε σταθερό αριθμό byte, που καθορίζεται από τον μετρητή. Το πρώτο byte που αποθηκεύεται είναι το μήκος της συμβολοσειράς ή 255, όποιο είναι μικρότερο. Ακολουθούν τα byte της συμβολοσειράς. Εάν η συμβολοσειρά που περνά στην pack() είναι πολύ μεγάλη (μεγαλύτερη από τον μετρητή μείον 1), αποθηκεύονται μόνο τα πρώτα count-1 byte της συμβολοσειράς. Εάν η συμβολοσειρά είναι μικρότερη από count-1, συμπληρώνεται με μηδενικά byte ώστε να χρησιμοποιηθούν ακριβώς τόσα byte όσα καθορίζει ο μετρητής. Σημειώστε ότι για τη unpack(), ο χαρακτήρας μορφοποίησης 'p' καταναλώνει count byte, αλλά η συμβολοσειρά που επιστρέφεται δεν μπορεί ποτέ να περιέχει περισσότερα από 255 byte.

Για το χαρακτήρα μορφής '?', η τιμή που επιστρέφεται είναι είτε True είτε False. Κατά την συσκευασία, χρησιμοποιείται η λογική τιμή του αντικειμένου-ορίσματος. Είτε 0 είτε 1 στη native ή τυπική αναπαράσταση του bool θα συσκευαστούν, και οποιαδήποτε μη μηδενική τιμή θα είναι True κατά την αποσυσκευασία.

Παραδείγματα

Σημείωση

All examples assume a native byte order, size, and alignment with a big-endian machine.

A basic example of packing/unpacking three integers:

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
b'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

Τα αποσυσκευασμένα πεδία μπορούν να ονομαστούν είτε αναθέτοντάς τα σε μεταβλητές είτε περιτυλίγοντάς τα σε μια ονομασμένη πλειάδα:

>>> record = b'raymond   \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)

The ordering of format characters may have an impact on size since the padding needed to satisfy alignment requirements is different:

>>> pack('ci', b'*', 0x12131415)
b'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, b'*')
b'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

The following format 'llh0l' specifies two pad bytes at the end, assuming longs are aligned on 4-byte boundaries:

>>> pack('llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

This only works when native size and alignment are in effect; standard size and alignment does not enforce any alignment.

Δείτε επίσης

Module array

Πακεταρισμένη δυαδική αποθήκευση ομοιογενών δεδομένων.

Module xdrlib

Packing and unpacking of XDR data.

Κλάσεις

Το module struct ορίζει επίσης τον ακόλουθο τύπο:

class struct.Struct(format)

Return a new Struct object which writes and reads binary data according to the format string format. Creating a Struct object once and calling its methods is more efficient than calling the struct functions with the same format since the format string only needs to be compiled once.

Σημείωση

The compiled versions of the most recent format strings passed to Struct and the module-level functions are cached, so programs that use only a few format strings needn’t worry about reusing a single Struct instance.

Τα μεταγλωττισμένα αντικείμενα Struct υποστηρίζουν τις ακόλουθες μεθόδους και ιδιότητες:

pack(v1, v2, ...)

Ταυτόσημο με τη συνάρτηση pack(), χρησιμοποιώντας τη μεταγλωττισμένη μορφή. (len(result) θα είναι ίσο με size.)

pack_into(buffer, offset, v1, v2, ...)

Ταυτόσημο με τη συνάρτηση pack_into(), χρησιμοποιώντας τη μεταγλωττισμένη μορφή.

unpack(buffer)

Ταυτόσημο με τη συνάρτηση unpack(), χρησιμοποιώντας τη μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes πρέπει να είναι ίσο με size.

unpack_from(buffer, offset=0)

Ταυτόσημο με τη συνάρτηση unpack_from(), χρησιμοποιώντας τη μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes, ξεκινώντας από τη θέση offset, πρέπει να είναι τουλάχιστον size.

iter_unpack(buffer)

Ταυτόσημο με τη συνάρτηση iter_unpack(), χρησιμοποιώντας τη μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes πρέπει να είναι πολλαπλάσιο του size.

Νέο στην έκδοση 3.4.

format

Η συμβολοσειρά μορφής που χρησιμοποιήθηκε για τη δημιουργία αυτού του αντικειμένου Struct.

Άλλαξε στην έκδοση 3.7: Ο τύπος της συμβολοσειράς μορφής είναι πλέον str αντί για bytes.

size

Το υπολογισμένο μέγεθος της δομής (και κατά συνέπεια του αντικειμένου bytes που παράγεται από τη μέθοδο pack()) που αντιστοιχεί στη format.