{"id":2726,"date":"2020-01-21T19:30:17","date_gmt":"2020-01-21T19:30:17","guid":{"rendered":"https:\/\/www.askpython.com\/?p=2726"},"modified":"2023-02-16T19:57:17","modified_gmt":"2023-02-16T19:57:17","slug":"python-struct-module","status":"publish","type":"post","link":"https:\/\/www.askpython.com\/python-modules\/python-struct-module","title":{"rendered":"Python struct Module"},"content":{"rendered":"\n

The Python struct module<\/a> is used to provide a simple Pythonic interface to access and manipulate C’s structure datatype. This can be a handy tool if you ever need to deal with C code and don’t have the time to write tools in C since it is a low-level language.<\/p>\n\n\n\n

This module can convert Python values to a C structure and vice-versa. The C structure is used as a Python bytes<\/a> object since there is nothing called an object in C; only byte-sized data structures.<\/p>\n\n\n\n

Let’s understand how we can use this module to have a Python interface to C structures.<\/p>\n\n\n\n

\n\n\n\n

Python struct Module Methods<\/h2>\n\n\n\n

In this module, since we are concerned with C structures, let’s look at some of the functions that this module provides us with.<\/p>\n\n\n\n

struct.pack()<\/h3>\n\n\n\n

This is used to pack elements into a Python byte-string (byte object). Since the mode of storage is based on bytes, C based programs can use the output of pack()<\/code>, from a Python program.<\/p>\n\n\n\n

Format: struct.pack(format, v1, v2, …)<\/strong><\/p>\n\n\n\n

v1<\/code>, v2<\/code>, … are the values which will be packed into the byte object. They represent the field values for the C structure. Since a C structure having n<\/code> fields must exactly have n<\/code> values, the arguments must match the values required by the format exactly.<\/p>\n\n\n\n

Here, format<\/code> refers to the format of the packing. This is needed since we need to specify the datatype of the byte-string, as it is used with C code. The below table lists the most common values for format<\/code>. We need one format per value to specify it’s datatype.<\/p>\n\n\n\n

Format<\/strong> <\/td>C Datatype<\/strong><\/td>Python type<\/strong><\/td><\/tr>
c<\/code><\/td>char<\/td>a string of length 1<\/td><\/tr>
?<\/code><\/td>_Bool<\/td>bool<\/td><\/tr>
h<\/code><\/td>short<\/td>integer<\/td><\/tr>
l<\/code><\/td>long<\/td>integer<\/td><\/tr>
i<\/code><\/td>int<\/td>integer<\/td><\/tr>
f<\/code><\/td>float<\/td>float<\/td><\/tr>
d<\/code><\/td>double<\/td>float<\/td><\/tr>
s<\/code><\/td>char[]<\/td>string<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Let’s understand this using some examples.<\/p>\n\n\n\n

The below snippet stores the 3 integers 1, 2 and 3 in a byte object using pack()<\/code>. Since the size of an integer is 4 bytes on my machine, you see 3 blocks of 4 bytes, which correspond to 3 integers in C.<\/p>\n\n\n

\nimport struct\n\n# We pack 3 integers, so 'iii' is required\nvariable = struct.pack('iii', 1, 2, 3)\nprint(type(variable), variable)\n\nvariable_2 = struct.pack('iic', 1, 2, b'A')\nprint('\\n', variable_2)\n<\/pre><\/div>\n\n\n
Output<\/strong><\/p>\n\n\n
\n<class 'bytes'> b'\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x03\\x00\\x00\\x00'\nb'\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00A'\n<\/pre><\/div>\n\n\n
If the appropriate type is not passed, the exception struct.error<\/code> will be raised by the Python struct module.<\/p>\n\n\n
\nimport struct\n\n# Error!! Incorrect datatype assignment\nvariable = struct.pack('ccc', 1, 2, 3)\nprint(type(variable), variable)\n<\/pre><\/div>\n\n\n
Output<\/strong><\/p>\n\n\n
\nstruct.error: char format requires a bytes object of length 1\n<\/pre><\/div>\n\n\n
\n\n\n\n
struct.unpack()<\/h3>\n\n\n\n
This function of the Python struct module, unpacks the packed value into its original representation according to an appropriate format. This returns a tuple of size equal to the number of values passed since the byte object is unpacked to give the elements.<\/p>\n\n\n\n
Format: struct.unpack(format, string)<\/strong><\/p>\n\n\n\n
This unpacks the byte string<\/code> according to the format<\/code> format specifier.<\/p>\n\n\n\n
This is the reverse of struct.pack()<\/code>. Let’s take one of the old byte strings that we produced using that and try to get back the python values passed to it using unpack()<\/code>.<\/p>\n\n\n
\nimport struct\n\nbyte_str = b'\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00A'\n\n# Using the same format specifier as before, since\n# we want to get Python values for the same byte-string\ntuple_vals = struct.unpack('iic', byte_str)\nprint(tuple_vals)\n<\/pre><\/div>\n\n\n
Output<\/strong><\/p>\n\n\n
\n(1, 2, b'A')\n<\/pre><\/div>\n\n\n
As you can see, indeed, we can get pack our old Python values from this tuple, provided we use the same format specifier for both pack()<\/code> and unpack()<\/code>.<\/p>\n\n\n\n
\n\n\n\n
struct.calcsize()<\/h3>\n\n\n\n
This function returns the total size of the String representation of the struct using a given format specifier, to retrieve the types of the data and calculate the size.<\/p>\n\n\n\n
Format: struct.calcsize(fmt)<\/strong><\/p>\n\n\n
\nimport struct\n\nprint('C Integer Size in Bytes:', struct.calcsize('i'))\nprint('Size of 3 characters in Bytes:', struct.calcsize('ccc'))\n<\/pre><\/div>\n\n\n
Output<\/strong><\/p>\n\n\n
\nC Integer Size in Bytes: 4\nSize of 3 characters in Bytes: 3\n<\/pre><\/div>\n\n\n
\n\n\n\n
struct.pack_into()<\/strong><\/h3>\n\n\n\n
This function is used pack values into a Python string buffer, available in the ctypes<\/code> module.<\/p>\n\n\n\n
Format: struct.pack_into(fmt, buffer, offset, v1, v2, …)<\/strong><\/p>\n\n\n\n
Here, fmt<\/code> refers to the format specifier, as always. buffer<\/code> is the string buffer which will now contain the packed values, specified. You can also specify an offset<\/code> location from the base address from which packing will occur.<\/p>\n\n\n\n
This does not return any value, and simply stores the values into the buffer<\/code> string.<\/p>\n\n\n
\nimport struct \nimport ctypes \n\n# We will create a string buffer having a size\n# equal to that of a struct with 'iic' values.\nbuf_size = struct.calcsize('iic') \n\n# Create the string buffer\nbuff = ctypes.create_string_buffer(buf_size) \n  \n# struct.pack() returns the packed data \nstruct.pack_into('iic', buff, 0, 1, 2, b'A')\n\nprint(buff)\n\n# Display the contents of the buffer\nprint(buff[:])\n<\/pre><\/div>\n\n\n
Output<\/strong><\/p>\n\n\n
\n<ctypes.c_char_Array_9 object at 0x7f4bccef1040>\nb'\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00A'\n<\/pre><\/div>\n\n\n
Indeed, we get our packed values in the buffer string.<\/p>\n\n\n\n
\n\n\n\n
struct.unpack_from()<\/h3>\n\n\n\n
Similar to unpack()<\/code>, a counterpart exists for unpacking values from a buffer string. This does the reverse of struct.pack_into()<\/code>.<\/p>\n\n\n\n
Format: struct.unpack_from(fmt, buffer, offset)<\/strong><\/p>\n\n\n\n
This will return a tuple of values, similar to struct.unpack()<\/code>.<\/p>\n\n\n
\nimport struct \nimport ctypes \n\n# We will create a string buffer having a size\n# equal to that of a struct with 'iic' values.\nbuf_size = struct.calcsize('iic') \n\n# Create the string buffer\nbuff = ctypes.create_string_buffer(buf_size) \n  \n# struct.pack() returns the packed data \nstruct.pack_into('iic', buff, 0, 1, 2, b'A')\n\nprint(struct.unpack_from('iic', buff, 0))\n<\/pre><\/div>\n\n\n
Output<\/strong><\/p>\n\n\n
\n(1, 2, b'A')\n<\/pre><\/div>\n\n\n
\n\n\n\n
Conclusion<\/h2>\n\n\n\n
In this article, we learned about using Python struct module to deal with C-type structure objects.<\/p>\n\n\n\n
References<\/h2>\n\n\n\n
  • JournalDev article on Python struct module<\/li><\/ul>\n\n\n\n
    \n","protected":false},"excerpt":{"rendered":"
    The Python struct module is used to provide a simple Pythonic interface to access and manipulate C’s structure datatype. This can be a handy tool if you ever need to deal with C code and don’t have the time to write tools in C since it is a low-level language. This module can convert Python […]<\/p>\n","protected":false},"author":7,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-2726","post","type-post","status-publish","format-standard","hentry","category-python-modules"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/posts\/2726","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/comments?post=2726"}],"version-history":[{"count":0,"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/posts\/2726\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/media?parent=2726"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/categories?post=2726"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.askpython.com\/wp-json\/wp\/v2\/tags?post=2726"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}