> **Источник:** https://python-all.ru/3.15/library/turtle.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `turtle` – Черепашья графика

**Исходный код:** [Lib/turtle.py](https://python-all.ru/src/3.15/Lib/turtle.py)

---

## Введение

Черепашья графика – это реализация [популярных инструментов геометрического рисования, впервые представленных в Logo](https://python-all.ru/3.15/library/turtle.html), разработанных Уолли Фёрзейгом, Сеймуром Пейпертом и Синтией Соломон в 1967 году.

Это [опциональный модуль](https://python-all.ru/3.15/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3.15/using/configure.html#optional-module-requirements).

## Начало работы

Представьте роботизированную черепашку, начинающую с точки (0, 0) на плоскости x-y. После `import turtle` дайте ей команду `turtle.forward(15)`, и она переместится (на экране!) на 15 пикселей в том направлении, куда смотрит, рисуя линию во время движения. Дайте ей команду `turtle.right(25)`, и она повернётся на месте на 25 градусов по часовой стрелке.

Черепашья звезда

Черепашка может рисовать сложные фигуры с помощью программ, повторяющих простые движения.

![../_images/turtle-star.png](https://python-all.ru/3.15/_images/turtle-star.png)

В Python черепашья графика предоставляет представление физической «черепашки» (маленького робота с пером), которая рисует на листе бумаги на полу.

Это эффективный и проверенный способ для учащихся знакомиться с концепциями программирования и взаимодействием с программным обеспечением, поскольку он обеспечивает мгновенную видимую обратную связь. Он также предоставляет удобный доступ к графическому выводу в целом.

Рисование с помощью черепашки было изначально создано как образовательный инструмент для использования учителями в классе. Для программиста, которому нужно получить некоторый графический вывод, это может быть способом сделать это без излишних сложностей, связанных с внедрением более сложных или внешних библиотек в свою работу.

## Учебное руководство

Здесь следует начать новым пользователям. В этом руководстве мы рассмотрим некоторые основы рисования с помощью черепашки.

### Запуск среды черепашки

В оболочке Python импортируйте все объекты модуля `turtle`:

```python
from turtle import *
```

Если вы столкнётесь с ошибкой `No module named '_tkinter'`, вам придётся установить [`Tk interface package`](https://python-all.ru/3.15/library/tkinter.html#module-tkinter) в вашу систему.

### Основы рисования

Отправьте черепашку вперёд на 100 шагов:

```python
forward(100)
```

Вы должны увидеть (скорее всего, в новом окне на вашем дисплее) линию, нарисованную черепашкой, направленную на восток. Измените направление черепашки так, чтобы она повернулась на 120 градусов влево (против часовой стрелки):

```python
left(120)
```

Давайте продолжим, нарисовав треугольник:

```python
forward(100)
left(120)
forward(100)
```

Обратите внимание, как черепашка, представленная стрелкой, указывает в разные направления по мере управления ею.

Экспериментируйте с этими командами, а также с `backward()` и `right()`.

#### Управление пером

Попробуйте изменить цвет (например, `color('blue')`) и толщину линии (например, `width(3)`), а затем снова нарисуйте.

Вы также можете перемещать черепашку без рисования, подняв перо: `up()` перед перемещением. Чтобы снова начать рисовать, используйте `down()`.

#### Позиция черепашки

Отправьте черепашку обратно в начальную точку (полезно, если она исчезла с экрана):

```python
home()
```

Домашняя позиция находится в центре экрана черепашки. Если вам когда-нибудь понадобится их узнать, получите x-y координаты черепашки с помощью:

```python
pos()
```

Дом находится в `(0, 0)`.

И через некоторое время, вероятно, будет полезно очистить окно, чтобы начать заново:

```python
clearscreen()
```

### Создание алгоритмических узоров

Используя циклы, можно построить геометрические узоры:

```python
for steps in range(100):
    for c in ('blue', 'red', 'green'):
        color(c)
        forward(steps)
        right(30)
```

– которые, конечно, ограничены только воображением!

Нарисуем звезду в верхней части этой страницы. Линии – красные, заливка – жёлтая:

```python
color('red')
fillcolor('yellow')
```

Так же, как `up()` и `down()` определяют, будут ли рисоваться линии, заливку можно включать и выключать:

```python
begin_fill()
```

Далее создадим цикл:

```python
while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break
```

`abs(pos()) < 1` – хороший способ узнать, когда черепашка вернулась в исходное положение.

Наконец, завершите заливку:

```python
end_fill()
```

(Обратите внимание: заливка фактически происходит только после команды `end_fill()`.)

## Как…

В этом разделе рассматриваются некоторые типичные варианты использования черепашьей графики и подходы к работе с ней.

### Начать как можно быстрее

Одно из удовольствий черепашьей графики – мгновенная визуальная обратная связь от простых команд. Это отличный способ познакомить детей с идеями программирования с минимальными усилиями (конечно, не только детей).

Модуль turtle делает это возможным, предоставляя всю базовую функциональность в виде функций, доступных через `from turtle import *`. В [руководстве по черепашьей графике](https://python-all.ru/3.15/library/turtle.html#turtle-tutorial) описан этот подход.

Стоит отметить, что многие команды черепашки имеют ещё более краткие эквиваленты, например `fd()` для [`forward()`](https://python-all.ru/3.15/library/turtle.html#turtle.forward). Они особенно полезны при работе с теми, кто ещё не освоил набор текста.

> Для работы черепашьей графики необходимо, чтобы в системе был установлен [`Tk interface package`](https://python-all.ru/3.15/library/tkinter.html#module-tkinter). Имейте в виду, что это не всегда тривиально, поэтому проверьте заранее, если планируете использовать черепашью графику с учеником.

### Автоматически начинать и завершать заливку

Начиная с Python 3.14, можно использовать [`fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.fill) [контекстный менеджер](https://python-all.ru/3.15/glossary.html#term-context-manager) вместо [`begin_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.begin_fill) и [`end_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.end_fill) для автоматического начала и завершения заливки. Вот пример:

```python
with fill():
    for i in range(4):
        forward(100)
        right(90)

forward(200)
```

Приведённый выше код эквивалентен:

```python
begin_fill()
for i in range(4):
    forward(100)
    right(90)
end_fill()

forward(200)
```

### Использовать пространство имён модуля `turtle`

Использовать `from turtle import *` удобно, но учтите: он импортирует довольно большое количество объектов, и если вы занимаетесь чем-то, кроме черепашьей графики, возникает риск конфликта имён (особенно если вы используете черепашью графику в скрипте, где могут импортироваться другие модули).

Решение – использовать `import turtle`: `fd()` становится `turtle.fd()`, `width()` становится `turtle.width()` и так далее. (Если постоянно набирать «turtle» утомительно, используйте, например, `import turtle as t`.)

### Использовать черепашью графику в скрипте

Рекомендуется использовать пространство имён модуля `turtle`, как описано непосредственно выше, например:

```python
import turtle as t
from random import random

for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)
```

Однако требуется ещё один шаг: как только скрипт завершится, Python закроет окно черепашки. Добавьте:

```python
t.mainloop()
```

в конец скрипта. Теперь скрипт будет ждать завершения и не завершится, пока его не прервут, например, закрыв окно черепашьей графики.

### Использовать объектно-ориентированную черепашью графику

> **См. также**
>
> [Объяснение объектно-ориентированного интерфейса](https://python-all.ru/3.15/library/turtle.html#turtle-explanation)

За исключением самых простых вводных целей или быстрого опробования, гораздо более привычно и эффективно использовать объектно-ориентированный подход к черепашьей графике. Например, это позволяет одновременно разместить на экране несколько черепашек.

В этом подходе различные команды черепашки являются методами объектов (в основном объектов `Turtle`). *Можно* использовать объектно-ориентированный подход в оболочке, но чаще это делают в Python-скрипте.

Тогда приведённый выше пример становится таким:

```python
from turtle import Turtle
from random import random

t = Turtle()
for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

t.screen.mainloop()
```

Обратите внимание на последнюю строку. `t.screen` – это экземпляр [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen), на котором существует экземпляр Turtle; он создаётся автоматически вместе с черепашкой.

Экран черепашки можно настроить, например:

```python
t.screen.title('Object-oriented turtle demo')
t.screen.bgcolor("orange")
```

## Справочник по черепашьей графике

> **Примечание**
>
> В следующей документации приведён список аргументов для функций. Методы, конечно, имеют дополнительный первый аргумент *self*, который здесь опущен.

### Методы черепахи

**Движение черепахи**

**Перемещение и рисование**

[`forward()`](https://python-all.ru/3.15/library/turtle.html#turtle.forward)

|

[`fd()`](https://python-all.ru/3.15/library/turtle.html#turtle.fd)

[`backward()`](https://python-all.ru/3.15/library/turtle.html#turtle.backward)

|

[`bk()`](https://python-all.ru/3.15/library/turtle.html#turtle.bk)

|

[`back()`](https://python-all.ru/3.15/library/turtle.html#turtle.back)

[`right()`](https://python-all.ru/3.15/library/turtle.html#turtle.right)

|

[`rt()`](https://python-all.ru/3.15/library/turtle.html#turtle.rt)

[`left()`](https://python-all.ru/3.15/library/turtle.html#turtle.left)

|

[`lt()`](https://python-all.ru/3.15/library/turtle.html#turtle.lt)

[`goto()`](https://python-all.ru/3.15/library/turtle.html#turtle.goto)

|

[`setpos()`](https://python-all.ru/3.15/library/turtle.html#turtle.setpos)

|

[`setposition()`](https://python-all.ru/3.15/library/turtle.html#turtle.setposition)

[`teleport()`](https://python-all.ru/3.15/library/turtle.html#turtle.teleport)

[`setx()`](https://python-all.ru/3.15/library/turtle.html#turtle.setx)

[`sety()`](https://python-all.ru/3.15/library/turtle.html#turtle.sety)

[`setheading()`](https://python-all.ru/3.15/library/turtle.html#turtle.setheading)

|

[`seth()`](https://python-all.ru/3.15/library/turtle.html#turtle.seth)

[`home()`](https://python-all.ru/3.15/library/turtle.html#turtle.home)

[`circle()`](https://python-all.ru/3.15/library/turtle.html#turtle.circle)

[`dot()`](https://python-all.ru/3.15/library/turtle.html#turtle.dot)

[`stamp()`](https://python-all.ru/3.15/library/turtle.html#turtle.stamp)

[`clearstamp()`](https://python-all.ru/3.15/library/turtle.html#turtle.clearstamp)

[`clearstamps()`](https://python-all.ru/3.15/library/turtle.html#turtle.clearstamps)

[`undo()`](https://python-all.ru/3.15/library/turtle.html#turtle.undo)

[`speed()`](https://python-all.ru/3.15/library/turtle.html#turtle.speed)

**Состояние черепахи**

[`position()`](https://python-all.ru/3.15/library/turtle.html#turtle.position)

|

[`pos()`](https://python-all.ru/3.15/library/turtle.html#turtle.pos)

[`towards()`](https://python-all.ru/3.15/library/turtle.html#turtle.towards)

[`xcor()`](https://python-all.ru/3.15/library/turtle.html#turtle.xcor)

[`ycor()`](https://python-all.ru/3.15/library/turtle.html#turtle.ycor)

[`heading()`](https://python-all.ru/3.15/library/turtle.html#turtle.heading)

[`distance()`](https://python-all.ru/3.15/library/turtle.html#turtle.distance)

**Настройка и измерение**

[`degrees()`](https://python-all.ru/3.15/library/turtle.html#turtle.degrees)

[`radians()`](https://python-all.ru/3.15/library/turtle.html#turtle.radians)

**Управление пером**

**Состояние рисования**

[`pendown()`](https://python-all.ru/3.15/library/turtle.html#turtle.pendown)

|

[`pd()`](https://python-all.ru/3.15/library/turtle.html#turtle.pd)

|

[`down()`](https://python-all.ru/3.15/library/turtle.html#turtle.down)

[`penup()`](https://python-all.ru/3.15/library/turtle.html#turtle.penup)

|

[`pu()`](https://python-all.ru/3.15/library/turtle.html#turtle.pu)

|

[`up()`](https://python-all.ru/3.15/library/turtle.html#turtle.up)

[`pensize()`](https://python-all.ru/3.15/library/turtle.html#turtle.pensize)

|

[`width()`](https://python-all.ru/3.15/library/turtle.html#turtle.width)

[`pen()`](https://python-all.ru/3.15/library/turtle.html#turtle.pen)

[`isdown()`](https://python-all.ru/3.15/library/turtle.html#turtle.isdown)

**Управление цветом**

[`color()`](https://python-all.ru/3.15/library/turtle.html#turtle.color)

[`pencolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.pencolor)

[`fillcolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.fillcolor)

**Заливка**

[`filling()`](https://python-all.ru/3.15/library/turtle.html#turtle.filling)

[`fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.fill)

[`begin_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.begin_fill)

[`end_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.end_fill)

**Дополнительное управление рисованием**

[`reset()`](https://python-all.ru/3.15/library/turtle.html#turtle.reset)

[`clear()`](https://python-all.ru/3.15/library/turtle.html#turtle.clear)

[`write()`](https://python-all.ru/3.15/library/turtle.html#turtle.write)

**Состояние черепахи**

**Видимость**

[`showturtle()`](https://python-all.ru/3.15/library/turtle.html#turtle.showturtle)

|

[`st()`](https://python-all.ru/3.15/library/turtle.html#turtle.st)

[`hideturtle()`](https://python-all.ru/3.15/library/turtle.html#turtle.hideturtle)

|

[`ht()`](https://python-all.ru/3.15/library/turtle.html#turtle.ht)

[`isvisible()`](https://python-all.ru/3.15/library/turtle.html#turtle.isvisible)

**Внешний вид**

[`shape()`](https://python-all.ru/3.15/library/turtle.html#turtle.shape)

[`resizemode()`](https://python-all.ru/3.15/library/turtle.html#turtle.resizemode)

[`shapesize()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapesize)

|

[`turtlesize()`](https://python-all.ru/3.15/library/turtle.html#turtle.turtlesize)

[`shearfactor()`](https://python-all.ru/3.15/library/turtle.html#turtle.shearfactor)

[`tiltangle()`](https://python-all.ru/3.15/library/turtle.html#turtle.tiltangle)

[`tilt()`](https://python-all.ru/3.15/library/turtle.html#turtle.tilt)

[`shapetransform()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapetransform)

[`get_shapepoly()`](https://python-all.ru/3.15/library/turtle.html#turtle.get_shapepoly)

**Использование событий**

[`onclick()`](https://python-all.ru/3.15/library/turtle.html#turtle.onclick)

[`onrelease()`](https://python-all.ru/3.15/library/turtle.html#turtle.onrelease)

[`ondrag()`](https://python-all.ru/3.15/library/turtle.html#turtle.ondrag)

**Специальные методы черепахи**

[`poly()`](https://python-all.ru/3.15/library/turtle.html#turtle.poly)

[`begin_poly()`](https://python-all.ru/3.15/library/turtle.html#turtle.begin_poly)

[`end_poly()`](https://python-all.ru/3.15/library/turtle.html#turtle.end_poly)

[`get_poly()`](https://python-all.ru/3.15/library/turtle.html#turtle.get_poly)

[`clone()`](https://python-all.ru/3.15/library/turtle.html#turtle.clone)

[`getturtle()`](https://python-all.ru/3.15/library/turtle.html#turtle.getturtle)

|

[`getpen()`](https://python-all.ru/3.15/library/turtle.html#turtle.getpen)

[`getscreen()`](https://python-all.ru/3.15/library/turtle.html#turtle.getscreen)

[`setundobuffer()`](https://python-all.ru/3.15/library/turtle.html#turtle.setundobuffer)

[`undobufferentries()`](https://python-all.ru/3.15/library/turtle.html#turtle.undobufferentries)

### Методы TurtleScreen/Screen

**Управление окном**

[`bgcolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.bgcolor)

[`bgpic()`](https://python-all.ru/3.15/library/turtle.html#turtle.bgpic)

[`clearscreen()`](https://python-all.ru/3.15/library/turtle.html#turtle.clearscreen)

[`resetscreen()`](https://python-all.ru/3.15/library/turtle.html#turtle.resetscreen)

[`screensize()`](https://python-all.ru/3.15/library/turtle.html#turtle.screensize)

[`setworldcoordinates()`](https://python-all.ru/3.15/library/turtle.html#turtle.setworldcoordinates)

**Управление анимацией**

[`no_animation()`](https://python-all.ru/3.15/library/turtle.html#turtle.no_animation)

[`delay()`](https://python-all.ru/3.15/library/turtle.html#turtle.delay)

[`tracer()`](https://python-all.ru/3.15/library/turtle.html#turtle.tracer)

[`update()`](https://python-all.ru/3.15/library/turtle.html#turtle.update)

**Использование событий экрана**

[`listen()`](https://python-all.ru/3.15/library/turtle.html#turtle.listen)

[`onkey()`](https://python-all.ru/3.15/library/turtle.html#turtle.onkey)

|

[`onkeyrelease()`](https://python-all.ru/3.15/library/turtle.html#turtle.onkeyrelease)

[`onkeypress()`](https://python-all.ru/3.15/library/turtle.html#turtle.onkeypress)

[`onclick()`](https://python-all.ru/3.15/library/turtle.html#turtle.onclick)

|

[`onscreenclick()`](https://python-all.ru/3.15/library/turtle.html#turtle.onscreenclick)

[`ontimer()`](https://python-all.ru/3.15/library/turtle.html#turtle.ontimer)

[`mainloop()`](https://python-all.ru/3.15/library/turtle.html#turtle.mainloop)

|

[`done()`](https://python-all.ru/3.15/library/turtle.html#turtle.done)

**Настройки и специальные методы**

[`mode()`](https://python-all.ru/3.15/library/turtle.html#turtle.mode)

[`colormode()`](https://python-all.ru/3.15/library/turtle.html#turtle.colormode)

[`getcanvas()`](https://python-all.ru/3.15/library/turtle.html#turtle.getcanvas)

[`getshapes()`](https://python-all.ru/3.15/library/turtle.html#turtle.getshapes)

[`register_shape()`](https://python-all.ru/3.15/library/turtle.html#turtle.register_shape)

|

[`addshape()`](https://python-all.ru/3.15/library/turtle.html#turtle.addshape)

[`turtles()`](https://python-all.ru/3.15/library/turtle.html#turtle.turtles)

[`window_height()`](https://python-all.ru/3.15/library/turtle.html#turtle.window_height)

[`window_width()`](https://python-all.ru/3.15/library/turtle.html#turtle.window_width)

**Методы ввода**

[`textinput()`](https://python-all.ru/3.15/library/turtle.html#turtle.textinput)

[`numinput()`](https://python-all.ru/3.15/library/turtle.html#turtle.numinput)

**Методы, специфичные для Screen**

[`bye()`](https://python-all.ru/3.15/library/turtle.html#turtle.bye)

[`exitonclick()`](https://python-all.ru/3.15/library/turtle.html#turtle.exitonclick)

[`save()`](https://python-all.ru/3.15/library/turtle.html#turtle.save)

[`setup()`](https://python-all.ru/3.15/library/turtle.html#turtle.setup)

[`title()`](https://python-all.ru/3.15/library/turtle.html#turtle.title)

## Методы RawTurtle/Turtle и соответствующие функции

Большинство примеров в этом разделе ссылаются на экземпляр Turtle с именем `turtle`.

### Движение черепахи

#### `turtle.forward(distance)`

#### `turtle.fd(distance)`

**Параметры:**

**distance** – число (целое или с плавающей запятой)

Перемещает черепаху вперед на указанное *distance*, в направлении, в котором черепаха смотрит.

```pycon
>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)
```

#### `turtle.back(distance)`

#### `turtle.bk(distance)`

#### `turtle.backward(distance)`

**Параметры:**

**distance** – число

Перемещает черепаху назад на *расстояние*, противоположно направлению, в котором черепаха смотрит. Направление черепахи не меняется.

```pycon
>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)
```

#### `turtle.right(angle)`

#### `turtle.rt(angle)`

**Параметры:**

**angle** – число (целое или с плавающей запятой)

Поворачивает черепаху вправо на *angle* единиц. (По умолчанию единицы – градусы, но их можно изменить с помощью функций [`degrees()`](https://python-all.ru/3.15/library/turtle.html#turtle.degrees) и [`radians()`](https://python-all.ru/3.15/library/turtle.html#turtle.radians).) Направление поворота зависит от режима черепахи, см. [`mode()`](https://python-all.ru/3.15/library/turtle.html#turtle.mode).

```pycon
>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0
```

#### `turtle.left(angle)`

#### `turtle.lt(angle)`

**Параметры:**

**angle** – число (целое или с плавающей запятой)

Поворачивает черепаху влево на *angle* единиц. (По умолчанию единицы – градусы, но их можно изменить с помощью функций [`degrees()`](https://python-all.ru/3.15/library/turtle.html#turtle.degrees) и [`radians()`](https://python-all.ru/3.15/library/turtle.html#turtle.radians).) Направление поворота зависит от режима черепахи, см. [`mode()`](https://python-all.ru/3.15/library/turtle.html#turtle.mode).

```pycon
>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0
```

#### `turtle.goto(x, y=None)`

#### `turtle.setpos(x, y=None)`

#### `turtle.setposition(x, y=None)`

**Параметры:**

- **x** – число или пара/вектор чисел
- **y** – число или `None`

Если *y* равно `None`, то *x* должно быть парой координат или [`Vec2D`](https://python-all.ru/3.15/library/turtle.html#turtle.Vec2D) (например, как возвращается функцией [`pos()`](https://python-all.ru/3.15/library/turtle.html#turtle.pos)).

Перемещает черепаху в абсолютную позицию. Если перо опущено, рисует линию. Направление черепахи не меняется.

```pycon
>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)
```

#### `turtle.teleport(x, y=None, *, fill_gap=False)`

**Параметры:**

- **x** – число или `None`
- **y** – число или `None`
- **fill\_gap** – логическое значение

Перемещает черепаху в абсолютную позицию. В отличие от goto(x, y), линия не рисуется. Направление черепахи не меняется. Если в данный момент выполняется заливка, многоугольник(и), из которого телепортировали, будут залиты после выхода, и заливка начнется снова после телепортации. Это можно отключить с помощью fill\_gap=True, что делает воображаемую линию, пройденную во время телепортации, барьером заливки, как в goto(x, y).

```pycon
>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.teleport(60)
>>> turtle.pos()
(60.00,0.00)
>>> turtle.teleport(y=10)
>>> turtle.pos()
(60.00,10.00)
>>> turtle.teleport(20, 30)
>>> turtle.pos()
(20.00,30.00)
```

Добавлено в версии 3.12.

#### `turtle.setx(x)`

**Параметры:**

**x** – число (целое или с плавающей запятой)

Устанавливает первую координату черепахи в *x*, вторая координата остается без изменений.

```pycon
>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)
```

#### `turtle.sety(y)`

**Параметры:**

**y** – число (целое или с плавающей запятой)

Устанавливает вторую координату черепахи в *y*, первая координата остается без изменений.

```pycon
>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)
```

#### `turtle.setheading(to_angle)`

#### `turtle.seth(to_angle)`

**Параметры:**

**to\_angle** – число (целое или с плавающей запятой)

Устанавливает направление черепахи в *to\_angle*. Вот некоторые распространенные направления в градусах:

| стандартный режим | режим Logo |
| --- | --- |
| 0 – восток | 0 – север |
| 90 – север | 90 – восток |
| 180 – запад | 180 – юг |
| 270 – юг | 270 – запад |

```pycon
>>> turtle.setheading(90)
>>> turtle.heading()
90.0
```

#### `turtle.home()`

Перемещает черепаху в начало координат – (0,0) – и устанавливает её направление в начальную ориентацию (зависит от режима, см. [`mode()`](https://python-all.ru/3.15/library/turtle.html#turtle.mode)).

```pycon
>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
```

#### `turtle.circle(radius, extent=None, steps=None)`

**Параметры:**

- **radius** – число
- **extent** – число (или `None`)
- **steps** – целое число (или `None`)

Рисует окружность с заданным *radius*. Центр находится на *radius* единиц левее черепахи; *extent* – угол – определяет, какая часть окружности рисуется. Если *extent* не указан, рисуется вся окружность. Если *extent* не является полной окружностью, одна из конечных точек дуги – это текущее положение пера. Дуга рисуется против часовой стрелки, если *radius* положительный, и по часовой стрелке в противном случае. В конце направление черепахи изменяется на величину *extent*.

Поскольку окружность аппроксимируется вписанным правильным многоугольником, *steps* определяет количество используемых шагов. Если не указано, вычисляется автоматически. Может использоваться для рисования правильных многоугольников.

```pycon
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # нарисовать полуокружность
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0
```

#### `turtle.dot()`

#### `turtle.dot(size)`

#### `turtle.dot(color, /)`

#### `turtle.dot(size, color, /)`

#### `turtle.dot(size, r, g, b, /)`

**Параметры:**

- **size** – целое число \>= 1 (если указано)
- **color** – строка цвета или кортеж числовых цветов

Рисует круглую точку диаметром *size*, используя *color*. Если *size* не указан, используется максимум из `pensize+4` и `2*pensize`.

```pycon
>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0
```

#### `turtle.stamp()`

Наносит копию формы черепахи на холст в текущей позиции черепахи. Возвращает stamp\_id для этой печати, который можно использовать для её удаления вызовом `clearstamp(stamp_id)`.

```pycon
>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)
```

#### `turtle.clearstamp(stampid)`

**Параметры:**

**stampid** – целое число, должно быть возвращаемым значением предыдущего вызова [`stamp()`](https://python-all.ru/3.15/library/turtle.html#turtle.stamp)

Удаляет печать с заданным *stampid*.

```pycon
>>> turtle.position()
(150.00,-0.00)
>>> turtle.color("blue")
>>> astamp = turtle.stamp()
>>> turtle.fd(50)
>>> turtle.position()
(200.00,-0.00)
>>> turtle.clearstamp(astamp)
>>> turtle.position()
(200.00,-0.00)
```

#### `turtle.clearstamps(n=None)`

**Параметры:**

**n** – целое число (или `None`)

Удаляет все или первые/последние *n* отпечатков черепашки. Если *n* равно `None`, удаляет все отпечатки, если *n* \> 0, удаляет первые *n* отпечатков, а если *n* \< 0, удаляет последние *n* отпечатков.

```pycon
>>> for i in range(8):
...     unused_stamp_id = turtle.stamp()
...     turtle.fd(30)
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()
```

#### `turtle.undo()`

Отменяет (повторно) последнее(ие) действие(я) черепашки. Количество доступных действий отмены определяется размером буфера отмены.

```pycon
>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()
```

#### `turtle.speed(speed=None)`

**Параметры:**

**speed** – целое число в диапазоне 0..10 или speedstring (см. ниже).

Устанавливает скорость черепашки в целое значение от 0 до 10. Если аргумент не указан, возвращает текущую скорость.

Если входное значение – число больше 10 или меньше 0.5, скорость устанавливается в 0. Speedstrings сопоставляются со значениями скорости следующим образом:

- «самый быстрый»: 0
- «быстрый»: 10
- “обычная”: 6
- “медленная”: 3
- “самая медленная”: 1

Скорости от 1 до 10 обеспечивают всё более быструю анимацию рисования линий и поворотов черепашки.

Внимание: *speed* = 0 означает, что *никакой* анимации не происходит. forward/back заставляют черепашку прыгать, а left/right заставляют черепашку мгновенно поворачиваться.

```pycon
>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9
```

### Состояние черепашки

#### `turtle.position()`

#### `turtle.pos()`

Возвращает текущее положение черепашки (x,y) (в виде [`Vec2D`](https://python-all.ru/3.15/library/turtle.html#turtle.Vec2D) вектора).

```pycon
>>> turtle.pos()
(440.00,-0.00)
```

#### `turtle.towards(x, y=None)`

**Параметры:**

- **x** – число или пара/вектор чисел, или экземпляр черепашки
- **y** – число, если *x* – число, иначе `None`

Возвращает угол между линией от положения черепашки до точки, указанной через (x,y), указанного вектора или другой черепашки. Это зависит от начальной ориентации черепашки, которая зависит от режима – “standard”/“world” или “logo”.

```pycon
>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0
```

#### `turtle.xcor()`

Возвращает x-координату черепашки.

```pycon
>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876
```

#### `turtle.ycor()`

Возвращает y-координату черепашки.

```pycon
>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254
```

#### `turtle.heading()`

Возвращает текущий курс черепашки (значение зависит от режима черепашки, см. [`mode()`](https://python-all.ru/3.15/library/turtle.html#turtle.mode)).

```pycon
>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0
```

#### `turtle.distance(x, y=None)`

**Параметры:**

- **x** – число или пара/вектор чисел, или экземпляр черепашки
- **y** – число, если *x* – число, иначе `None`

Возвращает расстояние от черепашки до точки (x,y), указанного вектора или указанной другой черепашки в единицах шага черепашки.

```pycon
>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0
```

### Настройки измерения

#### `turtle.degrees(fullcircle=360.0)`

**Параметры:**

**fullcircle** – число

Устанавливает единицы измерения углов, то есть задаёт количество «градусов» в полном обороте. Значение по умолчанию – 360 градусов.

```pycon
>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0

>>> # Изменить единицу измерения угла на град (также известный как гон,
>>> # град, или градиан, и равная 1/100 прямого угла.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0
```

#### `turtle.radians()`

Устанавливает единицы измерения углов в радианах. Эквивалентно `degrees(2*math.pi)`.

```pycon
>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966
```

### Управление пером

#### Состояние рисования

#### `turtle.pendown()`

#### `turtle.pd()`

#### `turtle.down()`

Опускает перо – рисование при движении.

#### `turtle.penup()`

#### `turtle.pu()`

#### `turtle.up()`

Поднимает перо – при движении не рисует.

#### `turtle.pensize(width=None)`

#### `turtle.width(width=None)`

**Параметры:**

**width** – положительное число

Устанавливает толщину линии в *width* или возвращает её. Если для resizemode установлено «auto» и форма черепашки является многоугольником, этот многоугольник рисуется с такой же толщиной линии. Если аргумент не указан, возвращается текущая толщина пера.

```pycon
>>> turtle.pensize()
1
>>> turtle.pensize(10)   # отсюда рисуются линии шириной 10
```

#### `turtle.pen(pen=None, **pendict)`

**Параметры:**

- **pen** – словарь, содержащий некоторые или все из перечисленных ниже ключей
- **pendict** – один или несколько именованных аргументов, использующих перечисленные ниже ключи

Возвращает или устанавливает атрибуты пера в виде «словаря пера» со следующими парами ключ/значение:

- “отображается”: True/False
- “перо опущено”: True/False
- “цвет пера”: строка цвета или кортеж цвета
- “цвет заливки”: строка цвета или кортеж цвета
- “размер пера”: положительное число
- “скорость”: число от 0 до 10
- “режим изменения размера”: “auto” or “user” or “noresize”
- “коэффициент растяжения”: (положительное число, положительное число)
- «outline»: положительное число
- «tilt»: число

Этот словарь можно передать аргументом в последующий вызов `pen()`, чтобы восстановить предыдущее состояние пера. Кроме того, один или несколько из этих атрибутов можно указать как именованные аргументы. Это позволяет установить несколько атрибутов пера одной инструкцией.

```pycon
>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]
```

#### `turtle.isdown()`

Возвращает `True`, если перо опущено, и `False`, если поднято.

```pycon
>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True
```

#### Управление цветом

#### `turtle.pencolor()`

#### `turtle.pencolor(color, /)`

#### `turtle.pencolor(r, g, b, /)`

Возвращает или задаёт цвет пера.

Допускаются четыре формата ввода:

**`pencolor()`**

Возвращает текущий цвет пера в виде строки описания цвета или кортежа (см. пример). Может использоваться как аргумент для другого вызова color/pencolor/fillcolor/bgcolor.

**`pencolor(colorstring)`**

Задаёт цвет пера равным *colorstring*, строке описания цвета Tk, например, `"red"`, `"yellow"` или `"#33cc8c"`.

**`pencolor((r, g, b))`**

Задаёт цвет пера по цвету RGB, представленному кортежем из *r*, *g* и *b*. Каждое из значений *r*, *g* и *b* должно быть в диапазоне 0..colormode, где colormode равен 1.0 или 255 (см. [`colormode()`](https://python-all.ru/3.15/library/turtle.html#turtle.colormode)).

**`pencolor(r, g, b)`**

Задаёт цвет пера по цвету RGB, заданному *r*, *g* и *b*. Каждое из значений *r*, *g* и *b* должно быть в диапазоне 0..colormode.

Если форма черепахи (turtleshape) является многоугольником, то контур этого многоугольника рисуется вновь заданным цветом пера.

```pycon
>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51.0, 204.0, 140.0)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
```

#### `turtle.fillcolor()`

#### `turtle.fillcolor(color, /)`

#### `turtle.fillcolor(r, g, b, /)`

Возвращает или задаёт цвет заливки.

Допускаются четыре формата ввода:

**`fillcolor()`**

Возвращает текущий цвет заливки в виде строки описания цвета, возможно в формате кортежа (см. пример). Может использоваться как аргумент для другого вызова color/pencolor/fillcolor/bgcolor.

**`fillcolor(colorstring)`**

Задаёт цвет заливки равным *colorstring*, строке описания цвета Tk, например, `"red"`, `"yellow"` или `"#33cc8c"`.

**`fillcolor((r, g, b))`**

Задаёт цвет заливки по цвету RGB, представленному кортежем из *r*, *g* и *b*. Каждое из значений *r*, *g* и *b* должно быть в диапазоне 0..colormode, где colormode равен 1.0 или 255 (см. [`colormode()`](https://python-all.ru/3.15/library/turtle.html#turtle.colormode)).

**`fillcolor(r, g, b)`**

Задаёт цвет заливки по цвету RGB, заданному *r*, *g* и *b*. Каждое из значений *r*, *g* и *b* должно быть в диапазоне 0..colormode.

Если форма черепахи (turtleshape) является многоугольником, то внутренняя область этого многоугольника закрашивается вновь заданным цветом заливки.

```pycon
>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor((50, 193, 143))  # Целые числа, не числа с плавающей точкой
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)
```

#### `turtle.color()`

#### `turtle.color(color, /)`

#### `turtle.color(r, g, b, /)`

#### `turtle.color(pencolor, fillcolor, /)`

Возвращает или задаёт цвет пера и цвет заливки.

Допускается несколько форматов ввода. Они используют от 0 до 3 аргументов следующим образом:

**`color()`**

Возвращает текущий цвет пера и текущий цвет заливки в виде пары строк или кортежей с описанием цвета, как в [`pencolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.pencolor) и [`fillcolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.fillcolor).

**`color(colorstring)`, `color((r,g,b))`, `color(r,g,b)`**

Аргументы как в [`pencolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.pencolor); устанавливает и fillcolor, и pencolor в указанное значение.

**`color(colorstring1, colorstring2)`, `color((r1,g1,b1), (r2,g2,b2))`**

Эквивалентно `pencolor(colorstring1)` и `fillcolor(colorstring2)`, а также аналогично при использовании другого формата ввода.

Если форма черепахи – многоугольник, его контур и внутренняя область рисуются новыми установленными цветами.

```pycon
>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))
```

См. также: метод Screen [`colormode()`](https://python-all.ru/3.15/library/turtle.html#turtle.colormode).

#### Заливка

#### `turtle.filling()`

Возвращает состояние заливки (`True`, если заливка активна, иначе `False`).

```pycon
>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)
```

#### `turtle.fill()`

Заливает фигуру, нарисованную в блоке `with turtle.fill():`.

```pycon
>>> turtle.color("black", "red")
>>> with turtle.fill():
...     turtle.circle(80)
```

Использование `fill()` эквивалентно добавлению [`begin_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.begin_fill) перед блоком заливки и [`end_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.end_fill) после блока заливки.

```pycon
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
```

Добавлено в версии 3.14.

#### `turtle.begin_fill()`

Вызывается непосредственно перед рисованием фигуры, которую нужно залить.

#### `turtle.end_fill()`

Заливает фигуру, нарисованную после последнего вызова [`begin_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.begin_fill).

Будут ли залиты области пересечения для самопересекающихся многоугольников или нескольких фигур, зависит от графической подсистемы операционной системы, типа пересечения и количества пересечений. Например, звезда черепахи выше может быть либо полностью жёлтой, либо содержать белые области.

```pycon
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
```

#### Дополнительное управление рисованием

#### `turtle.reset()`

Удаляет рисунки черепахи с экрана, перемещает черепаху в центр и сбрасывает переменные в значения по умолчанию.

```pycon
>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
```

#### `turtle.clear()`

Удаляет рисунки черепахи с экрана. Черепаха не перемещается. Состояние и положение черепахи, а также рисунки других черепах не затрагиваются.

#### `turtle.write(arg, move=False, align='left', font=('Arial', 8, 'normal'))`

**Параметры:**

- **arg** – объект, который будет записан на TurtleScreen.
- **move** – True/False
- **align** – одна из строк: «left», «center» или «right».
- **font** – тройка (имя\_шрифта, размер\_шрифта, тип\_шрифта)

Записывает текст (строковое представление *arg*) в текущей позиции черепахи в соответствии с выравниванием *align* («left», «center» или «right») и указанным шрифтом. Если *move* истинно, перо перемещается в правый нижний угол текста. По умолчанию *move* равно `False`.

```python
>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)
```

### Состояние черепахи

#### Видимость

#### `turtle.hideturtle()`

#### `turtle.ht()`

Делает черепаху невидимой. Рекомендуется делать это во время выполнения сложного рисунка, потому что скрытие черепахи заметно ускоряет рисование.

```pycon
>>> turtle.hideturtle()
```

#### `turtle.showturtle()`

#### `turtle.st()`

Делает черепаху видимой.

```pycon
>>> turtle.showturtle()
```

#### `turtle.isvisible()`

Возвращает `True`, если черепаха показана, и `False`, если она скрыта.

```python
>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True
```

#### Внешний вид

#### `turtle.shape(name=None)`

**Параметры:**

**name** – a string which is a valid shapename

Устанавливает форму черепахи как форму с заданным *name* или, если имя не указано, возвращает имя текущей формы. Форма с именем *name* должна существовать в словаре форм TurtleScreen. Изначально доступны следующие многоугольные формы: «стрелка», «черепаха», «круг», «квадрат», «треугольник», «классическая». Чтобы узнать, как работать с формами, см. метод Screen [`register_shape()`](https://python-all.ru/3.15/library/turtle.html#turtle.register_shape).

```pycon
>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'
```

#### `turtle.resizemode(rmode=None)`

**Параметры:**

**rmode** – one of the strings “auto”, “user”, “noresize”

Устанавливает режим изменения размера в одно из значений: «авто», «пользователь», «без изменения размера». Если *rmode* не указан, возвращает текущий режим изменения размера. Разные режимы изменения размера имеют следующие эффекты:

- “auto”: adapts the appearance of the turtle corresponding to the value of pensize.
- “user”: adapts the appearance of the turtle according to the values of stretchfactor and outlinewidth (outline), which are set by [`shapesize()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapesize).
- «без изменения размера»: адаптация внешнего вида черепахи не производится.

`resizemode("user")` вызывается [`shapesize()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapesize) при использовании с аргументами.

```pycon
>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'
```

#### `turtle.shapesize(stretch_wid=None, stretch_len=None, outline=None)`

#### `turtle.turtlesize(stretch_wid=None, stretch_len=None, outline=None)`

**Параметры:**

- **stretch\_wid** – положительное число
- **stretch\_len** – положительное число
- **outline** – положительное число

Возвращает или задаёт атрибуты пера: коэффициенты растяжения по x/y и/или контур. Устанавливает режим изменения размера в «пользователь». Если и только если режим изменения размера установлен в «пользователь», черепаха будет отображаться растянутой в соответствии с её коэффициентами растяжения: *stretch\_wid* – коэффициент растяжения перпендикулярно её ориентации, *stretch\_len* – коэффициент растяжения в направлении её ориентации, *outline* определяет ширину контура формы.

```pycon
>>> turtle.shapesize()
(1.0, 1.0, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)
```

#### `turtle.shearfactor(shear=None)`

**Параметры:**

**shear** – число (необязательно)

Set or return the current shearfactor. Shear the turtleshape according to the given shearfactor shear, which is the tangent of the shear angle. Do *not* change the turtle’s heading (direction of movement). If shear is not given: return the current shearfactor, i. e. the tangent of the shear angle, by which lines parallel to the heading of the turtle are sheared.

```pycon
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5
```

#### `turtle.tilt(angle)`

**Параметры:**

**angle** – a number

Повернуть форму черепахи на *angle* от текущего угла наклона, но *не* изменять направление черепахи (направление движения).

```pycon
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)
```

#### `turtle.tiltangle(angle=None)`

**Параметры:**

**angle** – число (необязательно)

Устанавливает или возвращает текущий угол наклона. Если задан угол, поворачивает форму черепахи, чтобы она указывала в направлении, заданном углом, независимо от текущего угла наклона, но *не* изменять направление черепахи (направление движения). Если угол не задан: возвращает текущий угол наклона, то есть угол между ориентацией формы черепахи и направлением черепахи (её направлением движения).

```pycon
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0
```

#### `turtle.shapetransform(t11=None, t12=None, t21=None, t22=None)`

**Параметры:**

- **t11** – число (необязательно)
- **t12** – число (необязательно)
- **t21** – число (необязательно)
- **t12** – число (необязательно)

Задаёт или возвращает текущую матрицу преобразования формы черепашки.

Если ни один из элементов матрицы не задан, возвращает матрицу преобразования в виде кортежа из 4 элементов. В противном случае задаёт указанные элементы и преобразует форму черепашки согласно матрице, состоящей из первой строки t11, t12 и второй строки t21, t22. Определитель t11 \* t22 - t12 \* t21 не должен быть равен нулю, иначе будет вызвана ошибка. Изменяет stretchfactor, shearfactor и tiltangle в соответствии с заданной матрицей.

```pycon
>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)
```

#### `turtle.get_shapepoly()`

Возвращает текущий многоугольник формы в виде кортежа пар координат. Это можно использовать для определения новой формы или компонентов составной формы.

```pycon
>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))
```

### Использование событий

#### `turtle.onclick(fun, btn=1, add=None)`

**Параметры:**

- **fun** – функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
- **btn** – номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
- **add** – `True` или `False` – если `True`, будет добавлена новая привязка, иначе она заменит предыдущую привязку

Привязывает *fun* к событиям щелчка мыши на этой черепашке. Если *fun* равно `None`, существующие привязки удаляются. Пример для анонимной черепашки, т.е. процедурного способа:

```pycon
>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # Теперь щелчок по черепашке повернёт её.
>>> onclick(None)  # привязка события будет удалена
```

#### `turtle.onrelease(fun, btn=1, add=None)`

**Параметры:**

- **fun** – функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
- **btn** – номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
- **add** – `True` или `False` – если `True`, будет добавлена новая привязка, иначе она заменит предыдущую привязку

Привязывает *fun* к событиям отпускания кнопки мыши на этой черепашке. Если *fun* равно `None`, существующие привязки удаляются.

```pycon
>>> class MyTurtle(Turtle):
...     def glow(self,x,y):
...         self.fillcolor("red")
...     def unglow(self,x,y):
...         self.fillcolor("")
...
>>> turtle = MyTurtle()
>>> turtle.onclick(turtle.glow)     # нажатие на черепашку меняет цвет заливки на красный,
>>> turtle.onrelease(turtle.unglow) # отпускание делает его прозрачным.
```

#### `turtle.ondrag(fun, btn=1, add=None)`

**Параметры:**

- **fun** – функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
- **btn** – номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
- **add** – `True` или `False` – если `True`, будет добавлена новая привязка, иначе она заменит предыдущую привязку

Привязывает *fun* к событиям перемещения мыши на этой черепашке. Если *fun* равно `None`, существующие привязки удаляются.

Примечание: Каждая последовательность событий перемещения мыши на черепашке предваряется событием щелчка мыши на этой черепашке.

```pycon
>>> turtle.ondrag(turtle.goto)
```

После этого щелчок и перетаскивание черепашки будет перемещать её по экрану, создавая рисунки от руки (если перо опущено).

### Специальные методы черепашки

#### `turtle.poly()`

Записывает вершины многоугольника, нарисованного в блоке `with turtle.poly():`. Первая и последняя вершины будут соединены.

```pycon
>>> with turtle.poly():
...     turtle.forward(100)
...     turtle.right(60)
...     turtle.forward(100)
```

Добавлено в версии 3.14.

#### `turtle.begin_poly()`

Начинает запись вершин многоугольника. Текущая позиция черепашки является первой вершиной многоугольника.

#### `turtle.end_poly()`

Остановить запись вершин многоугольника. Текущая позиция черепашки – последняя вершина многоугольника. Она будет соединена с первой вершиной.

#### `turtle.get_poly()`

Возвращает последний записанный многоугольник.

```pycon
>>> turtle.home()
>>> turtle.begin_poly()
>>> turtle.fd(100)
>>> turtle.left(20)
>>> turtle.fd(30)
>>> turtle.left(60)
>>> turtle.fd(50)
>>> turtle.end_poly()
>>> p = turtle.get_poly()
>>> register_shape("myFavouriteShape", p)
```

#### `turtle.clone()`

Создаёт и возвращает клон черепашки с теми же координатами, направлением и свойствами черепашки.

```pycon
>>> mick = Turtle()
>>> joe = mick.clone()
```

#### `turtle.getturtle()`

#### `turtle.getpen()`

Возвращает сам объект Turtle. Единственное разумное применение – как функция для возврата «анонимной черепашки»:

```pycon
>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>
```

#### `turtle.getscreen()`

Возвращает объект [`TurtleScreen`](https://python-all.ru/3.15/library/turtle.html#turtle.TurtleScreen), на котором черепашка рисует. Затем для этого объекта можно вызывать методы TurtleScreen.

```pycon
>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")
```

#### `turtle.setundobuffer(size)`

**Параметры:**

**size** – целое число или `None`

Устанавливает или отключает буфер отмены. Если *size* – целое число, создаётся пустой буфер отмены указанного размера. *size* задаёт максимальное количество действий черепашки, которые можно отменить с помощью метода/функции [`undo()`](https://python-all.ru/3.15/library/turtle.html#turtle.undo). Если *size* равно `None`, буфер отмены отключается.

```pycon
>>> turtle.setundobuffer(42)
```

#### `turtle.undobufferentries()`

Возвращает количество записей в буфере отмены.

```pycon
>>> while undobufferentries():
...     undo()
```

### Составные фигуры

Для использования составных фигур черепашки, состоящих из нескольких многоугольников разного цвета, необходимо явно использовать вспомогательный класс [`Shape`](https://python-all.ru/3.15/library/turtle.html#turtle.Shape), как описано ниже:

1. Создаёт пустой объект Shape типа «compound».
2. Добавьте в этот объект необходимое количество компонентов с помощью метода [`addcomponent()`](https://python-all.ru/3.15/library/turtle.html#turtle.Shape.addcomponent).

   Например:

   ```pycon
   >>> s = Shape("compound")
   >>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
   >>> s.addcomponent(poly1, "red", "blue")
   >>> poly2 = ((0,0),(10,-5),(-10,-5))
   >>> s.addcomponent(poly2, "blue", "red")
   ```
3. Теперь добавьте Shape в список фигур экрана и используйте его:

   ```pycon
   >>> register_shape("myshape", s)
   >>> shape("myshape")
   ```

> **Примечание**
>
> Класс [`Shape`](https://python-all.ru/3.15/library/turtle.html#turtle.Shape) используется внутри метода [`register_shape()`](https://python-all.ru/3.15/library/turtle.html#turtle.register_shape) разными способами. Разработчику приложения приходится иметь дело с классом Shape *только* при использовании составных фигур, как показано выше!

## Методы TurtleScreen/Screen и соответствующие функции

Большинство примеров в этом разделе относятся к экземпляру TurtleScreen с именем `screen`.

### Управление окном

#### `turtle.bgcolor()`

#### `turtle.bgcolor(color, /)`

#### `turtle.bgcolor(r, g, b, /)`

Возвращает или устанавливает цвет фона TurtleScreen.

Допускаются четыре формата ввода:

**`bgcolor()`**

Возвращает текущий цвет фона в виде строки спецификации цвета или кортежа (см. пример). Может использоваться как входные данные для другого вызова color/pencolor/fillcolor/bgcolor.

**`bgcolor(colorstring)`**

Устанавливает цвет фона в *colorstring*, строку спецификации цвета Tk, например `"red"`, `"yellow"` или `"#33cc8c"`.

**`bgcolor((r, g, b))`**

Устанавливает цвет фона в RGB-цвет, представленный кортежем *r*, *g* и *b*. Каждое из значений *r*, *g* и *b* должно быть в диапазоне 0..colormode, где colormode равен 1.0 или 255 (см. [`colormode()`](https://python-all.ru/3.15/library/turtle.html#turtle.colormode)).

**`bgcolor(r, g, b)`**

Устанавливает цвет фона в RGB-цвет, представленный *r*, *g* и *b*. Каждое из значений *r*, *g* и *b* должно находиться в диапазоне 0..colormode.

```pycon
>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)
```

#### `turtle.bgpic(picname=None)`

**Параметры:**

**picname** – строка, имя файла изображения (PNG, GIF, PGM и PPM) или `"nopic"`, или `None`

Устанавливает фоновое изображение или возвращает имя текущего фонового изображения. Если *picname* – имя файла, устанавливает соответствующее изображение как фон. Если *picname* равно `"nopic"`, удаляет фоновое изображение, если оно есть. Если *picname* равно `None`, возвращает имя файла текущего фонового изображения.

```python
>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"
```

#### `turtle.clear()`

> **Примечание**
>
> Этот метод TurtleScreen доступен как глобальная функция только под именем `clearscreen`. Глобальная функция `clear` – другая, производная от метода Turtle `clear`.

#### `turtle.clearscreen()`

Удаляет все рисунки и всех черепах с TurtleScreen. Сбрасывает теперь пустой TurtleScreen в исходное состояние: белый фон, без фонового изображения, без привязок событий и с включённой трассировкой.

#### `turtle.reset()`

> **Примечание**
>
> Этот метод TurtleScreen доступен как глобальная функция только под именем `resetscreen`. Глобальная функция `reset` – это другая, производная от метода Turtle `reset`.

#### `turtle.resetscreen()`

Сбрасывает всех черепах на экране в исходное состояние.

#### `turtle.screensize(canvwidth=None, canvheight=None, bg=None)`

**Параметры:**

- **canvwidth** – положительное целое, новая ширина холста в пикселях
- **canvheight** – положительное целое, новая высота холста в пикселях
- **bg** – строка цвета или кортеж цвета, новый цвет фона

Если аргументы не переданы, возвращает текущие (canvaswidth, canvasheight). В противном случае изменяет размер холста, на котором рисуют черепахи. Не изменяет окно рисования. Для просмотра скрытых частей холста используйте полосы прокрутки. С помощью этого метода можно сделать видимыми те части рисунка, которые раньше находились за пределами холста.

```python
>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)
```

например, для поиска случайно сбежавшей черепахи ;-)

#### `turtle.setworldcoordinates(llx, lly, urx, ury)`

**Параметры:**

- **llx** – число, x-координата левого нижнего угла холста
- **lly** – число, y-координата левого нижнего угла холста
- **urx** – число, x-координата правого верхнего угла холста
- **ury** – число, y-координата правого верхнего угла холста

Устанавливает пользовательскую систему координат и при необходимости переключается в режим «world». Это выполняет `screen.reset()`. Если режим «world» уже активен, все рисунки перерисовываются в соответствии с новыми координатами.

**ВНИМАНИЕ**: в пользовательских системах координат углы могут отображаться искажёнными.

```pycon
>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
...     left(10)
...
>>> for _ in range(8):
...     left(45); fd(2)   # правильный восьмиугольник
```

### Управление анимацией

#### `turtle.no_animation()`

Временно отключает анимацию черепахи. Код, написанный внутри блока `no_animation`, не будет анимирован; после выхода из блока кода рисунок появится.

```pycon
>>> with screen.no_animation():
...     for dist in range(2, 400, 2):
...         fd(dist)
...         rt(90)
```

Добавлено в версии 3.14.

#### `turtle.delay(delay=None)`

**Параметры:**

**delay** – положительное целое

Устанавливает или возвращает задержку *delay* рисования в миллисекундах. (Это приблизительно интервал времени между двумя последовательными обновлениями холста.) Чем больше задержка рисования, тем медленнее анимация.

Необязательный аргумент:

```pycon
>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
```

#### `turtle.tracer(n=None, delay=None)`

**Параметры:**

- **n** – неотрицательное целое число
- **delay** – неотрицательное целое число

Включает или выключает анимацию черепашки и устанавливает задержку для обновления рисунков. Если задан *n*, то реально выполняется только каждое n-е обычное обновление экрана. (Может использоваться для ускорения рисования сложной графики.) При вызове без аргументов возвращает текущее сохранённое значение n. Второй аргумент задаёт значение задержки (см. [`delay()`](https://python-all.ru/3.15/library/turtle.html#turtle.delay)).

```pycon
>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2
```

#### `turtle.update()`

Выполняет обновление TurtleScreen. Используется, когда tracer выключен.

См. также метод [`speed()`](https://python-all.ru/3.15/library/turtle.html#turtle.speed) RawTurtle/Turtle.

### Использование событий экрана

#### `turtle.listen(xdummy=None, ydummy=None)`

Устанавливает фокус на TurtleScreen (для сбора событий клавиш). Фиктивные аргументы предусмотрены, чтобы можно было передать `listen()` методу onclick.

#### `turtle.onkey(fun, key)`

#### `turtle.onkeyrelease(fun, key)`

**Параметры:**

- **fun** – функция без аргументов или `None`
- **key** – строка: клавиша (например, “a”) или символ клавиши (например, “space”)

Привязывает *fun* к событию отпускания клавиши key. Если *fun* равен `None`, привязки событий удаляются. Замечание: для регистрации событий клавиш TurtleScreen должен иметь фокус. (См. метод [`listen()`](https://python-all.ru/3.15/library/turtle.html#turtle.listen).)

```pycon
>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
```

#### `turtle.onkeypress(fun, key=None)`

**Параметры:**

- **fun** – функция без аргументов или `None`
- **key** – строка: клавиша (например, “a”) или символ клавиши (например, “space”)

Привязывает *fun* к событию нажатия клавиши key, если key задан, или к любому событию нажатия клавиши, если key не задан. Замечание: для регистрации событий клавиш TurtleScreen должен иметь фокус. (См. метод [`listen()`](https://python-all.ru/3.15/library/turtle.html#turtle.listen).)

```pycon
>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
```

#### `turtle.onclick(fun, btn=1, add=None)`

#### `turtle.onscreenclick(fun, btn=1, add=None)`

**Параметры:**

- **fun** – функция с двумя аргументами, которая будет вызвана с координатами точки щелчка на холсте
- **btn** – номер кнопки мыши, по умолчанию 1 (левая кнопка мыши)
- **add** – `True` или `False` – если `True`, будет добавлена новая привязка, иначе она заменит предыдущую привязку

Привязывает *fun* к событиям щелчка мыши на этом экране. Если *fun* равен `None`, существующие привязки удаляются.

Пример для экземпляра TurtleScreen с именем `screen` и экземпляра Turtle с именем `turtle`:

```pycon
>>> screen.onclick(turtle.goto) # Последующий щелчок по TurtleScreen заставит
>>>                             # черепашку переместиться в точку щелчка.
>>> screen.onclick(None)        # снова удалить привязку события
```

> **Примечание**
>
> Этот метод TurtleScreen доступен как глобальная функция только под именем `onscreenclick`. Глобальная функция `onclick` – это другая, производная от метода Turtle `onclick`.

#### `turtle.ontimer(fun, t=0)`

**Параметры:**

- **fun** – функция без аргументов
- **t** – число \>= 0

Устанавливает таймер, который вызывает *fun* через *t* миллисекунд.

```pycon
>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### заставляет черепашку обходить вокруг
>>> running = False
```

#### `turtle.mainloop()`

#### `turtle.done()`

Запускает цикл событий – вызывает функцию mainloop из Tkinter. Должна быть последней инструкцией в программе с черепашьей графикой. Должна *не* использоваться, если скрипт запускается из IDLE в режиме -n (без подпроцесса) – для интерактивного использования черепашьей графики.

```python
>>> screen.mainloop()
```

### Методы ввода

#### `turtle.textinput(title, prompt)`

**Параметры:**

- **title** – строка
- **prompt** – строка

Отображает диалоговое окно для ввода строки. Параметр title – заголовок диалогового окна, prompt – текст, в основном описывающий, какую информацию нужно ввести. Возвращает введённую строку. Если диалог отменён, возвращает `None`.

```python
>>> screen.textinput("NIM", "Name of first player:")
```

#### `turtle.numinput(title, prompt, default=None, minval=None, maxval=None)`

**Параметры:**

- **title** – строка
- **prompt** – строка
- **default** – число (необязательно)
- **minval** – число (необязательно)
- **maxval** – число (необязательно)

Отображает диалоговое окно для ввода числа. title – заголовок диалогового окна, prompt – текст, в основном описывающий, какую числовую информацию нужно ввести. default – значение по умолчанию, minval – минимальное значение для ввода, maxval – максимальное значение для ввода. Введённое число должно находиться в диапазоне от minval до maxval, если эти значения заданы. Если нет, выводится подсказка, и диалог остаётся открытым для исправления. Возвращает введённое число. Если диалог отменён, возвращает `None`.

```python
>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)
```

### Настройки и специальные методы

#### `turtle.mode(mode=None)`

**Параметры:**

**mode** – одна из строк “standard”, “logo” или “world”

Устанавливает режим черепахи (“standard”, “logo” или “world”) и выполняет сброс. Если режим не задан, возвращается текущий режим.

Режим “standard” совместим со старой `turtle`. Режим “logo” совместим с большинством черепашьих графических средств Logo. Режим “world” использует заданные пользователем «мировые координаты». **Внимание**: в этом режиме углы выглядят искажёнными, если `x/y` коэффициент единицы измерения не равен 1.

| Режим | Начальное направление черепахи | положительные углы |
| --- | --- | --- |
| “standard” | вправо (восток) | против часовой стрелки |
| “logo” | вверх (север) | по часовой стрелке |

```pycon
>>> mode("logo")   # сбрасывает направление черепашки на север
>>> mode()
'logo'
```

#### `turtle.colormode(cmode=None)`

**Параметры:**

**cmode** – одно из значений 1.0 или 255

Возвращает цветовой режим или устанавливает его в 1.0 или 255. Впоследствии значения *r*, *g*, *b* цветовых троек должны находиться в диапазоне от 0 до \*cmode\*.

```pycon
>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
     ...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)
```

#### `turtle.getcanvas()`

Возвращает Canvas данного TurtleScreen. Полезно для тех, кто знает, что делать с Canvas из Tkinter.

```pycon
>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>
```

#### `turtle.getshapes()`

Возвращает список названий всех доступных в данный момент форм черепашки.

```pycon
>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']
```

#### `turtle.register_shape(name, shape=None)`

#### `turtle.addshape(name, shape=None)`

Существует четыре способа вызова этой функции:

1. *name* – имя файла изображения (PNG, GIF, PGM и PPM), а *shape* равно `None`: устанавливается соответствующая форма изображения.

   ```python
   >>> screen.register_shape("turtle.gif")
   ```

   > **Примечание**
   >
   > Формы изображений *не* поворачиваются при повороте черепашки, поэтому они не отображают направление черепашки!
2. *name* – произвольная строка, а *shape* – имя файла изображения (PNG, GIF, PGM и PPM): устанавливает соответствующую форму изображения.

   ```python
   >>> screen.register_shape("turtle", "turtle.gif")
   ```

   > **Примечание**
   >
   > Формы изображений *не* поворачиваются при повороте черепашки, поэтому они не отображают направление черепашки!
3. *name* – произвольная строка, а *shape* – кортеж пар координат: устанавливает соответствующую многоугольную форму.

   ```pycon
   >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
   ```
4. *name* – произвольная строка, а *shape* – (составной) объект [`Shape`](https://python-all.ru/3.15/library/turtle.html#turtle.Shape): устанавливает соответствующую составную форму.

Добавляет форму черепашки в список форм TurtleScreen. Только зарегистрированные таким образом формы можно использовать, выполнив команду `shape(shapename)`.

Изменено в версии 3.14: Добавлена поддержка форматов изображений PNG, PGM и PPM. Можно указать как название формы, так и имя файла изображения.

#### `turtle.turtles()`

Возвращает список черепашек на экране.

```pycon
>>> for turtle in screen.turtles():
...     turtle.color("red")
```

#### `turtle.window_height()`

Возвращает высоту окна черепашки.

```python
>>> screen.window_height()
480
```

#### `turtle.window_width()`

Возвращает ширину окна черепашки.

```python
>>> screen.window_width()
640
```

### Методы, специфичные для Screen, не наследуемые от TurtleScreen

#### `turtle.bye()`

Закрывает окно графики черепашки.

#### `turtle.exitonclick()`

Привязывает метод `bye()` к щелчкам мыши на экране.

Если значение «using\_IDLE» в словаре конфигурации равно `False` (значение по умолчанию), также запускается главный цикл. Примечание: если используется IDLE с ключом `-n` (без подпроцесса), это значение следует установить в `True` в `turtle.cfg`. В этом случае собственный главный цикл IDLE активен также для клиентского скрипта.

#### `turtle.save(filename, overwrite=False)`

Сохраняет текущий рисунок черепашки (и черепашек) в файл PostScript.

**Параметры:**

- **filename** – путь к сохраняемому файлу PostScript
- **overwrite** – если `False` и файл с указанным именем уже существует, то функция вызовет исключение `FileExistsError`. Если же `True`, файл будет перезаписан.

```pycon
>>> screen.save("my_drawing.ps")
>>> screen.save("my_drawing.ps", overwrite=True)
```

Добавлено в версии 3.14.

#### `turtle.setup(width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])`

Устанавливает размер и положение главного окна. Значения аргументов по умолчанию хранятся в словаре конфигурации и могут быть изменены через файл `turtle.cfg`.

**Параметры:**

- **width** – если целое число, размер в пикселях; если число с плавающей запятой, доля экрана; по умолчанию – 50% экрана.
- **height** – если целое число, высота в пикселях; если число с плавающей запятой, доля от экрана; по умолчанию 75% экрана
- **startx** – если положительное, начальная позиция в пикселях от левого края экрана; если отрицательное – от правого края; если `None`, окно центрируется по горизонтали
- **starty** – если положительное, начальная позиция в пикселях от верхнего края экрана; если отрицательное – от нижнего края; если `None`, окно центрируется по вертикали

```pycon
>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # устанавливает окно размером 200x200 пикселей в верхнем левом углу экрана
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # устанавливает окно 75% на 50% экрана и центрирует его
```

#### `turtle.title(titlestring)`

**Параметры:**

**titlestring** – строка, отображаемая в заголовке окна черепашьей графики

Устанавливает заголовок окна черепашки равным *titlestring*.

```pycon
>>> screen.title("Welcome to the turtle zoo!")
```

## Открытые классы

#### `class turtle.RawTurtle(canvas)`

#### `class turtle.RawPen(canvas)`

**Параметры:**

**canvas** – `tkinter.Canvas`, [`ScrolledCanvas`](https://python-all.ru/3.15/library/turtle.html#turtle.ScrolledCanvas) или [`TurtleScreen`](https://python-all.ru/3.15/library/turtle.html#turtle.TurtleScreen)

Создаёт черепашку. Объект черепашки обладает всеми методами, описанными выше как «методы Turtle/RawTurtle».

#### `class turtle.Turtle`

Подкласс RawTurtle, имеет тот же интерфейс, но рисует на объекте [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen) по умолчанию, который создаётся автоматически при первом обращении.

#### `class turtle.TurtleScreen(cv)`

**Параметры:**

**cv** – `tkinter.Canvas`

Предоставляет экранно-ориентированные методы, такие как [`bgcolor()`](https://python-all.ru/3.15/library/turtle.html#turtle.bgcolor) и другие, описанные выше.

#### `class turtle.Screen`

Подкласс TurtleScreen, [дополненный четырьмя методами](https://python-all.ru/3.15/library/turtle.html#screenspecific).

#### `class turtle.ScrolledCanvas(master)`

**Параметры:**

**master** – виджет Tkinter, в который помещается ScrolledCanvas; например, Tkinter-холст с добавленными полосами прокрутки

Используется классом Screen, который, таким образом, автоматически предоставляет ScrolledCanvas в качестве поля для черепашек.

#### `class turtle.Shape(type_, data)`

**Параметры:**

**type\_** – одна из строк: «polygon», «image», «compound»

Структура данных для описания фигур. Пара `(type_, data)` должна соответствовать следующей спецификации:

| *type\_* | *данные* |
| --- | --- |
| «polygon» | кортеж многоугольника, т.е. кортеж пар координат |
| «image» | изображение (в таком виде используется только внутри!) |
| «compound» | `None` (составная фигура должна строиться с помощью метода [`addcomponent()`](https://python-all.ru/3.15/library/turtle.html#turtle.Shape.addcomponent)) |

#### `addcomponent(poly, fill, outline, None)`

**Параметры:**

- **poly** – многоугольник, т.е. кортеж пар чисел
- **fill** – цвет, которым будет заполнен *poly*
- **outline** – цвет контура многоугольника (если задан)

Пример:

```pycon
>>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... добавьте больше компонентов, а затем используйте register_shape()
```

См. [Составные фигуры](https://python-all.ru/3.15/library/turtle.html#compoundshapes).

#### `class turtle.Vec2D(x, y)`

Двумерный векторный класс, используемый как вспомогательный класс для реализации graphics черепашки. Может быть полезен и для программ с графикой черепашки. Производный от tuple, так что вектор – это кортеж!

Предоставляет (для векторов *a*, *b* и числа *k*):

- `a + b` сложение векторов
- `a - b` вычитание векторов
- `a * b` скалярное произведение
- `k * a` и `a * k` умножение на скаляр
- `abs(a)` абсолютное значение a
- `a.rotate(angle)` поворот

## Пояснение

Объект черепашки рисует на объекте экрана, и в объектно-ориентированном интерфейсе черепашки есть ряд ключевых классов, которые можно использовать для их создания и связи друг с другом.

Экземпляр [`Turtle`](https://python-all.ru/3.15/library/turtle.html#turtle.Turtle) автоматически создаст экземпляр [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen), если его ещё нет.

`Turtle` – подкласс [`RawTurtle`](https://python-all.ru/3.15/library/turtle.html#turtle.RawTurtle), который *не* создаёт автоматически поверхность для рисования – для него необходимо предоставить или создать *холст*. *Холст* может быть `tkinter.Canvas`, [`ScrolledCanvas`](https://python-all.ru/3.15/library/turtle.html#turtle.ScrolledCanvas) или [`TurtleScreen`](https://python-all.ru/3.15/library/turtle.html#turtle.TurtleScreen).

[`TurtleScreen`](https://python-all.ru/3.15/library/turtle.html#turtle.TurtleScreen) – основная поверхность для рисования черепашки. [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen) – подкласс `TurtleScreen` и включает [несколько дополнительных методов](https://python-all.ru/3.15/library/turtle.html#screenspecific) для управления своим внешним видом (включая размер и заголовок) и поведением. Конструктор `TurtleScreen` требует аргумент `tkinter.Canvas` или [`ScrolledCanvas`](https://python-all.ru/3.15/library/turtle.html#turtle.ScrolledCanvas).

Функциональный интерфейс для графики черепашки использует различные методы `Turtle` и `TurtleScreen`/`Screen`. За кулисами объект экрана автоматически создаётся при каждом вызове функции, производной от метода `Screen`. Аналогично, объект черепашки автоматически создаётся при каждом вызове любой из функций, производных от метода Turtle.

Для использования нескольких черепашек на одном экране необходимо использовать объектно-ориентированный интерфейс.

## Справка и настройка

### Как пользоваться справкой

Публичные методы классов Screen и Turtle подробно документированы через docstrings. Их можно использовать как онлайн-справку через средства помощи Python:

- При использовании IDLE всплывающие подсказки показывают сигнатуры и первые строки docstrings для введённых вызовов функций/методов.
- Вызов [`help()`](https://python-all.ru/3.15/library/functions.html#help) для методов или функций отображает docstrings:

  ```python
  >>> help(Screen.bgcolor)
  Help on method bgcolor in module turtle:

  bgcolor(self, *args) unbound turtle.Screen method
      Set or return backgroundcolor of the TurtleScreen.

      Arguments (if given): a color string or three numbers
      in the range 0..colormode or a 3-tuple of such numbers.

      >>> screen.bgcolor("orange")
      >>> screen.bgcolor()
      "orange"
      >>> screen.bgcolor(0.5,0,0.5)
      >>> screen.bgcolor()
      "#800080"

  >>> help(Turtle.penup)
  Help on method penup in module turtle:

  penup(self) unbound turtle.Turtle method
      Pull the pen up -- no drawing when moving.

      Aliases: penup | pu | up

      No argument

      >>> turtle.penup()
  ```
- Docstrings функций, производных от методов, имеют изменённую форму:

  ```python
  >>> help(bgcolor)
  Help on function bgcolor in module turtle:

  bgcolor(*args)
      Set or return backgroundcolor of the TurtleScreen.

      Arguments (if given): a color string or three numbers
      in the range 0..colormode or a 3-tuple of such numbers.

      Example::

        >>> bgcolor("orange")
        >>> bgcolor()
        "orange"
        >>> bgcolor(0.5,0,0.5)
        >>> bgcolor()
        "#800080"

  >>> help(penup)
  Help on function penup in module turtle:

  penup()
      Pull the pen up -- no drawing when moving.

      Aliases: penup | pu | up

      No argument

      Example:
      >>> penup()
  ```

Эти изменённые docstrings создаются автоматически вместе с определениями функций, которые производятся от методов во время импорта.

### Перевод docstrings на разные языки

Существует утилита для создания словаря, ключами которого являются имена методов, а значениями – docstrings публичных методов классов Screen и Turtle.

#### `turtle.write_docstringdict(filename='turtle_docstringdict')`

**Параметры:**

**filename** – строка, используемая как имя файла

Создаёт и записывает словарь docstring в Python-скрипт с заданным именем файла. Эту функцию необходимо вызывать явно (она не используется классами графики черепашки). Словарь docstring будет записан в Python-скрипт `filename.py`. Он предназначен для использования в качестве шаблона для перевода docstrings на разные языки.

Если вы (или ваши студенты) хотите использовать `turtle` с онлайн-справкой на вашем родном языке, необходимо перевести docstrings и сохранить полученный файл, например, как `turtle_docstringdict_german.py`.

Если в вашем файле `turtle.cfg` есть соответствующая запись, этот словарь будет считан на этапе импорта и заменит оригинальные англоязычные строки документации.

На момент написания этого текста есть словари строк документации на немецком и итальянском. (Запросы направляйте на [glingl@aon.at](https://python-all.ru/3.15/library/turtle.html).)

### Как настроить Screen и Turtles

Встроенная конфигурация по умолчанию имитирует внешний вид и поведение старого модуля turtle, чтобы сохранить максимально возможную совместимость с ним.

Если вы хотите использовать другую конфигурацию, которая лучше отражает возможности этого модуля или лучше соответствует вашим потребностям, например, для использования в классе, вы можете подготовить файл конфигурации `turtle.cfg`, который будет прочитан на этапе импорта и изменит конфигурацию в соответствии с его настройками.

Встроенная конфигурация соответствует следующему `turtle.cfg`:

```ini
width = 0.5
height = 0.75
leftright = None
topbottom = None
canvwidth = 400
canvheight = 300
mode = standard
colormode = 1.0
delay = 10
undobuffersize = 1000
shape = classic
pencolor = black
fillcolor = black
resizemode = noresize
visible = True
language = english
exampleturtle = turtle
examplescreen = screen
title = Python Turtle Graphics
using_IDLE = False
```

Краткое пояснение выбранных записей:

- Первые четыре строки соответствуют аргументам метода [`Screen.setup`](https://python-all.ru/3.15/library/turtle.html#turtle.setup).
- Строки 5 и 6 соответствуют аргументам метода [`Screen.screensize`](https://python-all.ru/3.15/library/turtle.html#turtle.screensize).
- *shape* может быть любой из встроенных форм, например: arrow, turtle и т.д. Для получения дополнительной информации попробуйте `help(shape)`.
- Если вы хотите не использовать цвет заливки (т.е. сделать черепашку прозрачной), вы должны написать `fillcolor = ""` (но все непустые строки не должны содержать кавычки в cfg-файле).
- Если вы хотите отразить состояние черепашки, вы должны использовать `resizemode = auto`.
- Если вы установите, например, `language = italian`, то словарь строк документации `turtle_docstringdict_italian.py` будет загружен во время импорта (если он присутствует в пути импорта, например, в той же директории, что и `turtle`).
- Записи *exampleturtle* и *examplescreen* задают имена этих объектов, как они встречаются в строках документации. Преобразование строк документации методов в строки документации функций удалит эти имена из строк документации.
- *using\_IDLE*: Установите это в `True`, если вы регулярно работаете с IDLE и его переключателем `-n` («нет подпроцесса»). Это предотвратит [`exitonclick()`](https://python-all.ru/3.15/library/turtle.html#turtle.exitonclick) от входа в главный цикл.

Может быть файл `turtle.cfg` в каталоге, где хранится `turtle`, и дополнительный файл в текущем рабочем каталоге. Последний переопределит настройки первого.

Каталог `Lib/turtledemo` содержит файл `turtle.cfg`. Вы можете изучить его как пример и увидеть его эффекты при запуске демонстраций (желательно не из средства просмотра демонстраций).

## `turtledemo` – Демонстрационные скрипты

Пакет `turtledemo` включает набор демонстрационных скриптов. Эти скрипты можно запускать и просматривать с помощью поставляемого средства просмотра демонстраций следующим образом:

```python
python -m turtledemo
```

В качестве альтернативы вы можете запускать демонстрационные скрипты по отдельности. Например,

```python
python -m turtledemo.bytedesign
```

Каталог пакета `turtledemo` содержит:

- Средство просмотра демонстраций `__main__.py`, которое можно использовать для просмотра исходного кода скриптов и одновременного их запуска.
- Несколько скриптов, демонстрирующих различные возможности модуля `turtle`. Примеры доступны через меню Examples. Их также можно запускать отдельно.
- Файл `turtle.cfg`, который служит примером того, как писать и использовать такие файлы.

Демонстрационные скрипты:

| Имя | Описание | Возможности |
| --- | --- | --- |
| `bytedesign` | сложный классический узор черепашьей графики | [`tracer()`](https://python-all.ru/3.15/library/turtle.html#turtle.tracer), [`delay()`](https://python-all.ru/3.15/library/turtle.html#turtle.delay), [`update()`](https://python-all.ru/3.15/library/turtle.html#turtle.update) |
| `chaos` | строит график динамики Ферхюльста, показывает, что компьютерные вычисления иногда могут давать результаты, противоречащие здравому смыслу | мировые координаты |
| `clock` | аналоговые часы, показывающие время вашего компьютера | черепашки в качестве стрелок часов, [`ontimer()`](https://python-all.ru/3.15/library/turtle.html#turtle.ontimer) |
| `colormixer` | эксперимент с r, g, b | [`ondrag()`](https://python-all.ru/3.15/library/turtle.html#turtle.ondrag) |
| `forest` | 3 дерева обхода в ширину | рандомизация |
| `fractalcurves` | Кривые Гильберта и Коха | рекурсия |
| `lindenmayer` | этноматематика (индийские коламы) | L-система |
| `minimal_hanoi` | Ханойские башни | Прямоугольные черепашки в качестве дисков Ханоя ([`shape()`](https://python-all.ru/3.15/library/turtle.html#turtle.shape), [`shapesize()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapesize)) |
| `nim` | игра в классический ним с тремя кучками палочек против компьютера. | черепашки как палочки нима, событийно-ориентированное управление (мышь, клавиатура) |
| `paint` | супер-минималистичная программа для рисования | [`onclick()`](https://python-all.ru/3.15/library/turtle.html#turtle.onclick) |
| `peace` | элементарный | черепашка: внешний вид и анимация |
| `penrose` | непериодическое замощение воздушными змеями и дротиками | [`stamp()`](https://python-all.ru/3.15/library/turtle.html#turtle.stamp) |
| `planet_and_moon` | симуляция гравитационной системы | составные фигуры, [`Vec2D`](https://python-all.ru/3.15/library/turtle.html#turtle.Vec2D) |
| `rosette` | узор из статьи в Википедии о черепашьей графике | [`clone()`](https://python-all.ru/3.15/library/turtle.html#turtle.clone), [`undo()`](https://python-all.ru/3.15/library/turtle.html#turtle.undo) |
| `round_dance` | танцующие черепашки, вращающиеся попарно в противоположных направлениях | составные фигуры, [`clone()`](https://python-all.ru/3.15/library/turtle.html#turtle.clone) [`shapesize()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapesize), [`tilt()`](https://python-all.ru/3.15/library/turtle.html#turtle.tilt), [`get_shapepoly()`](https://python-all.ru/3.15/library/turtle.html#turtle.get_shapepoly), [`update()`](https://python-all.ru/3.15/library/turtle.html#turtle.update) |
| `sorting_animate` | визуальная демонстрация различных методов сортировки | простое выравнивание, рандомизация |
| `tree` | (графическое) дерево обхода в ширину (с использованием генераторов) | [`clone()`](https://python-all.ru/3.15/library/turtle.html#turtle.clone) |
| `two_canvases` | простой дизайн | черепашки на двух холстах |
| `yinyang` | ещё один элементарный пример | [`circle()`](https://python-all.ru/3.15/library/turtle.html#turtle.circle) |

Удачи!

## Изменения, начиная с Python 2.6

- Методы [`Turtle.tracer`](https://python-all.ru/3.15/library/turtle.html#turtle.tracer), [`Turtle.window_width`](https://python-all.ru/3.15/library/turtle.html#turtle.window_width) и [`Turtle.window_height`](https://python-all.ru/3.15/library/turtle.html#turtle.window_height) были удалены. Методы с такими именами и функциональностью теперь доступны только как методы [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen). Производные от них функции остаются доступными. (На самом деле уже в Python 2.6 эти методы были просто дубликатами соответствующих методов [`TurtleScreen`](https://python-all.ru/3.15/library/turtle.html#turtle.TurtleScreen)/`Screen`.)
- Метод `Turtle.fill()` был удалён. Поведение [`begin_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.begin_fill) и [`end_fill()`](https://python-all.ru/3.15/library/turtle.html#turtle.end_fill) незначительно изменилось: теперь каждый процесс заливки должен завершаться вызовом `end_fill()`.
- Добавлен метод [`Turtle.filling`](https://python-all.ru/3.15/library/turtle.html#turtle.filling). Он возвращает булево значение: `True`, если процесс заливки выполняется, `False` в противном случае. Это поведение соответствует вызову `fill()` без аргументов в Python 2.6.

## Изменения, начиная с Python 3.0

- Были добавлены методы [`Turtle`](https://python-all.ru/3.15/library/turtle.html#turtle.Turtle): [`shearfactor()`](https://python-all.ru/3.15/library/turtle.html#turtle.shearfactor), [`shapetransform()`](https://python-all.ru/3.15/library/turtle.html#turtle.shapetransform) и [`get_shapepoly()`](https://python-all.ru/3.15/library/turtle.html#turtle.get_shapepoly). Таким образом, теперь доступен полный набор обычных линейных преобразований для трансформации форм черепашек. Функциональность [`tiltangle()`](https://python-all.ru/3.15/library/turtle.html#turtle.tiltangle) была расширена: теперь его можно использовать для получения или установки угла наклона.
- Метод [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen) [`onkeypress()`](https://python-all.ru/3.15/library/turtle.html#turtle.onkeypress) добавлен как дополнение к [`onkey()`](https://python-all.ru/3.15/library/turtle.html#turtle.onkey). Поскольку последний привязывает действия к событию отпускания клавиши, для него также был добавлен псевдоним [`onkeyrelease()`](https://python-all.ru/3.15/library/turtle.html#turtle.onkeyrelease).
- Метод [`Screen.mainloop`](https://python-all.ru/3.15/library/turtle.html#turtle.mainloop) добавлен, поэтому больше нет необходимости использовать отдельную функцию `mainloop()` при работе с объектами [`Screen`](https://python-all.ru/3.15/library/turtle.html#turtle.Screen) и [`Turtle`](https://python-all.ru/3.15/library/turtle.html#turtle.Turtle).
- Добавлены два метода ввода: [`Screen.textinput`](https://python-all.ru/3.15/library/turtle.html#turtle.textinput) и [`Screen.numinput`](https://python-all.ru/3.15/library/turtle.html#turtle.numinput). Они открывают диалоговые окна ввода и возвращают строки и числа соответственно.