py-cid: Self-describing content-addressed identifiers

0.5.0 · active · verified Thu Apr 16

py-cid is a Python library that provides an implementation of the Content Identifier (CID) specification. CIDs are self-describing content-addressed identifiers used in distributed systems like IPFS and IPLD, leveraging cryptographic hashing and multiformats for flexible self-description. The library is actively maintained, with version 0.5.0 being the latest release, supporting Python 3.10 and newer.

Common errors

```
ModuleNotFoundError: No module named 'cid'
```
cause The `py-cid` library is not installed or the environment is incorrect.

fix Install the library using `pip install py-cid`.
```
TypeError: make_cid() takes 1 positional argument but 2 were given
```
cause You are likely attempting to pass a 'codec' argument to `make_cid` when it expects to infer it from the input string, or are misusing the `CIDv1` constructor.

fix `make_cid` generally infers the CID version and codec from the provided string. For `CIDv1` with a raw multihash, use `CIDv1('codec-name', multihash_bytes)` directly. For example: `CIDv1('raw', b'\x12\x20' + b'hash_bytes')`.
```
AttributeError: 'CIDv0' object has no attribute 'encode_multibase'
```
cause You are trying to call a multibase encoding method on a CIDv0 object. CIDv0 only supports Base58 encoding.

fix Ensure you are working with a `CIDv1` object if you need flexible multibase encoding. For `CIDv0`, use `str(cid_obj)` or `cid_obj.encode()` to get its Base58 string representation.

Warnings

breaking The PyPI package `py-cid` was previously renamed to `py-multiformats-cid` around version 0.4.0 (2022-10-31). The current `py-cid` (version 0.5.0+) is a distinct project. Installing `py-multiformats-cid` will provide an older, incompatible API if you are expecting the current `py-cid` behavior.
Fix: Ensure you are installing `py-cid` from the `ipld/py-cid` project and using `pip install py-cid` for the current API. Avoid `py-multiformats-cid` if you intend to use the latest `py-cid` features.
gotcha CIDv0 and CIDv1 have fundamental differences in structure and string representation. CIDv0 CIDs are always Base58-encoded and use the `dag-pb` codec implicitly. CIDv1 CIDs are multibase-encoded (e.g., base32, base64) and explicitly include a codec prefix. Mixing up expectations can lead to incorrect CID parsing or encoding errors.
Fix: Be explicit about the CID version you expect. Use `make_cid` which handles both, or `CIDv0` and `CIDv1` constructors directly for specific versions. Remember `cid.encode()` on `CIDv0` will only produce Base58, while `CIDv1.encode(base)` allows various multibase encodings.

Install

pip install py-cid Install stable release

Imports

make_cid
```
from cid import make_cid
```
CIDv0
```
from cid import CIDv0
```
CIDv1
```
from cid import CIDv1
```

Quickstart

This quickstart demonstrates how to create CIDv0 and CIDv1 objects using `make_cid` from both base58 and multibase encoded strings. It also shows how to access their version, codec, multihash, and how to encode CIDv1 into different multibase formats.

from cid import make_cid, CIDv0, CIDv1

# Create a CIDv0 from a base58-encoded multihash
cid_v0_str = 'QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpu5rmrkPdT3L4'
cid0 = make_cid(cid_v0_str)
print(f"CIDv0: {cid0}")
print(f"Version: {cid0.version}, Codec: {cid0.codec}, Multihash: {cid0.multihash.hex()}")

# Create a CIDv1 from a multibase-encoded CID string
cid_v1_str = 'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3fzmsyqhwfsgr2zfdnc2dsxze'
cid1 = make_cid(cid_v1_str)
print(f"CIDv1: {cid1}")
print(f"Version: {cid1.version}, Codec: {cid1.codec}, Multihash: {cid1.multihash.hex()}")

# Accessing components
print(f"CIDv0 string: {str(cid0)}")
print(f"CIDv1 encoded in base32: {cid1.encode('base32')}") # requires py-multibase

view raw JSON →