dag package

Subpackages

• dag.codecs package
  • Submodules
  • dag.codecs.dag_cbor module
    • DagCborCodec
      • DagCborCodec.code
      • DagCborCodec.decode()
      • DagCborCodec.encode()
      • DagCborCodec.name
    • codec
    • decode()
    • encode()
  • dag.codecs.dag_json module
    • DagJsonCodec
      • DagJsonCodec.code
      • DagJsonCodec.decode()
      • DagJsonCodec.encode()
      • DagJsonCodec.name
    • codec
    • decode()
    • encode()
  • dag.codecs.dag_pb module
    • DagPbCodec
      • DagPbCodec.code
      • DagPbCodec.decode()
      • DagPbCodec.encode()
      • DagPbCodec.name
    • PBLink
      • PBLink.hash
      • PBLink.name
      • PBLink.tsize
    • PBNode
      • PBNode.data
      • PBNode.links
    • codec
    • decode()
    • encode()
  • dag.codecs.raw module
    • RawCodec
      • RawCodec.code
      • RawCodec.decode()
      • RawCodec.encode()
      • RawCodec.name
    • codec
    • decode()
    • encode()
  • Module contents
    • DagCborCodec
      • DagCborCodec.code
      • DagCborCodec.decode()
      • DagCborCodec.encode()
      • DagCborCodec.name
    • DagJsonCodec
      • DagJsonCodec.code
      • DagJsonCodec.decode()
      • DagJsonCodec.encode()
      • DagJsonCodec.name
    • DagPbCodec
      • DagPbCodec.code
      • DagPbCodec.decode()
      • DagPbCodec.encode()
      • DagPbCodec.name
    • RawCodec
      • RawCodec.code
      • RawCodec.decode()
      • RawCodec.encode()
      • RawCodec.name

Submodules

dag.block module

Block - the fundamental unit of data in IPLD.

A Block binds together three things: 1. The raw encoded bytes 2. A CID that addresses those bytes (hash + codec) 3. The decoded value (an IPLD data-model node)

This mirrors the JS @ipld/block design: - Block.encode({ value, codec, hasher }) → Block - Block.decode({ bytes, codec, hasher }) → Block - Block.create({ bytes, cid, value, codec }) → Block

Reference: https://github.com/multiformats/js-multiformats

class dag.block.Block(*, cid: CIDv0 | CIDv1, data: bytes, value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1, codec: BlockCodec | None = None)

Bases: object

An immutable IPLD block: CID + bytes + value.

Use the class methods encode, decode, or create rather than calling __init__ directly.

property bytes: bytes

The raw encoded bytes.

property cid: CIDv0 | CIDv1

The content identifier for this block.

property codec: BlockCodec | None

The codec used to create this block (if known).

classmethod create(*, data: bytes, cid: CIDv0 | CIDv1, value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1, codec: BlockCodec | None = None) → Block

Create a Block from pre-computed parts.

No encoding, decoding, or hashing is performed.

classmethod decode(*, data: bytes, codec: BlockCodec | int, hasher: str = 'sha2-256', version: int = 1) → Block

Decode raw bytes into a Block.

Parameters

data:

The raw encoded bytes.

codec:

A BlockCodec instance or a multicodec code (int).

hasher:

Multihash algorithm name (default "sha2-256").

version:

CID version (default 1).

classmethod encode(*, value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1, codec: BlockCodec | int, hasher: str = 'sha2-256', version: int = 1) → Block

Encode an IPLD value into a new Block.

Parameters

value:

The IPLD data-model value to encode.

codec:

A BlockCodec instance or a multicodec code (int).

hasher:

Multihash algorithm name (default "sha2-256").

version:

CID version (default 1). Use 0 only for dag-pb with sha2-256.

get(path: str) → Any

Resolve a /-separated path into this block’s value.

Returns the value at that path, or raises KeyError / IndexError if the path is invalid.

links() → Iterator[tuple[str, CIDv0 | CIDv1]]

Yield (path, cid) for every CID link in this block’s value.

tree() → Iterator[str]

Yield every path segment in this block’s value (depth-first).

property value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1

The decoded IPLD data-model value.

dag.codec module

Codec interface definitions for IPLD.

This module defines the abstract interfaces that every IPLD codec must implement, following the same pattern as the JS @ipld/interface (BlockEncoder / BlockDecoder / BlockCodec).

A codec is identified by: - name - a human-readable string (e.g. "dag-cbor") - code - the multicodec code (e.g. 0x71)

And provides two operations: - encode(node) → bytes - serialize an IPLD node - decode(data) → node - deserialize bytes into an IPLD node

class dag.codec.BlockCodec

Bases: BlockEncoder, BlockDecoder

A codec that can both encode and decode.

Concrete implementations should subclass this and provide name, code, encode, and decode.

class dag.codec.BlockDecoder

Bases: ABC

Abstract decoder - turns bytes into an IPLD node.

abstract property code: int

Multicodec code.

abstract decode(data: bytes) → None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1

Decode bytes into an IPLD data model value.

abstract property name: str

Human-readable codec name.

class dag.codec.BlockEncoder

Bases: ABC

Abstract encoder - turns an IPLD node into bytes.

abstract property code: int

Multicodec code (e.g. 0x71).

abstract encode(node: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1) → bytes

Encode an IPLD data model value into bytes.

abstract property name: str

Human-readable codec name (e.g. 'dag-cbor').

dag.codec.get_codec(code: int) → BlockCodec

Look up a registered codec by its multicodec code.

Raises KeyError if no codec is registered for code.

dag.codec.lookup_codec(name_or_code: str | int) → BlockCodec

Look up a codec by name or code.

Raises KeyError if not found.

dag.codec.register_codec(codec: BlockCodec) → None

Register a codec so it can be looked up by code.

dag.codec.registered_codecs() → dict[int, BlockCodec]

Return a copy of all registered codecs.

dag.dag module

class dag.dag.Link(name, size, multihash)

Bases: object

serialize()

class dag.dag.Node(data, links, serialized, multihash)

Bases: object

classmethod add_link(node, link)

clone()

classmethod create(data, links=None, hash_algorithm='sha2-256', serializer=<function dumps>)

property data

property links

property multihash

classmethod remove_link(node, name_or_multihash)

property serialized

property size

dag.ipld_model module

IPLD Data Model - the universal representation layer.

The IPLD Data Model defines the following kinds of values that can appear in any IPLD node:

Null, Bool, Int, Float, String, Bytes, List, Map, Link

A Link is a CID (Content IDentifier) that points to another block.

This module provides: - Kind enum for type discrimination - Helper predicates for checking values - Type alias IPLDNode for type-annotated IPLD data

Reference: https://ipld.io/docs/data-model/

dag.ipld_model.CID

A Content IDentifier - either CIDv0 or CIDv1.

alias of CIDv0 | CIDv1

dag.ipld_model.IPLDNode

Any value conforming to the IPLD Data Model.

• None → Null

• bool → Bool

• int → Int

• float → Float

• str → String

• bytes → Bytes

• list → List

• dict → Map (keys must be strings)

• CID → Link

alias of None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1

class dag.ipld_model.Kind(value)

Bases: Enum

IPLD Data Model kinds.

Every value in the IPLD Data Model belongs to exactly one kind.

BOOL = 'bool'

BYTES = 'bytes'

FLOAT = 'float'

INT = 'int'

LINK = 'link'

LIST = 'list'

MAP = 'map'

NULL = 'null'

STRING = 'string'

dag.ipld_model.is_cid(value: Any) → bool

Return True if value is a CID (IPLD Link).

dag.ipld_model.is_ipld_value(value: Any) → bool

Return True if value is representable in the IPLD Data Model.

dag.ipld_model.kind_of(value: Any) → Kind

Return the IPLD Kind of value.

Raises TypeError if the value is not representable in the IPLD Data Model.

dag.multicodec_codes module

Multicodec code constants for IPLD codecs and multihash functions.

These codes are defined by the multicodec table: https://github.com/multiformats/multicodec/blob/master/table.csv

dag.multicodec_codes.BLAKE2B_256_CODE = 45600

BLAKE2b-256 hash function.

dag.multicodec_codes.DAG_CBOR_CODE = 113

DAG-CBOR codec - deterministic CBOR with IPLD links.

dag.multicodec_codes.DAG_JSON_CODE = 297

DAG-JSON codec - deterministic JSON with IPLD links.

dag.multicodec_codes.DAG_PB_CODE = 112

DAG-PB (Protobuf) codec - used by legacy IPFS UnixFS.

dag.multicodec_codes.IDENTITY_CODE = 0

Identity hash function (no hashing).

dag.multicodec_codes.RAW_CODE = 85

Raw binary codec - identity, no transformation.

dag.multicodec_codes.SHA2_256_CODE = 18

SHA-256 hash function.

dag.multicodec_codes.SHA2_512_CODE = 19

SHA-512 hash function.

dag.multicodec_codes.SHA3_256_CODE = 22

SHA3-256 hash function.

dag.multicodec_codes.SHA3_512_CODE = 23

SHA3-512 hash function.

dag.utils module

Utility functions for py-ipld-dag.

Provides helpers for working with IPLD blocks, CIDs, and codecs.

dag.utils.bytes_to_cid(raw: bytes) → CIDv0 | CIDv1

Parse a CID from its binary representation.

dag.utils.cid_to_bytes(cid_obj: CIDv0 | CIDv1) → bytes

Convert a CID object to its binary representation.

dag.utils.cid_to_string(cid_obj: CIDv0 | CIDv1) → str

Convert a CID to its string representation.

dag.utils.collect_links(value: Any) → list[tuple[str, CIDv0 | CIDv1]]

Collect all CID links from an IPLD data-model value.

Returns a list of (path, cid) tuples.

Uses dag.block._walk_links() internally to avoid duplicating the recursive traversal logic.

dag.utils.create_cid(data: bytes, codec: str = 'dag-cbor', hasher: str = 'sha2-256', version: int = 1) → CIDv0 | CIDv1

Create a CID from raw encoded bytes.

Parameters

data:

The encoded bytes to hash.

codec:

The codec name (e.g. "dag-cbor").

hasher:

The multihash algorithm (e.g. "sha2-256").

version:

CID version (0 or 1).

Returns

CID

A new CID object.

dag.utils.node_to_link(node: Any) → Any

Convert a legacy Node to a legacy Link.

Deprecated since version This: function is retained for backward compatibility only. Use the codec/block API instead.

dag.utils.string_to_cid(s: str) → CIDv0 | CIDv1

Parse a CID from a string.

Module contents

py-ipld-dag - IPLD DAG implementation for Python.

A lean, modern implementation of the IPLD (InterPlanetary Linked Data) data model and codecs for Python, aligned with the JS multiformats ecosystem.

Provides:

• IPLD Data Model - kinds, type helpers, CID integration

• Block API - Block.encode() / Block.decode() / Block.create()

• Codec interface - BlockCodec base class + codec registry

• Built-in codecs: - dag-cbor (0x71) - deterministic CBOR with CID links - dag-json (0x0129) - deterministic JSON with CID links - dag-pb (0x70) - Protobuf-based Merkle DAG (legacy IPFS) - raw (0x55) - identity codec for raw bytes

Usage:

from dag import Block
from dag.codecs import dag_cbor

# Encode
block = Block.encode(value={"hello": "world"}, codec=dag_cbor.codec)
print(block.cid)   # bafyr...
print(block.bytes)  # raw DAG-CBOR

# Decode
restored = Block.decode(data=block.bytes, codec=dag_cbor.codec)
assert restored.value == {"hello": "world"}

class dag.Block(*, cid: CIDv0 | CIDv1, data: bytes, value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1, codec: BlockCodec | None = None)

Bases: object

An immutable IPLD block: CID + bytes + value.

Use the class methods encode, decode, or create rather than calling __init__ directly.

property bytes: bytes

The raw encoded bytes.

property cid: CIDv0 | CIDv1

The content identifier for this block.

property codec: BlockCodec | None

The codec used to create this block (if known).

classmethod create(*, data: bytes, cid: CIDv0 | CIDv1, value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1, codec: BlockCodec | None = None) → Block

Create a Block from pre-computed parts.

No encoding, decoding, or hashing is performed.

classmethod decode(*, data: bytes, codec: BlockCodec | int, hasher: str = 'sha2-256', version: int = 1) → Block

Decode raw bytes into a Block.

Parameters

data:

The raw encoded bytes.

codec:

A BlockCodec instance or a multicodec code (int).

hasher:

Multihash algorithm name (default "sha2-256").

version:

CID version (default 1).

classmethod encode(*, value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1, codec: BlockCodec | int, hasher: str = 'sha2-256', version: int = 1) → Block

Encode an IPLD value into a new Block.

Parameters

value:

The IPLD data-model value to encode.

codec:

A BlockCodec instance or a multicodec code (int).

hasher:

Multihash algorithm name (default "sha2-256").

version:

CID version (default 1). Use 0 only for dag-pb with sha2-256.

get(path: str) → Any

Resolve a /-separated path into this block’s value.

Returns the value at that path, or raises KeyError / IndexError if the path is invalid.

links() → Iterator[tuple[str, CIDv0 | CIDv1]]

Yield (path, cid) for every CID link in this block’s value.

tree() → Iterator[str]

Yield every path segment in this block’s value (depth-first).

property value: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1

The decoded IPLD data-model value.

class dag.BlockCodec

Bases: BlockEncoder, BlockDecoder

A codec that can both encode and decode.

Concrete implementations should subclass this and provide name, code, encode, and decode.

class dag.BlockDecoder

Bases: ABC

Abstract decoder - turns bytes into an IPLD node.

abstract property code: int

Multicodec code.

abstract decode(data: bytes) → None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1

Decode bytes into an IPLD data model value.

abstract property name: str

Human-readable codec name.

class dag.BlockEncoder

Bases: ABC

Abstract encoder - turns an IPLD node into bytes.

abstract property code: int

Multicodec code (e.g. 0x71).

abstract encode(node: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1) → bytes

Encode an IPLD data model value into bytes.

abstract property name: str

Human-readable codec name (e.g. 'dag-cbor').

class dag.Kind(value)

Bases: Enum

IPLD Data Model kinds.

Every value in the IPLD Data Model belongs to exactly one kind.

BOOL = 'bool'

BYTES = 'bytes'

FLOAT = 'float'

INT = 'int'

LINK = 'link'

LIST = 'list'

MAP = 'map'

NULL = 'null'

STRING = 'string'

dag.get_codec(code: int) → BlockCodec

Look up a registered codec by its multicodec code.

Raises KeyError if no codec is registered for code.

dag.is_cid(value: Any) → bool

Return True if value is a CID (IPLD Link).

dag.is_ipld_value(value: Any) → bool

Return True if value is representable in the IPLD Data Model.

dag.kind_of(value: Any) → Kind

Return the IPLD Kind of value.

Raises TypeError if the value is not representable in the IPLD Data Model.

dag.lookup_codec(name_or_code: str | int) → BlockCodec

Look up a codec by name or code.

Raises KeyError if not found.

dag.register_codec(codec: BlockCodec) → None

Register a codec so it can be looked up by code.

dag.registered_codecs() → dict[int, BlockCodec]

Return a copy of all registered codecs.