add type stubs

Author: zzstoatzz

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"]
+
 [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]

pytests/test_cid.py

@@ -2,31 +2,37 @@
 
 
 def test_cid_decode_multibase() -> None:
-    cid = libipld.decode_cid('bafyreig7jbijxpn4lfhvnvyuwf5u5jyhd7begxwyiqe7ingwxycjdqjjoa')
-    assert 1 == cid['version']
-    assert 113 == cid['codec']
-    assert 18 == cid['hash']['code']
-    assert 32 == cid['hash']['size']
-    assert cid['hash']['size'] == len(cid['hash']['digest'])
+    cid = libipld.decode_cid(
+        "bafyreig7jbijxpn4lfhvnvyuwf5u5jyhd7begxwyiqe7ingwxycjdqjjoa"
+    )
+    assert 1 == cid["version"]
+    assert 113 == cid["codec"]
+    assert 18 == cid["hash"]["code"]
+    assert 32 == cid["hash"]["size"]
+    assert cid["hash"]["size"] == len(cid["hash"]["digest"])
 
 
 def test_cid_decode_raw() -> None:
-    cid = libipld.decode_cid(b'\x01q\x12 \xb6\x81\x1a\x1d\x7f\x8c\x17\x91\xdam\x1bO\x13m\xc0\xe2&y\xea\xfe\xaaX\xd6M~/\xaa\xd5\x89\x0e\x9d\x9c')
-    assert 1 == cid['version']
-    assert 113 == cid['codec']
-    assert 18 == cid['hash']['code']
-    assert 32 == cid['hash']['size']
-    assert cid['hash']['size'] == len(cid['hash']['digest'])
+    cid = libipld.decode_cid(
+        b"\x01q\x12 \xb6\x81\x1a\x1d\x7f\x8c\x17\x91\xdam\x1bO\x13m\xc0\xe2&y\xea\xfe\xaaX\xd6M~/\xaa\xd5\x89\x0e\x9d\x9c"
+    )
+    assert 1 == cid["version"]
+    assert 113 == cid["codec"]
+    assert 18 == cid["hash"]["code"]
+    assert 32 == cid["hash"]["size"]
+    assert cid["hash"]["size"] == len(cid["hash"]["digest"])
 
 
 def test_cid_encode_multibase() -> None:
-    cid = 'bafyreig7jbijxpn4lfhvnvyuwf5u5jyhd7begxwyiqe7ingwxycjdqjjoa'
+    cid = "bafyreig7jbijxpn4lfhvnvyuwf5u5jyhd7begxwyiqe7ingwxycjdqjjoa"
     assert cid == libipld.encode_cid(cid)  # because it's already encoded
 
 
 def test_cid_encode_raw() -> None:
-    raw_cid = b'\x01q\x12 \xb6\x81\x1a\x1d\x7f\x8c\x17\x91\xdam\x1bO\x13m\xc0\xe2&y\xea\xfe\xaaX\xd6M~/\xaa\xd5\x89\x0e\x9d\x9c'
-    expected_cid_multibase = 'bafyreifwqenb274mc6i5u3i3j4jw3qhcez46v7vkldle27rpvlkysdu5tq'
+    raw_cid = b"\x01q\x12 \xb6\x81\x1a\x1d\x7f\x8c\x17\x91\xdam\x1bO\x13m\xc0\xe2&y\xea\xfe\xaaX\xd6M~/\xaa\xd5\x89\x0e\x9d\x9c"
+    expected_cid_multibase = (
+        "bafyreifwqenb274mc6i5u3i3j4jw3qhcez46v7vkldle27rpvlkysdu5tq"
+    )
 
     cid = libipld.decode_cid(raw_cid)
     cid_multibase = libipld.encode_cid(raw_cid)
@@ -38,4 +44,4 @@ def test_cid_encode_raw() -> None:
     assert cid == cid2
 
     # manual encoding for CID v1:
-    assert expected_cid_multibase == libipld.encode_multibase('b', raw_cid)
+    assert expected_cid_multibase == libipld.encode_multibase("b", raw_cid)

python/libipld/__init__.py

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

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

@@ -0,0 +1,11 @@
+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: ...

python/libipld/_libipld.pyi

@@ -7,8 +7,8 @@ use ::libipld::cid::{Cid, Error as CidError, Result as CidResult, Version};
 use anyhow::{anyhow, Result};
 use byteorder::{BigEndian, ByteOrder};
 use multihash::Multihash;
-use pyo3::{ffi, prelude::*, types::*, BoundObject, PyObject, Python};
 use pyo3::pybacked::PyBackedStr;
+use pyo3::{ffi, prelude::*, types::*, BoundObject, PyObject, Python};
 
 fn cid_hash_to_pydict<'py>(py: Python<'py>, cid: &Cid) -> Bound<'py, PyDict> {
     let hash = cid.hash();
@@ -17,7 +17,7 @@ fn cid_hash_to_pydict<'py>(py: Python<'py>, cid: &Cid) -> Bound<'py, PyDict> {
     dict_obj.set_item("code", hash.code()).unwrap();
     dict_obj.set_item("size", hash.size()).unwrap();
     dict_obj
-        .set_item("digest", PyBytes::new(py, &hash.digest()))
+        .set_item("digest", PyBytes::new(py, hash.digest()))
         .unwrap();
 
     dict_obj
@@ -74,7 +74,7 @@ fn sort_map_keys(keys: &Bound<PyList>, len: usize) -> Vec<(PyBackedStr, usize)>
         if s1.len() != s2.len() {
             s1.len().cmp(&s2.len())
         } else {
-            s1.cmp(&s2)
+            s1.cmp(s2)
         }
     });
 
@@ -100,7 +100,8 @@ fn string_new_bound<'py>(py: Python<'py>, s: &[u8]) -> Bound<'py, PyString> {
     let ptr = s.as_ptr() as *const c_char;
     let len = s.len() as ffi::Py_ssize_t;
     unsafe {
-        Bound::from_owned_ptr(py, ffi::PyUnicode_FromStringAndSize(ptr, len)).downcast_into_unchecked()
+        Bound::from_owned_ptr(py, ffi::PyUnicode_FromStringAndSize(ptr, len))
+            .downcast_into_unchecked()
     }
 }
 
@@ -113,7 +114,8 @@ fn decode_dag_cbor_to_pyobject<R: Read + Seek>(
         if depth > ffi::Py_GetRecursionLimit() as usize {
             PyErr::new::<pyo3::exceptions::PyRecursionError, _>(
                 "RecursionError: maximum recursion depth exceeded in DAG-CBOR decoding",
-            ).restore(py);
+            )
+            .restore(py);
 
             return Err(anyhow!("Maximum recursion depth exceeded"));
         }
@@ -122,14 +124,20 @@ fn decode_dag_cbor_to_pyobject<R: Read + Seek>(
     let major = decode::read_major(r)?;
     Ok(match major.kind() {
         MajorKind::UnsignedInt => decode::read_uint(r, major)?.into_pyobject(py)?.into(),
-        MajorKind::NegativeInt => (-1 - decode::read_uint(r, major)? as i64).into_pyobject(py)?.into(),
+        MajorKind::NegativeInt => (-1 - decode::read_uint(r, major)? as i64)
+            .into_pyobject(py)?
+            .into(),
         MajorKind::ByteString => {
             let len = decode::read_uint(r, major)?;
-            PyBytes::new(py, &decode::read_bytes(r, len)?).into_pyobject(py)?.into()
+            PyBytes::new(py, &decode::read_bytes(r, len)?)
+                .into_pyobject(py)?
+                .into()
         }
         MajorKind::TextString => {
             let len = decode::read_uint(r, major)?;
-            string_new_bound(py, &decode::read_bytes(r, len)?).into_pyobject(py)?.into()
+            string_new_bound(py, &decode::read_bytes(r, len)?)
+                .into_pyobject(py)?
+                .into()
         }
         MajorKind::Array => {
             let len: ffi::Py_ssize_t = decode_len(decode::read_uint(r, major)?)?.try_into()?;
@@ -138,10 +146,15 @@ fn decode_dag_cbor_to_pyobject<R: Read + Seek>(
                 let ptr = ffi::PyList_New(len);
 
                 for i in 0..len {
-                    ffi::PyList_SET_ITEM(ptr, i, decode_dag_cbor_to_pyobject(py, r, depth + 1)?.into_ptr());
+                    ffi::PyList_SET_ITEM(
+                        ptr,
+                        i,
+                        decode_dag_cbor_to_pyobject(py, r, depth + 1)?.into_ptr(),
+                    );
                 }
 
-                let list: Bound<'_, PyList> = Bound::from_owned_ptr(py, ptr).downcast_into_unchecked();
+                let list: Bound<'_, PyList> =
+                    Bound::from_owned_ptr(py, ptr).downcast_into_unchecked();
                 list.into_pyobject(py)?.into()
             }
         }
@@ -199,7 +212,7 @@ fn decode_dag_cbor_to_pyobject<R: Read + Seek>(
 }
 
 fn encode_dag_cbor_from_pyobject<'py, W: Write>(
-    py: Python<'py>,
+    _py: Python<'py>,
     obj: &Bound<'py, PyAny>,
     w: &mut W,
 ) -> Result<()> {
@@ -246,7 +259,7 @@ fn encode_dag_cbor_from_pyobject<'py, W: Write>(
         encode::write_u64(w, MajorKind::Array, len as u64)?;
 
         for i in 0..len {
-            encode_dag_cbor_from_pyobject(py, &l.get_item(i)?, w)?;
+            encode_dag_cbor_from_pyobject(_py, &l.get_item(i)?, w)?;
         }
 
         Ok(())
@@ -262,7 +275,7 @@ fn encode_dag_cbor_from_pyobject<'py, W: Write>(
             encode::write_u64(w, MajorKind::TextString, key_buf.len() as u64)?;
             w.write_all(key_buf)?;
 
-            encode_dag_cbor_from_pyobject(py, &values.get_item(i)?, w)?;
+            encode_dag_cbor_from_pyobject(_py, &values.get_item(i)?, w)?;
         }
 
         Ok(())
@@ -280,7 +293,7 @@ fn encode_dag_cbor_from_pyobject<'py, W: Write>(
     } else if let Ok(b) = obj.downcast::<PyBytes>() {
         // FIXME (MarshalX): it's not efficient to try to parse it as CID
         let cid = Cid::try_from(b.as_bytes());
-        if let Ok(_) = cid {
+        if cid.is_ok() {
             let buf = b.as_bytes();
             let len = buf.len();
 
@@ -332,7 +345,7 @@ fn read_u64_leb128<R: Read>(r: &mut R) -> Result<u64> {
 
     loop {
         let mut buf = [0];
-        if let Err(_) = r.read_exact(&mut buf) {
+        if r.read_exact(&mut buf).is_err() {
             return Err(anyhow!("Unexpected EOF while reading ULEB128 number."));
         }
 
@@ -377,7 +390,7 @@ fn read_cid_from_bytes<R: Read>(r: &mut R) -> CidResult<Cid> {
 pub fn decode_car<'py>(py: Python<'py>, data: &[u8]) -> PyResult<(PyObject, Bound<'py, PyDict>)> {
     let buf = &mut BufReader::new(Cursor::new(data));
 
-    if let Err(_) = read_u64_leb128(buf) {
+    if read_u64_leb128(buf).is_err() {
         return Err(get_err(
             "Failed to read CAR header",
             "Invalid uvarint".to_string(),
@@ -423,7 +436,7 @@ pub fn decode_car<'py>(py: Python<'py>, data: &[u8]) -> PyResult<(PyObject, Boun
     let parsed_blocks = PyDict::new(py);
 
     loop {
-        if let Err(_) = read_u64_leb128(buf) {
+        if read_u64_leb128(buf).is_err() {
             // FIXME (MarshalX): we are not raising an error here because of possible EOF
             break;
         }
@@ -472,7 +485,7 @@ pub fn decode_dag_cbor(py: Python, data: &[u8]) -> PyResult<PyObject> {
 
         if let Some(py_err) = PyErr::take(py) {
             py_err.set_cause(py, Option::from(err));
-            // in case something set global interpreter’s error,
+            // in case something set global interpreter's error,
             // for example C FFI function, we should return it
             // the real case: RecursionError (set by Py_EnterRecursiveCall)
             Err(py_err)
@@ -494,9 +507,10 @@ pub fn encode_dag_cbor<'py>(
     if let Err(e) = buf.flush() {
         return Err(get_err("Failed to flush buffer", e.to_string()));
     }
-    Ok(PyBytes::new(py, &buf.get_ref()))
+    Ok(PyBytes::new(py, buf.get_ref()))
 }
 
+#[allow(clippy::extra_unused_lifetimes)]
 fn get_cid_from_py_any<'py>(data: &Bound<PyAny>) -> PyResult<Cid> {
     let cid: CidResult<Cid>;
     if let Ok(s) = data.downcast::<PyString>() {
@@ -522,7 +536,10 @@ fn decode_cid<'py>(py: Python<'py>, data: &Bound<PyAny>) -> PyResult<Bound<'py,
 
 #[pyfunction]
 fn encode_cid<'py>(py: Python<'py>, data: &Bound<PyAny>) -> PyResult<Bound<'py, PyString>> {
-    Ok(PyString::new(py, get_cid_from_py_any(data)?.to_string().as_str()))
+    Ok(PyString::new(
+        py,
+        get_cid_from_py_any(data)?.to_string().as_str(),
+    ))
 }
 
 #[pyfunction]
@@ -557,6 +574,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)?)?;