The Turtle API

circuitpython_Turtle_draw.jpg
Valiant Technology Ltd. CC BY-SA 3.0

Controlling the Pen

penup()

Lower the pen, causing subsequent commands will draw.

Aliases: pd(), down()

pendown()

Raise the pen, causing subsequent commands to not draw.

Alaises: pu(), up()

pencolor(color=None)

The form without an argument will return the current pen color as a 24-bit integer. The other form sets the pen color to the specified value. The Color class should be used for this value: WHITE, BLACK, RED, ORANGE, YELLOW, GREEN, BLUE, PURPLE, PINK.

E.g. turtle.pencolor(adafruit_turtle.Color.RED)

Moving

forward(distance)

Move the turtle forward (on its current heading) by the specified distance. The distance is a number of pixels if the turtle is moving exactly vertically or horizontally.

Alias: fd

backward(distance)

Move the turtle backward (opposite its current heading) by the specified distance. The distance is a number of pixels if the turtle is moving exactly vertically or horizontally.

Aliases: bk, back

setx(x)

Set the turtle's horizontal coordinate.

sety(y)

Set the turtle's vertical coordinate.

goto(x, y)

Set both coordinates of the turtle.

Heading

Drawing in a straight line isn't that interesting, so the direction that the turtle is facing (and thus moving) can be changed. This is called its heading. The first two functions below set what it means to change the heading by some value. The result of calling these methods stay in effect until the next call to one of them. By default, degrees are used, with a change of 1 corresponding to 1 degree.

degrees(fullcircle=360)

A full circle is 360 degrees and, by default, changing the heading by 1 means changing it by one degree. Supplying a different value will serve to scale those incremental heading changes. For example, if you call degrees(180), changing the heading by 1 will change it by 2 degrees.

radians()

Use radians to turn the turtle. Changing the heading by 1 now means changing it by 1 radian (about 57.3 degrees).

The remaining methods change the turtle's heading.

left(angle)

Turn the turtle left by angle (what that means is subject to the above methods).

Alias: lt

right(angle)

Turn the turtle right by angle (what that means is subject to the above methods).

Alias: rt

setheading(angle)

Set the heading of the turtle to angle. Up is an angle of 0, right is 90.

Alias: seth

Shapes

dot(radius=None, color=None)

Draw a filled-in circle centered on the turtle's current position. Turtle position and heading are unchanged.

If radius is omitted a reasonable one is used, otherwise radius is used as the radius of the dot. If color is omitted the current pen color is used, otherwise color is used. This does not change the pen's color. As above, colors are available from the Color class.

circle(radius, extent=None, steps=None)

Draw a unfilled circle using the turtle's current pen color. This uses a computed sequence of calls to forward and left so the turtle's position and heading are changed.  Since the circle drawing uses left, it draws counterclockwise by default. If radius is negative (i.e. < 0) drawing is done clockwise.

The radius of the desired circle is specified by radius, which is a number of pixels from the center to the edge.

The argument extent specifies what portion of the circle to draw and is specified in the same units as calls to left and right, as determined by the most recent call to degrees or radians. The default is to draw the complete circle. Calling circle(10, extent=180) will draw half a circle of radius 10, assuming that radians hasn't been called and neither has degrees with an argument other than 360. The turtle's heading is always what it was after drawing the last part of the circle, regardless extent. This will always be at the tangent to the circle. You can use this in your drawings. E.g. to draw a closed half-circle:

Download: file
turtle.circle(20, extent=180)
turtle.left(90)
turtle.forward(40)

The final argument, steps, determines how many sides the circle has. By default (steps is None) as many are used as required to create a smooth circle. Specifying a value for steps has the effect of drawing that many line segments instead. So circle(radius r, steps=6) will draw a hexagon.

If you draw a full circle, the turtle will end up back where it started with the heading it started with. By drawing circles (of other polygons by using steps)  repeatedly and turning between each, some interesting designs can be created.

Download: file
for _ in range(36):
  turtle.circle(50, steps=6)
  turtle.left(10)

More control

home()

Move the turtle to its initial position and heading.

clear()

Clear the screen, the position and heading of the turtle is unaffected.

Queries

These methods let you ask the turtle about aspects of it's current state.

pos()

Returns the turtle's (x, y) position.

xcor()

Returns the turtle's x coordinate.

ycor()

Returns the turtle's y coordinate.

heading()

Returns the turtle's heading.

isdown()

Returns whether the pen is down (i.e. drawing).

This guide was first published on Nov 05, 2019. It was last updated on Nov 05, 2019. This page (The Turtle API) was last updated on Dec 05, 2019.