msgpack-types

Warnings

• gotcha When unpacking, the `raw` parameter in `msgpack.unpackb` (and `Unpacker`) determines whether 'str' (raw) types in MessagePack are decoded to Python `bytes` (`raw=True`) or `str` (Unicode, `raw=False`). The default for `msgpack>=1.0` is `raw=False`, assuming UTF-8. Be explicit to avoid encoding/decoding issues.
  Fix: Always explicitly set `raw=True` or `raw=False` in `msgpack.unpackb` and `msgpack.Unpacker` constructor to match expected data types. For example: `msgpack.unpackb(data, raw=False)` for UTF-8 strings or `msgpack.unpackb(data, raw=True)` for byte strings.
• breaking The `encoding` option for `msgpack.Packer` and `msgpack.Unpacker` was removed in `msgpack 1.0`. UTF-8 is now always used for string encoding and decoding when `raw=False`.
  Fix: Remove the `encoding` parameter from `Packer` and `Unpacker` calls. Ensure your string data is UTF-8 compatible when `raw=False` is used, or handle raw bytes explicitly with `raw=True`.
• gotcha Type stubs only provide static analysis; they do not alter runtime behavior. Installing `msgpack-types` without `msgpack` will not provide MessagePack serialization functionality at runtime, only type hints during development.
  Fix: Always install `msgpack` alongside `msgpack-types` if you intend to run the code. `pip install msgpack msgpack-types`.
• gotcha Prior to `msgpack 1.0`, `use_bin_type=True` was not the default for `Packer`, meaning `bytes` objects might have been encoded as 'raw' types instead of the 'bin' type specified in MessagePack spec 2.0. This can lead to compatibility issues with newer decoders.
  Fix: For compatibility with modern MessagePack implementations, always explicitly set `use_bin_type=True` in `msgpack.packb` and `msgpack.Packer` for `msgpack` versions older than 1.0, and be aware that `msgpack 1.0` and above default this to `True`.
• gotcha The `strict_map_key` option in `msgpack.Unpacker` defaults to `True` in `msgpack 1.0` to mitigate hash DoS attacks. If your MessagePack data contains map keys that are not `bytes` or `str` (e.g., integers as keys), unpacking will fail unless `strict_map_key=False` is set.
  Fix: If you need to unpack maps with non-string/non-bytes keys, explicitly pass `strict_map_key=False` to `msgpack.unpackb` or the `msgpack.Unpacker` constructor. Exercise caution when doing so with untrusted data.

Install

• pip install msgpack-types Install msgpack-types
• pip install msgpack Install the underlying msgpack library (required)

Imports

• packb

  import msgpack
  packed_data = msgpack.packb(...)

• unpackb

  import msgpack
  unpacked_data = msgpack.unpackb(...)

Quickstart

This quickstart demonstrates how to use the underlying `msgpack` library, with `msgpack-types` providing static type checking. After installing `msgpack-types`, a type checker like MyPy will analyze the `msgpack.packb` and `msgpack.unpackb` calls, ensuring correct argument types and inferring return types, as shown in the function signatures.

import msgpack

def process_data(data: dict) -> bytes:
    packed = msgpack.packb(data, use_bin_type=True)
    return packed

def decode_data(packed_data: bytes) -> dict:
    # raw=False decodes binary strings to Python str (UTF-8 assumed)
    unpacked = msgpack.unpackb(packed_data, raw=False)
    return unpacked # type: ignore

my_data = {'name': 'Alice', 'age': 30, 'cities': ['New York', 'London']}

# Using the functions with type hints
encoded = process_data(my_data)
decoded = decode_data(encoded)

print(f"Original: {my_data}")
print(f"Encoded: {encoded}")
print(f"Decoded: {decrypted}")

# Example of type checking with MyPy (after installing msgpack-types):
# If you were to do `process_data('not a dict')`, MyPy would flag a type error.