Registry / serialization / py-multicodec

py-multicodec

library1.0.0pypypi✓ verified 87d ago

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.

serialization

pip install py-multicodec

github ↗package ↗

INSTALL

IMPORT

SIG · PY-MULTICODEC

py-multicodec

serializationpythonv1.0.0

Install

2.5s avg

Import

34ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.028s · 19.4MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.5s · import 0.027s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

add_prefix

✓ from multicodec import add_prefix

remove_prefix

✓ from multicodec import remove_prefix

get_codec

✓ from multicodec import get_codec

Code

✓ from multicodec import Code

known_codes

✓ from multicodec import known_codes

SHA2_256

✓ from multicodec.code_table import SHA2_256, DAG_CBOR

For type-safe codec constants.

Demonstrates adding and removing multicodec prefixes, retrieving codec names, and using the `Code` object for type-safe codec handling and listing all supported codecs.

from multicodec import add_prefix, remove_prefix, get_codec, Code, known_codes from multicodec.code_table import SHA2_256 # Basic prefix operations prefixed_data = add_prefix('sha2-256', b'Some raw data') print(f"Prefixed data: {prefixed_data.hex()}") raw_data = remove_prefix(prefixed_data) print(f"Raw data: {raw_data}") codec_name = get_codec(prefixed_data) print(f"Codec name: {codec_name}") # Type-safe Code management sha2_256_code = SHA2_256 print(f"SHA2-256 Code: {sha2_256_code} (int: {int(sha2_256_code)}, str: {str(sha2_256_code)})") code_from_string = Code.from_string("sha2-256") print(f"Code from string: {code_from_string}") all_known_codes = known_codes() print(f"Number of known codes: {len(all_known_codes)}")

Debug

Known issues

gotchaThe 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.

fix

Confirm `pip install py-multicodec` and use `from multicodec import ...` for imports.

affects: All

breakingWhile 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.

fix

Consult the project's release notes or GitHub history for migration guides if upgrading from older pre-1.0.0 versions.

affects: <1.0.0

gotchaWhen 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.

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.

affects: All

gotchaThe 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.

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.

affects: All

Errors

Common errors & fixes

TypeError: a bytes-like object is required, not 'str'

Attempting to pass a Python `str` object directly to `add_prefix` or other functions expecting raw bytes.

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'))`.

NameError: name 'multicodec' is not defined

Trying to call functions like `multicodec.add_prefix` without explicitly importing the functions or the `multicodec` module itself.

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`.

ValueError: Found code 0x00 when unwrapping data, expected code 0x12

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).

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.

Upgrade

Version history

1.0.0latest on PyPI · released Dec 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Resources

githubhttps://github.com/multiformats/py-multicodec ↗

packagehttps://pypi.org/project/py-multicodec/ ↗