{"id":8462,"library":"py-multicodec","title":"py-multicodec","description":"Multicodec is a self-describing multiformat that wraps other formats with a tiny bit of self-description. A multicodec identifier is a varint and the code identifying the following data. This Python implementation provides functions for adding and removing prefixes, and for managing type-safe codec handling using `Code` objects. It is currently at version 1.0.0, released after a significant development period.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/multiformats/py-multicodec","tags":["multicodec","multiformats","codec","encoding","decoding","ipfs","ipld"],"install":[{"cmd":"pip install py-multicodec","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"add_prefix","correct":"from multicodec import add_prefix"},{"symbol":"remove_prefix","correct":"from multicodec import remove_prefix"},{"symbol":"get_codec","correct":"from multicodec import get_codec"},{"symbol":"Code","correct":"from multicodec import Code"},{"symbol":"known_codes","correct":"from multicodec import known_codes"},{"note":"For type-safe codec constants.","symbol":"SHA2_256","correct":"from multicodec.code_table import SHA2_256, DAG_CBOR"}],"quickstart":{"code":"from multicodec import add_prefix, remove_prefix, get_codec, Code, known_codes\nfrom multicodec.code_table import SHA2_256\n\n# Basic prefix operations\nprefixed_data = add_prefix('sha2-256', b'Some raw data')\nprint(f\"Prefixed data: {prefixed_data.hex()}\")\n\nraw_data = remove_prefix(prefixed_data)\nprint(f\"Raw data: {raw_data}\")\n\ncodec_name = get_codec(prefixed_data)\nprint(f\"Codec name: {codec_name}\")\n\n# Type-safe Code management\nsha2_256_code = SHA2_256\nprint(f\"SHA2-256 Code: {sha2_256_code} (int: {int(sha2_256_code)}, str: {str(sha2_256_code)})\")\n\ncode_from_string = Code.from_string(\"sha2-256\")\nprint(f\"Code from string: {code_from_string}\")\n\nall_known_codes = known_codes()\nprint(f\"Number of known codes: {len(all_known_codes)}\")\n","lang":"python","description":"Demonstrates adding and removing multicodec prefixes, retrieving codec names, and using the `Code` object for type-safe codec handling and listing all supported codecs."},"warnings":[{"fix":"Confirm `pip install py-multicodec` and use `from multicodec import ...` for imports.","message":"The library `py-multicodec` is distinct from `multicode` (a Unicode handling library) and is also a sub-module of the broader `multiformats` library. Ensure you install and import from `py-multicodec` for standalone multicodec functionality.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult the project's release notes or GitHub history for migration guides if upgrading from older pre-1.0.0 versions.","message":"While no specific 0.x to 1.x breaking changes are explicitly documented in the README, the jump to 1.0.0 implies a stable API. Users upgrading from pre-1.0.0 versions should review the changelog on GitHub for potential API alterations.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure the `Code` object used for unwrapping matches the codec embedded in the prefixed data, or use `remove_prefix` for a less strict approach that simply removes the prefix without validating its type against a specific `Code` object.","message":"When unwrapping data using an explicit `Code` object (e.g., `my_code.unwrap(prefixed_data)`), the library strictly enforces that the data's internal codec matches `my_code`. If they differ, a `ValueError` is raised.","severity":"gotcha","affected_versions":"All"},{"fix":"If working with very new or custom codecs, consider updating the local codec table by running the provided `update-table.py` script from the repository, or upgrade to the latest library version.","message":"The library's internal codec lookup table is based on the canonical multicodec table. If this table is updated upstream, your local `py-multicodec` installation might become outdated and not recognize new codecs. The project provides a tool to update this table.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Always convert string data to bytes using `.encode('utf-8')` (or another appropriate encoding) before passing it to `py-multicodec` functions, e.g., `add_prefix('sha2-256', 'my string'.encode('utf-8'))`.","cause":"Attempting to pass a Python `str` object directly to `add_prefix` or other functions expecting raw bytes.","error":"TypeError: a bytes-like object is required, not 'str'"},{"fix":"Use direct imports for the functions you need, e.g., `from multicodec import add_prefix`, or import the module as `import multicodec` and then call `multicodec.add_prefix`.","cause":"Trying to call functions like `multicodec.add_prefix` without explicitly importing the functions or the `multicodec` module itself.","error":"NameError: name 'multicodec' is not defined"},{"fix":"Ensure the `Code` object used for unwrapping (`my_code.unwrap()`) corresponds to the actual codec of the data. If you only want to remove the prefix without strict validation, use `multicodec.remove_prefix(prefixed_data)` instead.","cause":"This error occurs when using a specific `Code` object's `unwrap` method on data that was prefixed with a *different* codec (e.g., trying to unwrap 'identity' data with a 'sha2-256' Code object).","error":"ValueError: Found code 0x00 when unwrapping data, expected code 0x12"}]}