This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `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`.