sonolus.py 0.4.1__tar.gz → 0.4.2__tar.gz

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/PKG-INFO

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

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/docs/concepts/constructs.md

@@ -394,7 +394,9 @@ def g(a):
 
 Function returns follow the same rules as variable access. If a function returns a non-num value, it most only
 return that value. If the function always returns a num, it may have any number of returns. Similarly, if a function
-always returns None (`return None` or just `return`), it may have any number of returns.
+always returns None (`return None` or just `return`), it may have any number of returns. 
+The [`Maybe`][sonolus.script.maybe.Maybe] is also an exception, see the 
+[Maybe documentation](../reference/sonolus.script.maybe.md) for details
 
 The following are allowed:
 

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/docs/concepts/types.md

@@ -118,13 +118,10 @@ a2 = Array[int, 0]()
 a3 = +Array[int, 3]  # Create a zero-initialized array
 ```
 
-For type checker compatibility, `Literal` or [`Dim`][sonolus.script.array.Dim] can also be used to specify the size of
-the array:
-
+For type checker compatibility, the Python builtin `typing.Literal` or [`Dim`][sonolus.script.array.Dim] may be used
+for an array's size:
 ```python
-from sonolus.script.array import Dim
-
-a1 = Array[int, Dim(3)](1, 2, 3)
+a1 = Array[int, Dim[3]](1, 2, 3)
 a2 = Array[int, Literal[3]](1, 2, 3)
 ```
 

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/docs/index.md

@@ -13,12 +13,17 @@ Sonolus.py is available on PyPI and can be installed using a package manager lik
     uv add sonolus.py
     ```
 
+
 ## Getting Started
-Example Projects:
 
-- [pydori](https://github.com/qwewqa/pydori): A Bandori-like engine designed to be an example project for Sonolus.py.
+Before making a new Sonolus.py engine or even reading through the rest of this documentation, it may be helpful to look 
+at some examples to get a sense of how Sonolus.py is used.
+
+The [pydori](https://github.com/qwewqa/pydori) engine is an example Sonolus.py engine that implements a Bandori-style
+(vertical scrolling rhythm game) engine.
 
-New Project Template: [sonolus.py-template-project](https://github.com/qwewqa/sonolus.py-template-project)
+Once you're ready to start a new project, you may want to use the
+[new project template](https://github.com/qwewqa/sonolus.py-template-project).
 
 ## Documentation
 

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/docs/overview.md

@@ -1,14 +1,14 @@
 # Overview
 
-Sonolus.py is a Python library for creating Sonolus engines. This page provides an overview of the key functionality 
-available in the library. For more detailed information, see the [Concepts](concepts/index.md) and 
+Sonolus.py is a Python library for creating Sonolus engines. This page provides an overview of the key functionality
+available in the library. For detailed information, see the [Concepts](concepts/index.md) and
 [Reference](reference/index.md) sections.
 
 ## Language
 
-Sonolus.py functions by compiling Python code into Sonolus nodes. As such, it supports a subset of Python including
+Sonolus.py compiles Python code into Sonolus nodes. It supports a subset of Python including
 most syntax and a portion of the standard library. Additionally, Sonolus.py provides its own library of types and
-functions that are specifically designed for use in Sonolus engines.
+functions that are designed for use in Sonolus engines.
 
 ### Syntax
 
@@ -26,7 +26,7 @@ Most Python syntax is supported, but there are a few limitations. The primary re
 Sonolus.py will evaluate some expressions at compile time such as basic arithmetic operations on constants,
 boolean logical operations (`and`, `or`, `not`) on constants, and type checks (`isinstance`, `issubclass`).
 
-In control flow constructs like `if` and `match`, Sonolus.py may determine some branches to be unreachable at compile 
+In control flow constructs like `if` and `match`, Sonolus.py may determine some branches to be unreachable at compile
 and eliminate them without evaluating them. This allows code like the following to compile successfully:
 
 ```python
@@ -60,16 +60,16 @@ debug_log(a.x)
 Similar to variables, functions returning `int`, `float`, or `bool` can have any number of return statements. Functions
 returning `None` may also have any number of `return` or `return None` statements.
 
-Functions returning any other type must have exactly one `return` statement, and it must be the only exit point of the 
-function. It is ok, however, for a function to have other `return` statements that are eliminated at compile time. 
+Functions returning any other type must have exactly one `return` statement, and it must be the only exit point of the
+function [^1]. It is ok, however, for a function to have other `return` statements that are eliminated at compile time.
 For example, the following code will compile successfully:
 
 ```python
 def fn(a: int | Vec2):
     if isinstance(a, Vec2):
-        return a.x + a.y
+        return Vec2(a.x, a.y)
     else:
-        return a * 2
+        return Vec2(a, a)
 
 fn(123)
 ```
@@ -79,12 +79,12 @@ fn(123)
 ### Numbers
 
 Sonolus.py supports `int`, `float`, and `bool` types and most of the standard operations such as mathematical operations
-(`+`, `-`, `*`, `/`, `//`, `%`), comparisons (`<`, `<=`, `>`, `>=`, `==`, `!=`), and boolean operations 
+(`+`, `-`, `*`, `/`, `//`, `%`), comparisons (`<`, `<=`, `>`, `>=`, `==`, `!=`), and boolean operations
 (`and`, `or`, `not`).
 
 ### Record
 
-[`Record`](reference/sonolus.script.record.md) is the main way to define custom types in Sonolus.py. 
+[`Record`](reference/sonolus.script.record.md) is the main way to define custom types in Sonolus.py.
 It functions similarly to a data class and provides a way to define a type with named fields:
 
 ```python
@@ -116,7 +116,7 @@ assert record_1.a == record_2.value.a == 789
 
 ### Array
 
-[`Array`](reference/sonolus.script.array.md) is a type that represents a fixed-size array of elements of a 
+[`Array`](reference/sonolus.script.array.md) is a type that represents a fixed-size array of elements of a
 specific type:
 
 ```python
@@ -162,7 +162,7 @@ record_2 = +Array[int, 3]
 Records and arrays can be mutated in-place using the `@=` operator:
 
 ```python
-record_1 @= MyRecord(1, 2.3) 
+record_1 @= MyRecord(1, 2.3)
 array_1 @= Array(4, 5, 6)
 ```
 
@@ -192,10 +192,12 @@ assert record_1 == array_1[0] == MyRecord(4, 5.6)
 ```
 
 ### Other Types
+
 Sonolus.py has limited support for other types of values such as strings, tuples, and functions. These have restrictions
 such as not being valid as Record field types or Array element types.
 
 ## Modules
+
 Sonolus.py provides a number of built-in modules that can be used in Sonolus engines. These include:
 
 - Project
@@ -227,7 +229,7 @@ Sonolus.py provides a number of built-in modules that can be used in Sonolus eng
     - [random](reference/random.md): Supported random functions.
 - Utilities
     - [ArrayLike](reference/sonolus.script.array_like.md): Mixin for array functionality.
-    - [Containers](reference/sonolus.script.containers.md): Additional container types like `VarArray` and `ArrayMap`.
+    - [Containers](reference/sonolus.script.containers.md): Additional container types like [`VarArray`][sonolus.script.containers.VarArray] and [`ArrayMap`][sonolus.script.containers.ArrayMap].
     - [Debug](reference/sonolus.script.debug.md): Debugging utilities.
     - [Easing](reference/sonolus.script.easing.md): Easing functions for animations.
     - [Interval](reference/sonolus.script.interval.md): Mathematical intervals.
@@ -241,12 +243,6 @@ Sonolus.py provides a number of built-in modules that can be used in Sonolus eng
 
 For more details, see the [Reference](reference/index.md) section.
 
-## Getting Started
-
-Before making a new Sonolus.py engine, it may be helpful to look at some existing projects to see how they use
-the library:
-
-- [pydori](https://github.com/qwewqa/pydori): A Bandori-like engine designed to be an example project for Sonolus.py.
-
-If you're starting a new project, you'll probably want to use the
-[new project template](https://github.com/qwewqa/sonolus.py-template-project).
+[^1]:
+    The [`Maybe`][sonolus.script.maybe.Maybe] type is an exception to this rule. 
+    See the [`Maybe` documentation](reference/sonolus.script.maybe.md) for details.

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sonolus.py"
-version = "0.4.1"
+version = "0.4.2"
 description = "Sonolus engine development in Python"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -18,7 +18,7 @@ target-version = "py312"
 [tool.ruff.lint]
 preview = true
 select = ["F", "E", "W", "I", "N", "D", "UP", "YTT", "B", "A", "COM", "C4", "DTZ", "PIE", "PT", "Q", "SLOT", "SIM", "PTH", "PL", "PERF", "FURB", "LOG", "RUF"]
-ignore = ["E402", "D1", "COM812", "PLW2901", "PLW3201", "PLR6301", "PLC0415", "PLR2004", "PLR09", "SIM108", "FURB113", "A005", "B903", "FURB118"]
+ignore = ["E402", "D1", "COM812", "PLW2901", "PLW3201", "PLR6301", "PLC0415", "PLR2004", "PLR09", "SIM108", "FURB113", "A005", "B903", "FURB118", "E501"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/sonolus/backend/visitor.py

@@ -11,7 +11,7 @@ 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.constant import ConstantValue
@@ -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):
@@ -1423,6 +1426,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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/sonolus/script/easing.py

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

{sonolus_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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_py-0.4.1 → sonolus_py-0.4.2}/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