ipycc.turtle

   1from contextlib import contextmanager
   2import math
   3import time
   4from ipycanvas import hold_canvas
   5from .sketch import Sketch
   6from ._colors import named_colors
   7
   8
   9class Vec2D(tuple):
  10    """A 2 dimensional vector class, used as a helper class
  11    for implementing turtle graphics.
  12    May be useful for turtle graphics programs also.
  13    Derived from tuple, so a vector is a tuple!
  14
  15    Provides (for `a`, `b` vectors, `k` number):
  16    -  `a+b` vector addition
  17    - `a-b` vector subtraction
  18    - `a*b` inner product
  19    - `k*a` and `a*k` multiplication with scalar
  20    - `|a|` absolute value of `a`
  21    - `a.rotate(angle)` rotation
  22    """
  23
  24    def __new__(cls, x, y):
  25        return tuple.__new__(cls, (x, y))
  26
  27    def __add__(self, other):
  28        return Vec2D(self[0] + other[0], self[1] + other[1])
  29
  30    def __mul__(self, other):
  31        if isinstance(other, Vec2D):
  32            return self[0] * other[0] + self[1] * other[1]
  33        return Vec2D(self[0] * other, self[1] * other)
  34
  35    def __rmul__(self, other):
  36        if isinstance(other, int) or isinstance(other, float):
  37            return Vec2D(self[0] * other, self[1] * other)
  38        return NotImplemented
  39
  40    def __sub__(self, other):
  41        return Vec2D(self[0] - other[0], self[1] - other[1])
  42
  43    def __neg__(self):
  44        return Vec2D(-self[0], -self[1])
  45
  46    def __abs__(self):
  47        return math.hypot(*self)
  48
  49    def rotate(self, angle: int | float):
  50        """Returns a vector with the same magnitude that is rotated
  51        counterclockwise by a given angle.
  52
  53        Argument: `angle` -- a number
  54
  55        **Example**
  56        ```python
  57        from ipycc.turtle import Vec2D
  58
  59        v1 = Vec2D(1, 0)
  60        v2 = v1.rotate(90)
  61        print(v1) # (1.00,0.00)
  62        print(v2) # (0.00,1.00)
  63        ```
  64        """
  65        perp = Vec2D(-self[1], self[0])
  66        angle = math.radians(angle)
  67        c, s = math.cos(angle), math.sin(angle)
  68        return Vec2D(self[0] * c + perp[0] * s, self[1] * c + perp[1] * s)
  69
  70    def __getnewargs__(self):
  71        return (self[0], self[1])
  72
  73    def __repr__(self):
  74        return "(%.2f,%.2f)" % self
  75
  76
  77class TurtleGraphicsError(Exception):
  78    """Some TurtleGraphics Error.
  79    """
  80
  81
  82# Shape vertices.
  83_turtle_shapes = {
  84    "arrow" : ((-10, 0), (10, 0), (0, 10)),
  85    "turtle" : ((0, 16), (-2, 14), (-1, 10), (-4, 7),
  86                (-7, 9), (-9, 8), (-6, 5), (-7, 1), (-5, -3), (-8, -6),
  87                (-6,-8), (-4, -5), (0, -7), (4, -5), (6, -8), (8, -6),
  88                (5, -3), (7, 1), (6, 5), (9, 8), (7, 9), (4, 7), (1, 10),
  89                (2, 14)),
  90    "circle" : ((10, 0), (9.51, 3.09), (8.09, 5.88),
  91                (5.88, 8.09), (3.09, 9.51), (0, 10), (-3.09, 9.51),
  92                (-5.88, 8.09), (-8.09, 5.88), (-9.51, 3.09), (-10, 0),
  93                (-9.51, -3.09), (-8.09, -5.88), (-5.88, -8.09),
  94                (-3.09, -9.51), (-0.00, -10.00), (3.09, -9.51),
  95                (5.88, -8.09), (8.09, -5.88), (9.51, -3.09)),
  96    "square" : ((10, -10), (10, 10), (-10, 10),
  97                (-10, -10)),
  98    "triangle" : ((10, -5.77), (0, 11.55),
  99                (-10, -5.77)),
 100    "classic": ((0, 0),(-5, -9),(0, -7),(5, -9)),
 101}
 102
 103
 104# Default screen configuration.
 105_screen_width = 400
 106_screen_height = 400
 107
 108
 109class _Screen:
 110    """Provide the basic graphics functionality.
 111    """
 112    def __init__(self,
 113                 width: int | float =_screen_width,
 114                 height: int | float =_screen_height):
 115        self.width = width
 116        self.height = height
 117        self._sketch = Sketch(self.width, self.height)
 118        self._sketch_manager = self._sketch.canvas._canvas_manager
 119        self._colormode = 1.0
 120        self._bgcolor = "white"
 121        self._sketch.background(self._bgcolor)
 122        self._turtles = []
 123        self._delayvalue = 10
 124        self._tracing = 1
 125        self._updatecounter = 0
 126        self.xscale = self.yscale = 1.0
 127    
 128    def _iscolorstring(self, color) -> bool:
 129        """Check if the string color is a legal Tkinter color string.
 130        """
 131        return color in named_colors
 132
 133    def _colorstr(self, color: str | tuple[int | float]) -> str:
 134        """Return color string corresponding to args.
 135
 136        Argument may be a string or a tuple of three
 137        numbers corresponding to actual colormode,
 138        i.e. in the range 0<=n<=colormode.
 139
 140        If the argument doesn't represent a color,
 141        an error is raised.
 142        """
 143        if len(color) == 1:
 144            color = color[0]
 145        if isinstance(color, str):
 146            if self._iscolorstring(color) or color == "":
 147                return named_colors[color]
 148            else:
 149                raise TurtleGraphicsError("bad color string: %s" % str(color))
 150        try:
 151            r, g, b = color
 152        except (TypeError, ValueError):
 153            raise TurtleGraphicsError("bad color arguments: %s" % str(color))
 154        if self._colormode == 1.0:
 155            r, g, b = [round(255.0 * x) for x in (r, g, b)]
 156        if not ((0 <= r <= 255) and (0 <= g <= 255) and (0 <= b <= 255)):
 157            raise TurtleGraphicsError("bad color sequence: %s" % str(color))
 158        return "#%02x%02x%02x" % (r, g, b)
 159
 160    def _color(self, cstr) -> str | tuple:
 161        if not cstr.startswith("#"):
 162            return cstr
 163        if len(cstr) == 7:
 164            cl = [int(cstr[i:i + 2], 16) for i in (1, 3, 5)]
 165        elif len(cstr) == 4:
 166            cl = [16 * int(cstr[h], 16) for h in cstr[1:]]
 167        else:
 168            raise TurtleGraphicsError("bad colorstring: %s" % cstr)
 169        return tuple(c * self._colormode / 255 for c in cl)
 170
 171    def add_turtle(self, t):
 172        """Adds a turtle to be drawn."""
 173        if t not in self._turtles:
 174            self._turtles.append(t)
 175    
 176    def _incrementudc(self):
 177        """Increment update counter."""
 178        if self._tracing > 0:
 179            self._updatecounter += 1
 180            self._updatecounter %= self._tracing
 181
 182    def _update(self):
 183        """Redraws the screen."""
 184        if self._tracing == 0:
 185            return
 186        self._incrementudc()
 187        if self._updatecounter > 0:
 188            self._sketch_manager._caching = True
 189        if self._updatecounter == 0 and self._tracing > 0:
 190            with hold_canvas():
 191                self._sketch.background(self._bgcolor)
 192                for t in self._turtles:
 193                    self._sketch.canvas.save()
 194                    self._sketch.scale(1, -1)
 195                    self._sketch.translate(0, -self.height)
 196                    self._sketch.image(t._pen, 0, 0)
 197                    self._sketch.reset_matrix()
 198                    self._sketch.canvas.restore()
 199                for t in self._turtles: 
 200                    if t.isvisible():
 201                        self._sketch.canvas.save()
 202                        self._sketch.scale(1, -1)
 203                        self._sketch.translate(0, -self.height)
 204                        x, y = t._to_screen_coords(t._position)
 205                        self._sketch.translate(x, y)
 206                        angle = math.radians(t.heading() + t.tiltangle()) - math.pi / 2
 207                        self._sketch.rotate(angle)
 208                        self._sketch.stroke(t._pencolor)
 209                        self._sketch.stroke_weight(t._outlinewidth)
 210                        self._sketch.fill(t._fillcolor)
 211                        self._sketch.begin_shape()
 212                        shape = _turtle_shapes[t._shape]
 213                        sx, sy = t._stretchfactor
 214                        for v in shape:
 215                            self._sketch.vertex(sx * v[0], sy * v[1])
 216                        self._sketch.end_shape()
 217                        self._sketch.reset_matrix()
 218                        self._sketch.canvas.restore()
 219            self._sketch_manager._caching = False
 220            self._sketch_manager.flush()
 221
 222    def _delay(self, ms: int | float):
 223        """Delays animation for a given number of milliseconds."""
 224        time.sleep(ms * 0.001)
 225    
 226    def replace(self):
 227        """Copy the screen and reassign its turtles."""
 228        screen = _Screen(self.width, self.height)
 229        screen._bgcolor = self._bgcolor
 230        screen._sketch.background(self._bgcolor)
 231        screen._turtles = self._turtles
 232        screen._delayvalue = self._delayvalue
 233        screen._tracing = self._tracing
 234        screen._updatecounter = self._updatecounter
 235        screen.xscale = self.xscale
 236        screen.yscale = self.yscale
 237        return screen
 238
 239    def show(self):
 240        """Display the screen's drawing canvas."""
 241        self._update()
 242        self._sketch.show()
 243
 244
 245# Screen singleton.
 246_SCREEN = _Screen()
 247
 248
 249def setup(width: int | float, height: int | float):
 250    """Sets the size of the screen.
 251
 252    Arguments:
 253    - `width` -- a number
 254    - `height` -- a number
 255
 256    The first two arguments, `width` and `height`, set the width of the
 257    drawing screen in pixels.
 258
 259    Calling `setup()` will resize the screen and all turtles will be reset.
 260
 261    **Example**
 262    ```python
 263    from ipycc.turtle import Turtle, showscreen, setup
 264
 265    # Show the screen.
 266    showscreen()
 267
 268    # Set the screen to half size.
 269    setup(200, 200)
 270
 271    # Create a turtle.
 272    t = Turtle()
 273    ```
 274    """
 275    global _SCREEN
 276    new_screen = _Screen(width, height)
 277    new_screen._turtles = _SCREEN._turtles
 278    for t in new_screen._turtles:
 279        t._pen = Sketch(width, height)
 280        t.reset()
 281    _SCREEN = new_screen
 282
 283
 284def showscreen():
 285    """Shows the screen to which turtles are drawing.
 286
 287    Calling `showscreen()` displays the drawing screen beneath the
 288    code cell in which it's called.
 289
 290    **Example**
 291    ```python
 292    from ipycc.turtle import Turtle, showscreen
 293
 294    # Show the screen.
 295    showscreen()
 296
 297    # Create a turtle and move it.
 298    t = Turtle()
 299    t.forward(100)
 300
 301    # Create a turtle and move it.
 302    t2 = Turtle()
 303    for i in range(4):
 304        t2.forward(50)
 305        t2.left(90)
 306    ```
 307    """
 308    global _SCREEN
 309    # Copy the screen and reassign its turtles.
 310    new_screen = _SCREEN.replace()
 311    _SCREEN = new_screen
 312    # Show the screen.
 313    _SCREEN.show()
 314
 315
 316def tracer(n: int = None, delay: int = None) -> int:
 317    """Turns turtle animation on/off and set delay for updating drawings.
 318
 319    Optional arguments:
 320    - `n` -- a nonnegative integer
 321    - `delay` -- a nonnegative integer
 322    
 323    If no argument is passed, the current rate of screen updates is returned. The
 324    default value is 1.
 325
 326    If `n` is given, only each n-th regular screen update is really performed.
 327    This feature can be used to accelerate the drawing of complex graphics.
 328
 329    If `delay` is given, it sets the screen's delay value.
 330    
 331    **Example**
 332    ```python
 333    from ipycc.turtle import Turtle, showscreen, tracer
 334
 335    # Show the screen.
 336    showscreen()
 337
 338    # Create a turtle.
 339    t = Turtle()
 340
 341    # Draw every 8th frame with a delay of 25 ms.
 342    tracer(8, 25)
 343    dist = 2
 344    for i in range(200):
 345        fd(dist)
 346        rt(90)
 347        dist += 2
 348    ```
 349    """
 350    if n is None:
 351        return _SCREEN._tracing
 352    _SCREEN._tracing = int(n)
 353    _SCREEN._updatecounter = 0
 354    if delay is not None:
 355        _SCREEN._delayvalue = int(delay)
 356    if _SCREEN._tracing:
 357        _SCREEN._update()
 358
 359
 360def delay(delay: int = None) -> int:
 361    """ Return or set the drawing delay in milliseconds.
 362
 363    Optional argument:
 364    `delay` -- positive integer
 365
 366    **Example**
 367    ```python
 368    from ipycc.turtle import delay
 369
 370    delay(15)
 371    print(delay()) # 15
 372    ```
 373    """
 374    if delay is None:
 375        return _SCREEN._delayvalue
 376    _SCREEN._delayvalue = int(delay)
 377
 378
 379@contextmanager
 380def no_animation():
 381    """Temporarily turn off auto-updating the screen.
 382
 383    This is useful for drawing complex shapes where even the fastest setting
 384    is too slow. Once this context manager is exited, the drawing will
 385    be displayed.
 386
 387    **Example**
 388    ```python
 389    from ipycc.turtle import Turtle, showscreen, no_animation
 390
 391    # Show the screen.
 392    showscreen()
 393
 394    # Create a turtle.
 395    t = Turtle()
 396
 397    # Draw a circle without animation.
 398    with no_animation():
 399        for i in range(360):
 400            t.forward(1)
 401            t.left(1)
 402    ```
 403    """
 404    t = tracer()
 405    try:
 406        tracer(0)
 407        yield
 408    finally:
 409        tracer(t)
 410
 411
 412def clearscreen():
 413    """Delete all drawings and all turtles from the screen.
 414    
 415    Resets the now empty screen to its initial state with a white background.
 416
 417    **Example**
 418    ```python
 419    from ipycc.turtle import Turtle, showscreen, clearscreen
 420
 421    # Show the screen.
 422    showscreen()
 423
 424    # Create a turtle.
 425    t = Turtle()
 426
 427    # Move the turtle forward.
 428    t.forward(100)
 429    
 430    # Clear the screen.
 431    clearscreen()
 432    ```
 433    """
 434    for t in _SCREEN._turtles:
 435        t.clear()
 436        t.hideturtle()
 437    _SCREEN._turtles = []
 438    _SCREEN._sketch.background("white")
 439
 440
 441def resetscreen():
 442    """Reset all turtles on the screen to their initial state.
 443
 444    Calling `resetscreen()` resets all turtles on the screen.
 445
 446    **Example**
 447    ```python
 448    from ipycc.turtle import Turtle, showscreen, resetscreen
 449
 450    # Show the screen.
 451    showscreen()
 452
 453    # Create a turtle.
 454    t = Turtle()
 455
 456    # Move the turtle forward.
 457    t.forward(100)
 458    
 459    # Reset the screen.
 460    resetscreen()
 461    ```
 462    """
 463    for t in _SCREEN._turtles:
 464        t.reset()
 465
 466
 467def colormode(cmode: int | float = None) -> None | int | float:
 468    """Return the colormode or set it to 1.0 or 255.
 469
 470    Optional argument:
 471    `cmode` -- one of the values 1.0 or 255
 472
 473    r, g, b values of colortriples have to be in range `0..cmode`.
 474
 475    **Example**
 476    ```python
 477    from ipycc.turtle import Turtle, showscreen
 478
 479    # Show the screen.
 480    showscreen()
 481
 482    # Create a turtle.
 483    t = Turtle()
 484
 485    # Print the turtle's default color mode.
 486    print(t.colormode()) # 1.0
 487    # Change the turtle's color mode and change its color.
 488    t.colormode(255)
 489    t.color(240, 160, 80)
 490    ```
 491    """
 492    if cmode is None:
 493        return _SCREEN._colormode
 494    if cmode == 1.0:
 495        _SCREEN._colormode = float(cmode)
 496    elif cmode == 255:
 497        _SCREEN._colormode = int(cmode)
 498
 499
 500def bgcolor(*args) -> None | str:
 501    """Set or return background color of the turtle's screen.
 502
 503    Arguments:
 504    Four input formats are allowed:
 505        - `bgcolor()`
 506        Return the current background as color specification string,
 507        possibly in hex-number format (see example).
 508        May be used as input to another color/pencolor/fillcolor call.
 509        - `bgcolor(colorstring)`
 510        a [Tk color specification string](https://www.tcl-lang.org/man/tcl8.4/TkCmd/colors.htm),
 511        such as `"red"` or `"yellow"`
 512        - `bgcolor((r, g, b))`
 513        *a tuple* of `r`, `g`, and `b`, which represent, an RGB color,
 514        and each of `r`, `g`, and `b` are in the range `0..colormode`,
 515        where `colormode` is either 1.0 or 255
 516        - `bgcolor(r, g, b)`
 517        `r`, `g`, and `b` represent an RGB color, and each of `r`, `g`,
 518        and `b` are in the range `0..colormode`
 519
 520    **Example**
 521    ```python
 522    from ipycc.turtle import showscreen, bgcolor
 523
 524    # Show the screen.
 525    showscreen()
 526
 527    # Set the screen's background color and print it.
 528    bgcolor("orange")
 529    print(bgcolor()) # 'orange'
 530    ```
 531    """
 532    if args:
 533        _SCREEN._bgcolor = _SCREEN._colorstr(args)
 534        _SCREEN._update()
 535    else:
 536        return _SCREEN._bgcolor
 537
 538
 539class Turtle:
 540    """A class to describe a virtual turtle robot drawing on a screen."""
 541
 542    def __init__(self):
 543        self._pen = Sketch(_SCREEN.width, _SCREEN.height)
 544        _SCREEN.add_turtle(self)
 545        self.reset()
 546
 547    def _to_screen_coords(self, v: Vec2D) -> Vec2D:
 548        x = _SCREEN.width * 0.5 + v[0]
 549        y = _SCREEN.height * 0.5 + v[1]
 550        return Vec2D(x, y)
 551
 552    # ========================================
 553    #              Turtle Motion
 554    # ========================================
 555
 556    def _update(self):
 557        """Perform a Turtle-data update.
 558        """
 559        if _SCREEN._tracing == 0:
 560            return
 561        _SCREEN._update()
 562        _SCREEN._delay(_SCREEN._delayvalue)
 563
 564    def _go(self, distance: int | float):
 565        """Move turtle forward by specified distance"""
 566        ende = self._position + self._orient * distance
 567        self._goto(ende)
 568
 569    def _goto(self, end: Vec2D):
 570        """Move the pen to the point end, thereby drawing a line
 571        if pen is down. All other methods for turtle movement depend
 572        on this one.
 573        """
 574        start = self._position
 575        if self._speed and _SCREEN._tracing == 1:
 576            diff = end - start
 577            diffsq = (diff[0] * _SCREEN.xscale)**2 + (diff[1] * _SCREEN.yscale)**2
 578            nhops = 1 + int((diffsq**0.5) / (3 * (1.1**self._speed) * self._speed))
 579            delta = diff * (1.0 / nhops)
 580            for n in range(1, nhops + 1):
 581                self._position = start + delta * n
 582                if self._drawing:
 583                    x1, y1 = self._to_screen_coords(start)
 584                    x2, y2 = self._to_screen_coords(self._position)
 585                    self._pen.line(x1, y1, x2, y2)
 586                self._update()
 587        else:
 588            x1, y1 = self._to_screen_coords(start)
 589            x2, y2 = self._to_screen_coords(end)
 590            if self._drawing:
 591                self._pen.line(x1, y1, x2, y2)
 592        if isinstance(self._fillpath, list):
 593            self._fillpath.append(end)
 594        self._position = end
 595        self._update()
 596
 597    def forward(self, distance: int | float):
 598        """Move the turtle forward by the specified distance.
 599
 600        Aliases: `forward` | `fd`
 601
 602        Argument:
 603        `distance` -- a number (integer or float)
 604
 605        Move the turtle forward by the specified `distance`, in the direction
 606        the turtle is headed.
 607
 608        **Example**
 609        ```python
 610        from ipycc.turtle import Turtle, showscreen
 611
 612        # Show the screen.
 613        showscreen()
 614
 615        # Create a turtle.
 616        t = Turtle()
 617
 618        print(t.position()) # (0.00, 0.00)
 619        t.forward(25)
 620        print(t.position()) # (25.00,0.00)
 621        t.forward(-75)
 622        print(t.position()) # (-50.00,0.00)
 623        ```
 624        """
 625        self._go(distance)
 626
 627    fd = forward
 628
 629    def backward(self, distance: int | float):
 630        """Move the turtle backward by distance.
 631
 632        Aliases: `back` | `backward` | `bk`
 633
 634        Argument:
 635        `distance` -- a number
 636
 637        Move the turtle backward by `distance`, opposite to the direction the
 638        turtle is headed. Do not change the turtle's heading.
 639
 640        **Example**
 641        ```python
 642        from ipycc.turtle import Turtle, showscreen
 643
 644        # Show the screen.
 645        showscreen()
 646
 647        # Create a turtle.
 648        t = Turtle()
 649
 650        # Print the turtle's position before and after moving.
 651        print(t.position()) # (0.00, 0.00)
 652        t.backward(30)
 653        print(t.position()) # (-30.00, 0.00)
 654        ```
 655        """
 656        self._go(-distance)
 657
 658    back = backward
 659    bk = backward
 660
 661    def _rotate(self, angle: int | float):
 662        """Turn turtle counterclockwise by specified angle if angle > 0."""
 663        self._orient = self._orient.rotate(angle)
 664        self._update()
 665
 666    def right(self, angle: int | float):
 667        """Turn turtle right by angle units.
 668
 669        Aliases: `right` | `rt`
 670
 671        Argument:
 672        `angle` -- a number (integer or float)
 673
 674        Turn turtle right by `angle` units. (Units are by default degrees,
 675        but can be set via the `degrees()` and `radians()` methods.)
 676        Angle orientation depends on mode. (See this.)
 677
 678        **Example**
 679        ```python
 680        from ipycc.turtle import Turtle, showscreen
 681
 682        # Show the screen.
 683        showscreen()
 684
 685        # Create a turtle.
 686        t = Turtle()
 687
 688        # Print the turtle's heading before and after turning.
 689        print(t.heading()) # 22.0
 690        t.right(45)
 691        print(t.heading()) # 337.0
 692        ```
 693        """
 694        self._rotate(-angle)
 695
 696    rt = right
 697
 698    def left(self, angle: int | float):
 699        """Turn turtle left by angle units.
 700
 701        Aliases: `left` | `lt`
 702
 703        Argument:
 704        `angle` -- a number (integer or float)
 705
 706        Turn turtle left by `angle` units. (Units are by default degrees,
 707        but can be set via the `degrees()` and `radians()` methods.)
 708        Angle orientation depends on mode.
 709
 710        **Example**
 711        ```python
 712        from ipycc.turtle import Turtle, showscreen
 713
 714        # Show the screen.
 715        showscreen()
 716
 717        # Create a turtle.
 718        t = Turtle()
 719
 720        # Print the turtle's heading before and after turning.
 721        print(t.heading()) # 22.0
 722        t.left(45)
 723        print(t.heading()) # 67.0
 724        ```
 725        """
 726        self._rotate(angle)
 727
 728    lt = left
 729
 730    def goto(self, x: int | float | tuple | Vec2D, y: int | float = None):
 731        """Move turtle to an absolute position.
 732
 733        Aliases: `setpos` | `setposition` | `goto`:
 734
 735        Arguments:
 736        - `x` -- a number or vector
 737        - `y` -- a number (optional)
 738
 739        Move turtle to an absolute position. If the pen is down,
 740        a line will be drawn. The turtle's orientation does not change.
 741
 742        **Example**
 743        ```python
 744        from ipycc.turtle import Turtle, showscreen
 745
 746        # Show the screen.
 747        showscreen()
 748
 749        # Create a turtle.
 750        t = Turtle()
 751
 752        # Print the turtle's position before and after moving.
 753        print(t.pos()) # (0.00, 0.00)
 754        t.goto(60, 30)
 755        print(t.pos()) # (60.00, 30.00)
 756        ```
 757        """
 758        if y is None:
 759            self._goto(Vec2D(*x))
 760        else:
 761            self._goto(Vec2D(x, y))
 762
 763    setpos = goto
 764    setposition = goto
 765
 766    def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None:
 767        """Instantly move turtle to an absolute position.
 768
 769        Arguments:
 770        - `x` -- a number      or     `None`
 771        - `y` -- a number             `None`
 772        - `fill_gap` -- a boolean     This argument must be specified by name.
 773
 774        Move turtle to an absolute position. Unlike `goto(x, y)`, a line will not
 775        be drawn. The turtle's orientation does not change. If currently
 776        filling, the polygon(s) teleported from will be filled after leaving,
 777        and filling will begin again after teleporting. This can be disabled
 778        with `fill_gap=True`, which makes the imaginary line traveled during
 779        teleporting act as a fill barrier like in `goto(x, y)`.
 780
 781        **Example**
 782        ```python
 783        from ipycc.turtle import Turtle, showscreen
 784
 785        # Show the screen.
 786        showscreen()
 787
 788        # Create a turtle.
 789        t = Turtle()
 790
 791        tp = t.pos()
 792        print(tp)      # (0.00,0.00)
 793        t.teleport(60)
 794        print(t.pos()) # (60.00,0.00)
 795        t.teleport(y=10)
 796        print(t.pos()) # (60.00,10.00)
 797        t.teleport(20, 30)
 798        print(t.pos()) # (20.00,30.00)
 799        ```
 800        """
 801        pendown = self.isdown()
 802        was_filling = self.filling()
 803        if pendown:
 804            self.penup()
 805        if was_filling and not fill_gap:
 806            self.end_fill()
 807        new_x = x if x is not None else self._position[0]
 808        new_y = y if y is not None else self._position[1]
 809        self._position = Vec2D(new_x, new_y)
 810        if pendown:
 811            self.pendown()
 812        if was_filling and not fill_gap:
 813            self.begin_fill()
 814        self._update()
 815
 816    def setx(self, x: int | float):
 817        """Set the turtle's first coordinate to `x`.
 818
 819        Argument:
 820        `x` -- a number (integer or float)
 821
 822        Set the turtle's first coordinate to `x`, leave second coordinate
 823        unchanged.
 824
 825        **Example**
 826        ```python
 827        from ipycc.turtle import Turtle, showscreen
 828
 829        # Show the screen.
 830        showscreen()
 831
 832        # Create a turtle.
 833        t = Turtle()
 834
 835        # Print the turtle's position before and after moving.
 836        print(t.position()) # (0.00, 240.00)
 837        t.setx(10)
 838        print(t.position()) # (10.00, 240.00)
 839        ```
 840        """
 841        self._goto(Vec2D(x, self._position[1]))
 842
 843    def sety(self, y: int | float):
 844        """Set the turtle's second coordinate to `y`.
 845
 846        Argument:
 847        `y` -- a number (integer or float)
 848
 849        Set the turtle's first coordinate to `x`, second coordinate remains
 850        unchanged.
 851
 852        **Example**
 853        ```python
 854        from ipycc.turtle import Turtle, showscreen
 855
 856        # Show the screen.
 857        showscreen()
 858
 859        # Create a turtle.
 860        t = Turtle()
 861
 862        # Print the turtle's position before and after moving.
 863        print(t.position()) # (0.00, 40.00)
 864        t.sety(-10)
 865        print(t.position()) # (0.00, -10.00)
 866        ```
 867        """
 868        self._goto(Vec2D(self._position[0], y))
 869
 870    def setheading(self, to_angle: int | float):
 871        """Set the orientation of the turtle to `to_angle`.
 872
 873        Aliases:  `setheading` | `seth`
 874
 875        Argument:
 876        `to_angle` -- a number (integer or float)
 877
 878        Set the orientation of the turtle to `to_angle`.
 879        Here are some common directions in degrees:
 880        - 0 - east
 881        - 90 - north
 882        - 180 - west
 883        - 270 - south
 884
 885        **Example**
 886        ```python
 887        from ipycc.turtle import Turtle, showscreen
 888
 889        # Show the screen.
 890        showscreen()
 891
 892        # Create a turtle.
 893        t = Turtle()
 894
 895        # Set the turtle's heading and print it.
 896        t.setheading(90)
 897        print(t.heading()) # 90
 898        ```
 899        """
 900        angle = (to_angle - self.heading()) * self._angleOrient
 901        full = self._fullcircle
 902        half = full / 2.0
 903        angle = (angle + half) % full - half
 904        self._rotate(angle)
 905
 906    seth = setheading
 907
 908    def home(self):
 909        """Move turtle to the origin - coordinates `(0,0)`.
 910
 911        No arguments.
 912
 913        Move turtle to the origin and reset its heading to 0.
 914
 915        **Example**
 916        ```python
 917        from ipycc.turtle import Turtle, showscreen
 918
 919        # Show the screen.
 920        showscreen()
 921
 922        # Create a turtle.
 923        t = Turtle()
 924
 925        # Move the turtle forward, then move it back home.
 926        t.forward(100)
 927        t.home()
 928        ```
 929        """
 930        self.goto(0, 0)
 931        self.setheading(0)
 932
 933    def dot(self, size: int = None, *color: str | tuple[int | float]):
 934        """Draw a dot with diameter size, using color.
 935
 936        Optional arguments:
 937        - `size` -- an integer >= 1 (if given)
 938        - `color` -- a colorstring or a numeric color tuple
 939
 940        Draw a circular dot with diameter size, using `color`.
 941        If `size` is not given, the maximum of `pensize+4` and `2*pensize` is
 942        used.
 943
 944        **Example**
 945        ```python
 946        from ipycc.turtle import Turtle, showscreen
 947
 948        # Show the screen.
 949        showscreen()
 950
 951        # Create a turtle.
 952        t = Turtle()
 953
 954        # Draw dots.
 955        t.dot()
 956        t.forward(50)
 957        t.dot(20, "blue")
 958        t.forward(50)
 959        ```
 960        """
 961        if not color:
 962            if isinstance(size, (str, tuple)):
 963                color = _SCREEN._colorstr(size)
 964                size = self._pensize + max(self._pensize, 4)
 965            else:
 966                color = self._pencolor
 967                if not size:
 968                    size = self._pensize + max(self._pensize, 4)
 969        else:
 970            if size is None:
 971                size = self._pensize + max(self._pensize, 4)
 972            color = _SCREEN._colorstr(color)
 973        self._pen.canvas.save()
 974        self._pen.no_stroke()
 975        self._pen.fill(color)
 976        x, y = self._to_screen_coords(self._position)
 977        self._pen.circle(x, y, size)
 978        self._pen.canvas.restore()
 979        self._update()
 980
 981    def stamp(self):
 982        """Stamp a copy of the turtleshape onto the canvas.
 983
 984        No argument.
 985
 986        Stamp a copy of the turtle shape onto the canvas at the current
 987        turtle position.
 988
 989        **Example**
 990        ```python
 991        from ipycc.turtle import Turtle, showscreen
 992
 993        # Show the screen.
 994        showscreen()
 995
 996        # Create a turtle.
 997        t = Turtle()
 998
 999        # Draw a stamp and move.
1000        t.color("blue")
1001        t.stamp()
1002        t.forward(50)
1003        ```
1004        """
1005        self._pen.canvas.save()
1006        x, y = self._to_screen_coords(self._position)
1007        self._pen.translate(x, y)
1008        angle = math.radians(self.heading()) - math.pi / 2
1009        self._pen.rotate(angle)
1010        self._pen.stroke(self._pencolor)
1011        self._pen.stroke_weight(self._outlinewidth)
1012        self._pen.fill(self._fillcolor)
1013        self._pen.begin_shape()
1014        shape = _turtle_shapes[self._shape]
1015        for v in shape:
1016            sx, sy = self._stretchfactor
1017            self._pen.vertex(sx * v[0], sy * v[1])
1018        self._pen.end_shape()
1019        self._pen.reset_matrix()
1020        self._pen.canvas.restore()
1021        self._update()
1022
1023    def speed(self, speed: int | float | str = None) -> None | int:
1024        """Return or set the turtle's speed.
1025
1026        Optional argument:
1027        `speed` -- an integer in the range `0..10` or a `speedstring`
1028        (see below)
1029
1030        Set the turtle's speed to an integer value in the range `0..10`.
1031        If no argument is given: return current speed.
1032
1033        If input is a number greater than 10 or smaller than 0.5,
1034        speed is set to 0.
1035        Speedstrings  are mapped to speedvalues in the following way:
1036        - `'fastest'` :  0
1037        - `'fast'`    :  10
1038        - `'normal'`  :  6
1039        - `'slow'`    :  3
1040        - `'slowest'` :  1
1041        speeds from 1 to 10 enforce increasingly faster animation of
1042        line drawing and turtle turning.
1043
1044        Attention:
1045        `speed = 0` : *no* animation takes place. forward/back makes turtle jump
1046        and likewise left/right make the turtle turn instantly.
1047
1048        **Example**
1049        ```python
1050        from ipycc.turtle import Turtle, showscreen
1051
1052        # Show the screen.
1053        showscreen()
1054
1055        # Create a turtle.
1056        t = Turtle()
1057
1058        # Set the turtle's speed.
1059        t.speed(3)
1060        ```
1061        """
1062        speeds = {"fastest": 0, "fast": 10, "normal": 6, "slow": 3, "slowest": 1}
1063        if speed is None:
1064            return self._speed
1065        if speed in speeds:
1066            speed = speeds[speed]
1067        elif 0.5 < speed < 10.5:
1068            speed = int(round(speed))
1069        else:
1070            speed = 0
1071        self._speed = speed
1072
1073    def position(self) -> Vec2D:
1074        """Return the turtle's current location `(x,y)`, as a `Vec2D`.
1075
1076        Aliases: `pos` | `position`
1077
1078        No arguments.
1079
1080        **Example**
1081        ```python
1082        from ipycc.turtle import Turtle, showscreen
1083
1084        # Show the screen.
1085        showscreen()
1086
1087        # Create a turtle.
1088        t = Turtle()
1089
1090        # Print the turtle's position.
1091        print(t.pos()) # (0.00, 0.00)
1092        ```
1093        """
1094        return self._position
1095
1096    pos = position
1097
1098    def towards(self, x: int | float | tuple | Vec2D, y: int | float = None) -> float:
1099        """Return the angle of the line from the turtle's position to `(x,y)`.
1100
1101        Arguments:
1102        - `x` -- a number   or  a pair/vector of numbers   or   a turtle instance
1103        - `y` -- a number (optional)
1104
1105        Return the angle, between the line from turtle-position to position
1106        specified by `x`, `y` and the turtle's start orientation.
1107
1108        **Example**
1109        ```python
1110        from ipycc.turtle import Turtle, showscreen, Vec2D
1111
1112        # Show the screen.
1113        showscreen()
1114
1115        # Create a turtle.
1116        t = Turtle()
1117
1118        # Print the turtle's position and heading.
1119        print(t.pos()) # (10.00, 10.00)
1120        print(t.towards(0, 0)) # 225.0
1121        print(t.towards((0, 0))) # 225.0
1122        v = Vec2D(0, 0)
1123        print(t.towards(v)) # 225.0
1124        ```
1125        """
1126        if y is not None:
1127            pos = Vec2D(x, y)
1128        if isinstance(x, Vec2D):
1129            pos = x
1130        elif isinstance(x, tuple):
1131            pos = Vec2D(*x)
1132        elif isinstance(x, Turtle):
1133            pos = x._position
1134        x, y = pos - self._position
1135        result = round(math.degrees(math.atan2(y, x)), 10) % 360.0
1136        result /= self._degreesPerAU
1137        return (self._angleOffset + self._angleOrient * result) % self._fullcircle
1138
1139    def xcor(self) -> float:
1140        """Return the turtle's x coordinate.
1141
1142        No arguments.
1143
1144        **Example**
1145        ```python
1146        from ipycc.turtle import Turtle, showscreen
1147
1148        # Show the screen.
1149        showscreen()
1150
1151        # Create a turtle.
1152        t = Turtle()
1153
1154        # Move the turtle and print its x-coordinate.
1155        t.left(60)
1156        t.forward(100)
1157        print(tutrtle.xcor()) # 50.0
1158        ```
1159        """
1160        return self._position[0]
1161
1162    def ycor(self) -> float:
1163        """Return the turtle's y coordinate.
1164
1165        No arguments.
1166
1167        **Example**
1168        ```python
1169        from ipycc.turtle import Turtle, showscreen
1170
1171        # Show the screen.
1172        showscreen()
1173
1174        # Create a turtle.
1175        t = Turtle()
1176
1177        # Move the turtle and print its y-coordinate.
1178        t.left(60)
1179        t.forward(100)
1180        print(t.ycor()) # 86.6025403784
1181        ```
1182        """
1183        return self._position[1]
1184
1185    def heading(self) -> float:
1186        """Return the turtle's current heading.
1187
1188        No arguments.
1189
1190        **Example**
1191        ```python
1192        from ipycc.turtle import Turtle, showscreen
1193
1194        # Show the screen.
1195        showscreen()
1196
1197        # Create a turtle.
1198        t = Turtle()
1199
1200        # Turn the turtle and print its heading.
1201        t.left(67)
1202        print(t.heading()) # 67.0
1203        ```
1204        """
1205        x, y = self._orient
1206        result = round(math.degrees(math.atan2(y, x)), 10) % 360.0
1207        result /= self._degreesPerAU
1208        return (self._angleOffset + self._angleOrient*result) % self._fullcircle
1209
1210    def distance(self, x, y: int | float = None) -> float:
1211        """Return the distance from the turtle to `(x,y)` in turtle step units.
1212
1213        Arguments:
1214        - `x` -- a number or a pair/vector of numbers or a `Turtle` instance
1215        - `y` -- a number (optional)
1216
1217        **Example**
1218        ```python
1219        from ipycc.turtle import Turtle, showscreen
1220
1221        # Show the screen.
1222        showscreen()
1223
1224        # Create a turtle.
1225        t = Turtle()
1226
1227        # Print the turtle's position and distance to a point.
1228        print(t.pos()) # (0.00, 0.00)
1229        print(t.distance(30, 40)) # 50.0
1230
1231        # Create another turtle.
1232        t2 = Turtle()
1233
1234        # Move the second turtle and print its distance from
1235        # the first turtle.
1236        t2.forward(77)
1237        print(t.distance(t2)) # 77.0
1238        ```
1239        """
1240        if y is not None:
1241            pos = Vec2D(x, y)
1242        if isinstance(x, Vec2D):
1243            pos = x
1244        elif isinstance(x, tuple):
1245            pos = Vec2D(*x)
1246        elif isinstance(x, Turtle):
1247            pos = x._position
1248        return abs(pos - self._position)
1249
1250    def _setDegreesPerAU(self, fullcircle):
1251        """Helper function for degrees() and radians()"""
1252        self._fullcircle = fullcircle
1253        self._degreesPerAU = 360/fullcircle
1254        self._angleOffset = 0
1255
1256    def degrees(self, fullcircle: int | float = 360.0):
1257        """Set angle measurement units to degrees.
1258
1259        Optional argument:
1260        `fullcircle` -  a number
1261
1262        Set angle measurement units, i. e. set number
1263        of 'degrees' for a full circle. Default value is
1264        360 degrees.
1265
1266        **Example**
1267        ```python
1268        from ipycc.turtle import Turtle, showscreen
1269
1270        # Show the screen.
1271        showscreen()
1272
1273        # Create a turtle.
1274        t = Turtle()
1275
1276        # Turn the turtle and print its heading.
1277        t.left(90)
1278        print(t.heading()) # 90
1279
1280        # Change angle measurement unit to grad (also known as gon,
1281        # grade, or gradian and equals 1/100-th of the right angle.)
1282        t.degrees(400.0)
1283        print(t.heading()) # 100
1284        ```
1285        """
1286        self._setDegreesPerAU(fullcircle)
1287
1288    def radians(self):
1289        """Set the angle measurement units to radians.
1290
1291        No arguments.
1292
1293        **Example**
1294        ```python
1295        from ipycc.turtle import Turtle, showscreen
1296
1297        # Show the screen.
1298        showscreen()
1299
1300        # Create a turtle.
1301        t = Turtle()
1302
1303        # Print the turtle's heading in degrees and radians.
1304        print(t.heading()) # 90
1305        t.radians()
1306        print(t.heading()) # 1.5707963267948966
1307        ```
1308        """
1309        self._setDegreesPerAU(math.tau)
1310
1311    # ========================================
1312    #               Pen Control
1313    # ========================================
1314
1315    def pendown(self):
1316        """Pull the pen down -- drawing when moving.
1317
1318        Aliases: `pendown` | `pd` | `down`
1319
1320        No argument.
1321
1322        **Example**
1323        ```python
1324        from ipycc.turtle import Turtle, showscreen
1325
1326        # Show the screen.
1327        showscreen()
1328
1329        # Create a turtle.
1330        t = Turtle()
1331
1332        # Put the turtle's pen down and move.
1333        t.pendown()
1334        t.forward(100)
1335        ```
1336        """
1337        self._drawing = True
1338
1339    pd = pendown
1340    down = pendown
1341
1342    def penup(self):
1343        """Pull the pen up -- no drawing when moving.
1344
1345        Aliases: `penup` | `pu` | `up`
1346
1347        No argument
1348
1349        **Example**
1350        ```python
1351        from ipycc.turtle import Turtle, showscreen
1352
1353        # Show the screen.
1354        showscreen()
1355
1356        # Create a turtle.
1357        t = Turtle()
1358
1359        # Pick the turtle's pen up and move.
1360        t.penup()
1361        t.forward(100)
1362        ```
1363        """
1364        self._drawing = False
1365
1366    pu = penup
1367    up = penup
1368
1369    def pensize(self, width: int | float = None) -> None | float:
1370        """Set or return the line thickness.
1371
1372        Aliases:  `pensize` | `width`
1373
1374        Argument:
1375        `width` -- positive number
1376
1377        Set the line thickness to `width` or return it. If no argument is
1378        given, current pensize is returned.
1379
1380        **Example**
1381        ```python
1382        from ipycc.turtle import Turtle, showscreen
1383
1384        # Show the screen.
1385        showscreen()
1386
1387        # Create a turtle.
1388        t = Turtle()
1389
1390        # Print the turtle's pen size and move.
1391        print(t.pensize()) # 1
1392        t.forward(50)
1393
1394        # Change the turtle's pen size and move.
1395        t.pensize(10)   # from here on lines of width 10 are drawn
1396        t.forward(50)
1397        ```
1398        """
1399        if width is None:
1400            return self._pensize
1401        self._pensize = width
1402        self._pen.stroke_weight(self._pensize)
1403
1404    width = pensize
1405
1406    def isdown(self) -> bool:
1407        """Return `True` if pen is down, `False` if it's up.
1408
1409        No argument.
1410
1411        **Example**
1412        ```python
1413        from ipycc.turtle import Turtle, showscreen
1414
1415        # Show the screen.
1416        showscreen()
1417
1418        # Create a turtle.
1419        t = Turtle()
1420
1421        # Pick the turtle's pen up and print its state.
1422        t.penup()
1423        print(t.isdown()) # False
1424        # Put the turtle's pen down and print its state.
1425        t.pendown()
1426        print(t.isdown()) # True
1427        ```
1428        """
1429        return self._drawing
1430
1431    def color(self, *args) -> None | str | tuple:
1432        """Return or set the pencolor and fillcolor.
1433
1434        Arguments:
1435        Several input formats are allowed.
1436        They use 0, 1, 2, or 3 arguments as follows:
1437
1438        - `color()` returns the current pencolor and the current fillcolor
1439        as a pair of color specification strings.
1440        - `color(colorstring)`, `color((r,g,b))`, `color(r,g,b)` sets both
1441        `fillcolor()` and `pencolor()` to the given value.
1442        - `color(colorstring1, colorstring2)`, `color((r1,g1,b1), (r2,g2,b2))`
1443        sets `pencolor(colorstring1)` and `fillcolor(colorstring2)` or
1444        `pencolor((r1,g1,b1))` and `fillcolor((r2,g2,b2))`.
1445
1446        If turtleshape is a polygon, outline and interior of that polygon
1447        is drawn with the newly set colors.
1448
1449        For more info see: `pencolor()`, `fillcolor()`
1450
1451        **Example**
1452        ```python
1453        from ipycc.turtle import Turtle, showscreen
1454
1455        # Show the screen.
1456        showscreen()
1457
1458        # Create a turtle.
1459        t = Turtle()
1460
1461        # Set the turtle's pen and fill color, then print them.
1462        t.color('red', 'green')
1463        print(t.color()) # ('red', 'green')
1464        # Change the color mode.
1465        t.colormode(255)
1466        # Set the turtle's pen and fill color, then print them.
1467        t.color((40, 80, 120), (160, 200, 240))
1468        print(t.color()) # ('#285078', '#a0c8f0')
1469        ```
1470        """
1471        if args:
1472            l = len(args)
1473            if l == 1:
1474                pcolor = fcolor = args[0]
1475            elif l == 2:
1476                pcolor, fcolor = args
1477            elif l == 3:
1478                pcolor = fcolor = args
1479            pcolor = _SCREEN._colorstr(pcolor)
1480            fcolor = _SCREEN._colorstr(fcolor)
1481            self._pencolor = pcolor
1482            self._pen.stroke(self._pencolor)
1483            self._pen.stroke_weight(self._pensize)
1484            self._fillcolor = fcolor
1485            self._pen.fill(self._fillcolor)
1486            self._update()
1487        else:
1488            return _SCREEN._color(self._pencolor), _SCREEN._color(self._fillcolor)
1489
1490    def pencolor(self, *args) -> None | str | tuple:
1491        """ Return or set the pencolor.
1492
1493        Arguments:
1494        Four input formats are allowed:
1495          - `pencolor()`
1496            Return the current pencolor as color specification string,
1497            possibly in hex-number format (see example).
1498            May be used as input to another color/pencolor/fillcolor call.
1499          - `pencolor(colorstring)`
1500            a [Tk color specification string](https://www.tcl-lang.org/man/tcl8.4/TkCmd/colors.htm),
1501            such as `"red"` or `"yellow"`
1502          - `pencolor((r, g, b))`
1503            *a tuple* of `r`, `g`, and `b`, which represent, an RGB color,
1504            and each of `r`, `g`, and `b` are in the range `0..colormode`,
1505            where `colormode` is either 1.0 or 255
1506          - `pencolor(r, g, b)`
1507            `r`, `g`, and `b` represent an RGB color, and each of `r`, `g`,
1508            and `b` are in the range `0..colormode`
1509
1510        If turtleshape is a polygon, the outline of that polygon is drawn
1511        with the newly set pencolor.
1512
1513        **Example**
1514        ```python
1515        from ipycc.turtle import Turtle, showscreen
1516
1517        # Show the screen.
1518        showscreen()
1519
1520        # Create a turtle.
1521        t = Turtle()
1522
1523        # Set the turtle's pen color to brown, then print it.
1524        t.pencolor('brown')
1525        print(t.pencolor()) # 'brown'
1526        # Set the turtle's pen color using a tuple, then print it.
1527        tup = (0.2, 0.8, 0.55)
1528        t.pencolor(tup)
1529        print(t.pencolor()) # '#33cc8c'
1530        ```
1531        """
1532        if args:
1533            color = _SCREEN._colorstr(args)
1534            if color == self._pencolor:
1535                return
1536            self._pencolor = color
1537            self._pen.stroke(self._pencolor)
1538            self._pen.stroke_weight(self._pensize)
1539            self._update()
1540        else:
1541            return _SCREEN._color(self._pencolor)
1542
1543    def fillcolor(self, *args) -> None | str | tuple:
1544        """Return or set the fillcolor.
1545
1546        Arguments:
1547        Four input formats are allowed:
1548          - `fillcolor()`
1549            Return the current fillcolor as color specification string,
1550            possibly in hex-number format (see example).
1551            May be used as input to another color/pencolor/fillcolor call.
1552          - `fillcolor(colorstring)`
1553            a [Tk color specification string](https://www.tcl-lang.org/man/tcl8.4/TkCmd/colors.htm),
1554            such as `"red"` or `"yellow"`
1555          - `fillcolor((r, g, b))`
1556            *a tuple* of `r`, `g`, and `b`, which represent, an RGB color,
1557            and each of `r`, `g`, and `b` are in the range `0..colormode`,
1558            where `colormode` is either 1.0 or 255
1559          - `fillcolor(r, g, b)`
1560            `r`, `g`, and `b` represent an RGB color, and each of `r`, `g`, and `b`
1561            are in the range `0..colormode`
1562
1563        If turtleshape is a polygon, the interior of that polygon is drawn
1564        with the newly set fillcolor.
1565
1566        **Example**
1567        ```python
1568        from ipycc.turtle import Turtle, showscreen
1569
1570        # Show the screen.
1571        showscreen()
1572
1573        # Create a turtle.
1574        t = Turtle()
1575
1576        # Set the turtle's fill color to violet.
1577        t.fillcolor('violet')
1578        # Set the turtle's fill color to its pen color.
1579        col = t.pencolor()
1580        t.fillcolor(col)
1581        # Set the turtle's fill color using RGB values.
1582        t.fillcolor(0, 0.5, 0)
1583        ```
1584        """
1585        if args:
1586            color = _SCREEN._colorstr(args)
1587            if color == self._fillcolor:
1588                return
1589            self._fillcolor = color
1590            self._pen.fill(self._fillcolor)
1591            self._update()
1592        else:
1593            return _SCREEN._color(self._fillcolor)
1594
1595    def filling(self) -> bool:
1596        """Return fillstate (`True` if filling, `False` otherwise).
1597
1598        No argument.
1599
1600        **Example**
1601        ```python
1602        from ipycc.turtle import Turtle, showscreen
1603
1604        # Show the screen.
1605        showscreen()
1606
1607        # Create a turtle.
1608        t = Turtle()
1609
1610        # Begin filling.
1611        t.begin_fill()
1612        # Change the turtle's pen size if it is filling.
1613        if t.filling():
1614            t.pensize(5)
1615        else:
1616            t.pensize(3)
1617        ```
1618        """
1619        return isinstance(self._fillpath, list)
1620
1621    @contextmanager
1622    def fill(self):
1623        """A context manager for filling a shape.
1624
1625        No argument.
1626
1627        Implicitly ensures the code block is wrapped with
1628        `begin_fill()` and `end_fill()`.
1629
1630        **Example**
1631        ```python
1632        from ipycc.turtle import Turtle, showscreen
1633
1634        # Show the screen.
1635        showscreen()
1636
1637        # Create a turtle.
1638        t = Turtle()
1639        t.color("black", "red")
1640
1641        # Fill.
1642        with t.fill():
1643            t.circle(60)
1644        ```
1645        """
1646        self.begin_fill()
1647        try:
1648            yield
1649        finally:
1650            self.end_fill()
1651
1652    def begin_fill(self):
1653        """Called just before drawing a shape to be filled.
1654
1655        No argument.
1656
1657        **Example**
1658        ```python
1659        from ipycc.turtle import Turtle, showscreen
1660
1661        # Show the screen.
1662        showscreen()
1663
1664        # Create a turtle.
1665        t = Turtle()
1666
1667        # Set the turtle's pen and fill colors.
1668        t.color("black", "red")
1669
1670        # Begin filling.
1671        t.begin_fill()
1672        t.circle(60)
1673        # Stop filling.
1674        t.end_fill()
1675        ```
1676        """
1677        self._fillpath = [self._position]
1678
1679    def end_fill(self):
1680        """Fill the shape drawn after the call `begin_fill()`.
1681
1682        No argument.
1683
1684        **Example**
1685        ```python
1686        from ipycc.turtle import Turtle, showscreen
1687
1688        # Show the screen.
1689        showscreen()
1690
1691        # Create a turtle.
1692        t = Turtle()
1693
1694        # Set the turtle's pen and fill color.
1695        t.color("black", "red")
1696    
1697        # Begin filling.
1698        t.begin_fill()
1699        t.circle(60)
1700        # Stop filling.
1701        t.end_fill()
1702        ```
1703        """
1704        if self.filling():
1705            if len(self._fillpath) > 2:
1706                self._pen.begin_shape()
1707                for v in self._fillpath:
1708                    x, y = self._to_screen_coords(v)
1709                    self._pen.vertex(x, y)
1710                self._pen.end_shape()
1711            self._fillpath = None
1712            self._update()
1713
1714    @contextmanager
1715    def poly(self):
1716        """A context manager for recording the vertices of a polygon.
1717
1718        No argument.
1719
1720        Implicitly ensures that the code block is wrapped with
1721        `begin_poly()` and `end_poly()`
1722
1723        **Example**
1724        ```python
1725        from ipycc.turtle import Turtle, showscreen
1726
1727        # Show the screen.
1728        showscreen()
1729
1730        # Create a turtle.
1731        t = Turtle()
1732
1733        # Set the turtle's pen and fill color.
1734        t.color("black", "red")
1735
1736        # Begin filling.
1737        t.begin_fill()
1738
1739        # Create a polygon.
1740        with t.poly():
1741            for i in range(4):
1742                t.forward(50)
1743                t.left(90)
1744        
1745        # Stop filling.
1746        t.end_fill()
1747        ```
1748        """
1749        self.begin_poly()
1750        try:
1751            yield
1752        finally:
1753            self.end_poly()
1754
1755    def begin_poly(self):
1756        """Start recording the vertices of a polygon.
1757
1758        No argument.
1759
1760        Start recording the vertices of a polygon. Current turtle position
1761        is first point of polygon.
1762
1763        **Example**
1764        ```python
1765        from ipycc.turtle import Turtle, showscreen
1766
1767        # Show the screen.
1768        showscreen()
1769
1770        # Create a turtle.
1771        t = Turtle()
1772
1773        # Set the turtle's pen and fill color.
1774        t.color("black", "red")
1775
1776        # Begin filling.
1777        t.begin_fill()
1778
1779        # Begin creating a polygon.
1780        t.begin_poly()
1781        for i in range(4):
1782            t.forward(50)
1783            t.left(90)
1784
1785        # Stop creating a polygon.
1786        t.end_poly()
1787
1788        # Stop filling.
1789        t.end_fill()
1790        ```
1791        """
1792        self._poly = [self._position]
1793        self._creatingPoly = True
1794
1795    def end_poly(self):
1796        """Stop recording the vertices of a polygon.
1797
1798        No argument.
1799
1800        Stop recording the vertices of a polygon. Current turtle position is
1801        last point of polygon. This will be connected with the first point.
1802
1803        **Example**
1804        ```python
1805        from ipycc.turtle import Turtle, showscreen
1806
1807        # Show the screen.
1808        showscreen()
1809
1810        # Create a turtle.
1811        t = Turtle()
1812
1813        # Set the turtle's pen and fill color.
1814        t.color("black", "red")
1815    
1816        # Begin filling.
1817        t.begin_fill()
1818    
1819        # Begin creating a polygon.
1820        t.begin_poly()
1821        for i in range(4):
1822            t.forward(50)
1823            t.left(90)
1824
1825        # Stop creating a polygon.
1826        t.end_poly()
1827
1828        # Stop filling.
1829        t.end_fill()
1830        ```
1831        """
1832        self._creatingPoly = False
1833
1834    def circle(
1835        self, radius: int | float, extent: int | float = None, steps: int = None
1836    ):
1837        """Draw a circle with given radius.
1838
1839        Arguments:
1840        - `radius` -- a number
1841        - `extent` (optional) -- a number
1842        - `steps` (optional) -- an integer
1843
1844        Draw a circle with given radius. The center is `radius` units left
1845        of the turtle; `extent` - an angle - determines which part of the
1846        circle is drawn. If `extent` is not given, draw the entire circle.
1847        If `extent` is not a full circle, one endpoint of the arc is the
1848        current pen position. Draw the arc in counterclockwise direction
1849        if `radius` is positive, otherwise in clockwise direction. Finally
1850        the direction of the turtle is changed by the amount of extent.
1851
1852        As the circle is approximated by an inscribed regular polygon,
1853        `steps` determines the number of steps to use. If not given,
1854        it will be calculated automatically. May be used to draw regular
1855        polygons.
1856
1857        **Example**
1858        ```python
1859        from ipycc.turtle import Turtle, showscreen
1860
1861        # Show the screen.
1862        showscreen()
1863
1864        # Create a turtle.
1865        t = Turtle()
1866
1867        t.circle(50)
1868        t.circle(120, 180)  # semicircle
1869        ```
1870        """
1871        speed = self.speed()
1872        if extent is None:
1873            extent = self._fullcircle
1874        if steps is None:
1875            frac = abs(extent) / self._fullcircle
1876            steps = 1+int(min(11+abs(radius)/6.0, 59.0)*frac)
1877        w = 1.0 * extent / steps
1878        w2 = 0.5 * w
1879        l = 2.0 * radius * math.sin(math.radians(w2)*self._degreesPerAU)
1880        if radius < 0:
1881            l, w, w2 = -l, -w, -w2
1882        tr = tracer()
1883        dl = delay()
1884        if speed == 0:
1885            tracer(0, 0)
1886        else:
1887            self.speed(0)
1888        self._rotate(w2)
1889        for i in range(steps):
1890            self.speed(speed)
1891            self._go(l)
1892            self.speed(0)
1893            self._rotate(w)
1894        self._rotate(-w2)
1895        if speed == 0:
1896            tracer(tr, dl)
1897        self.speed(speed)
1898
1899    def reset(self):
1900        """Return the turtle to its initial state and clear its drawings from
1901        the screen.
1902
1903        No arguments.
1904
1905        **Example**
1906        ```python
1907        from ipycc.turtle import Turtle, showscreen
1908
1909        # Show the screen.
1910        showscreen()
1911
1912        # Create a turtle.
1913        t = Turtle()
1914
1915        # Move the turtle forward.
1916        t.forward(50)
1917
1918        # Reset the turtle.
1919        t.reset()
1920        ```
1921        """
1922        self._drawing = True
1923        self._pencolor = "black"
1924        self._pensize = 1
1925        self._pen.stroke(self._pencolor)
1926        self._pen.stroke_weight(self._pensize)
1927        self._speed = 3
1928        self._shown = True
1929        self._fillcolor = "black"
1930        self._is_filling = False
1931        self._poly = []
1932        self._fillpath = None
1933        self._pen.no_fill()
1934        self._creatingPoly = False
1935        self._position = Vec2D(0, 0)
1936        self._shape = "classic"
1937        self._stretchfactor = (1.0, 1.0)
1938        self._shearfactor = 0.0
1939        self._tilt = 0.0
1940        self._outlinewidth = 1
1941        self._orient = Vec2D(1, 0)
1942        self._angleOrient = 1.0
1943        self.degrees()
1944        self.clear()
1945        self.home()
1946
1947    def clear(self):
1948        """Delete the turtle's drawings from the screen. Do not move turtle.
1949
1950        No arguments.
1951
1952        Delete the turtle's drawings from the screen. Do not move turtle.
1953        State and position of the turtle as well as drawings of other
1954        turtles are not affected.
1955
1956        **Example**
1957        ```python
1958        from ipycc.turtle import Turtle, showscreen
1959
1960        # Show the screen.
1961        showscreen()
1962
1963        # Create a turtle.
1964        t = Turtle()
1965
1966        # Move the turtle forward.
1967        t.forward(50)
1968
1969        # Clear the turtle's drawings.
1970        t.clear()
1971        ```
1972        """
1973        self._pen.clear()
1974        self._update()
1975
1976    def _write(self, txt: str, align: str, fontname: str, fontsize: int | float, fonttype: str):
1977        """Performs the writing for write()
1978        """
1979        self._pen.canvas.save()
1980        self._pen.scale(1, -1)
1981        self._pen.translate(0, -self._pen.height)
1982        x, y = self._to_screen_coords(self._position)
1983        self._pen.fill(self._pencolor)
1984        self._pen.no_stroke()
1985        self._pen.text_align(align)
1986        self._pen.text_font(fontname)
1987        self._pen.text_size(fontsize)
1988        self._pen.text_style(fonttype)
1989        self._pen.text(txt, x, self._pen.height - y)
1990        self._pen.canvas.restore()
1991        self._update()
1992
1993    def write(self, arg, align: str = "left", font: tuple = ("Arial", 8, "normal")):
1994        """Write text at the current turtle position.
1995
1996        Arguments:
1997        - `arg` -- info, which is to be written to the screen
1998        - `align` (optional) -- one of the strings `"left"`, `"center"` or
1999        `"right"`
2000        - `font` (optional) -- a triple (fontname, fontsize, fonttype)
2001
2002        Write text - the string representation of `arg` - at the current
2003        turtle position according to align (`"left"`, `"center"` or `"right"`)
2004        and with the given font.
2005
2006        **Example**
2007        ```python
2008        from ipycc.turtle import Turtle, showscreen
2009
2010        # Show the screen.
2011        showscreen()
2012
2013        # Create a turtle.
2014        t = Turtle()
2015
2016        # Write messages to the screen.
2017        t.write('Home = ', align="center")
2018        t.write((0, 0))
2019        ```
2020        """
2021        fontname, fontsize, fonttype = font
2022        if not align.lower() in (Sketch.LEFT, Sketch.CENTER, Sketch.RIGHT):
2023            raise TurtleGraphicsError('Invalid text alignment. Must be "left", "center", or "right".')
2024        if not isinstance(fontsize, (int, float)):
2025            raise TurtleGraphicsError('Font size must be a number.')
2026        if not fonttype in (Sketch.NORMAL, Sketch.ITALIC, Sketch.BOLD, Sketch.BOLDITALIC):
2027            raise TurtleGraphicsError('Invalid font type. Must be "normal", "italic", "bold", or "bolditalic".')
2028        self._write(str(arg), align.lower(), fontname, fontsize, fonttype)
2029
2030    # ========================================
2031    #             Turtle State
2032    # ========================================
2033
2034    def showturtle(self):
2035        """Make the turtle visible.
2036
2037        Aliases:  `showturtle` | `st`
2038
2039        **Example**
2040        ```python
2041        from ipycc.turtle import Turtle, showscreen
2042
2043        # Show the screen.
2044        showscreen()
2045
2046        # Create a turtle.
2047        t = Turtle()
2048
2049        # Hide the turtle.
2050        t.hideturtle()
2051
2052        # Show the turtle.
2053        t.showturtle()
2054        ```
2055        """
2056        self._shown = True
2057        self._update()
2058
2059    st = showturtle
2060
2061    def hideturtle(self):
2062        """Make the turtle invisible.
2063
2064        Aliases:  `hideturtle` | `ht`
2065
2066        **Example**
2067        ```python
2068        from ipycc.turtle import Turtle, showscreen
2069
2070        # Show the screen.
2071        showscreen()
2072
2073        # Create a turtle.
2074        t = Turtle()
2075
2076        # Hide the turtle.
2077        t.hideturtle()
2078
2079        # Show the turtle.
2080        t.showturtle()
2081        ```
2082        """
2083        self._shown = False
2084        self._update()
2085
2086    ht = hideturtle
2087
2088    def isvisible(self) -> bool:
2089        """Return `True` if the turtle is shown, `False` if it's hidden.
2090
2091        **Example**
2092        ```python
2093        from ipycc.turtle import Turtle, showscreen
2094
2095        # Show the screen.
2096        showscreen()
2097
2098        # Create a turtle.
2099        t = Turtle()
2100
2101        # Hide the turtle and print whether it is visible.
2102        t.hideturtle()
2103        print(t.isvisible()) # False
2104        # Show the turtle and print whether it is visible.
2105        t.showturtle()
2106        print(t.isvisible()) # True
2107        ```
2108        """
2109        return self._shown
2110
2111    def shape(self, name: str = None) -> None | str:
2112        """Set turtle shape to shape with given name / return current shapename.
2113
2114        Optional argument:
2115        `name` -- a string, which is a valid shapename
2116
2117        Set turtle shape to shape with given `name` or, if `name` is not given,
2118        return name of current shape.
2119        Valid shapenames are:
2120        - `"arrow"`
2121        - `"turtle"`
2122        - `"circle"`
2123        - `"square"`
2124        - `"triangle"`
2125        - `"classic"`
2126
2127        ```python
2128        from ipycc.turtle import Turtle, showscreen
2129
2130        # Show the screen.
2131        showscreen()
2132
2133        # Create a turtle.
2134        t = Turtle()
2135
2136        # Print the turtle's default shape.
2137        print(t.shape()) # 'arrow'
2138
2139        # Change the turtle's shape and print it.
2140        t.shape("turtle")
2141        print(t.shape()) # 'turtle'
2142        ```
2143        """
2144        if name is None:
2145            return self._shape
2146        if not name in _turtle_shapes:
2147            raise NameError("There is no shape named %s" % name)
2148        self._shape = name
2149        self._update()
2150
2151    def shapesize(
2152        self, stretch_wid: int | float = None, stretch_len: int | float = None
2153    ) -> float:
2154        """Set/return turtle's stretchfactors/outline. Set resizemode to "user".
2155
2156        Optional arguments:
2157        - `stretch_wid` : positive number
2158        - `stretch_len` : positive number
2159        - `outline`  : positive number
2160
2161        Return or set the pen's attributes x/y-stretchfactors and/or outline.
2162        The turtle will be displayed stretched according to its stretchfactors:
2163        - `stretch_wid` is stretchfactor perpendicular to orientation.
2164        - `stretch_len` is stretchfactor in direction of the turtle's orientation.
2165        - `outline` determines the width of the shapes's outline.
2166
2167        ```python
2168        from ipycc.turtle import Turtle, showscreen
2169
2170        # Show the screen.
2171        showscreen()
2172
2173        # Create a turtle.
2174        t = Turtle()
2175
2176        # Change the turtle's shape size.
2177        t.shapesize(5, 5, 12)
2178        t.shapesize(outline=8)
2179        ```
2180        """
2181        if stretch_wid is stretch_len is None:
2182            return self._stretchfactor
2183        if stretch_wid == 0 or stretch_len == 0:
2184            raise TurtleGraphicsError("stretch_wid/stretch_len must not be zero")
2185        if stretch_wid is not None:
2186            if stretch_len is None:
2187                self._stretchfactor = stretch_wid, stretch_wid
2188            else:
2189                self._stretchfactor = stretch_wid, stretch_len
2190        elif stretch_len is not None:
2191            self._stretchfactor = self._stretchfactor[0], stretch_len
2192        else:
2193            self._stretchfactor = self._stretchfactor
2194        self._update()
2195
2196    def shearfactor(self, shear: int | float = None) -> None | float:
2197        """Set or return the current shearfactor.
2198
2199        Optional argument: `shear` -- number, tangent of the shear angle
2200
2201        Shear the turtleshape according to the given shearfactor `shear`,
2202        which is the tangent of the shear angle. Doesn't change the
2203        turtle's heading (direction of movement).
2204        If `shear` is not given: return the current shearfactor, i. e. the
2205        tangent of the shear angle, by which lines parallel to the
2206        heading of the turtle are sheared.
2207
2208        ```python
2209        from ipycc.turtle import Turtle, showscreen
2210
2211        # Show the screen.
2212        showscreen()
2213
2214        # Create a turtle.
2215        t = Turtle()
2216
2217        # Set the turtle's shape and size.
2218        t.shape("circle")
2219        t.shapesize(5, 2)
2220
2221        # Set the turtle's shear factor and print it.
2222        t.shearfactor(0.5)
2223        print(t.shearfactor()) # 0.5
2224        ```
2225        """
2226        if shear is None:
2227            return self._shearfactor
2228        self._shearfactor = shear
2229
2230    def tiltangle(self, angle: int | float = None) -> None | float:
2231        """Set or return the current tilt-angle.
2232
2233        Optional argument: `angle` -- number
2234
2235        Rotate the turtleshape to point in the direction specified by `angle`,
2236        regardless of its current tilt-angle. Doesn't change the turtle's
2237        heading (direction of movement).
2238        If `angle` is not given: return the current tilt-angle, i. e. the angle
2239        between the orientation of the turtleshape and the heading of the
2240        turtle (its direction of movement).
2241
2242        **Example**
2243        ```python
2244        from ipycc.turtle import Turtle, showscreen
2245
2246        # Show the screen.
2247        showscreen()
2248
2249        # Create a turtle.
2250        t = Turtle()
2251
2252        # Set the turtle's shape and size.
2253        t.shape("circle")
2254        t.shapesize(5, 2)
2255
2256        # Print the turtle's tilt angle.
2257        print(t.tiltangle()) # 0.0
2258
2259        # Tilt the turtle and print the angle.
2260        t.tiltangle(45)
2261        print(t.tiltangle()) # 45.0
2262
2263        # Stamp the turtle's shape.
2264        t.stamp()
2265        
2266        # Move the turtle forward.
2267        t.forward(50)
2268    
2269        #  Tilt the turtle back to its original angle and print it.
2270        t.tiltangle(-45)
2271        print(t.tiltangle()) # 315.0
2272    
2273        # Stamp the turtle's shape and move forward.
2274        t.stamp()
2275        t.forward(50)
2276        ```
2277        """
2278        if angle is None:
2279            tilt = -math.degrees(self._tilt) * self._angleOrient
2280            return (tilt / self._degreesPerAU) % self._fullcircle
2281        else:
2282            tilt = -angle * self._degreesPerAU * self._angleOrient
2283            tilt = math.radians(tilt) % math.tau
2284            self._tilt = tilt
2285
2286    def tilt(self, angle: int | float):
2287        """Rotate the turtleshape by angle.
2288
2289        Argument:
2290        `angle` -- a number
2291
2292        Rotate the turtleshape by `angle` from its current tilt-angle,
2293        but don't change the turtle's heading (direction of movement).
2294
2295        **Example**
2296        ```python
2297        from ipycc.turtle import Turtle, showscreen
2298
2299        # Show the screen.
2300        showscreen()
2301
2302        # Create a turtle.
2303        t = Turtle()
2304
2305        # Set the turtle's shape and size.
2306        t.shape("circle")
2307        t.shapesize(5, 2)
2308    
2309        # Tilt the turtle and move forward.
2310        t.tilt(30)
2311        t.forward(50)
2312
2313        # Tilt the turtle again and move forward.
2314        t.tilt(30)
2315        t.forward(50)
2316        ```
2317        """
2318        self.tiltangle(angle + self.tiltangle())
2319
2320
2321__all__ = ["Turtle", "Vec2D", "setup", "showscreen", "tracer", "delay", "no_animation", "clearscreen", "resetscreen", "colormode", "bgcolor"]