# 16.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.

`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.

`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 up -- 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.

`circle`(radius[, extent])
  Draw a circle with radius radius whose center-point is where the pen would be if a `forward(radius)` were called. 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.

`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.

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 `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.

Subsections

- 16.4.1 Pen and RawPen Objects