## 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:

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.

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