sonolus.py 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

sonolus/backend/optimize/constant_evaluation.py

@@ -124,6 +124,8 @@ class SparseConditionalConstantPropagation(CompilerPass):
                             new_values.add(arg)
                     if len(new_values) == 1:
                         new_value = next(iter(new_values))
+                    elif len(new_values) > 100:
+                        new_value = NAC  # Give up to save performance
                     else:
                         new_value = frozenset(new_values)
             else:

sonolus/backend/utils.py

@@ -24,14 +24,29 @@ class FindFunction(ast.NodeVisitor):
     def __init__(self, line):
         self.line = line
         self.results: list[ast.FunctionDef | ast.Lambda] = []
+        self.current_fn = None
 
     def visit_FunctionDef(self, node: ast.FunctionDef):
         self.results.append(node)
+        outer_fn = self.current_fn
+        self.current_fn = node
         self.generic_visit(node)
+        self.current_fn = outer_fn
 
     def visit_Lambda(self, node: ast.Lambda):
         self.results.append(node)
+        outer_fn = self.current_fn
+        self.current_fn = node
         self.generic_visit(node)
+        self.current_fn = outer_fn
+
+    # Visitors have high overhead, so we detect generators here rather than in a separate pass.
+
+    def visit_Yield(self, node):
+        self.current_fn.has_yield = True
+
+    def visit_YieldFrom(self, node):
+        self.current_fn.has_yield = True
 
 
 @cache
@@ -65,27 +80,3 @@ def scan_writes(node: ast.AST) -> set[str]:
     visitor = ScanWrites()
     visitor.visit(node)
     return set(visitor.writes)
-
-
-class HasDirectYield(ast.NodeVisitor):
-    def __init__(self):
-        self.started = False
-        self.has_yield = False
-
-    def visit_Yield(self, node: ast.Yield):
-        self.has_yield = True
-
-    def visit_YieldFrom(self, node: ast.YieldFrom):
-        self.has_yield = True
-
-    def visit_FunctionDef(self, node: ast.FunctionDef):
-        if self.started:
-            return
-        self.started = True
-        self.generic_visit(node)
-
-
-def has_yield(node: ast.AST) -> bool:
-    visitor = HasDirectYield()
-    visitor.visit(node)
-    return visitor.has_yield

sonolus/backend/visitor.py

@@ -11,9 +11,9 @@ from types import FunctionType, MethodType, MethodWrapperType
 from typing import Any, Never
 
 from sonolus.backend.excepthook import install_excepthook
-from sonolus.backend.utils import get_function, has_yield, scan_writes
+from sonolus.backend.utils import get_function, scan_writes
 from sonolus.script.debug import assert_true
-from sonolus.script.internal.builtin_impls import BUILTIN_IMPLS, _bool, _float, _int, _len
+from sonolus.script.internal.builtin_impls import BUILTIN_IMPLS, _bool, _float, _int, _len, _super
 from sonolus.script.internal.constant import ConstantValue
 from sonolus.script.internal.context import Context, EmptyBinding, Scope, ValueBinding, ctx, set_ctx, using_ctx
 from sonolus.script.internal.descriptor import SonolusDescriptor
@@ -39,6 +39,8 @@ def compile_and_call[**P, R](fn: Callable[P, R], /, *args: P.args, **kwargs: P.k
 def compile_and_call_at_definition[**P, R](fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
     if not ctx():
         return fn(*args, **kwargs)
+    if ctx().no_eval:
+        return compile_and_call(fn, *args, **kwargs)
     source_file, node = get_function(fn)
     location_args = {
         "lineno": node.lineno,
@@ -279,7 +281,8 @@ class Visitor(ast.NodeVisitor):
                 ctx().scope.set_value("$return", validate_value(None))
             case _:
                 raise NotImplementedError("Unsupported syntax")
-        if has_yield(node) or isinstance(node, ast.GeneratorExp):
+        # has_yield is set by the find_function visitor
+        if getattr(node, "has_yield", False) or isinstance(node, ast.GeneratorExp):
             return_ctx = Context.meet([*self.return_ctxs, ctx()])
             result_binding = return_ctx.scope.get_binding("$return")
             if not isinstance(result_binding, ValueBinding):
@@ -1110,6 +1113,21 @@ class Visitor(ast.NodeVisitor):
                     kwargs.update(value.value)
                 else:
                     raise ValueError("Starred keyword arguments (**kwargs) must be dictionaries")
+        if fn._is_py_() and fn._as_py_() is _super and not args and not kwargs and "__class__" in self.globals:
+            class_value = self.get_name("__class__")
+            first_param_name = next(
+                (
+                    name
+                    for name, param in self.bound_args.signature.parameters.items()
+                    if param.kind in {inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD}
+                ),
+                None,
+            )
+            if first_param_name is not None:
+                first_param_value = self.get_name(first_param_name)
+                args = (validate_value(class_value), validate_value(first_param_value))
+            else:
+                args = (validate_value(class_value),)
         return self.handle_call(node, fn, *args, **kwargs)
 
     def visit_FormattedValue(self, node):
@@ -1133,23 +1151,26 @@ class Visitor(ast.NodeVisitor):
         raise NotImplementedError("Starred expressions are not supported")
 
     def visit_Name(self, node):
-        if node.id in self.used_parent_binding_values:
-            return self.used_parent_binding_values[node.id]
+        return self.get_name(node.id)
+
+    def get_name(self, name: str):
+        if name in self.used_parent_binding_values:
+            return self.used_parent_binding_values[name]
         self.active_ctx = ctx()
         v = self
         while v:
-            if not isinstance(v.active_ctx.scope.get_binding(node.id), EmptyBinding):
-                result = v.active_ctx.scope.get_value(node.id)
+            if not isinstance(v.active_ctx.scope.get_binding(name), EmptyBinding):
+                result = v.active_ctx.scope.get_value(name)
                 if v is not self:
-                    self.used_parent_binding_values[node.id] = result
+                    self.used_parent_binding_values[name] = result
                 return result
             v = v.parent
-        if node.id in self.globals:
-            value = self.globals[node.id]
+        if name in self.globals:
+            value = self.globals[name]
             if value is ctx:
                 raise ValueError("Unexpected use of ctx in non meta-function")
             return validate_value(BUILTIN_IMPLS.get(id(value), value))
-        raise NameError(f"Name {node.id} is not defined")
+        raise NameError(f"Name {name} is not defined")
 
     def visit_List(self, node):
         raise NotImplementedError("List literals are not supported")
@@ -1423,6 +1444,9 @@ class Visitor(ast.NodeVisitor):
         self, node: ast.stmt | ast.expr, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
     ) -> R:
         """Executes the given function at the given node for a better traceback."""
+        if ctx().no_eval:
+            return fn(*args, **kwargs)
+
         location_args = {
             "lineno": node.lineno,
             "col_offset": node.col_offset,

sonolus/build/cli.py

@@ -166,13 +166,13 @@ def main():
     def add_common_arguments(parser):
         optimization_group = parser.add_mutually_exclusive_group()
         optimization_group.add_argument(
-            "-o0", "--optimize-minimal", action="store_true", help="Use minimal optimization passes"
+            "-O0", "--optimize-minimal", action="store_true", help="Use minimal optimization passes"
         )
         optimization_group.add_argument(
-            "-o1", "--optimize-fast", action="store_true", help="Use fast optimization passes"
+            "-O1", "--optimize-fast", action="store_true", help="Use fast optimization passes"
         )
         optimization_group.add_argument(
-            "-o2", "--optimize-standard", action="store_true", help="Use standard optimization passes"
+            "-O2", "--optimize-standard", action="store_true", help="Use standard optimization passes"
         )
 
         build_components = parser.add_argument_group("build components")

sonolus/build/compile.py

@@ -21,6 +21,7 @@ from sonolus.script.internal.context import (
     ctx,
     using_ctx,
 )
+from sonolus.script.internal.error import CompilationError
 from sonolus.script.num import _is_num
 
 
@@ -140,7 +141,21 @@ def callback_to_cfg(
     name: str,
     archetype: type[_BaseArchetype] | None = None,
 ) -> BasicBlock:
-    callback_state = CallbackContextState(name)
+    try:
+        # Default to no_eval=True for performance unless there's an error.
+        return _callback_to_cfg(global_state, callback, name, archetype, no_eval=True)
+    except CompilationError:
+        return _callback_to_cfg(global_state, callback, name, archetype, no_eval=False)
+
+
+def _callback_to_cfg(
+    global_state: GlobalContextState,
+    callback: Callable,
+    name: str,
+    archetype: type[_BaseArchetype] | None,
+    no_eval: bool,
+) -> BasicBlock:
+    callback_state = CallbackContextState(name, no_eval=no_eval)
     context = Context(global_state, callback_state)
     with using_ctx(context):
         if archetype is not None:

sonolus/script/archetype.py

@@ -190,7 +190,8 @@ def imported(*, name: str | None = None) -> Any:
 
     In watch mode, data may also be loaded from a corresponding exported field in play mode.
 
-    Imported fields may only be updated in the `preprocess` callback, and are read-only in other callbacks.
+    Imported fields may only be updated in the [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess]
+    callback, and are read-only in other callbacks.
 
     Usage:
         ```python
@@ -205,10 +206,12 @@ def imported(*, name: str | None = None) -> Any:
 def entity_data() -> Any:
     """Declare a field as entity data.
 
-    Entity data is accessible from other entities, but may only be updated in the `preprocess` callback
+    Entity data is accessible from other entities, but may only be updated in the
+    [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess] callback
     and is read-only in other callbacks.
 
-    It functions like `imported` and shares the same underlying storage, except that it is not loaded from a level.
+    It functions like [`imported`][sonolus.script.archetype.imported] and shares the same underlying storage,
+    except that it is not loaded from a level.
 
     Usage:
         ```python
@@ -242,7 +245,8 @@ def entity_memory() -> Any:
     Entity memory is private to the entity and is not accessible from other entities. It may be read or updated in any
     callback associated with the entity.
 
-    Entity memory fields may also be set when an entity is spawned using the `spawn()` method.
+    Entity memory fields may also be set when an entity is spawned using the
+    [`spawn()`][sonolus.script.archetype.PlayArchetype.spawn] method.
 
     Usage:
         ```python
@@ -260,7 +264,9 @@ def shared_memory() -> Any:
     Shared memory is accessible from other entities.
 
     Shared memory may be read in any callback, but may only be updated by sequential callbacks
-    (`preprocess`, `update_sequential`, and `touch`).
+    ([`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess],
+    [`update_sequential`][sonolus.script.archetype.PlayArchetype.update_sequential],
+    and [`touch`][sonolus.script.archetype.PlayArchetype.touch]).
 
     Usage:
         ```python
@@ -688,7 +694,7 @@ class PlayArchetype(_BaseArchetype):
     def spawn_order(self) -> float:
         """Return the spawn order of the entity.
 
-        Runs when the level is loaded after `preprocess`.
+        Runs when the level is loaded after [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess].
         """
 
     def should_spawn(self) -> bool:
@@ -709,13 +715,15 @@ class PlayArchetype(_BaseArchetype):
         Runs first each frame.
 
         This is where logic affecting shared memory should be placed.
-        Other logic should be placed in `update_parallel` for better performance.
+        Other logic should typically be placed in
+        [`update_parallel`][sonolus.script.archetype.PlayArchetype.update_parallel]
+        for better performance.
         """
 
     def update_parallel(self):
         """Perform parallel actions for this frame.
 
-        Runs after `touch` each frame.
+        Runs after [`touch`][sonolus.script.archetype.PlayArchetype.touch] each frame.
 
         This is where most gameplay logic should be placed.
         """
@@ -723,7 +731,7 @@ class PlayArchetype(_BaseArchetype):
     def touch(self):
         """Handle user input.
 
-        Runs after `update_sequential` each frame.
+        Runs after [`update_sequential`][sonolus.script.archetype.PlayArchetype.update_sequential] each frame.
         """
 
     def terminate(self):
@@ -863,13 +871,14 @@ class WatchArchetype(_BaseArchetype):
         Runs first each frame.
 
         This is where logic affecting shared memory should be placed.
-        Other logic should be placed in `update_parallel` for better performance.
+        Other logic should typically be placed in
+        [`update_parallel`][sonolus.script.archetype.PlayArchetype.update_parallel] for better performance.
         """
 
     def update_parallel(self):
         """Parallel update callback.
 
-        Runs after `touch` each frame.
+        Runs after [`touch`][sonolus.script.archetype.PlayArchetype.touch] each frame.
 
         This is where most gameplay logic should be placed.
         """
@@ -1094,7 +1103,7 @@ class WatchEntityInput(Record):
 class EntityRef[A: _BaseArchetype](Record):
     """Reference to another entity.
 
-    May be used with `Any` to reference an unknown archetype.
+    May be used with `typing.Any` to reference an unknown archetype.
 
     Usage:
         ```python

sonolus/script/array.py

@@ -16,7 +16,7 @@ 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."""
+"""Shorthand for `typing.Literal` intended for use in array dimensions for type checker compatibility."""
 
 
 class ArrayMeta(ABCMeta):

sonolus/script/bucket.py

@@ -103,9 +103,16 @@ class Judgment(IntEnum):
     """The judgment of a hit."""
 
     MISS = 0
+    """A miss. Breaks combo."""
+
     PERFECT = 1
+    """A perfect hit."""
+
     GREAT = 2
+    """A great hit."""
+
     GOOD = 3
+    """A good hit. Breaks combo."""
 
 
 @native_function(Op.Judge)

sonolus/script/containers.py

@@ -33,7 +33,7 @@ class Box[T](Record):
         x: T = ...
         y: T = ...
         box = Box(x)
-        box.value = y  # Works regardless of whether x is a Num or not
+        box.value = y  # Works regardless of whether x is a Num, array, or record
         ```
     """
 

sonolus/script/easing.py

@@ -1,4 +1,3 @@
-# ruff: noqa: E501
 import math
 
 from sonolus.backend.ops import Op

sonolus/script/effect.py

@@ -38,7 +38,8 @@ class Effect(Record):
     def schedule(self, time: float, distance: float = 0) -> None:
         """Schedule the effect clip to play at a specific time.
 
-        This is not suitable for real-time effects such as responses to user input. Use `play` instead.
+        This is not suitable for real-time effects such as responses to user input.
+        Use [`play`][sonolus.script.effect.Effect.play] instead.
 
         This may be called in preprocess to schedule effects upfront.
 
@@ -61,7 +62,8 @@ class Effect(Record):
     def schedule_loop(self, start_time: float) -> ScheduledLoopedEffectHandle:
         """Schedule the effect clip to play in a loop until stopped.
 
-        This is not suitable for real-time effects such as responses to user input. Use `loop` instead.
+        This is not suitable for real-time effects such as responses to user input.
+        Use [`loop`][sonolus.script.effect.Effect.loop] instead.
 
         Returns:
             A handle to stop the loop.

sonolus/script/globals.py

@@ -235,7 +235,10 @@ def _tutorial_instruction[T](cls: type[T]) -> T:
 def level_memory[T](cls: type[T]) -> T:
     """Define level memory.
 
-    Level memory may be modified during gameplay in sequential callbacks (`preprocess`, `update_sequential`, `touch`).
+    Level memory may be modified during gameplay in sequential callbacks
+    ([`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess],
+    [`update_sequential`][sonolus.script.archetype.PlayArchetype.update_sequential],
+    [`touch`][sonolus.script.archetype.PlayArchetype.touch]).
 
     Usage:
         ```python
@@ -265,7 +268,7 @@ def level_memory[T](cls: type[T]) -> T:
 def level_data[T](cls: type[T]) -> T:
     """Define level data.
 
-    Level data may only be modified during preprocessing.
+    Level data may only be modified during [`preprocess`][sonolus.script.archetype.PlayArchetype.preprocess].
 
     Usage:
         ```python

sonolus/script/internal/builtin_impls.py

@@ -377,6 +377,12 @@ def _iter(iterable):
     return iterable.__iter__()  # type: ignore # noqa: PLC2801
 
 
+@meta_fn
+def _super(*args):
+    """Get the super class of a class or instance."""
+    return super(*(arg._as_py_() if arg._is_py_() else arg for arg in args))
+
+
 # classmethod, property, staticmethod are supported as decorators, but not within functions
 
 BUILTIN_IMPLS = {
@@ -399,6 +405,7 @@ BUILTIN_IMPLS = {
     id(next): _next,
     id(range): Range,
     id(reversed): _reversed,
+    id(super): _super,
     id(zip): _zip,
     **MATH_BUILTIN_IMPLS,  # Includes round
     **RANDOM_BUILTIN_IMPLS,

sonolus/script/internal/context.py

@@ -61,10 +61,12 @@ class GlobalContextState:
 class CallbackContextState:
     callback: str
     used_names: dict[str, int]
+    no_eval: bool
 
-    def __init__(self, callback: str):
+    def __init__(self, callback: str, no_eval: bool = False):
         self.callback = callback
         self.used_names = {}
+        self.no_eval = no_eval
 
 
 class Context:
@@ -111,6 +113,10 @@ class Context:
     def used_names(self) -> dict[str, int]:
         return self.callback_state.used_names
 
+    @property
+    def no_eval(self) -> bool:
+        return self.callback_state.no_eval
+
     def check_readable(self, place: BlockPlace):
         if debug_config().unchecked_reads:
             return

sonolus/script/internal/impl.py

@@ -83,6 +83,7 @@ def try_validate_value(value: Any) -> Value | None:
             | NoneType()
             | NotImplementedType()
             | EllipsisType()
+            | super()
         ):
             return BasicConstantValue.of(value)
         case special_form if value in {

sonolus/script/internal/native.py

@@ -32,7 +32,7 @@ def native_function[**P, R](op: Op) -> Callable[[Callable[P, R]], Callable[P, R]
             if ctx():
                 bound_args = signature.bind(*args)
                 bound_args.apply_defaults()
-                return native_call(op, *(Num._accept_(arg) for arg in bound_args.args))
+                return native_call(op, *bound_args.args)
             return fn(*args)  # type: ignore
 
         return wrapper

sonolus/script/iterator.py

@@ -14,7 +14,8 @@ class SonolusIterator[T]:
 
     This class is used to define custom iterators that can be used in Sonolus.py.
 
-    Inheritors must implement the `next` method, which should return a `Maybe[T]`.
+    Inheritors must implement the [`next`][sonolus.script.iterator.SonolusIterator.next] method,
+    which should return a [`Maybe[T]`][sonolus.script.maybe.Maybe].
 
     Usage:
         ```python
@@ -28,6 +29,7 @@ class SonolusIterator[T]:
 
     @meta_fn
     def next(self) -> Maybe[T]:
+        """Return the next item from the iterator as a [`Maybe`][sonolus.script.maybe.Maybe]."""
         raise NotImplementedError
 
     def __next__(self) -> T:
@@ -120,7 +122,7 @@ class _FilteringIterator[T, Fn](Record, SonolusIterator):
 
 @meta_fn
 def maybe_next[T](iterator: Iterator[T]) -> Maybe[T]:
-    """Get the next item from an iterator as a `Maybe` if it exists or `Nothing` otherwise."""
+    """Get the next item from an iterator as a [`Maybe`][sonolus.script.maybe.Maybe]."""
     from sonolus.backend.visitor import compile_and_call
 
     if not isinstance(iterator, SonolusIterator):

sonolus/script/maybe.py

@@ -14,10 +14,11 @@ from sonolus.script.values import copy, zeros
 class Maybe[T](TransientValue):
     """A type that either has a value or is empty.
 
-    Maybe has special behavior when returned from a function: it may be returned from multiple places
-    in a function, provided that all but one return statement returns the literal `Nothing`.
+    `Maybe` has special behavior when returned from a function: unlike records and arrays, it may be returned from
+    multiple places in a function, provided that all but one return statement returns the literal
+    [`Nothing`][sonolus.script.maybe.Nothing].
 
-    This type is not intended for other uses, such as being stored in a Record, Array, or Archetype.
+    Storing values of this type in a Record, Array, or Archetype is not supported.
 
     Usage:
         ```python
@@ -73,28 +74,30 @@ class Maybe[T](TransientValue):
     def map[R](self, fn: Callable[[T], R], /) -> Maybe[R]:
         """Map the contained value to a new value using the provided function.
 
-        If the value is not present, returns `Nothing`.
+        If the value is not present, returns [`Nothing`][sonolus.script.maybe.Nothing].
 
         Args:
             fn: A function that takes the contained value and returns a new value.
 
         Returns:
-            A `Maybe` instance containing the result of the function if the value is present, otherwise `Nothing`.
+            A [`Maybe`][sonolus.script.maybe.Maybe] instance containing the result of the function if the value
+            is present, otherwise [`Nothing`][sonolus.script.maybe.Nothing].
         """
         if self.is_some:
             return Some(fn(self.get_unsafe()))
         return Nothing
 
     def flat_map[R](self, fn: Callable[[T], Maybe[R]], /) -> Maybe[R]:
-        """Flat map the contained value to a new `Maybe` using the provided function.
+        """Flat map the contained value to a new [`Maybe`][sonolus.script.maybe.Maybe] using the provided function.
 
-        If the value is not present, returns `Nothing`.
+        If the value is not present, returns [`Nothing`][sonolus.script.maybe.Nothing].
 
         Args:
-            fn: A function that takes the contained value and returns a new `Maybe`.
+            fn: A function that takes the contained value and returns a new [`Maybe`][sonolus.script.maybe.Maybe].
 
         Returns:
-            A `Maybe` instance containing the result of the function if the value is present, otherwise `Nothing`.
+            A [`Maybe`][sonolus.script.maybe.Maybe] instance containing the result of the function if the value
+            is present, otherwise [`Nothing`][sonolus.script.maybe.Nothing].
         """
         if self.is_some:
             return fn(self.get_unsafe())
@@ -216,13 +219,13 @@ class Maybe[T](TransientValue):
 
 
 def Some[T](value: T) -> Maybe[T]:  # noqa: N802
-    """Create a `Maybe` instance with a value.
+    """Create a [`Maybe`][sonolus.script.maybe.Maybe] instance with a value.
 
     Args:
         value: The contained value.
 
     Returns:
-        A `Maybe` instance that contains the provided value.
+        A [`Maybe`][sonolus.script.maybe.Maybe] instance that contains the provided value.
     """
     return Maybe(present=True, value=value)
 
@@ -231,7 +234,7 @@ Nothing: Maybe[Any] = Maybe(present=False, value=None)  # type: ignore
 
 # Note: has to come after the definition to hide the definition in the docs.
 Nothing: Maybe[Any]
-"""The empty `Maybe` instance."""
+"""The empty [`Maybe`][sonolus.script.maybe.Maybe] instance."""
 
 
 @meta_fn

sonolus/script/sprite.py

@@ -291,7 +291,7 @@ def skin[T](cls: type[T]) -> T | Skin:
         ```python
         @skin
         class Skin:
-            render_mode: RenderMode
+            render_mode: RenderMode = RenderMode.LIGHTWEIGHT
 
             note: StandardSprite.NOTE_HEAD_RED
             other: Sprite = skin_sprite("other")

sonolus/script/stream.py

@@ -63,7 +63,8 @@ class _StreamDataField(SonolusDescriptor):
 def streams[T](cls: type[T]) -> T:
     """Decorator to define streams and stream groups.
 
-    Streams and stream groups are declared by annotating class attributes with `Stream` or `StreamGroup`.
+    Streams and stream groups are declared by annotating class attributes with
+    [`Stream`][sonolus.script.stream.Stream] or [`StreamGroup`][sonolus.script.stream.StreamGroup].
 
     Other types are also supported in the form of data fields. They may be used to store additional data to export from
     Play to Watch mode.
@@ -180,8 +181,8 @@ class _SparseStreamBacking(BackingValue):
 class Stream[T](Record):
     """Represents a stream.
 
-    Most users should use [`@streams`][sonolus.script.stream.streams] to declare streams and stream groups rather than
-    using this class directly.
+    Most users should use [`@streams`][sonolus.script.stream.streams] to declare streams and stream groups, rather than
+    creating instances of this class directly.
 
     If used directly, it is important that streams do not overlap. No other streams should have an offset in
     `range(self.offset, self.offset + max(1, sizeof(self.element_type())))`, or they will overlap and interfere
@@ -285,12 +286,12 @@ class Stream[T](Record):
         return previous_key < key
 
     def next_key_inclusive(self, key: int | float) -> int | float:
-        """Like `next_key`, but returns the key itself if it is in the stream."""
+        """Like [`next_key`][sonolus.script.stream.Stream.next_key], but returns the key itself if it is in the stream."""
         _check_can_read_stream()
         return key if key in self else self.next_key(key)
 
     def previous_key_inclusive(self, key: int | float) -> int | float:
-        """Like `previous_key`, but returns the key itself if it is in the stream."""
+        """Like [`previous_key`][sonolus.script.stream.Stream.previous_key], but returns the key itself if it is in the stream."""
         _check_can_read_stream()
         return key if key in self else self.previous_key(key)
 

{sonolus_py-0.4.1.dist-info → sonolus_py-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.4.1
+Version: 0.5.0
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12

{sonolus_py-0.4.1.dist-info → sonolus_py-0.5.0.dist-info}/RECORD

@@ -10,11 +10,11 @@ sonolus/backend/mode.py,sha256=NkcPZJm8dn83LX35uP24MtQOCnfRDFZ280dHeEEfauE,613
 sonolus/backend/node.py,sha256=eEzPP14jzWJp2xrZCAaPlNtokxdoqg0bSM7xQiwx1j8,1254
 sonolus/backend/ops.py,sha256=5weB_vIxbkwCSJuzYZyKUk7vVXsSIEDJYRlvE-2ke8A,10572
 sonolus/backend/place.py,sha256=7qwV732hZ4WP-9GNN8FQSEKssPJZELip1wLXTWfop7Y,4717
-sonolus/backend/utils.py,sha256=c8zje-7-lmRHW14YbVZPGbLbvN9pe3eFqTRus5i2NR8,2441
-sonolus/backend/visitor.py,sha256=NIs3OPBhGoHjoApem2MSLxqKwhA8xvuVSxKJlG3HrMI,62160
+sonolus/backend/utils.py,sha256=DDgYUVHh4h_eSY65v2KcxUaLSBYGYS6oHar5gTdV7QU,2356
+sonolus/backend/visitor.py,sha256=UAdp3Lg9kFVcFmBfn6rqpE9xM_CWBWlsB2o6OJiFqxQ,63193
 sonolus/backend/optimize/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sonolus/backend/optimize/allocate.py,sha256=CuumoMphkpQlGRNeKLHT4FBGE0XVj5pwhfNdrqiLFSs,7535
-sonolus/backend/optimize/constant_evaluation.py,sha256=OyjlgHIT6oPKCyBtNzEpo1nWYjr-_mwYUo8FrNV4eO4,21331
+sonolus/backend/optimize/constant_evaluation.py,sha256=U--9moGsXFzrgweWWwHIiEuuMzwetd1IOjjtrCscoNM,21450
 sonolus/backend/optimize/copy_coalesce.py,sha256=45YL7QmRLL-FiQX4sDs56o4hyP7lX8KIJ0lIbyVw8h8,4549
 sonolus/backend/optimize/dead_code.py,sha256=ZRJ95zJ49R-wZTzJtcSSbl5LYKHWI-byHM3n6jOyAqc,8307
 sonolus/backend/optimize/dominance.py,sha256=3jAgXqXTbuYLpXvIm8UB06NkIOLtaoVp7pBVPcLb5vY,3259
@@ -26,29 +26,29 @@ sonolus/backend/optimize/passes.py,sha256=YyFKy6qCwcR_Ua2_SXpcBODfvBbm_ygVYcqloO
 sonolus/backend/optimize/simplify.py,sha256=RDNVTKfC7ByRyxY5z30_ShimOAKth_pKlVFV_36pDG4,14082
 sonolus/backend/optimize/ssa.py,sha256=raQO0furQQRPYb8iIBKfNrJlj-_5wqtI4EWNfLZ8QFo,10834
 sonolus/build/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sonolus/build/cli.py,sha256=jzJVdPdEn0uaEbv5B7BuQZioytAeG9P2vDXwiRTXA8s,10113
+sonolus/build/cli.py,sha256=-_lTN8zT7nQB2lySM8itAEPVutcEQI-TJ13BcPIfGb4,10113
 sonolus/build/collection.py,sha256=kOVnpQC_KHAsyTM4nAplSh6QE16CgO-H6PP1GItWm78,12187
-sonolus/build/compile.py,sha256=hF8CnaqMQqak4OyEQvxJLo_mpzZDQipMa14syZsWLEA,5976
+sonolus/build/compile.py,sha256=B7w6Uqa4HlZPNklNhhjJoq9ncXMVXLCYabGLxtxWGV4,6521
 sonolus/build/engine.py,sha256=zUl0KfRygqNhIM8BABNJkKG-0zXFwcYwck-5hJy59yk,13338
 sonolus/build/level.py,sha256=yXsQtnabkJK0vuVmZ_Wr1jx37jFLgInCS7lTlXjkv9Q,706
 sonolus/build/node.py,sha256=gnX71RYDUOK_gYMpinQi-bLWO4csqcfiG5gFmhxzSec,1330
 sonolus/build/project.py,sha256=mv2OuzgIDG-E9G4SIRiUDL5XiPCd1i81wVl1p7itFHA,6329
 sonolus/script/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sonolus/script/archetype.py,sha256=vNNX6YGi_CUQcjf0xG1Rkpz9kUd_84hEPuY1Ew9uFxA,41666
-sonolus/script/array.py,sha256=lnobVrrEOE6PgPasq3DovrshlDKPbX8kKUsGmJz2oK0,12360
+sonolus/script/archetype.py,sha256=HJeKJ_vj7xUYaCAmNdGYO45rhFMSLMwOLyvpKjulfVY,42418
+sonolus/script/array.py,sha256=9uOUHZIDMyMT9q3APcXJWXWt97yG-AZoRlxwrvSY6SU,12367
 sonolus/script/array_like.py,sha256=jFOfXkniTLrIK4ER6HO_tUyKn_TvwjyM4B3SDd9cUS8,9678
-sonolus/script/bucket.py,sha256=5VU-Bh7qYifl6NcgZFCo7eAEgi3iGTX-PUTmXiPCJaQ,7535
-sonolus/script/containers.py,sha256=FDz3cJlxUdxtXe_vbmuonob1xnb_QzH66uVF--bfDu0,18669
+sonolus/script/bucket.py,sha256=VxsSgHidYhY_Y5UXpBZY_tzjQff0TRgNJVj4Al8LVec,7654
+sonolus/script/containers.py,sha256=WX0qRnr6gNtn3C0q7MwMyrzvY-C0Bd1tzLGxSkUwL9U,18680
 sonolus/script/debug.py,sha256=_Hg1cXQJ8fBXMiwhmoPb2X9CKcQ8QO26WNa59K518og,4305
-sonolus/script/easing.py,sha256=7zaDKIfM_whUpb4FBz1DAF4NNG2vk_nDjl8kL2Y90aU,11396
-sonolus/script/effect.py,sha256=pqfsOhmGVDMkifumkRr9rD2trWZU6Rw-_gTApNIaz7g,5854
+sonolus/script/easing.py,sha256=txf0OPFP5v7cOFDvJKCyKLK-d2uKIOu56ntLEHfD9QI,11377
+sonolus/script/effect.py,sha256=mhl58IgHUl7GI6kDdwK6l_KWVXYWxxpAcfOjSkdrLj4,5944
 sonolus/script/engine.py,sha256=etI9dJsQ7V9YZICVNZg54WqpLijPxG8eTPHiV-_EiG8,10687
-sonolus/script/globals.py,sha256=FOv8uiLM5U6X-yMLCXukMvLgV3rs-xVJbobST_MhLcU,9782
+sonolus/script/globals.py,sha256=USwh_TuyZh1qORPVLk6x9qe3ca9iLhf5gnqT773gVvY,10007
 sonolus/script/instruction.py,sha256=iBjY7nCNDT3w0SBJKlix3Z-85e7eE2qKeHp6C2Nq7KA,6753
 sonolus/script/interval.py,sha256=dj6F2wn5uP6I6_mcZn-wIREgRUQbsLzhvhzB0oEyAdU,11290
-sonolus/script/iterator.py,sha256=ESZ3opzDTXmkRMxF8itp9_bywXDiufn9cRtgWAw9m-w,3601
+sonolus/script/iterator.py,sha256=_ICY_yX7FG0Zbgs3NhVnaIBdVDpAeXjxJ_CQtq30l7Y,3774
 sonolus/script/level.py,sha256=vnotMbdr_4-MJUsTXMbvWiw2MlMjMHme3q0XRdNFXRg,6349
-sonolus/script/maybe.py,sha256=UfF26g6BF_KGuHYGuEeuxeGKSmIH-fYAVHi9I-adp9E,7785
+sonolus/script/maybe.py,sha256=VYvTWgEfPzoXqI3i3zXhc4dz0pWBVoHmW8FtWH0GQvM,8194
 sonolus/script/metadata.py,sha256=ttRK27eojHf3So50KQJ-8yj3udZoN1bli5iD-knaeLw,753
 sonolus/script/num.py,sha256=924kWWZusW7oaWuvtQzdAMzkb4ZItWSJwNj3W9XrqZU,16041
 sonolus/script/options.py,sha256=KlOud4QOf_lW1o6avKXbkjcMCDPkhLcEwt5PW7ZCH3s,9435
@@ -59,8 +59,8 @@ sonolus/script/project.py,sha256=2XVUXcW49iiTfljvcFuYqtFzqhQIRvD7H7OwH1Mm98w,400
 sonolus/script/quad.py,sha256=XoAjaUqR60zIrC_CwheZs7HwS-DRS58yUmlj9GIjX7k,11179
 sonolus/script/record.py,sha256=-Ff60wBoF1v4-MJWzCNI9n5K3os6WphswZpdTBezeRs,12713
 sonolus/script/runtime.py,sha256=rJZM_KbKmnwpjhDEpR0DrM6EMSEu46apIErWA_pfLJA,33321
-sonolus/script/sprite.py,sha256=mMDTXckn58YR8mrx3fzdBaduQ8cn9YTtTVruXXK1ow0,16272
-sonolus/script/stream.py,sha256=4b0AV5MRPo4wzTHmaN95jwODxPVt6WuN3QxmGccdwRU,24517
+sonolus/script/sprite.py,sha256=pgFQvzWB-uy9MsOfV8QabXKjnNgx5vN6md9uNYztHco,16297
+sonolus/script/stream.py,sha256=q3uJUfUP9fx0Go7qXQopl9DMh_RJkT-96p5WlAo4x0M,24693
 sonolus/script/text.py,sha256=wxujIgKYcCfl2AD2_Im8g3vh0lDEHYwTSRZg9wsBPEU,13402
 sonolus/script/timing.py,sha256=ZR0ypV2PIoDCMHHGOMfCeezStCsBQdzomdqaz5VKex0,2981
 sonolus/script/transform.py,sha256=w5mr7hTuNYU0eTAdnN_wTVibaQa0mZrkl-W-kgewJxQ,21345
@@ -68,26 +68,26 @@ sonolus/script/ui.py,sha256=DYPGWIjHj1IFPxW1zaEuIUQx0b32FJPXtiwCvrtJ6oo,7528
 sonolus/script/values.py,sha256=6iJG6h4IDlbcK8FH4GENSHOQc7C_7fCGa34wM80qToA,1629
 sonolus/script/vec.py,sha256=oVx5C5zGj8gX37F7y1FEJOrTYzb7EWfQWQuKU8KGLdc,7486
 sonolus/script/internal/__init__.py,sha256=T6rzLoiOUaiSQtaHMZ88SNO-ijSjSSv33TKtUwu-Ms8,136
-sonolus/script/internal/builtin_impls.py,sha256=vzyaSTsxoZoE6a-aBBHn4aIfjGxxYzojEnOog3-HETI,12686
+sonolus/script/internal/builtin_impls.py,sha256=POmWRyTQa-9mpQ_jATDYlFWo_n0a65vXAgqitkKYzGY,12870
 sonolus/script/internal/callbacks.py,sha256=vWzJG8uiJoEtsNnbeZPqOHogCwoLpz2D1MnHY2wVV8s,2801
 sonolus/script/internal/constant.py,sha256=3ycbGkDJVUwcrCZ96vLjAoAARgsvaqDM8rJ_YCrLrvo,4289
-sonolus/script/internal/context.py,sha256=8wLclCnLyDJt7BGbSqMD6rngYt9jI2JYji6XV8cbCAw,16742
+sonolus/script/internal/context.py,sha256=qn8xp5BB1C3IaUS8jsSUfkMUJgPzeaIV7K4FY9mHHQo,16903
 sonolus/script/internal/descriptor.py,sha256=XRFey-EjiAm_--KsNl-8N0Mi_iyQwlPh68gDp0pKf3E,392
 sonolus/script/internal/dict_impl.py,sha256=alu_wKGSk1kZajNf64qbe7t71shEzD4N5xNIATH8Swo,1885
 sonolus/script/internal/error.py,sha256=ZNnsvQVQAnFKzcvsm6-sste2lo-tP5pPI8sD7XlAZWc,490
 sonolus/script/internal/generic.py,sha256=F0-cCiRNGTaUJvYlpmkiOsU3Xge_XjoBpBwBhH_qS_s,7577
-sonolus/script/internal/impl.py,sha256=I3IlPZZZtXVJb044cpULg5FDYUjiLtAucnsA6w_0xUk,3233
+sonolus/script/internal/impl.py,sha256=alcFJs1yDx9ixEOxg-r_1IvWG2arMSUKSc-Eg9nAHOw,3255
 sonolus/script/internal/introspection.py,sha256=MfdXo3GFHNZT2-vAKuvsE54V-5TOfbg4vU9dBI6sLqo,1032
 sonolus/script/internal/math_impls.py,sha256=nHSLgA7Tcx7jY1p07mYBCeSRmVx713bwdNayCIcaXSE,2652
-sonolus/script/internal/native.py,sha256=WrZ3sVYfrc9plFxJJSWCqwq3ymruw3WhET_UjmhKj38,1628
+sonolus/script/internal/native.py,sha256=DQxmzxgLG_UsLpXhIEtBdO7eIeDFprU78UBDC4OZzw0,1597
 sonolus/script/internal/random.py,sha256=6Ku5edRcDUh7rtqEEYCJz0BQavw69RALsVHS25z50pI,1695
 sonolus/script/internal/range.py,sha256=YeqB1TPh7JdvW6kDuA5tpQL5psVxYQjepBZs7RNcP5Y,3426
 sonolus/script/internal/simulation_context.py,sha256=LGxLTvxbqBIhoe1R-SfwGajNIDwIJMVsHle0kvzd500,4818
 sonolus/script/internal/transient.py,sha256=y2AWABqF1aoaP6H4_2u4MMpNioC4OsZQCtPyNI0txqo,1634
 sonolus/script/internal/tuple_impl.py,sha256=DPNdmmRmupU8Ah4_XKq6-PdT336l4nt15_uCJKQGkkk,3587
 sonolus/script/internal/value.py,sha256=OngrCdmY_h6mV2Zgwqhuo4eYFad0kTk6263UAxctZcY,6963
-sonolus_py-0.4.1.dist-info/METADATA,sha256=WBzfeJ7FRbh942MqkM1vjS7k98pHoZ52YsseEMn9OlY,302
-sonolus_py-0.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sonolus_py-0.4.1.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
-sonolus_py-0.4.1.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
-sonolus_py-0.4.1.dist-info/RECORD,,
+sonolus_py-0.5.0.dist-info/METADATA,sha256=UCeZWEVfiGWGob4XES8cE9MgkmE44kD_6PJ-dVEQypI,302
+sonolus_py-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sonolus_py-0.5.0.dist-info/entry_points.txt,sha256=oTYspY_b7SA8TptEMTDxh4-Aj-ZVPnYC9f1lqH6s9G4,54
+sonolus_py-0.5.0.dist-info/licenses/LICENSE,sha256=JEKpqVhQYfEc7zg3Mj462sKbKYmO1K7WmvX1qvg9IJk,1067
+sonolus_py-0.5.0.dist-info/RECORD,,