v1.1.0

Date:

January 1st, 2025

Changes

• Drop support for Python 3.7.

• Implement an asynchronous unpacking API.

  • This allows users to unpack asynchronously using coroutines and the await syntax, which may in certain cases be necessary or otherwise desirable.

  • Where there is something that involves unpacking, there will be an asynchronous version of it suffixed with _async, including the following:

    • The Type.unpack_async() method.

    • The Packet.unpack_async() method.

    • The new functions in the test module.

  • All Types in Pak provide both the synchronous and asynchronous unpacking APIs, however custom Types are empowered to only provide one or the other, as often only one will be relevant to a certain usecase.

• Add DeferringType.

  • This allows a Type to defer its behavior to another Type of its choosing depending on the relevant Type.Context. This is useful, for instance, if you are supporting multiple versions of a protocol which might have different fields act like different Types depending on the protocol version.

• Improve customizing the endianness of StructType.

  • The following methods were added to be able to tersely specify the desired endianness of a StructType:

    • StructType.little_endian()

    • StructType.big_endian()

    • StructType.native_endian()

  • This allows users to, for instance, call pak.UInt16.big_endian() in order to use a big-endian UInt16, instead of the default little-endian version.

• Add LEB128.Limited and ULEB128.Limited.

  • These allow users to limit the maximum number of bytes that a LEB128 or ULEB128 may have, which may be useful to prevent malicious actors from always setting the top bit of each byte to cause unpacking to never end.

• Reorder the bases of the returned class of Packet.GenericWithID() to have more intuitive behavior.

  • The data field from GenericPacket is now situated at the end of the Packet, so that it will capture any remaining uncaptured data after the rest of the fields.

• Give EmptyType an alignment of 1.

  • This better allows fields to be effectively “disabled” in an aligned context, such as when using AlignedPacket.

• Give RawByte an alignment of 1.

• Refactor Array to use specialized subclasses.

  • These specialized subclasses are:

    • Array.FixedSize

    • Array.SizePrefixed

    • Array.Unbounded

    • Array.FunctionSized

• Refactor Optional to use specialized subclasses.

  • These specialized subclasses are:

    • Optional.PrefixChecked

    • Optional.Unchecked

    • Optional.FunctionChecked

• Add Type.UnsuppressedError.

  • Exceptions which inherit from Type.UnsuppressedError indicate unambiguous errors in logic, which should not be suppressed by certain Type facilities like Array.Unbounded and Optional.Unchecked.

• Types in Pak now more consistently raise errors if they are unable to read enough data when unpacking.

• Make the Type.prepare_types() decorator remove all parameter annotations of Type from its decorated function.

  • This prevents potentially confusing annotations of Type from leaking out into documentation or other tools where those annotations may be misinterpreted. For instance, they could be mistaken as type hints. Parameter annotations of Type when using Type.prepare_types() are only internally relevant, and should not be shown externally.

• Restrict certain function parameters to being positional-only in order to better enforce caching.

• Fix typo in the name of PacketHandler.unregister_packet_listener(), which was previously named unregsiter_packet_listener.