arcadeturtle 0.1.0__py3-none-any.whl

arcadeturtle/__init__.py

@@ -0,0 +1,33 @@
+"""ArcadeTurtle — همان API ماژول turtle، روی موتور Arcade."""
+
+from ._errors import ArcadeTurtleError, Terminator
+from .api import *  # noqa: F401,F403 — API تابعی سراسری
+from .api import (  # صریح، برای ابزارهای تحلیل کد
+    addshape, backward, begin_fill, begin_poly, bgcolor, bgpic, bk, back,
+    bye, circle, clear, clearscreen, clearstamp, clearstamps, clone, color,
+    colormode, degrees, delay, distance, done, dot, down, end_fill,
+    end_poly, exitonclick, fd, fillcolor, filling, forward, getcanvas,
+    getpen, get_poly, get_shapepoly, getshapes, getturtle, goto, heading,
+    hideturtle, home, ht, isdown, isvisible, left, lt, mainloop, mode,
+    pen, pencolor, pendown, pensize, penup, pd, pos, position, pu,
+    radians, register_shape,
+    reset, resetscreen, resizemode, right, rt, screensize, seth, setheading,
+    setpos, setposition, settiltangle, setup, setworldcoordinates, setx,
+    sety, shapetransform, shearfactor, teleport, tilt, tiltangle, listen,
+    onclick, ondrag, onkey, onkeypress, onkeyrelease, onrelease,
+    onscreenclick, ontimer, shape,
+    shapesize, showturtle, speed, st, stamp, textinput, title, towards,
+    tracer, turtles, turtlesize, undo, undobufferentries, setundobuffer, up,
+    update, numinput, width, window_height, window_width, write,
+    write_docstringdict, xcor, ycor,
+)
+from .screen import Screen, ScrolledCanvas, TurtleScreen
+from .turtle_obj import Pen, RawPen, RawTurtle, Turtle
+from ._shapes import Shape
+from ._vec2d import Vec2D
+
+
+def getscreen():
+    return Screen()
+
+__version__ = "0.1.0"

arcadeturtle/_commands.py

@@ -0,0 +1,45 @@
+"""فرمان‌های صف — واحدهای پخش انیمیشن در Engine.
+
+هر فراخوانی API کاربر در حالت RECORDING یکی از این‌ها را به صف سراسری اضافه می‌کند.
+ترتیب صف = ترتیب فراخوانی برنامه (یک صف واحد برای همه لاک‌پشت‌ها).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+Point = tuple[float, float]
+Color = tuple[int, int, int]
+
+
+@dataclass
+class MoveCmd:
+    """حرکت خطی (forward/backward/goto). انیمیشن با سرعت خطی."""
+    turtle_id: int
+    start: Point
+    end: Point
+    pen_down: bool
+    color: Color
+    size: int
+    speed: int  # سرعت لاک‌پشت در لحظه ثبت فرمان
+
+
+@dataclass
+class RotateCmd:
+    """چرخش (left/right/setheading). انیمیشن با سرعت زاویه‌ای."""
+    turtle_id: int
+    start_heading: float
+    end_heading: float
+    delta: float  # علامت‌دار: مثبت = پادساعتگرد؛ اندازه واقعی چرخش
+    speed: int
+
+
+@dataclass
+class InstantCmd:
+    """فرمان بدون انیمیشن (penup، رنگ، dot، write، ...).
+
+    fn وقتی نوبتش در صف رسید اجرا می‌شود تا ترتیب دیداری حفظ شود.
+    """
+    turtle_id: int
+    fn: Callable[[], None]

arcadeturtle/_coords.py

@@ -0,0 +1,46 @@
+"""تبدیل مختصات و زاویه بین دنیای Turtle و دنیای Arcade.
+
+قرارداد Turtle: مبدأ وسط صفحه، y به بالا، زاویه صفر = شرق، درجه پادساعتگرد.
+قرارداد Arcade: مبدأ گوشه پایین-چپ، y به بالا.
+
+هیچ‌جای دیگر پروژه نباید width/2 یا height/2 اضافه کند — فقط اینجا.
+"""
+
+from __future__ import annotations
+
+# مختصات جهانی دلخواه (setworldcoordinates): (llx, lly, urx, ury) یا None
+# برای حالت پیش‌فرض. وقتی فعال است، این مستطیل به کل پنجره کشیده می‌شود —
+# اگر نسبت x/y آن با نسبت پنجره یکی نباشد، زاویه‌ها کج‌نما می‌شوند؛ همان
+# چیزی که خودِ turtle استاندارد هم صراحتاً هشدار می‌دهد.
+World = tuple[float, float, float, float]
+
+
+def to_arcade(tx: float, ty: float, width: int, height: int,
+             world: World | None = None) -> tuple[float, float]:
+    if world is None:
+        return tx + width / 2, ty + height / 2
+    llx, lly, urx, ury = world
+    ax = (tx - llx) / (urx - llx) * width
+    ay = (ty - lly) / (ury - lly) * height
+    return ax, ay
+
+
+def to_turtle(ax: float, ay: float, width: int, height: int,
+             world: World | None = None) -> tuple[float, float]:
+    if world is None:
+        return ax - width / 2, ay - height / 2
+    llx, lly, urx, ury = world
+    tx = ax / width * (urx - llx) + llx
+    ty = ay / height * (ury - lly) + lly
+    return tx, ty
+
+
+def heading_to_arcade_angle(heading: float) -> float:
+    """زاویه turtle (پادساعتگرد از شرق) → زاویه دوران چندضلعی کرسر.
+
+    چندضلعی‌های کرسر در _renderer «رو به شرق» تعریف شده‌اند و با ماتریس دوران
+    استاندارد (پادساعتگرد) چرخانده می‌شوند؛ پس heading مستقیم قابل استفاده است.
+    اگر روزی Sprite تصویری اضافه شد (Sprite.angle در Arcade 3 ساعتگرد است)،
+    تبدیلش فقط همین‌جا اضافه می‌شود.
+    """
+    return heading

arcadeturtle/_engine.py

@@ -0,0 +1,285 @@
+"""Engine — قلب کتابخانه: صف فرمان، پخش انیمیشن، مدیریت پنجره و لاک‌پشت‌ها.
+
+مدل اجرا (تصمیم ۱ پلن، ساده‌شده):
+- state «منطقی» هر لاک‌پشت همان لحظه‌ی فراخوانی API آپدیت می‌شود تا
+  کوئری‌هایی مثل position()/heading() همیشه جواب درست بدهند.
+- هر فرمان دیداری وارد یک صف واحد FIFO می‌شود (چه در اسکریپت، چه در callback).
+- tick() هر فریم صف را خالی می‌کند: با انیمیشن روی state «بصری»، یا آنی
+  (speed == 0 یا tracer(0)). چون callback ها هم به همین صف می‌ریزند، به حالت
+  LIVE جداگانه نیازی نیست — ترتیب همیشه حفظ است.
+"""
+
+from __future__ import annotations
+
+import atexit
+import math
+import sys
+import weakref
+from collections import deque
+from dataclasses import dataclass
+from enum import Enum
+
+from ._commands import InstantCmd, MoveCmd, RotateCmd
+from ._events import EventRegistry
+from ._renderer import Renderer
+from ._state import TurtleState
+
+# سرعت‌های پخش (جدول قطعی پلن)
+MOVE_PX_PER_SEC = 250
+ROTATE_DEG_PER_SEC = 400
+
+
+class Mode(Enum):
+    RECORDING = "recording"  # قبل از done()
+    PLAYING = "playing"      # داخل حلقه arcade
+
+
+@dataclass
+class TurtleRuntime:
+    logical: TurtleState
+    visual: TurtleState
+
+
+class Engine:
+    def __init__(self):
+        self.mode = Mode.RECORDING
+        # توجه: این «mode» حالت اجرای موتور است (RECORDING/PLAYING)، نه
+        # turtle-mode ی standard/logo/world که Screen.mode() کنترل می‌کند —
+        # آن یکی عمداً نام دیگری دارد تا تداخل نکنند.
+        self.mode_name = "standard"
+        self.queue: deque = deque()
+        self.turtles: dict[int, TurtleRuntime] = {}
+        # شیءهای Turtle کاربر — weak تا لاک‌پشت دورریخته نشتی حافظه نسازد.
+        # Screen.reset() برای ریست‌کردن همه لاک‌پشت‌ها به این نیاز دارد، چون
+        # Turtle.reset() به فیلدهای روی خود شیء (مثل _pen_color_raw) دست می‌زند.
+        self.turtle_objects: weakref.WeakSet = weakref.WeakSet()
+        self.active_cmd = None
+        self._progress = 0.0
+        self.tracer_n = 1
+        self._tracer_counter = 0
+        self.renderer = Renderer()
+        self.events = EventRegistry(self)
+        self.window = None
+        # تنظیمات پنجره قبل از ساخته‌شدنش
+        self.pending_width = 800
+        self.pending_height = 600
+        self.pending_title = "ArcadeTurtle"
+        self.pending_bg = (255, 255, 255)
+        self._next_turtle_id = 0
+        self._ran = False
+
+    # ---------- لاک‌پشت‌ها ----------
+
+    def new_turtle(self) -> int:
+        tid = self._next_turtle_id
+        self._next_turtle_id += 1
+        st = TurtleState()
+        self.turtles[tid] = TurtleRuntime(logical=st, visual=st.copy_pose())
+        return tid
+
+    def visible_states(self):
+        return [rt.visual for rt in self.turtles.values()]
+
+    # ---------- پنجره ----------
+
+    def ensure_window(self):
+        if self.window is None:
+            from ._window import ArcadeTurtleWindow
+            self.window = ArcadeTurtleWindow(
+                self, self.pending_width, self.pending_height, self.pending_title
+            )
+            self.window.background_color = self.pending_bg
+            self.renderer.set_size(self.pending_width, self.pending_height)
+        return self.window
+
+    def set_bgcolor(self, color) -> None:
+        self.pending_bg = color
+        if self.window is not None:
+            self.window.background_color = color
+
+    def set_title(self, text: str) -> None:
+        self.pending_title = text
+        if self.window is not None:
+            self.window.set_caption(text)
+
+    def run(self) -> None:
+        """done()/mainloop() — پنجره را می‌سازد و حلقه arcade را شروع می‌کند."""
+        if self._ran:
+            return
+        self._ran = True
+        import arcade
+        self.ensure_window()
+        self.mode = Mode.PLAYING
+        arcade.run()
+
+    # ---------- صف و پخش ----------
+
+    def submit(self, cmd) -> None:
+        self.queue.append(cmd)
+
+    def set_tracer(self, n: int) -> None:
+        self.tracer_n = n
+        if n == 0 and self.active_cmd is not None:
+            # فرمان نیمه‌کاره فوراً تمام شود
+            self.renderer.clear_live_line()
+            self._apply_instant(self.active_cmd)
+            self.active_cmd = None
+
+    def flush_turtle(self, turtle_id: int) -> None:
+        """فرمان‌های در صف یا در حال انیمیشنِ این لاک‌پشت را آنی اعمال می‌کند
+        (بدون دست‌زدن به فرمان‌های بقیه لاک‌پشت‌ها). undo() قبل از برگرداندنِ
+        آخرین اقدام از این استفاده می‌کند تا مطمئن شود چیزی نیمه‌کاره نمانده —
+        وگرنه معلوم نیست چه چیزی را باید undo کرد: خطِ هنوز پخته‌نشده، یا
+        فرمانی که هنوز حتی از صف بیرون نیامده."""
+        if self.active_cmd is not None and self.active_cmd.turtle_id == turtle_id:
+            self.renderer.clear_live_line()
+            self._apply_instant(self.active_cmd)
+            self.active_cmd = None
+        remaining = deque()
+        for cmd in self.queue:
+            if cmd.turtle_id != turtle_id:
+                remaining.append(cmd)
+            elif isinstance(cmd, InstantCmd):
+                cmd.fn()
+            else:
+                self._apply_instant(cmd)
+        self.queue = remaining
+
+    def tick(self, dt: float) -> None:
+        remaining = dt
+        while True:
+            if self.active_cmd is None:
+                if not self.queue:
+                    return
+                cmd = self.queue.popleft()
+                if isinstance(cmd, InstantCmd):
+                    cmd.fn()
+                    continue
+                if self.tracer_n == 0 or cmd.speed == 0:
+                    self._apply_instant(cmd)
+                    continue
+                if self.tracer_n > 1:
+                    # مثل tracer(n) در turtle اصلی: فقط هر n اُمین حرکت
+                    # واقعاً پخش/انیمیشن می‌شود؛ بقیه آنی اعمال می‌شوند تا
+                    # صحنه سریع‌تر جلو برود (ولی موقعیت منطقی هرگز نمی‌پرد،
+                    # چون آن از قبل هم‌زمان با فراخوانی API به‌روز شده بود).
+                    self._tracer_counter += 1
+                    if self._tracer_counter % self.tracer_n != 0:
+                        self._apply_instant(cmd)
+                        continue
+                self.active_cmd = cmd
+                self._progress = 0.0
+            if remaining <= 0:
+                return
+            remaining = self._advance(remaining)
+            if self.active_cmd is not None:
+                return  # فرمان فعال هنوز تمام نشده؛ فریم بعد ادامه می‌یابد
+
+    def _visual(self, turtle_id: int) -> TurtleState:
+        return self.turtles[turtle_id].visual
+
+    def _apply_instant(self, cmd) -> None:
+        v = self._visual(cmd.turtle_id)
+        if isinstance(cmd, MoveCmd):
+            if cmd.pen_down:
+                self.renderer.add_line(cmd.turtle_id, cmd.start, cmd.end, cmd.color, cmd.size)
+            v.x, v.y = cmd.end
+        elif isinstance(cmd, RotateCmd):
+            v.heading = cmd.end_heading % 360.0
+
+    def _advance(self, dt: float) -> float:
+        """فرمان فعال را به‌اندازه dt جلو می‌برد؛ زمانِ مصرف‌نشده را برمی‌گرداند."""
+        cmd = self.active_cmd
+        v = self._visual(cmd.turtle_id)
+        if isinstance(cmd, MoveCmd):
+            length = math.dist(cmd.start, cmd.end)
+            pps = cmd.speed * MOVE_PX_PER_SEC
+            needed = (length - self._progress) / pps if pps > 0 else 0.0
+            if dt >= needed or length == 0:
+                self.renderer.clear_live_line()
+                self._apply_instant(cmd)
+                self.active_cmd = None
+                return dt - needed
+            self._progress += dt * pps
+            t = self._progress / length
+            cur = (
+                cmd.start[0] + (cmd.end[0] - cmd.start[0]) * t,
+                cmd.start[1] + (cmd.end[1] - cmd.start[1]) * t,
+            )
+            v.x, v.y = cur
+            if cmd.pen_down:
+                self.renderer.set_live_line(cmd.start, cur, cmd.color, cmd.size)
+            return 0.0
+        if isinstance(cmd, RotateCmd):
+            total = abs(cmd.delta)
+            dps = cmd.speed * ROTATE_DEG_PER_SEC
+            needed = (total - self._progress) / dps if dps > 0 else 0.0
+            if dt >= needed or total == 0:
+                self._apply_instant(cmd)
+                self.active_cmd = None
+                return dt - needed
+            self._progress += dt * dps
+            sign = 1.0 if cmd.delta >= 0 else -1.0
+            v.heading = (cmd.start_heading + sign * self._progress) % 360.0
+            return 0.0
+        # نوع ناشناخته — نباید رخ دهد
+        self.active_cmd = None
+        return dt
+
+
+_engine: Engine | None = None
+_atexit_registered = False
+_died_with_exception = False
+
+
+def _install_excepthook() -> None:
+    """اگر اسکریپت با یک خطای واقعی بمیرد علامت می‌زند.
+
+    بدون این، هنرجویی که برنامه‌اش با خطای خودش کرش کرده بعد از traceback
+    واقعی پیام «done() را فراموش کرده‌ای» را هم می‌بیند و دنبال مشکل اشتباه
+    می‌رود. به‌جای sys.last_value (که رفتارش بین ۳.۱۰ تا ۳.۱۳ فرق دارد)
+    این‌جا hook قبلی را زنجیر می‌کنیم تا با pytest/IDE هم تداخل نکند.
+    """
+    previous = sys.excepthook
+
+    def hook(exc_type, exc, tb):
+        global _died_with_exception
+        _died_with_exception = True
+        previous(exc_type, exc, tb)
+
+    sys.excepthook = hook
+
+
+def _warn_if_done_forgotten() -> None:
+    eng = _engine
+    if eng is None or eng._ran or not eng.turtles or _died_with_exception:
+        return
+    print(
+        "\n⚠️  به نظر می‌رسد done() را فراموش کرده‌ای؛ "
+        "بدون آن پنجره هرگز باز نمی‌شود.\n"
+        "    آخرین خط برنامه‌ات را با turtle.done() تمام کن.\n",
+        file=sys.stderr,
+    )
+
+
+def get_engine() -> Engine:
+    global _engine, _atexit_registered
+    if _engine is None:
+        _engine = Engine()
+        if not _atexit_registered:
+            atexit.register(_warn_if_done_forgotten)
+            _install_excepthook()
+            _atexit_registered = True
+    return _engine
+
+
+def reset_engine() -> None:
+    """فقط برای تست‌ها — موتور فعلی را «مصرف‌شده» علامت می‌زند تا هشدار
+    فراموشیِ done() برای اسکریپت‌های آزمایشی که عمداً done() صدا نمی‌زنند
+    نمایش داده نشود. حالت رنگ هم به پیش‌فرض برمی‌گردد تا تست‌ها به هم نشت نکنند."""
+    global _engine
+    if _engine is not None:
+        _engine._ran = True
+    _engine = None
+    from ._errors import set_colormode
+    set_colormode(255)

arcadeturtle/_errors.py

@@ -0,0 +1,128 @@
+"""خطاهای مهربان فارسی و جدول رنگ‌ها."""
+
+from __future__ import annotations
+
+
+class ArcadeTurtleError(Exception):
+    """خطای آموزشی با پیام فارسی."""
+
+
+class Terminator(Exception):
+    """فقط برای سازگاری import (`from turtle import Terminator`).
+
+    در turtle استاندارد وقتی کاربر پنجره را می‌بندد ولی اسکریپت هنوز در
+    حلقه‌ی خودش دستور می‌دهد، این استثنا برای متوقف‌کردن آن حلقه raise
+    می‌شود. در ArcadeTurtle نیازی به آن نیست: بستن پنجره فقط باعث پایان
+    done()/mainloop() می‌شود و اسکریپت به همان‌جا برمی‌گردد، نه ادامه‌ی
+    یک حلقه‌ی بی‌نهایت داخل موتور."""
+
+
+# رنگ‌های رایج آموزشی (نام‌های Tk/CSS که در آموزش‌های turtle استفاده می‌شوند)
+COLOR_NAMES: dict[str, tuple[int, int, int]] = {
+    "black": (0, 0, 0), "white": (255, 255, 255),
+    "red": (255, 0, 0), "green": (0, 128, 0), "blue": (0, 0, 255),
+    "yellow": (255, 255, 0), "orange": (255, 165, 0), "purple": (128, 0, 128),
+    "pink": (255, 192, 203), "brown": (165, 42, 42), "gray": (128, 128, 128),
+    "grey": (128, 128, 128), "lightgray": (211, 211, 211),
+    "lightgrey": (211, 211, 211), "darkgray": (169, 169, 169),
+    "darkgrey": (169, 169, 169), "cyan": (0, 255, 255), "magenta": (255, 0, 255),
+    "lime": (0, 255, 0), "limegreen": (50, 205, 50), "navy": (0, 0, 128),
+    "teal": (0, 128, 128), "olive": (128, 128, 0), "maroon": (128, 0, 0),
+    "silver": (192, 192, 192), "gold": (255, 215, 0), "violet": (238, 130, 238),
+    "indigo": (75, 0, 130), "turquoise": (64, 224, 208), "salmon": (250, 128, 114),
+    "coral": (255, 127, 80), "tomato": (255, 99, 71), "orchid": (218, 112, 214),
+    "plum": (221, 160, 221), "khaki": (240, 230, 140), "beige": (245, 245, 220),
+    "ivory": (255, 255, 240), "snow": (255, 250, 250),
+    "skyblue": (135, 206, 235), "lightblue": (173, 216, 230),
+    "royalblue": (65, 105, 225), "dodgerblue": (30, 144, 255),
+    "steelblue": (70, 130, 180), "midnightblue": (25, 25, 112),
+    "darkblue": (0, 0, 139), "darkgreen": (0, 100, 0),
+    "forestgreen": (34, 139, 34), "seagreen": (46, 139, 87),
+    "springgreen": (0, 255, 127), "greenyellow": (173, 255, 47),
+    "darkred": (139, 0, 0), "crimson": (220, 20, 60), "firebrick": (178, 34, 34),
+    "hotpink": (255, 105, 180), "deeppink": (255, 20, 147),
+    "lavender": (230, 230, 250), "wheat": (245, 222, 179), "tan": (210, 180, 140),
+    "chocolate": (210, 105, 30), "sienna": (160, 82, 45),
+    "slategray": (112, 128, 144), "slategrey": (112, 128, 144),
+    "aqua": (0, 255, 255), "fuchsia": (255, 0, 255),
+    "lightgreen": (144, 238, 144), "lightyellow": (255, 255, 224),
+    "lightpink": (255, 182, 193), "peachpuff": (255, 218, 185),
+}
+
+
+# حالت رنگ، دقیقاً مثل turtle استاندارد: پیش‌فرض ۲۵۵.
+# قبلاً به‌جای این، حدس زده می‌شد که «اگر هر سه عدد بین ۰ و ۱ بودند یعنی اعشاری»،
+# ولی آن حدس (1, 1, 1) را سفید می‌کرد در حالی که turtle اصلی آن را تقریباً سیاه
+# می‌بیند — تله‌ای برای هنرجویی که آموزش ۰-۲۵۵ را دنبال می‌کند.
+_colormode: float = 255
+
+
+def get_colormode() -> float:
+    return _colormode
+
+
+def set_colormode(cmode) -> None:
+    global _colormode
+    if cmode in (1, 1.0):
+        _colormode = 1.0
+    elif cmode == 255:
+        _colormode = 255
+    else:
+        raise ArcadeTurtleError(
+            f"colormode فقط 1.0 یا 255 می‌تواند باشد، نه {cmode!r}\n"
+            "colormode(255) یعنی رنگ‌ها 0 تا 255، colormode(1.0) یعنی 0 تا 1"
+        )
+
+
+def resolve_color(value) -> tuple[int, int, int]:
+    """نام رنگ / '#rrggbb' / تاپل (r,g,b) را به تاپل ۰-۲۵۵ تبدیل می‌کند."""
+    if isinstance(value, str):
+        name = value.strip().lower().replace(" ", "")
+        if name in COLOR_NAMES:
+            return COLOR_NAMES[name]
+        if name.startswith("#") and len(name) == 7:
+            try:
+                return tuple(int(name[i:i + 2], 16) for i in (1, 3, 5))
+            except ValueError:
+                pass
+        raise ArcadeTurtleError(
+            f"رنگ '{value}' را نمی‌شناسم. 🎨\n"
+            "نمونه رنگ‌های درست: red, blue, green, yellow, purple, orange\n"
+            "یا کد رنگی مثل '#ff0000' یا تاپل مثل (255, 0, 0)"
+        )
+    if isinstance(value, (tuple, list)) and len(value) == 3:
+        try:
+            nums = [float(c) for c in value]
+        except (TypeError, ValueError):
+            raise ArcadeTurtleError(
+                f"رنگ {value!r} معتبر نیست؛ سه عدد لازم است، مثل (255, 0, 0)"
+            ) from None
+        top = _colormode
+        if all(0 <= c <= top for c in nums):
+            if top == 1.0:
+                return tuple(round(c * 255) for c in nums)
+            return tuple(round(c) for c in nums)
+        if top == 1.0:
+            raise ArcadeTurtleError(
+                f"اعداد رنگ {value!r} باید بین 0 تا 1 باشند، "
+                "چون colormode(1.0) فعال است.\n"
+                "برای رنگ‌های 0 تا 255 اول colormode(255) را صدا بزن."
+            )
+        raise ArcadeTurtleError(
+            f"اعداد رنگ {value!r} باید بین 0 تا 255 باشند.\n"
+            "برای رنگ‌های اعشاری (0 تا 1) اول colormode(1.0) را صدا بزن."
+        )
+    raise ArcadeTurtleError(
+        f"رنگ {value!r} معتبر نیست.\n"
+        "رنگ می‌تواند نام انگلیسی ('red')، کد ('#ff0000') یا تاپل (255, 0, 0) باشد."
+    )
+
+
+def require_number(value, func_name: str, example: str = "100"):
+    """اگر value عدد نبود، خطای فارسی آموزشی می‌دهد."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ArcadeTurtleError(
+            f"{func_name} یک عدد می‌خواهد، مثل {func_name}({example})\n"
+            f"ولی به آن {value!r} داده شد."
+        )
+    return value