# 20.4 `turtle` -- Turtle graphics for Tk

Availability: Tk.

The `turtle` module provides turtle graphics primitives, in both an object-oriented and procedure-oriented ways. Because it uses `Tkinter` for the underlying graphics, it needs a version of python installed with Tk support.

The procedural interface uses a pen and a canvas which are automagically created when any of the functions are called.

The `turtle` module defines the following functions:

`degrees`( | )

  Set angle measurement units to degrees.

`radians`( | )

  Set angle measurement units to radians.

`setup`( | **kwargs)

  Sets the size and position of the main window. Keywords are:
  - `width`: either a size in pixels or a fraction of the screen. The default is 50% of the screen.
  - `height`: either a size in pixels or a fraction of the screen. The default is 50% of the screen.
  - `startx`: starting position in pixels from the left edge of the screen. `None` is the default value and centers the window horizontally on screen.
  - `starty`: starting position in pixels from the top edge of the screen. `None` is the default value and centers the window vertically on screen.

  Examples:

      # Uses default geometry: 50% x 50% of screen, centered.
      setup()

      # Sets window to 200x200 pixels, in upper left of screen
      setup (width=200, height=200, startx=0, starty=0)

      # Sets window to 75% of screen by 50% of screen, and centers it.
      setup(width=.75, height=0.5, startx=None, starty=None)

`title`( | title_str)

  Set the window's title to title.

`done`( | )

  Enters the Tk main loop. The window will continue to be displayed until the user closes it or the process is killed.

`reset`( | )

  Clear the screen, re-center the pen, and set variables to the default values.

`clear`( | )

  Clear the screen.

`tracer`( | flag)

  Set tracing on/off (according to whether flag is true or not). Tracing means line are drawn more slowly, with an animation of an arrow along the line.

`speed`( | speed)

  Set the speed of the turtle. Valid values for the parameter speed are `'fastest'` (no delay), `'fast'`, (delay 5ms), `'normal'` (delay 10ms), `'slow'` (delay 15ms), and `'slowest'` (delay 20ms). New in version 2.5.

`delay`( | delay)

  Set the speed of the turtle to delay, which is given in ms. New in version 2.5.

`forward`( | distance)

  Go forward distance steps.

`backward`( | distance)

  Go backward distance steps.

`left`( | angle)

  Turn left angle units. Units are by default degrees, but can be set via the `degrees()` and `radians()` functions.

`right`( | angle)

  Turn right angle units. Units are by default degrees, but can be set via the `degrees()` and `radians()` functions.

`up`( | )

  Move the pen up -- stop drawing.

`down`( | )

  Move the pen down -- draw when moving.

`width`( | width)

  Set the line width to width.

`color`( | s)

`color`( | (r, g, b))

`color`( | r, g, b)

  Set the pen color. In the first form, the color is specified as a Tk color specification as a string. The second form specifies the color as a tuple of the RGB values, each in the range [0..1]. For the third form, the color is specified giving the RGB values as three separate parameters (each in the range [0..1]).

`write`( | text[, move])

  Write text at the current pen position. If move is true, the pen is moved to the bottom-right corner of the text. By default, move is false.

`fill`( | flag)

  The complete specifications are rather complex, but the recommended usage is: call `fill(1)` before drawing a path you want to fill, and call `fill(0)` when you finish to draw the path.

`begin_fill`( | )

  Switch turtle into filling mode; Must eventually be followed by a corresponding end_fill() call. Otherwise it will be ignored. New in version 2.5.

`end_fill`( | )

  End filling mode, and fill the shape; equivalent to `fill(0)`. New in version 2.5.

`circle`( | radius[, extent])

  Draw a circle with radius radius whose center-point is radius units left of the turtle. extent determines which part of a circle is drawn: if not given it defaults to a full circle.

  If extent is not a full circle, one endpoint of the arc is the current pen position. The arc is drawn in a counter clockwise direction if radius is positive, otherwise in a clockwise direction. In the process, the direction of the turtle is changed by the amount of the extent.

`goto`( | x, y)

`goto`( | (x, y))

  Go to co-ordinates x, y. The co-ordinates may be specified either as two separate arguments or as a 2-tuple.

`towards`( | x, y)

  Return the angle of the line from the turtle's position to the point x, y. The co-ordinates may be specified either as two separate arguments, as a 2-tuple, or as another pen object. New in version 2.5.

`heading`( | )

  Return the current orientation of the turtle. New in version 2.3.

`setheading`( | angle)

  Set the orientation of the turtle to angle. New in version 2.3.

`position`( | )

  Return the current location of the turtle as an `(x,y)` pair. New in version 2.3.

`setx`( | x)

  Set the x coordinate of the turtle to x. New in version 2.3.

`sety`( | y)

  Set the y coordinate of the turtle to y. New in version 2.3.

`window_width`( | )

  Return the width of the canvas window. New in version 2.3.

`window_height`( | )

  Return the height of the canvas window. New in version 2.3.

This module also does `from math import *`, so see the documentation for the `math` module for additional constants and functions useful for turtle graphics.

`demo`( | )

  Exercise the module a bit.

exception `Error`
  Exception raised on any error caught by this module.

For examples, see the code of the `demo()` function.

This module defines the following classes:

class `Pen`( | )

  Define a pen. All above functions can be called as a methods on the given pen. The constructor automatically creates a canvas do be drawn on.

class `Turtle`( | )

  Define a pen. This is essentially a synonym for `Pen()`; `Turtle` is an empty subclass of `Pen`.

class `RawPen`( | canvas)

  Define a pen which draws on a canvas canvas. This is useful if you want to use the module to create graphics in a ``real'' program.