sonolus.py 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

sonolus/build/level.py

@@ -1,16 +1,16 @@
-from sonolus.build.engine import package_output
+from sonolus.build.engine import JsonValue, package_output
 from sonolus.script.level import LevelData
 
 
 def package_level_data(
     level_data: LevelData,
-):
+) -> bytes:
     return package_output(build_level_data(level_data))
 
 
 def build_level_data(
     level_data: LevelData,
-):
+) -> JsonValue:
     level_refs = {entity: f"{i}_{entity.name}" for i, entity in enumerate(level_data.entities)}
     return {
         "bgmOffset": level_data.bgm_offset,

sonolus/build/project.py

@@ -17,7 +17,7 @@ BLANK_AUDIO = (
 )
 
 
-def build_project_to_collection(project: Project, config: BuildConfig):
+def build_project_to_collection(project: Project, config: BuildConfig | None):
     collection = load_resources_files_to_collection(project.resources)
     add_engine_to_collection(collection, project, project.engine, config)
     for level in project.levels:
@@ -26,7 +26,7 @@ def build_project_to_collection(project: Project, config: BuildConfig):
     return collection
 
 
-def add_engine_to_collection(collection: Collection, project: Project, engine: Engine, config: BuildConfig):
+def add_engine_to_collection(collection: Collection, project: Project, engine: Engine, config: BuildConfig | None):
     packaged_engine = package_engine(engine.data, config)
     item = {
         "name": engine.name,

sonolus/script/archetype.py

@@ -1,3 +1,4 @@
+# type: ignore
 from __future__ import annotations
 
 import inspect
@@ -117,7 +118,7 @@ class _ArchetypeField(SonolusDescriptor):
         if result is None:
             raise RuntimeError("Invalid storage type")
         if ctx():
-            return result._get_()
+            return result._get_readonly_()
         else:
             return result._as_py_()
 
@@ -312,7 +313,7 @@ class StandardImport:
 def callback[T: Callable](*, order: int = 0) -> Callable[[T], T]:
     """Annotate a callback with its order.
 
-    Callbacks are execute from lowest to highest order. By default, callbacks have an order of 0.
+    Callbacks are executed from lowest to highest order. By default, callbacks have an order of 0.
 
     Usage:
         ```python
@@ -327,7 +328,7 @@ def callback[T: Callable](*, order: int = 0) -> Callable[[T], T]:
     """
 
     def decorator(func: T) -> T:
-        func._callback_order_ = order
+        func._callback_order_ = order  # type: ignore
         return func
 
     return decorator
@@ -338,9 +339,9 @@ class _ArchetypeSelfData:
 
 
 class _ArchetypeReferenceData:
-    index: Num
+    index: int
 
-    def __init__(self, index: Num):
+    def __init__(self, index: int):
         self.index = index
 
 
@@ -416,21 +417,21 @@ class _BaseArchetype:
 
     @classmethod
     @meta_fn
-    def at(cls, index: Num) -> Self:
+    def at(cls, index: int) -> Self:
         result = cls._new()
         result._data_ = _ArchetypeReferenceData(index=Num._accept_(index))
         return result
 
     @classmethod
     @meta_fn
-    def is_at(cls, index: Num) -> bool:
+    def is_at(cls, index: int) -> bool:
         if not ctx():
             raise RuntimeError("is_at is only available during compilation")
         return entity_info_at(index).archetype_id == cls.id()
 
     @classmethod
     @meta_fn
-    def id(cls):
+    def id(cls) -> int:
         if not ctx():
             raise RuntimeError("Archetype id is only available during compilation")
         result = ctx().global_state.archetypes.get(cls)
@@ -635,11 +636,11 @@ class _BaseArchetype:
         """
         match self._data_:
             case _ArchetypeSelfData():
-                return EntityRef[type(self)](index=self.index)
+                return EntityRef[type(self)](index=self.index)  # type: ignore
             case _ArchetypeReferenceData(index=index):
-                return EntityRef[type(self)](index=index)
+                return EntityRef[type(self)](index=index)  # type: ignore
             case _ArchetypeLevelData():
-                result = EntityRef[type(self)](index=-1)
+                result = EntityRef[type(self)](index=-1)  # type: ignore
                 result._ref_ = self
                 return result
             case _:
@@ -992,7 +993,7 @@ class PreviewArchetype(_BaseArchetype):
 
 
 @meta_fn
-def entity_info_at(index: Num) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
+def entity_info_at(index: int) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
     """Retrieve entity info of the entity at the given index.
 
     Available in play, watch, and preview mode.
@@ -1016,8 +1017,8 @@ def archetype_life_of(archetype: type[_BaseArchetype] | _BaseArchetype) -> Arche
 
     Available in play and watch mode.
     """
-    archetype = validate_value(archetype)
-    archetype = archetype._as_py_()
+    archetype = validate_value(archetype)  # type: ignore
+    archetype = archetype._as_py_()  # type: ignore
     if not ctx():
         raise RuntimeError("Calling archetype_life_of is only allowed within a callback")
     match ctx().global_state.mode:
@@ -1047,24 +1048,24 @@ class PreviewEntityInfo(Record):
 class ArchetypeLife(Record):
     """How an entity contributes to life."""
 
-    perfect_increment: Num
+    perfect_increment: int
     """Life increment for a perfect judgment."""
 
-    great_increment: Num
+    great_increment: int
     """Life increment for a great judgment."""
 
-    good_increment: Num
+    good_increment: int
     """Life increment for a good judgment."""
 
-    miss_increment: Num
+    miss_increment: int
     """Life increment for a miss judgment."""
 
     def update(
         self,
-        perfect_increment: Num | None = None,
-        great_increment: Num | None = None,
-        good_increment: Num | None = None,
-        miss_increment: Num | None = None,
+        perfect_increment: int | None = None,
+        great_increment: int | None = None,
+        good_increment: int | None = None,
+        miss_increment: int | None = None,
     ):
         """Update the life increments."""
         if perfect_increment is not None:
@@ -1110,7 +1111,7 @@ class EntityRef[A: _BaseArchetype](Record):
         """Get the archetype type."""
         return cls.type_var_value(A)
 
-    def with_archetype(self, archetype: type[A]) -> EntityRef[A]:
+    def with_archetype[T: _BaseArchetype](self, archetype: type[T]) -> EntityRef[T]:
         """Return a new reference with the given archetype type."""
         return EntityRef[archetype](index=self.index)
 
@@ -1137,11 +1138,13 @@ class EntityRef[A: _BaseArchetype](Record):
         if ref is None:
             return Num._accept_(self.index)._to_list_()
         else:
+            if level_refs is None:
+                raise RuntimeError("Unexpected missing level_refs")
             if ref not in level_refs:
                 raise KeyError("Reference to entity not in level data")
             return [level_refs[ref]]
 
-    def _copy_from_(self, value: Self):
+    def _copy_from_(self, value: Any):
         super()._copy_from_(value)
         if hasattr(value, "_ref_"):
             self._ref_ = value._ref_

sonolus/script/array.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+from abc import ABCMeta
 from collections.abc import Iterable
-from typing import Any, Self, final
+from typing import Any, Literal, Self, final
 
 from sonolus.backend.ir import IRConst, IRSet
 from sonolus.backend.place import BlockPlace
@@ -14,8 +15,11 @@ from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.internal.value import BackingSource, DataValue, Value
 from sonolus.script.num import Num
 
+Dim = Literal
+"""Shorthand for `Literal` intended for use in array dimensions for type checker compatibility."""
 
-class ArrayMeta(type):
+
+class ArrayMeta(ABCMeta):
     @meta_fn
     def __pos__[T](cls: type[T]) -> T:
         """Create a zero-initialized array instance."""
@@ -31,6 +35,8 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         array_1 = Array(1, 2, 3)
         array_2 = Array[int, 0]()
         array_3 = +Array[int, 3]  # Create a zero-initialized array
+        array_4 = +Array[int, Dim[3]]  # Alternative syntax for compliance with type checkers
+        array_5 = +array_1  # Create a copy of array_1
         ```
     """
 
@@ -77,7 +83,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         super().__init__()
 
     @classmethod
-    def _with_value(cls, value) -> Self:
+    def _with_value(cls, value) -> Array[T, Size]:
         result = object.__new__(cls)
         result._value = value
         return result
@@ -91,11 +97,11 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return False
 
     @classmethod
-    def _from_backing_source_(cls, source: BackingSource) -> Self:
+    def _from_backing_source_(cls, source: BackingSource) -> Array[T, Size]:
         return cls._with_value(source)
 
     @classmethod
-    def _from_place_(cls, place: BlockPlace) -> Self:
+    def _from_place_(cls, place: BlockPlace) -> Array[T, Size]:
         return cls._with_value(place)
 
     @classmethod
@@ -103,7 +109,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return isinstance(value, cls)
 
     @classmethod
-    def _accept_(cls, value: Any) -> Self:
+    def _accept_(cls, value: Any) -> Array[T, Size]:
         if not cls._accepts_(value):
             raise TypeError(f"Cannot accept value {value} as {cls.__name__}")
         return value
@@ -117,7 +123,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return self
 
     @classmethod
-    def _from_list_(cls, values: Iterable[DataValue]) -> Self:
+    def _from_list_(cls, values: Iterable[DataValue]) -> Array[T, Size]:
         iterator = iter(values)
         return cls(*(cls.element_type()._from_list_(iterator) for _ in range(cls.size())))
 
@@ -142,19 +148,19 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
     def _flat_keys_(cls, prefix: str) -> list[str]:
         return [entry for i in range(cls.size()) for entry in cls.element_type()._flat_keys_(f"{prefix}[{i}]")]
 
-    def _get_(self) -> Self:
+    def _get_(self) -> Array[T, Size]:
         return self
 
-    def _set_(self, value: Self):
+    def _set_(self, value: Any):
         raise TypeError("Array does not support _set_")
 
-    def _copy_from_(self, value: Self):
+    def _copy_from_(self, value: Any):
         if not isinstance(value, type(self)):
             raise TypeError("Cannot copy from different type")
         for i in range(self.size()):
             self[i] = value[i]
 
-    def _copy_(self) -> Self:
+    def _copy_(self) -> Array[T, Size]:
         if ctx():
             place = ctx().alloc(size=self._size_())
             result: Self = self._from_place_(place)
@@ -165,7 +171,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             return self._with_value([value._copy_() for value in self._value])
 
     @classmethod
-    def _alloc_(cls) -> Self:
+    def _alloc_(cls) -> Array[T, Size]:
         if ctx():
             place = ctx().alloc(size=cls._size_())
             return cls._from_place_(place)
@@ -173,7 +179,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             return cls._with_value([cls.element_type()._alloc_() for _ in range(cls.size())])
 
     @classmethod
-    def _zero_(cls) -> Self:
+    def _zero_(cls) -> Array[T, Size]:
         if ctx():
             place = ctx().alloc(size=cls._size_())
             result: Self = cls._from_place_(place)
@@ -186,7 +192,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         return self.size()
 
     @meta_fn
-    def __getitem__(self, index: Num) -> T:
+    def __getitem__(self, index: int) -> T:
         index: Num = Num._accept_(get_positive_index(index, self.size()))
         if index._is_py_() and 0 <= index._as_py_() < self.size():
             const_index = index._as_py_()
@@ -206,7 +212,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
                 )
             elif callable(self._value):
                 return self.element_type()._from_backing_source_(
-                    lambda offset: self._value((Num(offset) + Num(const_index * self.element_type()._size_())).ir())
+                    lambda offset: self._value((Num(offset) + Num(const_index * self.element_type()._size_())).ir())  # type: ignore
                 )
             else:
                 raise InternalError("Unexpected array value")
@@ -224,13 +230,13 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             elif callable(self._value):
                 base_offset = index * Num(self.element_type()._size_())
                 return self.element_type()._from_backing_source_(
-                    lambda offset: self._value((Num(offset) + base_offset).ir())
+                    lambda offset: self._value((Num(offset) + base_offset).ir())  # type: ignore
                 )
             else:
                 raise InternalError("Unexpected array value")
 
     @meta_fn
-    def __setitem__(self, index: Num, value: T):
+    def __setitem__(self, index: int, value: T):
         index: Num = Num._accept_(get_positive_index(index, self.size()))
         value = self.element_type()._accept_(value)
         if ctx():
@@ -251,7 +257,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             elif callable(self._value):
                 base_offset = index * Num(self.element_type()._size_())
                 dst = self.element_type()._from_backing_source_(
-                    lambda offset: self._value((Num(offset) + base_offset).ir())
+                    lambda offset: self._value((Num(offset) + base_offset).ir())  # type: ignore
                 )
             else:
                 raise InternalError("Unexpected array value")
@@ -305,6 +311,6 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
             return f"{type(self).__name__}({', '.join(repr(self[i]) for i in range(self.size()))})"
 
     @meta_fn
-    def __pos__(self) -> Self:
+    def __pos__(self) -> Array[T, Size]:
         """Return a copy of the array."""
         return self._copy_()

sonolus/script/array_like.py

@@ -2,12 +2,13 @@ from __future__ import annotations
 
 import random
 from abc import abstractmethod
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from typing import Any
 
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn
 from sonolus.script.iterator import SonolusIterator
+from sonolus.script.maybe import Maybe, Nothing, Some
 from sonolus.script.num import Num
 from sonolus.script.record import Record
 from sonolus.script.values import copy
@@ -15,7 +16,7 @@ from sonolus.script.values import copy
 # Note: we don't use Range in this file because Range itself inherits from ArrayLike
 
 
-class ArrayLike[T]:
+class ArrayLike[T](Sequence):
     """Mixin for array-like objects.
 
     Inheritors must implement `__len__`, `__getitem__`, and `__setitem__`.
@@ -26,10 +27,10 @@ class ArrayLike[T]:
             def __len__(self) -> int:
                 ...
 
-            def __getitem__(self, index: Num) -> T:
+            def __getitem__(self, index: int) -> T:
                 ...
 
-            def __setitem__(self, index: Num, value: T):
+            def __setitem__(self, index: int, value: T):
                 ...
         ```
     """
@@ -41,7 +42,7 @@ class ArrayLike[T]:
         """Return the length of the array."""
 
     @abstractmethod
-    def __getitem__(self, index: Num) -> T:
+    def __getitem__(self, index: int) -> T:
         """Return the item at the given index.
 
         Args:
@@ -49,7 +50,7 @@ class ArrayLike[T]:
         """
 
     @abstractmethod
-    def __setitem__(self, index: Num, value: T):
+    def __setitem__(self, index: int, value: T):
         """Set the value of the item at the given index.
 
         Args:
@@ -78,10 +79,10 @@ class ArrayLike[T]:
         """Return a reversed view of the array."""
         return _ArrayReverser(self)
 
-    def _enumerate_(self, start: Num = 0) -> SonolusIterator[T]:
+    def _enumerate_(self, start: int = 0) -> SonolusIterator[T]:
         return _ArrayEnumerator(0, start, self)
 
-    def index(self, value: T, start: Num = 0, stop: Num | None = None) -> Num:
+    def index(self, value: T, start: int = 0, stop: int | None = None) -> int:
         """Return the index of the value in the array equal to the given value.
 
         Args:
@@ -98,7 +99,7 @@ class ArrayLike[T]:
             i += 1
         return -1
 
-    def count(self, value: T) -> Num:
+    def count(self, value: T) -> int:
         """Return the number of elements in the array equal to the given value.
 
         Args:
@@ -112,7 +113,7 @@ class ArrayLike[T]:
             i += 1
         return count
 
-    def last_index(self, value: T) -> Num:
+    def last_index(self, value: T) -> int:
         """Return the last index of the value in the array equal to the given value.
 
         Args:
@@ -125,7 +126,7 @@ class ArrayLike[T]:
             i -= 1
         return -1
 
-    def index_of_max(self, *, key: Callable[T, Any] | None = None) -> Num:
+    def index_of_max(self, *, key: Callable[[T], Any] | None = None) -> int:
         """Return the index of the maximum value in the array.
 
         Args:
@@ -134,16 +135,16 @@ class ArrayLike[T]:
         if len(self) == 0:
             return -1
         if key is None:
-            key = _identity
+            key = _identity  # type: ignore
         max_index = 0
         i = 1
         while i < len(self):
-            if key(self[i]) > key(self[max_index]):
+            if key(self[i]) > key(self[max_index]):  # type: ignore
                 max_index = i
             i += 1
         return max_index
 
-    def index_of_min(self, *, key: Callable[T, Any] | None = None) -> Num:
+    def index_of_min(self, *, key: Callable[[T], Any] | None = None) -> int:
         """Return the index of the minimum value in the array.
 
         Args:
@@ -152,26 +153,26 @@ class ArrayLike[T]:
         if len(self) == 0:
             return -1
         if key is None:
-            key = _identity
+            key = _identity  # type: ignore
         min_index = 0
         i = 1
         while i < len(self):
-            if key(self[i]) < key(self[min_index]):
+            if key(self[i]) < key(self[min_index]):  # type: ignore
                 min_index = i
             i += 1
         return min_index
 
-    def _max_(self, key: Callable[T, Any] | None = None) -> T:
+    def _max_(self, key: Callable[[T], Any] | None = None) -> T:
         index = self.index_of_max(key=key)
         assert index != -1
         return self[index]
 
-    def _min_(self, key: Callable[T, Any] | None = None) -> T:
+    def _min_(self, key: Callable[[T], Any] | None = None) -> T:
         index = self.index_of_min(key=key)
         assert index != -1
         return self[index]
 
-    def swap(self, i: Num, j: Num, /):
+    def swap(self, i: int, j: int, /):
         """Swap the values at the given indices.
 
         Args:
@@ -182,7 +183,7 @@ class ArrayLike[T]:
         self[i] = self[j]
         self[j] = temp
 
-    def sort(self, *, key: Callable[T, Any] | None = None, reverse: bool = False):
+    def sort(self, *, key: Callable[[T], Any] | None = None, reverse: bool = False):
         """Sort the values in the array in place.
 
         Args:
@@ -191,12 +192,12 @@ class ArrayLike[T]:
         """
         if len(self) < 15 or key is not None:
             if key is None:
-                key = _identity
+                key = _identity  # type: ignore
             # May be worth adding a block sort variant for better performance on large arrays in the future
-            _insertion_sort(self, 0, len(self), key, reverse)
+            _insertion_sort(self, 0, len(self), key, reverse)  # type: ignore
         else:
             # Heap sort is unstable, so if there's a key, we can't rely on it
-            _heap_sort(self, 0, len(self), reverse)
+            _heap_sort(self, 0, len(self), reverse)  # type: ignore
 
     def shuffle(self):
         """Shuffle the values in the array in place."""
@@ -216,32 +217,32 @@ def _identity[T](value: T) -> T:
     return value
 
 
-def _insertion_sort[T](array: ArrayLike[T], start: Num, end: Num, key: Callable[T, Any], reverse: bool):
+def _insertion_sort[T](array: ArrayLike[T], start: int, end: int, key: Callable[[T], Any], reverse: bool):
     i = start + 1
     if reverse:
         while i < end:
             j = i
-            while j > start and key(array[j - 1]) < key(array[j]):
+            while j > start and key(array[j - 1]) < key(array[j]):  # type: ignore
                 array.swap(j - 1, j)
                 j -= 1
             i += 1
     else:
         while i < end:
             j = i
-            while j > start and key(array[j - 1]) > key(array[j]):
+            while j > start and key(array[j - 1]) > key(array[j]):  # type: ignore
                 array.swap(j - 1, j)
                 j -= 1
             i += 1
 
 
-def _heapify[T](array: ArrayLike[T], end: Num, index: Num, reverse: bool):
+def _heapify[T](array: ArrayLike[T], end: int, index: int, reverse: bool):
     while True:
         left = index * 2 + 1
         right = left + 1
         largest = index
-        if left < end and (array[left] > array[largest]) != reverse:
+        if left < end and (array[left] > array[largest]) != reverse:  # type: ignore
             largest = left
-        if right < end and (array[right] > array[largest]) != reverse:
+        if right < end and (array[right] > array[largest]) != reverse:  # type: ignore
             largest = right
         if largest == index:
             break
@@ -249,7 +250,7 @@ def _heapify[T](array: ArrayLike[T], end: Num, index: Num, reverse: bool):
         index = largest
 
 
-def _heap_sort[T](array: ArrayLike[T], start: Num, end: Num, reverse: bool):
+def _heap_sort[T](array: ArrayLike[T], start: int, end: int, reverse: bool):
     i = end // 2 - 1
     while i >= start:
         _heapify(array, end, i, reverse)
@@ -265,14 +266,12 @@ class _ArrayIterator[V: ArrayLike](Record, SonolusIterator):
     i: int
     array: V
 
-    def has_next(self) -> bool:
-        return self.i < len(self.array)
-
-    def get(self) -> V:
-        return self.array[self.i]
-
-    def advance(self):
-        self.i += 1
+    def next(self) -> Maybe[V]:
+        if self.i < len(self.array):
+            value = self.array[self.i]
+            self.i += 1
+            return Some(value)
+        return Nothing
 
 
 class _ArrayReverser[V: ArrayLike](Record, ArrayLike):
@@ -281,10 +280,10 @@ class _ArrayReverser[V: ArrayLike](Record, ArrayLike):
     def __len__(self) -> int:
         return len(self.array)
 
-    def __getitem__(self, index: Num) -> V:
+    def __getitem__(self, index: int) -> V:
         return self.array[len(self) - 1 - index]
 
-    def __setitem__(self, index: Num, value: V):
+    def __setitem__(self, index: int, value: V):
         self.array[len(self) - 1 - index] = value
 
     def reversed(self) -> ArrayLike[V]:
@@ -296,18 +295,16 @@ class _ArrayEnumerator[V: ArrayLike](Record, SonolusIterator):
     offset: int
     array: V
 
-    def has_next(self) -> bool:
-        return self.i < len(self.array)
-
-    def get(self) -> tuple[int, Any]:
-        return self.i + self.offset, self.array[self.i]
-
-    def advance(self):
-        self.i += 1
+    def next(self) -> Maybe[tuple[int, Any]]:
+        if self.i < len(self.array):
+            result = (self.i + self.offset, self.array[self.i])
+            self.i += 1
+            return Some(result)
+        return Nothing
 
 
 @meta_fn
-def get_positive_index(index: Num, length: Num) -> Num:
+def get_positive_index(index: int, length: int) -> int:
     """Get the positive index for the given index in the array of the given length.
 
     This is used to convert negative indixes relative to the end of the array to positive indices.

sonolus/script/bucket.py

@@ -220,7 +220,7 @@ def bucket(*, sprites: list[_BucketSprite], unit: str | None = None) -> Any:
     return _BucketInfo(sprites, unit)
 
 
-type Buckets = NewType("Buckets", Any)
+type Buckets = NewType("Buckets", Any)  # type: ignore
 
 
 @dataclass_transform()