py-cid ↔ go-cid Feature Parity Analysis #1365

sumanjeet0012 · 2026-07-04T20:54:26Z

sumanjeet0012
Jul 4, 2026
Maintainer

py-cid Feature Parity Analysis

Date: 2026-07-05
Python version analyzed: py-cid v0.5.0
Go version analyzed: go-cid v0.6.1
Source: py-cid · go-cid

Executive Summary

The Python implementation (py-cid) and the Go reference implementation (go-cid) are much closer to parity than the other multiformat libraries analysed. Both support CIDv0/v1, builders, prefixes, sets, JSON serialization, and stream parsing. However, Go leads in several important areas: typed error handling, zero-allocation operations (ByteLen, WriteBytes), standard Go serialization interfaces, a universal Parse() function, fuzz testing, and benchmarks. Python leads with a cleaner OOP design (separate CIDv0/CIDv1 classes), version conversion methods, IPFS path parsing, and more Pythonic set operations.

Area	Status
CID type & core operations	✅ Near parity (different design)
Construction & parsing	✅ Parity achieved
Encoding & string representation	⚠️ Missing `StringOfBase()`, `Encode(encoder)`
JSON serialization	✅ Parity achieved
Binary/Text marshaling interfaces	❌ Missing
Properties & accessors	✅ Parity achieved (different API style)
Version conversion (to_v0/to_v1)	✅ Python extra
Prefix	✅ Parity achieved
Builder pattern	⚠️ V1Builder limited hash support
CID Set	✅ Near parity
Error handling	❌ Generic `ValueError` vs Go's typed errors
`CidFromReader` robustness	⚠️ Python version is fragile
`Undef` sentinel	❌ Missing
Zero-allocation `ByteLen()` / `WriteBytes()`	❌ Missing
Fuzz testing	❌ Missing
Benchmarks	❌ Missing
`Parse(interface{})` universal parser	❌ Missing

Architecture Comparison

Go Architecture (Single Type, Performance-Oriented)

go-cid/
├── cid.go              # Cid struct, Prefix, Parse/Decode/Cast, CidFromBytes/Reader,
│                       # MarshalJSON/Binary/Text, String/StringOfBase/Encode,
│                       # Version/Type/Hash/Bytes/ByteLen/WriteBytes/Equals/...
├── builder.go          # Builder interface, V0Builder, V1Builder
├── set.go              # Set (Add/Has/Remove/Len/Keys/Visit/ForEach)
├── deprecated.go       # NewPrefixV0, NewPrefixV1
├── varint.go           # String-based uvarint (avoids []byte allocation)
├── cid_fuzz.go         # Fuzz testing
├── cid_test.go         # 912 lines of tests
├── builder_test.go     # Builder tests
├── set_test.go         # Set tests
├── benchmark_test.go   # Performance benchmarks
├── varint_test.go      # Varint tests
└── version.json        # v0.6.1

Key design principle: Cid is a single struct wrapping a binary string (Cid{str string}). CIDv0 and CIDv1 are distinguished only by the Version() method. This enables zero-copy operations and avoids allocations. The internal string stores the raw CID bytes directly.

Dependencies: go-multibase, go-multihash, go-varint.

Python Architecture (OOP, Two Classes)

py-cid/
├── cid/
│   ├── __init__.py     # Public API exports
│   ├── cid.py          # BaseCID, CIDv0, CIDv1, make_cid, from_string, from_bytes,
│   │                   # from_bytes_strict, from_reader, must_parse, is_cid,
│   │                   # extract_encoding, parse_ipfs_path, CIDJSONEncoder
│   ├── builder.py      # Builder ABC, V0Builder, V1Builder
│   ├── prefix.py       # Prefix class (version, codec, mh_type, mh_length)
│   ├── set.py          # CIDSet (add/has/remove/keys/visit/for_each)
│   └── base58.py       # Bundled base58 implementation
├── tests/
│   ├── test_cid.py     # 338 lines
│   ├── test_new_features.py  # 403 lines
│   └── test_prefix.py  # 149 lines
└── pyproject.toml

Key design difference: Python uses separate classes for CIDv0 and CIDv1 with a shared BaseCID base. This provides type-level distinction but means more isinstance checks and no single-type uniformity.

Dependencies: py-multibase, py-multicodec, py-multihash, morphys, varint.

Feature-by-Feature Gap Analysis

3.1 CID Type Design

Feature	Go	Python	Gap?
Type	Single `Cid` struct (`Cid{str string}`)	Two classes: `CIDv0(BaseCID)`, `CIDv1(BaseCID)`	Design choice
Internal storage	Binary string (raw bytes as Go string)	Separate `_version`, `_codec`, `_multihash` fields	Design choice
`Undef` sentinel	✅ `var Undef = Cid{}`	❌ No equivalent	YES
`Defined()`	✅ `c.str != ""`	✅ `defined()`	No
`Equals(other)`	✅	✅ `__eq__`	No
`__hash__` / hashable	⚠️ Not hashable by default (struct with string)	✅ `__hash__` based on (version, codec, multihash)	Python extra
`Compare` / ordering	❌	❌	Both missing

Key insight: Go's Undef is a zero-value Cid{} that can be used as a sentinel for "no CID" — similar to nil but without pointer semantics. Python has no equivalent; None is used instead.

3.2 Construction & Parsing

Feature	Go	Python	Gap?
`NewCidV0(mhash)`	✅ (panics on invalid)	✅ `CIDv0(mhash)`	No
`NewCidV1(codec, mhash)`	✅ (panics on invalid)	✅ `CIDv1(codec, mhash)`	No
`Decode(string)`	✅	✅ `from_string(s)`	No
`Cast([]byte)`	✅	✅ `from_bytes(b)`	No
`Cast` with trailing bytes check	✅ Explicit error	✅ `from_bytes_strict(b)`	No
`Parse(interface{})`	✅ Accepts string/[]byte/Multihash/Cid	❌	YES
`MustParse(interface{})`	✅ Panics on error	✅ `must_parse(v)`	No
`CidFromBytes(data)` → (n, Cid, err)	✅ Returns bytes consumed	⚠️ `from_bytes()` doesn't return bytes consumed	YES
`CidFromReader(r)` → (n, Cid, err)	✅ Robust, handles io.EOF, OOM protection	⚠️ `from_reader()` exists but is fragile	YES
CIDv0 auto-detection (Qm prefix)	✅	✅	No
CIDv0 validation (sha2-256, 32 bytes)	✅ `tryNewCidV0()` enforces	❌ `CIDv0()` constructor doesn't validate	YES
IPFS path extraction	✅ `Parse()` handles `/ipfs/`	✅ `parse_ipfs_path()` + `from_string()`	No

3.2.1 CIDv0 Validation Gap

Go validates CIDv0 on construction:

func tryNewCidV0(mhash mh.Multihash) (Cid, error) {
    dec, err := mh.Decode(mhash)
    if dec.Code != mh.SHA2_256 || dec.Length != 32 {
        return Undef, ErrInvalidCid{...}
    }
    return Cid{string(mhash)}, nil
}

Python's CIDv0.__init__() accepts any multihash without validation:

class CIDv0(BaseCID):
    def __init__(self, multihash):
        super().__init__(0, self.CODEC, multihash)  # No validation!

This means CIDv0(b"\x00\x00") succeeds in Python but would panic in Go.

3.2.2 `CidFromReader` Robustness Gap

Go's CidFromReader is a 90-line function that:

Uses a bufByteReader to avoid allocations
Handles io.EOF vs io.ErrUnexpectedEOF correctly
Has a 32 MiB max allocation guard against OOM
Validates the multihash after reading
Returns accurate byte count even on error

Python's from_reader() is ~60 lines but:

Reads fixed-size chunks with reader.read(n)
Assumes single-byte varints for codec and multihash code
Doesn't handle multi-byte varints properly
No OOM protection
Doesn't validate the multihash after reading

3.3 Encoding & String Representation

Feature	Go	Python	Gap?
`String()` (default)	✅ base32 for v1, base58 for v0	✅ `__str__()` → base58btc for both	⚠️ Different defaults
`StringOfBase(base)`	✅ Encode with specific base	❌	YES
`Encode(encoder)`	✅ Encode with encoder object	⚠️ `encode(encoding)` accepts string name	YES (different API)
CIDv0 always base58	✅ Enforced	✅ Enforced	No
CIDv1 default base32	✅	❌ Default is base58btc	YES (spec divergence)

Spec note: The CID specification recommends base32 for CIDv1 string representation. Go follows this; Python defaults to base58btc.

3.4 Serialization (JSON / Binary / Text)

Feature	Go	Python	Gap?
`MarshalJSON` / `UnmarshalJSON`	✅ `{"/": "<cid>"}`	✅ `to_json_dict()` / `from_json_dict()` + `CIDJSONEncoder`	No
`MarshalBinary` / `UnmarshalBinary`	✅ Go standard interface	❌	YES
`MarshalText` / `UnmarshalText`	✅ Go standard interface	❌	YES
JSON null handling	✅ `Undef` → `null`	❌ No sentinel for undefined CID	YES

3.5 Properties & Accessors

Feature	Go	Python	Gap?
`Version()`	✅ `uint64`	✅ `version` property → `int`	No
`Type()` (codec)	✅ `uint64` (multicodec code)	✅ `codec` property → `str` (name)	⚠️ Different types
`Hash()` (multihash)	✅ `mh.Multihash`	✅ `multihash` property → `bytes`	No
`Bytes()`	✅ `[]byte`	✅ `buffer` / `to_bytes()` → `bytes`	No
`ByteLen()`	✅ Zero-allocation length	❌	YES
`WriteBytes(w io.Writer)`	✅ Zero-allocation write	❌	YES
`KeyString()`	✅ Binary string for map keys	✅ `key_string()` → latin-1 decoded string	No
`Loggable()`	✅ `map[string]interface{}`	✅ `loggable()` → `dict`	No
`Prefix()`	✅ Returns `Prefix` struct	✅ `prefix()` → `Prefix` object	No

3.6 Version Conversion

Feature	Go	Python	Gap?
CIDv0 → CIDv1	❌ No method	✅ `to_v1()`	No (Python extra)
CIDv1 → CIDv0	❌ No method	✅ `to_v0()` (validates dag-pb)	No (Python extra)

3.7 Prefix

Feature	Go	Python	Gap?
`Prefix` struct	✅ `{Version, Codec, MhType, MhLength}` (all uint64/int)	✅ `Prefix(version, codec, mh_type, mh_length)` (str for codec/mh_type)	Design choice
`Prefix.Sum(data)`	✅ Uses `mh.Sum()` with all hash types	⚠️ Only sha2-256 and sha2-512 implemented	YES
`Prefix.Sum()` identity hash handling	✅ Special-cases `mh.IDENTITY`	❌	YES
`Prefix.Bytes()`	✅ Varint serialization	✅ `to_bytes()`	No
`PrefixFromBytes(buf)`	✅	✅ `Prefix.from_bytes(data)`	No
`Prefix.GetCodec()`	✅	❌ (use `.codec` property)	No (different API)
`Prefix.WithCodec(c)`	✅ Returns new Builder	❌	YES
CIDv0 validation in Sum	✅ Rejects non-sha2-256	❌	YES
Convenience constructors	❌	✅ `Prefix.v0()`, `Prefix.v1()`	No (Python extra)

3.7.1 `Prefix.Sum()` Hash Type Support

Go's Prefix.Sum() delegates to mh.Sum() which supports all registered multihash functions (sha1, sha2-, sha3-, blake2*, keccak, etc.). Python's Prefix.sum() only implements sha2-256 and sha2-512, raising NotImplementedError for everything else:

def sum(self, data: bytes):
    if self.mh_type == "sha2-256":
        digest = hashlib.sha256(data).digest()
    elif self.mh_type == "sha2-512":
        digest = hashlib.sha512(data).digest()
    else:
        raise NotImplementedError(f"Hash type {self.mh_type} not fully implemented")

3.8 Builder Pattern

Feature	Go	Python	Gap?
`Builder` interface	✅ `Sum/GetCodec/WithCodec`	✅ `Builder` ABC with `sum/get_codec/with_codec`	No
`V0Builder`	✅	✅	No
`V1Builder`	✅	✅	No
`V1Builder.Sum()` hash support	✅ All hash types via `mh.Sum()`	⚠️ Only sha2-256, sha2-512	YES
`V1Builder.WithCodec()`	✅ Returns new builder	✅ Returns new builder	No
`V0Builder.WithCodec()` auto-upgrade	✅ Switches to V1Builder	✅ Switches to V1Builder	No
Prefix as Builder	✅ `Prefix` implements `Builder`	❌ `Prefix` is separate from `Builder`	YES

3.9 CID Set

Feature	Go `Set`	Python `CIDSet`	Gap?
`NewSet()` / constructor	✅ `NewSet()`	✅ `CIDSet()`	No
`Add(c)`	✅	✅ `add(cid)`	No
`Has(c)`	✅	✅ `has(cid)` + `__contains__`	No
`Remove(c)`	✅ (actually deletes)	⚠️ `remove()` uses `discard()` (no error if missing)	YES (semantic difference)
`Len()`	✅	✅ `__len__()`	No
`Keys()`	✅ Returns `[]Cid`	✅ `keys()` returns `list`	No
`Visit(c)` → bool	✅	✅ `visit(cid)`	No
`ForEach(f func(Cid) error) error`	✅ Returns first error	⚠️ `for_each(func)` returns None	YES (no error propagation)
`__iter__`	❌ (use Keys())	✅	No (Python extra)

3.10 Error Handling

Go Error	Python Equivalent	Gap?
`ErrInvalidCid{Err}` (typed, wrappable)	`ValueError` (generic)	YES
`ErrCidTooShort`	`ValueError("argument length can not be zero")`	YES
`ErrInvalidEncoding`	`ValueError`	YES
`errors.Is(err, ErrInvalidCid)` support	❌ No error hierarchy	YES
Panic on invalid `NewCidV0`/`NewCidV1`	❌ No validation in constructor	YES

Go has a proper typed error system:

type ErrInvalidCid struct { Err error }
func (e ErrInvalidCid) Is(err error) bool { ... }  // supports errors.Is()

Python uses generic ValueError for everything, making it impossible to distinguish CID-specific errors from other value errors.

3.11 Utility Functions

Feature	Go	Python	Gap?
`ExtractEncoding(v)`	✅ Returns `mbase.Encoding`	✅ `extract_encoding(cid_str)` returns `str`	No
`Parse(v interface{})`	✅ Universal parser	❌	YES
`MustParse(v)`	✅	✅ `must_parse(v)`	No
`parse_ipfs_path()`	⚠️ Inline in `Parse()`	✅ Standalone function	No (Python extra)
`is_cid(s)`	❌	✅	No (Python extra)
`make_cid(*args)`	❌	✅ Flexible constructor	No (Python extra)

3.12 Testing & Benchmarks

Feature	Go	Python	Gap?
Core CID tests	✅ 912 lines	✅ 338 lines	No
Builder tests	✅ 112 lines	✅ In test_new_features.py	No
Set tests	✅ 88 lines	✅ In test_new_features.py	No
Prefix tests	✅ In cid_test.go	✅ 149 lines	No
Varint tests	✅ 56 lines	❌	YES
Benchmark tests	✅ `benchmark_test.go`	❌	YES
Fuzz testing	✅ `cid_fuzz.go`	❌	YES
Round-trip tests	✅ Extensive	⚠️ Basic	YES
Error case tests	✅ Extensive	⚠️ Basic	YES

Feature Matrix Summary

#	Feature	Priority	Status
1	CIDv0 validation in constructor (sha2-256, 32 bytes)	High	❌ Missing
2	`Undef` sentinel value	Medium	❌ Missing
3	`Parse(interface{})` universal parser	Medium	❌ Missing
4	`CidFromBytes()` returns bytes consumed	Medium	❌ Missing
5	`CidFromReader()` robustness (multi-byte varints, OOM guard)	High	⚠️ Fragile
6	`StringOfBase(base)` method	Medium	❌ Missing
7	`Encode(encoder)` with encoder object	Low	⚠️ Different API
8	CIDv1 default string → base32 (per spec)	Medium	⚠️ Uses base58btc
9	`MarshalBinary` / `UnmarshalBinary`	Medium	❌ Missing
10	`MarshalText` / `UnmarshalText`	Medium	❌ Missing
11	`ByteLen()` zero-allocation	Low	❌ Missing
12	`WriteBytes(w)` zero-allocation	Low	❌ Missing
13	Typed error hierarchy (`InvalidCIDError`, etc.)	High	❌ Missing
14	`Prefix.Sum()` full hash type support	High	⚠️ Only sha2-256/512
15	`Prefix.Sum()` identity hash handling	Medium	❌ Missing
16	`Prefix.WithCodec()` method	Low	❌ Missing
17	`Prefix` as `Builder` (implements Builder interface)	Low	❌ Missing
18	`V1Builder.Sum()` full hash type support	High	⚠️ Only sha2-256/512
19	`Set.Remove()` raises on missing (vs discard)	Low	⚠️ Semantic difference
20	`Set.ForEach()` error propagation	Low	⚠️ Returns None
21	Fuzz testing	Low	❌ Missing
22	Benchmark suite	Low	❌ Missing
23	JSON null handling for undefined CID	Low	❌ Missing

Phased Roadmap

Phase 1 – Critical Correctness & API Gaps

Goal: Fix validation gaps and add the most important missing APIs.

Estimated effort: 1–2 weeks

1.1 Add CIDv0 validation in constructor

class CIDv0(BaseCID):
    def __init__(self, multihash: str | bytes) -> None:
        multihash = ensure_bytes(multihash)
        # Validate: must be sha2-256 with 32-byte digest
        try:
            decoded = mh.decode(multihash)
        except ValueError as e:
            raise ValueError(f"invalid multihash for CIDv0: {e}") from e
        
        if decoded.code != 0x12 or decoded.length != 32:  # sha2-256
            raise ValueError(
                f"invalid hash for CIDv0: must be sha2-256 with 32-byte digest, "
                f"got {decoded.name} with {decoded.length}-byte digest"
            )
        super().__init__(0, self.CODEC, multihash)

1.2 Add `UNDEF` sentinel

class _UndefCID:
    """Sentinel for undefined/nil CID."""
    def defined(self) -> bool:
        return False
    def __bool__(self) -> bool:
        return False
    def __repr__(self) -> str:
        return "CID.Undef"
    def __eq__(self, other) -> bool:
        return isinstance(other, _UndefCID) or (isinstance(other, BaseCID) and not other.defined())

UNDEF = _UndefCID()

1.3 Add `parse()` universal function

def parse(v: str | bytes | CIDv0 | CIDv1 | None) -> CIDv0 | CIDv1:
    """Parse a CID from various input types.
    
    Accepts:
    - str: CID string (with optional /ipfs/ prefix)
    - bytes: CID bytes
    - CIDv0/CIDv1: returned as-is
    - None: returns UNDEF
    """
    if v is None:
        return UNDEF
    if isinstance(v, (CIDv0, CIDv1)):
        return v
    if isinstance(v, str):
        return from_string(v)
    if isinstance(v, bytes):
        return from_bytes(v)
    raise ValueError(f"cannot parse {type(v)} as CID")

1.4 Fix `from_reader()` for robustness

Rewrite to properly handle multi-byte varints and add OOM protection:

MAX_DIGEST_ALLOC = 32 << 20  # 32 MiB

def from_reader(reader) -> tuple[int, CIDv0 | CIDv1]:
    """Parse CID from reader, returning (bytes_read, CID)."""
    buf = bytearray()
    
    # Read first varint (version or mh code for v0)
    first_varint, n = _read_varint_from_reader(reader, buf)
    
    if first_varint == 0x12:  # sha2-256 → CIDv0
        # Read remaining 33 bytes (1 byte length + 32 byte digest)
        remaining = reader.read(33)
        buf.extend(remaining)
        if len(remaining) < 33:
            raise ValueError("not enough bytes for CIDv0")
        return len(buf), from_bytes(bytes(buf))
    
    if first_varint != 1:
        raise ValueError(f"expected CID version 1, got {first_varint}")
    
    # Read codec varint
    _, n2 = _read_varint_from_reader(reader, buf)
    
    # Read multihash code varint
    _, n3 = _read_varint_from_reader(reader, buf)
    
    # Read multihash length varint
    mh_length, n4 = _read_varint_from_reader(reader, buf)
    
    if mh_length > MAX_DIGEST_ALLOC:
        raise ValueError(f"refusing to allocate {mh_length} bytes for digest")
    
    # Read digest
    digest = reader.read(mh_length)
    buf.extend(digest)
    if len(digest) < mh_length:
        raise ValueError("not enough bytes for multihash digest")
    
    return len(buf), from_bytes(bytes(buf))

1.5 Expand `Prefix.sum()` hash type support

Use multihash.sum() to support all registered hash functions:

def sum(self, data: bytes) -> CIDv0 | CIDv1:
    """Hash data and create CID."""
    length = self.mh_length
    # Handle identity hash
    mh_code = self._mh_type_to_code(self.mh_type)
    if mh_code == 0x00:  # identity
        length = -1
    
    mhash = mh.sum(data, self.mh_type, length)
    
    if self.version == 0:
        return CIDv0(mhash)
    return CIDv1(self.codec, mhash)

Phase 2 – Serialization & Zero-Allocation Operations

Goal: Add standard serialization interfaces and performance-oriented methods.

Estimated effort: 3–5 days

2.1 Change CIDv1 default encoding to base32

Per the CID specification, CIDv1 should default to base32 encoding:

class CIDv1(BaseCID):
    def encode(self, encoding: str | None = "base32") -> bytes:
        return multibase.encode(encoding, self.buffer)

2.2 Add `string_of_base()` method

def string_of_base(self, encoding: str) -> str:
    """Encode CID with specific base encoding."""
    if self.version == 0:
        if encoding != "base58btc":
            raise ValueError("CIDv0 can only be encoded as base58btc")
        return base58.b58encode(self.buffer).decode()
    return multibase.encode(encoding, self.buffer).decode()

2.3 Add `byte_len()` method

def byte_len(self) -> int:
    """Return the length of the CID in bytes without allocation."""
    return len(self._bytes)  # or len(self.buffer)

2.4 Add binary/text marshaling helpers

def marshal_binary(self) -> bytes:
    """Serialize to binary (equivalent to buffer/to_bytes)."""
    return self.buffer

def unmarshal_binary(self, data: bytes) -> None:
    """Deserialize from binary."""
    parsed = from_bytes(data)
    self._version = parsed.version
    self._codec = parsed.codec
    self._multihash = parsed.multihash

def marshal_text(self) -> bytes:
    """Serialize to text."""
    return str(self).encode()

Phase 3 – Error Handling & Robustness

Goal: Add typed error hierarchy and improve error messages.

Estimated effort: 3–5 days

3.1 Add typed error hierarchy

# cid/exceptions.py
class CIDError(Exception):
    """Base exception for CID operations."""
    pass

class InvalidCIDError(CIDError):
    """Raised when a CID is invalid."""
    def __init__(self, message: str, cause: Exception | None = None):
        super().__init__(f"invalid cid: {message}")
        self.cause = cause

class CIDTooShortError(InvalidCIDError):
    """Raised when CID bytes are too short."""
    def __init__(self):
        super().__init__("cid too short")

class InvalidEncodingError(CIDError):
    """Raised when base encoding is invalid."""
    pass

3.2 Update `Set.remove()` to match Go semantics

class CIDSet:
    def remove(self, cid):
        """Remove CID from set. Raises KeyError if not present."""
        self._set.remove(cid)  # Raises KeyError, unlike discard()

3.3 Add error propagation to `CIDSet.for_each()`

def for_each(self, func):
    """Call function for each CID. Stops and returns error if func raises."""
    for cid in self._set:
        try:
            func(cid)
        except Exception as e:
            return e
    return None

Phase 4 – Testing, Benchmarks & Polish

Goal: Add comprehensive tests, benchmarks, and fuzz testing.

Estimated effort: 1–2 weeks

4.1 Add benchmark suite

# tests/test_benchmarks.py
import pytest
from cid import CIDv1, make_cid, from_bytes, from_string

BENCH_DATA = b"benchmark test data for CID operations"

@pytest.mark.benchmark
def test_bench_cidv1_creation(benchmark):
    import hashlib, multihash
    digest = hashlib.sha256(BENCH_DATA).digest()
    mhash = multihash.encode(digest, "sha2-256")
    benchmark(CIDv1, "raw", mhash)

@pytest.mark.benchmark
def test_bench_from_string(benchmark):
    benchmark(from_string, "bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenosa")

@pytest.mark.benchmark
def test_bench_from_bytes(benchmark):
    cid = make_cid("bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenosa")
    raw = cid.to_bytes()
    benchmark(from_bytes, raw)

@pytest.mark.benchmark
def test_bench_prefix(benchmark):
    cid = make_cid("bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenosa")
    benchmark(cid.prefix)

4.2 Add round-trip tests

def test_roundtrip_all_encodings():
    """Test CID roundtrip through all supported base encodings."""
    cid = make_cid(1, "raw", some_multihash)
    for encoding in ["base32", "base58btc", "base64", "base16"]:
        encoded = cid.string_of_base(encoding)
        decoded = from_string(encoded)
        assert decoded == cid

def test_roundtrip_bytes():
    """Test CID bytes roundtrip."""
    cid = make_cid(1, "dag-pb", some_multihash)
    assert from_bytes(cid.to_bytes()) == cid

4.3 Add error case tests

def test_cidv0_rejects_non_sha256():
    """CIDv0 must reject non-sha2-256 multihashes."""
    with pytest.raises(ValueError, match="sha2-256"):
        CIDv0(some_sha512_multihash)

def test_from_bytes_trailing_bytes():
    """from_bytes_strict rejects trailing bytes."""
    cid_bytes = some_valid_cid.to_bytes() + b"\x00"
    with pytest.raises(ValueError, match="trailing bytes"):
        from_bytes_strict(cid_bytes)

4.4 Add property-based testing with hypothesis

from hypothesis import given, strategies as st

@given(st.binary(min_size=34, max_size=34))
def test_cidv0_always_34_bytes(data):
    """CIDv0 bytes are always exactly 34 bytes."""
    try:
        cid = from_bytes(data)
        if cid.version == 0:
            assert len(cid.to_bytes()) == 34
    except ValueError:
        pass  # Invalid CID is fine

Appendix – Python-Exclusive Features

These features exist in Python but not in Go:

Feature	Description
Separate `CIDv0` / `CIDv1` classes	Type-level distinction between versions
`to_v0()` / `to_v1()` methods	Version conversion on CID objects
`from_bytes_strict()`	Validates no trailing bytes
`parse_ipfs_path()`	Standalone IPFS path extraction
`CIDJSONEncoder`	Custom `json.JSONEncoder` subclass
`CIDSet.__iter__`	Pythonic iteration over set
`CIDSet.__contains__`	`in` operator support
`Prefix.v0()` / `Prefix.v1()` class methods	Convenience constructors
`is_cid()` function	Quick validation without exception
`make_cid()` flexible constructor	Accepts 1 or 3 arguments
`CIDSet.__len__`	`len()` support
`__hash__` on CID	CIDs usable as dict keys / set members

Summary Timeline

Phase	Focus	Effort	Key Deliverables
Phase 1	Correctness & Core API	1–2 weeks	CIDv0 validation, `UNDEF`, `parse()`, robust `from_reader()`, full hash support in `Prefix.sum()`
Phase 2	Serialization & Performance	3–5 days	base32 default for CIDv1, `string_of_base()`, `byte_len()`, binary/text marshaling
Phase 3	Error Handling	3–5 days	Typed error hierarchy, `Set.remove()` fix, `Set.for_each()` error propagation
Phase 4	Testing & Benchmarks	1–2 weeks	Benchmarks, round-trip tests, error case tests, hypothesis property tests

Total estimated effort: 3–5 weeks

The highest-priority items are Phase 1 correctness fixes — especially CIDv0 validation (currently accepts invalid multihashes) and Prefix.sum() hash type support (currently only 2 of 100+ hash types work). These are real bugs that would cause incorrect behavior in production.

The Python implementation's OOP design (separate classes, to_v0()/to_v1(), Pythonic set) are genuine usability advantages that should be preserved and documented as differentiators from Go's single-type approach.

Navigation Menu

Repository navigation

py-cid ↔ go-cid Feature Parity Analysis #1365

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

py-cid ↔ go-cid Feature Parity Analysis #1365

Uh oh!

sumanjeet0012 Jul 4, 2026 Maintainer

py-cid Feature Parity Analysis

Table of Contents

Executive Summary

Architecture Comparison

Go Architecture (Single Type, Performance-Oriented)

Python Architecture (OOP, Two Classes)

Feature-by-Feature Gap Analysis

3.1 CID Type Design

3.2 Construction & Parsing

3.2.1 CIDv0 Validation Gap

3.2.2 CidFromReader Robustness Gap

3.3 Encoding & String Representation

3.4 Serialization (JSON / Binary / Text)

3.5 Properties & Accessors

3.6 Version Conversion

3.7 Prefix

3.7.1 Prefix.Sum() Hash Type Support

3.8 Builder Pattern

3.9 CID Set

3.10 Error Handling

3.11 Utility Functions

3.12 Testing & Benchmarks

Feature Matrix Summary

Phased Roadmap

Phase 1 – Critical Correctness & API Gaps

1.1 Add CIDv0 validation in constructor

1.2 Add UNDEF sentinel

1.3 Add parse() universal function

1.4 Fix from_reader() for robustness

1.5 Expand Prefix.sum() hash type support

Phase 2 – Serialization & Zero-Allocation Operations

2.1 Change CIDv1 default encoding to base32

2.2 Add string_of_base() method

2.3 Add byte_len() method

2.4 Add binary/text marshaling helpers

Phase 3 – Error Handling & Robustness

3.1 Add typed error hierarchy

3.2 Update Set.remove() to match Go semantics

3.3 Add error propagation to CIDSet.for_each()

Phase 4 – Testing, Benchmarks & Polish

4.1 Add benchmark suite

4.2 Add round-trip tests

4.3 Add error case tests

4.4 Add property-based testing with hypothesis

Appendix – Python-Exclusive Features

Summary Timeline

Replies: 0 comments

sumanjeet0012
Jul 4, 2026
Maintainer

3.2.2 `CidFromReader` Robustness Gap

3.7.1 `Prefix.Sum()` Hash Type Support

1.2 Add `UNDEF` sentinel

1.3 Add `parse()` universal function

1.4 Fix `from_reader()` for robustness

1.5 Expand `Prefix.sum()` hash type support

2.2 Add `string_of_base()` method

2.3 Add `byte_len()` method

3.2 Update `Set.remove()` to match Go semantics

3.3 Add error propagation to `CIDSet.for_each()`