sonolus.py 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

sonolus/script/level.py

@@ -5,6 +5,19 @@ from sonolus.script.archetype import PlayArchetype, StandardArchetypeName, Stand
 
 
 class Level:
+    """A Sonolus level.
+
+    Args:
+        name: The name of the level.
+        title: The title of the level.
+        rating: The rating of the level.
+        artists: The artists of the level.
+        author: The author of the level.
+        cover: The cover of the level.
+        bgm: The background music of the level.
+        data: The data of the level.
+    """
+
     version = 1
 
     def __init__(
@@ -30,6 +43,13 @@ class Level:
 
 
 class LevelData:
+    """The data of a Sonolus level.
+
+    Args:
+        bgm_offset: The background music audio offset.
+        entities: The entities of the level.
+    """
+
     bgm_offset: float
     entities: list[PlayArchetype]
 
@@ -39,6 +59,8 @@ class LevelData:
 
 
 class BpmChange(PlayArchetype):
+    """The standard bpm change archetype."""
+
     name = StandardArchetypeName.BPM_CHANGE
 
     beat: StandardImport.BEAT
@@ -46,6 +68,8 @@ class BpmChange(PlayArchetype):
 
 
 class TimescaleChange(PlayArchetype):
+    """The standard timescale change archetype."""
+
     name = StandardArchetypeName.TIMESCALE_CHANGE
 
     beat: StandardImport.BEAT

sonolus/script/num.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import operator
 from collections.abc import Callable, Iterable
-from typing import TYPE_CHECKING, Any, Self, TypeIs, final
+from typing import TYPE_CHECKING, Any, Self, TypeIs, final, runtime_checkable
 
 from sonolus.backend.ir import IRConst, IRGet, IRPureInstr, IRSet
 from sonolus.backend.ops import Op
@@ -14,18 +14,18 @@ from sonolus.script.internal.impl import meta_fn
 from sonolus.script.internal.value import Value
 
 
-class NumMeta(type):
+class _NumMeta(type):
     def __instancecheck__(cls, instance):
-        return isinstance(instance, float | int | bool) or is_num(instance)
+        return isinstance(instance, float | int | bool) or _is_num(instance)
 
 
-def is_num(value: Any) -> TypeIs[Num]:
+def _is_num(value: Any) -> TypeIs[Num]:
     """Check if a value is a precisely Num instance."""
     return type.__instancecheck__(Num, value)  # type: ignore # noqa: PLC2801
 
 
 @final
-class _Num(Value, metaclass=NumMeta):
+class _Num(Value, metaclass=_NumMeta):
     # This works for ints, floats, and bools
     # Since we don't support complex numbers, real is equal to the original number
     __match_args__ = ("real",)
@@ -37,7 +37,7 @@ class _Num(Value, metaclass=NumMeta):
             raise TypeError("Cannot create a Num from a complex number")
         if isinstance(data, int):
             data = float(data)
-        if is_num(data):
+        if _is_num(data):
             raise InternalError("Cannot create a Num from a Num")
         self.data = data
 
@@ -73,7 +73,7 @@ class _Num(Value, metaclass=NumMeta):
     def _accept_(cls, value: Any) -> Self:
         if not cls._accepts_(value):
             raise TypeError(f"Cannot accept {value}")
-        if is_num(value):
+        if _is_num(value):
             return value
         return cls(value)
 
@@ -122,7 +122,10 @@ class _Num(Value, metaclass=NumMeta):
         raise ValueError("Cannot assign to a number")
 
     def _copy_(self) -> Self:
-        return self
+        if ctx():
+            return self._get_()
+        else:
+            return Num(self.data)
 
     @classmethod
     def _alloc_(cls) -> Self:
@@ -168,7 +171,7 @@ class _Num(Value, metaclass=NumMeta):
     def __eq__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data == b.data)
+                return Num(a._as_py_() == b._as_py_())
             if a.data == b.data:
                 return Num(True)
             return None
@@ -184,7 +187,7 @@ class _Num(Value, metaclass=NumMeta):
     def __ne__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data != b.data)
+                return Num(a._as_py_() != b._as_py_())
             if a.data == b.data:
                 return Num(False)
             return None
@@ -195,7 +198,7 @@ class _Num(Value, metaclass=NumMeta):
     def __lt__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data < b.data)
+                return Num(a._as_py_() < b._as_py_())
             if a.data == b.data:
                 return Num(False)
             return None
@@ -206,7 +209,9 @@ class _Num(Value, metaclass=NumMeta):
     def __le__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data <= b.data)
+                return Num(a._as_py_() <= b._as_py_())
+            if a.data == b.data:
+                return Num(True)
             return None
 
         return self._bin_op(other, const_fn, Op.LessOr)
@@ -215,7 +220,7 @@ class _Num(Value, metaclass=NumMeta):
     def __gt__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data > b.data)
+                return Num(a._as_py_() > b._as_py_())
             if a.data == b.data:
                 return Num(False)
             return None
@@ -226,7 +231,9 @@ class _Num(Value, metaclass=NumMeta):
     def __ge__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data >= b.data)
+                return Num(a._as_py_() >= b._as_py_())
+            if a.data == b.data:
+                return Num(True)
             return None
 
         return self._bin_op(other, const_fn, Op.GreaterOr)
@@ -235,10 +242,10 @@ class _Num(Value, metaclass=NumMeta):
     def __add__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data + b.data)
-            if a._is_py_() and a.data == 0:
+                return Num(a._as_py_() + b._as_py_())
+            if a._is_py_() and a._as_py_() == 0:
                 return b
-            if b._is_py_() and b.data == 0:
+            if b._is_py_() and b._as_py_() == 0:
                 return a
             return None
 
@@ -248,10 +255,10 @@ class _Num(Value, metaclass=NumMeta):
     def __sub__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data - b.data)
-            if a._is_py_() and a.data == 0:
+                return Num(a._as_py_() - b._as_py_())
+            if a._is_py_() and a._as_py_() == 0:
                 return -b
-            if b._is_py_() and b.data == 0:
+            if b._is_py_() and b._as_py_() == 0:
                 return a
             return None
 
@@ -261,16 +268,16 @@ class _Num(Value, metaclass=NumMeta):
     def __mul__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data * b.data)
+                return Num(a._as_py_() * b._as_py_())
             if a._is_py_():
-                if a.data == 0:
+                if a._as_py_() == 0:
                     return Num(0)
-                if a.data == 1:
+                if a._as_py_() == 1:
                     return b
             if b._is_py_():
-                if b.data == 0:
+                if b._as_py_() == 0:
                     return Num(0)
-                if b.data == 1:
+                if b._as_py_() == 1:
                     return a
             return None
 
@@ -280,13 +287,13 @@ class _Num(Value, metaclass=NumMeta):
     def __truediv__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                if b.data == 0:
+                if b._as_py_() == 0:
                     return None
-                return Num(a.data / b.data)
+                return Num(a._as_py_() / b._as_py_())
             if b._is_py_():
-                if b.data == 1:
+                if b._as_py_() == 1:
                     return a
-                if b.data == -1:
+                if b._as_py_() == -1:
                     return -a
             return None
 
@@ -296,13 +303,13 @@ class _Num(Value, metaclass=NumMeta):
     def __floordiv__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                if b.data == 0:
+                if b._as_py_() == 0:
                     return None
-                return Num(a.data // b.data)
+                return Num(a._as_py_() // b._as_py_())
             if b._is_py_():
-                if b.data == 1:
+                if b._as_py_() == 1:
                     return a
-                if b.data == -1:
+                if b._as_py_() == -1:
                     return -a
             return None
 
@@ -312,9 +319,9 @@ class _Num(Value, metaclass=NumMeta):
     def __mod__(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                if b.data == 0:
+                if b._as_py_() == 0:
                     return None
-                return Num(a.data % b.data)
+                return Num(a._as_py_() % b._as_py_())
             return None
 
         return self._bin_op(other, const_fn, Op.Mod)
@@ -324,13 +331,13 @@ class _Num(Value, metaclass=NumMeta):
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
                 try:
-                    return Num(a.data**b.data)
+                    return Num(a._as_py_() ** b._as_py_())
                 except OverflowError:
                     return None
             if b._is_py_():
-                if b.data == 0:
+                if b._as_py_() == 0:
                     return Num(1)
-                if b.data == 1:
+                if b._as_py_() == 1:
                     return a
             return None
 
@@ -360,9 +367,9 @@ class _Num(Value, metaclass=NumMeta):
     def and_(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data and b.data)
+                return Num(a._as_py_() and b._as_py_())
             if a._is_py_():
-                if a.data == 0:
+                if a._as_py_() == 0:
                     return a
                 else:
                     return b
@@ -373,9 +380,9 @@ class _Num(Value, metaclass=NumMeta):
     def or_(self, other) -> Self:
         def const_fn(a: Self, b: Self) -> Num | None:
             if a._is_py_() and b._is_py_():
-                return Num(a.data or b.data)
+                return Num(a._as_py_() or b._as_py_())
             if a._is_py_():
-                if a.data == 0:
+                if a._as_py_() == 0:
                     return b
                 else:
                     return a
@@ -396,11 +403,36 @@ class _Num(Value, metaclass=NumMeta):
 
 
 if TYPE_CHECKING:
-
-    class __Num(float, int, bool, _Num):  # type: ignore
-        pass
-
-    Num = __Num | _Num | float | int | bool
+    from typing import Protocol
+
+    @runtime_checkable
+    class Num[T](Protocol, int, bool, float):
+        def __add__(self, other: T, /) -> Num: ...
+        def __sub__(self, other: T, /) -> Num: ...
+        def __mul__(self, other: T, /) -> Num: ...
+        def __truediv__(self, other: T, /) -> Num: ...
+        def __floordiv__(self, other: T, /) -> Num: ...
+        def __mod__(self, other: T, /) -> Num: ...
+        def __pow__(self, other: T, /) -> Num: ...
+
+        def __neg__(self, /) -> Num: ...
+        def __pos__(self, /) -> Num: ...
+        def __abs__(self, /) -> Num: ...
+
+        def __eq__(self, other: Any, /) -> bool: ...
+        def __ne__(self, other: Any, /) -> bool: ...
+        def __lt__(self, other: T, /) -> bool: ...
+        def __le__(self, other: T, /) -> bool: ...
+        def __gt__(self, other: T, /) -> bool: ...
+        def __ge__(self, other: T, /) -> bool: ...
+
+        def __hash__(self, /) -> int: ...
+
+        @property
+        def real(self) -> Num: ...
+
+        @property
+        def imag(self) -> Num: ...
 else:
     # Need to do this to satisfy type checkers (especially Pycharm)
     _Num.__name__ = "Num"

sonolus/script/options.py

@@ -13,7 +13,7 @@ from sonolus.script.num import Num
 
 
 @dataclass
-class SliderOption:
+class _SliderOption:
     name: str | None
     standard: bool
     advanced: bool
@@ -43,7 +43,7 @@ class SliderOption:
 
 
 @dataclass
-class ToggleOption:
+class _ToggleOption:
     name: str | None
     standard: bool
     advanced: bool
@@ -64,7 +64,7 @@ class ToggleOption:
 
 
 @dataclass
-class SelectOption:
+class _SelectOption:
     name: str | None
     standard: bool
     advanced: bool
@@ -98,7 +98,20 @@ def slider_option(
     unit: str | None = None,
     scope: str | None = None,
 ) -> Any:
-    return SliderOption(name, standard, advanced, scope, default, min, max, step, unit)
+    """Define a slider option.
+
+    Args:
+        name: The name of the option.
+        standard: Whether the option is standard.
+        advanced: Whether the option is advanced.
+        default: The default value of the option.
+        min: The minimum value of the option.
+        max: The maximum value of the option.
+        step: The step value of the option.
+        unit: The unit of the option.
+        scope: The scope of the option.
+    """
+    return _SliderOption(name, standard, advanced, scope, default, min, max, step, unit)
 
 
 def toggle_option(
@@ -109,7 +122,16 @@ def toggle_option(
     default: bool,
     scope: str | None = None,
 ) -> Any:
-    return ToggleOption(name, standard, advanced, scope, default)
+    """Define a toggle option.
+
+    Args:
+        name: The name of the option.
+        standard: Whether the option is standard.
+        advanced: Whether the option is advanced.
+        default: The default value of the option.
+        scope: The scope of the option.
+    """
+    return _ToggleOption(name, standard, advanced, scope, default)
 
 
 def select_option(
@@ -121,18 +143,28 @@ def select_option(
     values: list[str],
     scope: str | None = None,
 ) -> Any:
-    return SelectOption(name, standard, advanced, scope, default, values)
+    """Define a select option.
+
+    Args:
+        name: The name of the option.
+        standard: Whether the option is standard.
+        advanced: Whether the option is advanced.
+        default: The default value of the option.
+        values: The values of the option.
+        scope: The scope of the option.
+    """
+    return _SelectOption(name, standard, advanced, scope, default, values)
 
 
 type Options = NewType("Options", Any)
-type OptionInfo = SliderOption | ToggleOption | SelectOption
+type _OptionInfo = _SliderOption | _ToggleOption | _SelectOption
 
 
-class OptionField(SonolusDescriptor):
-    info: OptionInfo
+class _OptionField(SonolusDescriptor):
+    info: _OptionInfo
     index: int
 
-    def __init__(self, info: OptionInfo, index: int):
+    def __init__(self, info: _OptionInfo, index: int):
         self.info = info
         self.index = index
 
@@ -160,6 +192,40 @@ class OptionField(SonolusDescriptor):
 
 @dataclass_transform()
 def options[T](cls: type[T]) -> T | Options:
+    """Decorator to define options.
+
+    Usage:
+        ```python
+        @options
+        class Options:
+            slider_option: float = slider_option(
+                name='Slider Option',
+                standard=True,
+                advanced=False,
+                default=0.5,
+                min=0,
+                max=1,
+                step=0.1,
+                unit='unit',
+                scope='scope',
+            )
+            toggle_option: bool = toggle_option(
+                name='Toggle Option',
+                standard=True,
+                advanced=False,
+                default=True,
+                scope='scope',
+            )
+            select_option: int = select_option(
+                name='Select Option',
+                standard=True,
+                advanced=False,
+                default='value',
+                values=['value'],
+                scope='scope',
+            )
+        ```
+    """
     if len(cls.__bases__) != 1:
         raise ValueError("Options class must not inherit from any class (except object)")
     instance = cls()
@@ -175,12 +241,12 @@ def options[T](cls: type[T]) -> T | Options:
         if annotation_type is not Num:
             raise TypeError(f"Invalid annotation type for options: {annotation_type}")
         annotation_value = annotation_values[0]
-        if not isinstance(annotation_value, SliderOption | ToggleOption | SelectOption):
+        if not isinstance(annotation_value, _SliderOption | _ToggleOption | _SelectOption):
             raise TypeError(f"Invalid annotation value for options: {annotation_value}")
         if annotation_value.name is None:
             annotation_value.name = name
         entries.append(annotation_value)
-        setattr(cls, name, OptionField(annotation_value, i))
+        setattr(cls, name, _OptionField(annotation_value, i))
     instance._options_ = entries
     instance._is_comptime_value_ = True
     return instance

sonolus/script/particle.py

@@ -4,29 +4,50 @@ from dataclasses import dataclass
 from typing import Annotated, Any, NewType, dataclass_transform, get_origin
 
 from sonolus.backend.ops import Op
-from sonolus.script.graphics import QuadLike, flatten_quad
 from sonolus.script.internal.introspection import get_field_specifiers
 from sonolus.script.internal.native import native_function
+from sonolus.script.quad import QuadLike, flatten_quad
 from sonolus.script.record import Record
 
 
 class Particle(Record):
+    """A particle effect."""
+
     id: int
 
     def is_available(self) -> bool:
+        """Check if the particle effect is available."""
         return _has_particle_effect(self.id)
 
     def spawn(self, quad: QuadLike, duration: float, loop: bool = False) -> ParticleHandle:
+        """Spawn the particle effect.
+
+        Args:
+            quad: The quad to spawn the particle effect on.
+            duration: The duration of the particle effect.
+            loop: Whether to loop the particle effect.
+
+        Returns:
+            ParticleHandle: A handle to the spawned particle effect.
+        """
         return ParticleHandle(_spawn_particle_effect(self.id, *flatten_quad(quad), duration, loop))
 
 
 class ParticleHandle(Record):
+    """A handle to a looping particle effect."""
+
     id: int
 
     def move(self, quad: QuadLike) -> None:
+        """Move the particle effect to a new location.
+
+        Args:
+            quad: The new quad to move the particle effect to.
+        """
         _move_particle_effect(self.id, *flatten_quad(quad))
 
     def destroy(self) -> None:
+        """Destroy the particle effect."""
         _destroy_particle_effect(self.id)
 
 
@@ -65,12 +86,12 @@ def _destroy_particle_effect(handle: int) -> None:
 
 
 @dataclass
-class ParticleInfo:
+class _ParticleInfo:
     name: str
 
 
 def particle(name: str) -> Any:
-    return ParticleInfo(name)
+    return _ParticleInfo(name)
 
 
 type Particles = NewType("Particles", Any)
@@ -78,6 +99,16 @@ type Particles = NewType("Particles", Any)
 
 @dataclass_transform()
 def particles[T](cls: type[T]) -> T | Particles:
+    """Decorator to define particles.
+
+    Usage:
+        ```python
+        @particles
+        class Particles:
+            tap: StandardParticle.NOTE_CIRCULAR_TAP_RED
+            other: Particle = particle("other")
+        ```
+    """
     if len(cls.__bases__) != 1:
         raise ValueError("Particles class must not inherit from any class (except object)")
     instance = cls()
@@ -89,7 +120,7 @@ def particles[T](cls: type[T]) -> T | Particles:
         annotation_values = annotation.__metadata__
         if annotation_type is not Particle:
             raise TypeError(f"Invalid annotation for particles: {annotation}, expected annotation of type Particle")
-        if len(annotation_values) != 1 or not isinstance(annotation_values[0], ParticleInfo):
+        if len(annotation_values) != 1 or not isinstance(annotation_values[0], _ParticleInfo):
             raise TypeError(
                 f"Invalid annotation for particles: {annotation}, expected a single string annotation value"
             )
@@ -102,6 +133,8 @@ def particles[T](cls: type[T]) -> T | Particles:
 
 
 class StandardParticle:
+    """Standard particles."""
+
     NOTE_CIRCULAR_TAP_NEUTRAL = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_NEUTRAL")]
     NOTE_CIRCULAR_TAP_RED = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_RED")]
     NOTE_CIRCULAR_TAP_GREEN = Annotated[Particle, particle("#NOTE_CIRCULAR_TAP_GREEN")]

sonolus/script/pointer.py

@@ -1,11 +1,11 @@
 from sonolus.backend.place import BlockPlace
 from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.internal.value import Value
-from sonolus.script.num import Num, is_num
+from sonolus.script.num import Num, _is_num
 
 
 @meta_fn
-def deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
+def _deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
     block = Num._accept_(block)
     offset = Num._accept_(offset)
     type_ = validate_value(type_)._as_py_()
@@ -14,7 +14,7 @@ def deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
         if not isinstance(block, int):
             raise TypeError("block must be an integer")
     else:
-        if not is_num(block):
+        if not _is_num(block):
             raise TypeError("block must be a Num")
         block = block.index()
     if offset._is_py_():
@@ -22,7 +22,7 @@ def deref[T: Value](block: Num, offset: Num, type_: type[T]) -> T:
         if not isinstance(offset, int):
             raise TypeError("offset must be an integer")
     else:
-        if not is_num(offset):
+        if not _is_num(offset):
             raise TypeError("offset must be a Num")
         offset = offset.index()
     if not (isinstance(type_, type) and issubclass(type_, Value)):

sonolus/script/print.py

@@ -7,6 +7,8 @@ from sonolus.script.vec import Vec2
 
 
 class PrintFormat(IntEnum):
+    """Print format."""
+
     NUMBER = 0
     PERCENTAGE = 1
     TIME = 10
@@ -19,6 +21,8 @@ class PrintFormat(IntEnum):
 
 
 class PrintColor(IntEnum):
+    """Print color."""
+
     THEME = -1
     NEUTRAL = 0
     RED = 1
@@ -45,7 +49,7 @@ def _print(
     alpha: float,
     horizontal_align: HorizontalAlign,
     background: bool,
-):
+) -> None:
     raise NotImplementedError
 
 
@@ -63,6 +67,23 @@ def print_number(
     horizontal_align: HorizontalAlign = HorizontalAlign.LEFT,
     background: bool = False,
 ):
+    """Print a number.
+
+    Only supported in preview mode.
+
+    Args:
+        value: The value to print.
+        fmt: The print format.
+        decimal_places: The number of decimal places.
+        anchor: The anchor.
+        pivot: The pivot.
+        dimensions: The dimensions.
+        rotation: The rotation.
+        color: The color.
+        alpha: The alpha.
+        horizontal_align: The horizontal alignment.
+        background: Whether to show a background.
+    """
     _print(
         value,
         fmt,