add type stubs

.gitignore

@@ -28,3 +28,6 @@ test.py
 __pycache__
 .benchmarks
 .pytest_cache
+
+# Build artifacts
+*.so

pyproject.toml

@@ -37,13 +37,19 @@ classifiers = [
 "Tracker" = "https://github.com/MarshalX/python-libipld/issues"
 "Author" = "https://github.com/MarshalX"
 
+[dependency-groups]
+dev = ["maturin", "pytest", "pytest-benchmark"]
+
 [tool.pytest.ini_options]
 addopts = [
     '--benchmark-columns', 'min,mean,stddev,outliers,rounds,iterations',
     '--benchmark-disable',  # use --benchmark-enable
 ]
 
 [tool.maturin]
+python-source = "python"
+module-name = "libipld._libipld"
+bindings = "pyo3"
 features = ["pyo3/extension-module"]
 
 [build-system]

python/libipld/__init__.py

@@ -0,0 +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.pyi

@@ -0,0 +1,95 @@
+from __future__ import annotations
+from typing import Any
+
+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
+    """

src/lib.rs

@@ -557,6 +557,7 @@ fn get_err(msg: &str, err: String) -> PyErr {
 }
 
 #[pymodule]
+#[pyo3(name = "_libipld")]
 fn libipld(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(decode_cid, m)?)?;
     m.add_function(wrap_pyfunction!(encode_cid, m)?)?;