feat(core): Support List|Dict.py() (#55)

This PR introduces `List.py()` and `Dict.py()` which supports
recursively converting MLC's list/dict back to Python's native list/dict

Author: potatomashed

python/mlc/_cython/__init__.py

@@ -26,6 +26,7 @@
     dtype_normalize,
 )
 from .core import (  # type: ignore[import-not-found]
+    container_to_py,
     device_as_pair,
     dtype_as_triple,
     dtype_from_triple,

python/mlc/_cython/core.pyx

@@ -1418,6 +1418,18 @@ cpdef void tensor_init(PyAny self, object value):
     self._mlc_any = ret._mlc_any
     ret._mlc_any = _MLCAnyNone()
 
+cpdef object container_to_py(object self):
+    from mlc.core.list import List as mlc_list
+    from mlc.core.dict import Dict as mlc_dict
+
+    if isinstance(self, mlc_list):
+        return [container_to_py(v) for v in self]
+    if isinstance(self, mlc_dict):
+        return {container_to_py(k): container_to_py(v) for k, v in self.items()}
+    if isinstance(self, Str):
+        return str(self)
+    return self
+
 cpdef object tensor_data(PyAny self):
     cdef DLTensor* tensor = _pyany_to_dl_tensor(self)
     cdef void* data = tensor[0].data

python/mlc/core/dict.py

@@ -5,7 +5,7 @@
 from collections.abc import ItemsView, Iterable, Iterator, KeysView, Mapping, ValuesView
 from typing import Any, TypeVar, overload
 
-from mlc._cython import MetaNoSlots, Ptr, c_class_core
+from mlc._cython import MetaNoSlots, Ptr, c_class_core, container_to_py
 
 from .object import Object
 
@@ -134,6 +134,9 @@ def __eq__(self, other: Any) -> bool:
     def __ne__(self, other: Any) -> bool:
         return not (self == other)
 
+    def py(self) -> dict[K, V]:
+        return container_to_py(self)
+
 
 class _DictKeysView(KeysView[K]):
     def __init__(self, mapping: Dict[K, V]) -> None:

python/mlc/core/list.py

@@ -4,7 +4,7 @@
 from collections.abc import Iterable, Iterator, Sequence
 from typing import Any, TypeVar, overload
 
-from mlc._cython import MetaNoSlots, Ptr, c_class_core
+from mlc._cython import MetaNoSlots, Ptr, c_class_core, container_to_py
 
 from .object import Object
 
@@ -100,6 +100,9 @@ def __ne__(self, other: Any) -> bool:
     def __delitem__(self, i: int) -> None:
         self.pop(i)
 
+    def py(self) -> list[T]:
+        return container_to_py(self)
+
 
 def _normalize_index(i: int, length: int) -> int:
     if not -length <= i < length:

tests/python/test_core_dict.py

@@ -104,3 +104,32 @@ def test_dict_ne_1() -> None:
     b = {i: i * i for i in range(1, 5)}
     assert a != b
     assert b != a
+
+
+def test_dict_to_py_0() -> None:
+    a = Dict({i: i * i for i in range(1, 5)}).py()
+    assert isinstance(a, dict)
+    assert len(a) == 4
+    assert isinstance(a[1], int) and a[1] == 1
+    assert isinstance(a[2], int) and a[2] == 4
+    assert isinstance(a[3], int) and a[3] == 9
+    assert isinstance(a[4], int) and a[4] == 16
+
+
+def test_dict_to_py_1() -> None:
+    a = Dict(
+        {
+            "a": {
+                "b": [2],
+                "c": 3.0,
+            },
+            1: "one",
+            None: "e",
+        }
+    ).py()
+    assert len(a) == 3 and set(a.keys()) == {"a", 1, None}
+    assert isinstance(a["a"], dict) and len(a["a"]) == 2
+    assert isinstance(a["a"]["b"], list) and len(a["a"]["b"]) == 1 and a["a"]["b"][0] == 2
+    assert isinstance(a["a"]["c"], float) and a["a"]["c"] == 3.0
+    assert isinstance(a[1], str) and a[1] == "one"
+    assert isinstance(a[None], str) and a[None] == "e"

tests/python/test_core_list.py

@@ -229,3 +229,28 @@ def test_list_delitem_out_of_by(seq: list[int], i: int) -> None:
     with pytest.raises(IndexError) as e:
         del a[i]
     assert str(e.value) == f"list index out of range: {i}"
+
+
+def test_list_to_py_0() -> None:
+    a = List([1, 2, 3]).py()
+    assert isinstance(a, list)
+
+
+def test_list_to_py_1() -> None:
+    a = List([{"a": 1}, ["b"], 1, 2.0, "anything"]).py()
+    assert isinstance(a, list)
+    assert len(a) == 5
+    assert isinstance(a[0], dict)
+    assert isinstance(a[1], list)
+    assert isinstance(a[2], int)
+    assert isinstance(a[3], float)
+    assert isinstance(a[4], str)
+    assert isinstance(a[0], dict)
+    # make sure those types are exactly Python's `str`, `int`, `float`
+    assert len(a[0]) == 1 and isinstance(a[0], dict)
+    assert a[0]["a"] == 1 and type(next(a[0].__iter__())) is str
+    assert len(a[1]) == 1 and isinstance(a[1], list)
+    assert a[1][0] == "b" and type(a[1][0]) is str
+    assert a[2] == 1 and type(a[2]) is int
+    assert a[3] == 2.0 and type(a[3]) is float
+    assert a[4] == "anything" and type(a[4]) is str