From 961cebe48b298b22d8bef5bb2c7ff38ab386c528 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Thu, 1 Dec 2022 16:48:20 +0100
Subject: [PATCH] ustruct: Document modules.

---
 doc/main/index.rst               |  1 +
 doc/main/micropython/ustruct.rst | 56 +++++++++++++++++++++
 src/ustruct/__init__.py          | 85 ++++++++++++++++++++++++++++++++
 3 files changed, 142 insertions(+)
 create mode 100644 doc/main/micropython/ustruct.rst
 create mode 100644 src/ustruct/__init__.py

diff --git a/doc/main/index.rst b/doc/main/index.rst
index bb3206e..6fb0b8f 100644
--- a/doc/main/index.rst
+++ b/doc/main/index.rst
@@ -83,4 +83,5 @@ on your hub. Check `pybricks.com/install`_ to learn how.
    micropython/umath
    micropython/urandom
    micropython/uselect
+   micropython/ustruct
    micropython/usys
diff --git a/doc/main/micropython/ustruct.rst b/doc/main/micropython/ustruct.rst
new file mode 100644
index 0000000..def0921
--- /dev/null
+++ b/doc/main/micropython/ustruct.rst
@@ -0,0 +1,56 @@
+.. pybricks-requirements:: stm32-extra
+
+:mod:`ustruct` -- Pack and unpack binary data
+====================================================
+
+.. automodule:: ustruct
+
+The following byte orders are supported:
+
++-----------+------------------------+----------+-----------+
+| Character | Byte order             | Size     | Alignment |
++===========+========================+==========+===========+
+| @         | native                 | native   | native    |
++-----------+------------------------+----------+-----------+
+| <         | little-endian          | standard | none      |
++-----------+------------------------+----------+-----------+
+| >         | big-endian             | standard | none      |
++-----------+------------------------+----------+-----------+
+| !         | network (= big-endian) | standard | none      |
++-----------+------------------------+----------+-----------+
+
+The following data types are supported:
+
++--------+--------------------+-------------+---------------+
+| Format | C Type             | Python type | Standard size |
++========+====================+=============+===============+
+| b      | signed char        | integer     | 1             |
++--------+--------------------+-------------+---------------+
+| B      | unsigned char      | integer     | 1             |
++--------+--------------------+-------------+---------------+
+| h      | short              | integer     | 2             |
++--------+--------------------+-------------+---------------+
+| H      | unsigned short     | integer     | 2             |
++--------+--------------------+-------------+---------------+
+| i      | int                | integer     | 4             |
++--------+--------------------+-------------+---------------+
+| I      | unsigned int       | integer     | 4             |
++--------+--------------------+-------------+---------------+
+| l      | long               | integer (1) | 4             |
++--------+--------------------+-------------+---------------+
+| L      | unsigned long      | integer (1) | 4             |
++--------+--------------------+-------------+---------------+
+| q      | long long          | integer (1) | 8             |
++--------+--------------------+-------------+---------------+
+| Q      | unsigned long long | integer (1) | 8             |
++--------+--------------------+-------------+---------------+
+| f      | float              | float       | 4             |
++--------+--------------------+-------------+---------------+
+| d      | double             | float       | 8             |
++--------+--------------------+-------------+---------------+
+| s      | char[]             | bytes       |               |
++--------+--------------------+-------------+---------------+
+| P      | void *             | integer     |               |
++--------+--------------------+-------------+---------------+
+
+   - \(1\) Supports values up to +/-1073741823
diff --git a/src/ustruct/__init__.py b/src/ustruct/__init__.py
new file mode 100644
index 0000000..23b15c1
--- /dev/null
+++ b/src/ustruct/__init__.py
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021 The Pybricks Authors
+#
+# Portions of documentation copied from:
+# https://raw.githubusercontent.com/micropython/micropython/1e6d18c915ccea0b6a19ffec9710d33dd7e5f866/docs/library/ustruct.rst
+# Copyright (c) 2014-2021, Damien P. George, Paul Sokolovsky, and contributors
+
+"""
+This module provides functions to convert between Python values and C-like
+data structs.
+"""
+
+from typing import Union, Tuple
+
+
+def calcsize(format: str) -> int:
+    """
+    Gets the data size corresponding to a format string
+
+    Arguments:
+        format (str): Data format string.
+
+    Returns:
+        The number of bytes needed to represent this format.
+    """
+
+
+def pack(format: str, *values) -> bytes:
+    """
+    pack(format, value1, value2, ...)
+
+    Packs the values using the given format.
+
+    Arguments:
+        format (str): Data format string.
+
+    Returns:
+        The data encoded as bytes.
+    """
+
+
+def pack_into(format: str, buffer: bytearray, offset: int, *values) -> bytes:
+    """
+    pack_into(format, buffer, offset, value1, value2, ...)
+
+    Encode the values using the given format and write them to a given buffer.
+
+    Arguments:
+        format (str): Data format string.
+        buffer (bytearray): Buffer to store the encoded data.
+        offset (int): Offset from the start of the buffer. Use a negative value
+            to count from the end of the buffer.
+    """
+
+
+def unpack(format: str, data: Union[bytes, bytearray]) -> Tuple:
+    """
+    unpack(format, data) -> Tuple
+
+    Decodes the binary data using the given format.
+
+    Arguments:
+        format (str): Data format string.
+        data (bytes or bytearray): Data to unpack.
+
+    Returns:
+        The decoded data as a tuple of values.
+    """
+
+
+def unpack_from(format: str, data: Union[bytes, bytearray], offset: int) -> Tuple:
+    """
+    unpack_from(format, data, offset) -> Tuple
+
+    Decodes binary data from a buffer using the given format.
+
+    Arguments:
+        format (str): Data format string.
+        data (bytes or bytearray): Data buffer to unpack.
+        offset (int): Offset from the start of the data. Use a negative value
+            to count from the end of the data.
+
+    Returns:
+        The decoded data as a tuple of values.
+    """