{"id":4990,"library":"msgpack-types","title":"msgpack-types","description":"msgpack-types is a Python library that provides type stubs for the popular 'msgpack' serialization library. Its purpose is to enable static type checking and enhance developer tooling like autocompletion for code that interacts with MessagePack data. The current version is 0.7.0, and it is actively maintained with frequent releases, often in sync with or following updates to the core `msgpack` library.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/sbdchd/msgpack-types","tags":["typing","type hints","static analysis","msgpack","serialization","stubs"],"install":[{"cmd":"pip install msgpack-types","lang":"bash","label":"Install msgpack-types"},{"cmd":"pip install msgpack","lang":"bash","label":"Install the underlying msgpack library (required)"}],"dependencies":[{"reason":"msgpack-types provides type stubs for the msgpack library; msgpack itself must be installed for runtime execution.","package":"msgpack","optional":false}],"imports":[{"symbol":"packb","correct":"import msgpack\npacked_data = msgpack.packb(...)"},{"symbol":"unpackb","correct":"import msgpack\nunpacked_data = msgpack.unpackb(...)"}],"quickstart":{"code":"import msgpack\n\ndef process_data(data: dict) -> bytes:\n    packed = msgpack.packb(data, use_bin_type=True)\n    return packed\n\ndef decode_data(packed_data: bytes) -> dict:\n    # raw=False decodes binary strings to Python str (UTF-8 assumed)\n    unpacked = msgpack.unpackb(packed_data, raw=False)\n    return unpacked # type: ignore\n\nmy_data = {'name': 'Alice', 'age': 30, 'cities': ['New York', 'London']}\n\n# Using the functions with type hints\nencoded = process_data(my_data)\ndecoded = decode_data(encoded)\n\nprint(f\"Original: {my_data}\")\nprint(f\"Encoded: {encoded}\")\nprint(f\"Decoded: {decrypted}\")\n\n# Example of type checking with MyPy (after installing msgpack-types):\n# If you were to do `process_data('not a dict')`, MyPy would flag a type error.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"msgpack >= 1.0 (implicitly affects msgpack-types users)"},{"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`.","message":"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`.","severity":"breaking","affected_versions":"msgpack >= 1.0 (implicitly affects msgpack-types users)"},{"fix":"Always install `msgpack` alongside `msgpack-types` if you intend to run the code. `pip install msgpack msgpack-types`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"msgpack < 1.0 (implicitly affects msgpack-types users)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"msgpack >= 1.0 (implicitly affects msgpack-types users)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}