fix a couple stubs

Author: zzstoatzz

pyproject.toml

@@ -2,13 +2,24 @@
 name = "libipld"
 dynamic = ["version"]
 description = "Python binding to the Rust IPLD library"
-authors = [
-    {name = "Ilya (Marshal)", email = "ilya@marshal.dev"}
-]
+authors = [{ name = "Ilya (Marshal)", email = "ilya@marshal.dev" }]
 license = "MIT"
 repository = "https://github.com/MarshalX/python-libipld"
 readme = "README.md"
-keywords = ["library", "lib", "ipld", "cid", "multibase", "multihash", "dag", "cbor", "json", "pb", "dag-cbor", "dag-json"]
+keywords = [
+    "library",
+    "lib",
+    "ipld",
+    "cid",
+    "multibase",
+    "multihash",
+    "dag",
+    "cbor",
+    "json",
+    "pb",
+    "dag-cbor",
+    "dag-json",
+]
 requires-python = ">=3.8"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -38,12 +49,13 @@ classifiers = [
 "Author" = "https://github.com/MarshalX"
 
 [dependency-groups]
-dev = ["maturin", "pytest"]
+dev = ["maturin", "pytest", "pytest-benchmark"]
 
 [tool.pytest.ini_options]
 addopts = [
-    '--benchmark-columns', 'min,mean,stddev,outliers,rounds,iterations',
-    '--benchmark-disable',  # use --benchmark-enable
+    '--benchmark-columns',
+    'min,mean,stddev,outliers,rounds,iterations',
+    '--benchmark-disable',                        # use --benchmark-enable
 ]
 
 [tool.maturin]

pytests/test_decode_car.py

@@ -2,24 +2,27 @@
 
 import libipld
 import pytest
+from pytest_benchmark.fixture import BenchmarkFixture
 
 from conftest import load_car_fixture
 
-_DID = os.environ.get('CAR_REPO_DID', 'did:plc:w4es6sfh43zlht3bgrzi5qzq')  # default is public bot in bsky.app
-_REPO_CAR_PATH = os.path.join(os.path.dirname(__file__), '..', 'data', 'repo.car')
+_DID = os.environ.get(
+    "CAR_REPO_DID", "did:plc:w4es6sfh43zlht3bgrzi5qzq"
+)  # default is public bot in bsky.app
+_REPO_CAR_PATH = os.path.join(os.path.dirname(__file__), "..", "data", "repo.car")
 
 
-@pytest.fixture(scope='session')
+@pytest.fixture(scope="session")
 def car() -> bytes:
     return load_car_fixture(_DID, _REPO_CAR_PATH)
 
 
-def test_decode_car(benchmark, car) -> None:
+def test_decode_car(benchmark: BenchmarkFixture, car: bytes) -> None:
     header, blocks = benchmark(libipld.decode_car, car)
 
-    assert 1 == header['version']
-    assert isinstance(header['roots'], list)
-    assert 1 == len(header['roots'])
+    assert 1 == header["version"]
+    assert isinstance(header["roots"], list)
+    assert 1 == len(header["roots"])
 
     assert isinstance(blocks, dict)
     assert all(isinstance(k, bytes) for k in blocks.keys())
@@ -30,71 +33,71 @@ def test_decode_car(benchmark, car) -> None:
 
 def test_decode_car_invalid_header_len() -> None:
     with pytest.raises(ValueError) as exc_info:
-        libipld.decode_car(b'')
+        libipld.decode_car(b"")
 
-    assert 'Invalid uvarint' in str(exc_info.value)
+    assert "Invalid uvarint" in str(exc_info.value)
 
 
 def test_decode_car_invalid_header_type() -> None:
     with pytest.raises(TypeError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor('strInsteadOfObj')
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor("strInsteadOfObj")
         libipld.decode_car(header_len + header_obj)
 
     assert "cannot be converted to 'PyDict'" in str(exc_info.value)
 
 
 def test_decode_car_invalid_header_version_key() -> None:
     with pytest.raises(ValueError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor({'blabla': 'blabla'})
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor({"blabla": "blabla"})
         libipld.decode_car(header_len + header_obj)
 
-    assert 'Version is None' in str(exc_info.value)
+    assert "Version is None" in str(exc_info.value)
 
 
 def test_decode_car_invalid_header_version_value() -> None:
     with pytest.raises(ValueError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor({'version': 2})
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor({"version": 2})
         libipld.decode_car(header_len + header_obj)
 
-    assert 'Version must be 1' in str(exc_info.value)
+    assert "Version must be 1" in str(exc_info.value)
 
 
 def test_decode_car_invalid_header_roots_key() -> None:
     with pytest.raises(ValueError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor({'version': 1})
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor({"version": 1})
         libipld.decode_car(header_len + header_obj)
 
-    assert 'Roots is None' in str(exc_info.value)
+    assert "Roots is None" in str(exc_info.value)
 
 
 def test_decode_car_invalid_header_roots_value_type() -> None:
     with pytest.raises(TypeError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor({'version': 1, 'roots': 123})
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor({"version": 1, "roots": 123})
         libipld.decode_car(header_len + header_obj)
 
     assert "cannot be converted to 'PyList'" in str(exc_info.value)
 
 
 def test_decode_car_invalid_header_roots_value_empty_list() -> None:
     with pytest.raises(ValueError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor({'version': 1, 'roots': []})
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor({"version": 1, "roots": []})
         libipld.decode_car(header_len + header_obj)
 
-    assert 'Roots is empty' in str(exc_info.value)
+    assert "Roots is empty" in str(exc_info.value)
 
 
 def test_decode_car_invalid_block_cid() -> None:
     with pytest.raises(ValueError) as exc_info:
-        header_len = bytes.fromhex('33')  # 3
-        header_obj = libipld.encode_dag_cbor({'version': 1, 'roots': ['blabla']})
-        block1 = bytes.fromhex('33') + b'invalidSid'
+        header_len = bytes.fromhex("33")  # 3
+        header_obj = libipld.encode_dag_cbor({"version": 1, "roots": ["blabla"]})
+        block1 = bytes.fromhex("33") + b"invalidSid"
 
         libipld.decode_car(header_len + header_obj + block1)
 
-    assert 'Failed to read CID of block' in str(exc_info.value)
+    assert "Failed to read CID of block" in str(exc_info.value)

python/libipld/__init__.py

@@ -1,15 +1,21 @@
 from ._libipld import (
     decode_cid,
     encode_cid,
+    encode_dag_cbor,
     decode_car,
     decode_dag_cbor,
     decode_dag_cbor_multi,
+    decode_multibase,
+    encode_multibase,
 )
 
 __all__ = [
     "decode_cid",
     "encode_cid",
+    "encode_dag_cbor",
     "decode_car",
     "decode_dag_cbor",
     "decode_dag_cbor_multi",
+    "decode_multibase",
+    "encode_multibase",
 ]

python/libipld/_libipld.cpython-313-darwin.so

@@ -1,11 +1,95 @@
 from __future__ import annotations
 from typing import Any
 
-def decode_cid(data: str | bytes) -> dict[str, Any]: ...
-def encode_cid(data: bytes) -> str: ...
-def decode_car(data: bytes) -> tuple[dict[str, Any], dict[bytes, dict[str, Any]]]: ...
-def decode_dag_cbor(data: bytes) -> dict[str, Any]: ...
-def decode_dag_cbor_multi(data: bytes) -> list[dict[str, Any]]: ...
-def encode_dag_cbor(data: dict[str, Any]) -> bytes: ...
-def decode_multibase(data: str) -> tuple[str, bytes]: ...
-def encode_multibase(code: str, data: str | bytes) -> str: ...
+def decode_cid(data: str | bytes) -> dict[str, Any]:
+    """Decode a CID from either its string representation or raw bytes.
+
+    Args:
+        data: Either a CID string (e.g. 'bafy...') or raw CID bytes
+
+    Returns:
+        A dict containing:
+        - version: int (0 or 1)
+        - codec: int (e.g. 113 for DAG-CBOR)
+        - hash: dict containing:
+            - code: int (hash algorithm code)
+            - size: int (hash size in bytes)
+            - digest: bytes (hash digest)
+    """
+
+def encode_cid(data: str | bytes) -> str:
+    """Encode a CID to its string representation.
+
+    Args:
+        data: Either a CID string (will be returned as-is) or raw CID bytes
+
+    Returns:
+        A CID string (e.g. 'bafy...')
+    """
+
+def decode_car(data: bytes) -> tuple[dict[str, Any], dict[bytes, dict[str, Any]]]:
+    """Decode a CAR file.
+
+    Args:
+        data: Raw CAR file bytes
+
+    Returns:
+        A tuple containing:
+        - header: dict (CAR header)
+        - blocks: dict mapping CID bytes to block data
+    """
+
+def decode_dag_cbor(data: bytes) -> Any:
+    """Decode DAG-CBOR data to Python objects.
+
+    Args:
+        data: Raw DAG-CBOR bytes
+
+    Returns:
+        A Python object (dict, list, str, bytes, int, float, bool, or None)
+    """
+
+def decode_dag_cbor_multi(data: bytes) -> list[Any]:
+    """Decode multiple DAG-CBOR objects from bytes.
+
+    Args:
+        data: Raw DAG-CBOR bytes containing multiple objects
+
+    Returns:
+        A list of Python objects
+    """
+
+def encode_dag_cbor(data: Any) -> bytes:
+    """Encode Python objects to DAG-CBOR.
+
+    Args:
+        data: Any Python object that can be encoded to DAG-CBOR
+              (dict, list, str, bytes, int, float, bool, or None)
+
+    Returns:
+        Raw DAG-CBOR bytes
+    """
+
+def decode_multibase(data: str) -> tuple[str, bytes]:
+    """Decode multibase-encoded data.
+
+    Args:
+        data: Multibase-encoded string (e.g. 'u' for base58btc)
+
+    Returns:
+        A tuple containing:
+        - base: str (the base code, e.g. 'u')
+        - data: bytes (the decoded data)
+    """
+
+def encode_multibase(code: str, data: Any) -> str:
+    """Encode data using multibase.
+
+    Args:
+        code: str (base code, e.g. 'u' for base58btc)
+        data: Any Python object that can be converted to bytes
+              (str, bytes, bytearray, or other objects that can be converted to bytes)
+
+    Returns:
+        Multibase-encoded string
+    """