From f5af7ec3d9554c35f72ed42be6719f49438201c2 Mon Sep 17 00:00:00 2001
From: stefan <mail@s-holst.de>
Date: Sat, 27 Jun 2026 11:26:23 +0900
Subject: [PATCH] typing and docs for interpret, mvarray

---
 src/kyupy/__init__.py |  2 ++
 src/kyupy/circuit.py  |  3 +--
 src/kyupy/logic.py    | 11 ++++++-----
 3 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/kyupy/__init__.py b/src/kyupy/__init__.py
index b4076e7..dd56e2e 100644
--- a/src/kyupy/__init__.py
+++ b/src/kyupy/__init__.py
@@ -12,6 +12,8 @@ import gzip
 
 import numpy as np
 
+type NestedNumericList = list['int|NestedNumericList']
+type NestedStrIntDict = dict[str,'int|NestedStrIntDict']
 
 _pop_count_lut = np.asarray([bin(x).count('1') for x in range(256)])
 
diff --git a/src/kyupy/circuit.py b/src/kyupy/circuit.py
index 11ef657..2761c27 100644
--- a/src/kyupy/circuit.py
+++ b/src/kyupy/circuit.py
@@ -17,8 +17,7 @@ import re
 
 import numpy as np
 
-type NestedNumericList = list['int|NestedNumericList']
-type NestedStrIntDict = dict[str,'int|NestedStrIntDict']
+from . import NestedNumericList, NestedStrIntDict
 
 class GrowingList[T](list[T]):
     def __setitem__(self, index, value):
diff --git a/src/kyupy/logic.py b/src/kyupy/logic.py
index 644189e..6dcf2ab 100644
--- a/src/kyupy/logic.py
+++ b/src/kyupy/logic.py
@@ -49,7 +49,7 @@ from collections.abc import Iterable
 import numpy as np
 from numpy.typing import DTypeLike
 
-from . import numba, hr_bytes
+from . import numba, hr_bytes, NestedNumericList
 
 
 ZERO = 0b000
@@ -104,7 +104,7 @@ _mv_merge = np.array([[0,0,0,1,1,1,1,1], # 0
                       ], dtype=np.uint8)
 
 
-def interpret(value):
+def interpret(value) -> int|NestedNumericList:
     """Converts characters, strings, and lists of them to lists of logic constants defined above.
 
     :param value: A character (string of length 1), Boolean, Integer, None, or Iterable.
@@ -123,11 +123,12 @@ def interpret(value):
     return UNKNOWN
 
 
-def mvarray(*a):
+def mvarray(*a) -> np.ndarray[tuple[int]|tuple[int,int],np.dtype[np.uint8]]:
     """Converts (lists of) Boolean values or strings into a multi-valued array.
 
-    The given values are interpreted and the axes are arranged as per KyuPy's convention.
-    Use this function to convert strings into multi-valued arrays.
+    Iterable over characters, Booleans, Integers (0,1), None are interpreted as a single pattern.
+    Multi-character strings are Iterables over characters and are interpreted as a single pattern.
+    Lists of said patterns form a pattern set as ndarray with the axes are arranged as per KyuPy's convention.
     """
     mva = np.array(interpret(a), dtype=np.uint8)
     if mva.ndim < 2: return mva