`turtle` --- タートルグラフィックス¶

ソースコード: Lib/turtle.py

x-y 平面の (0, 0) から動き出す、亀のロボットを想像してください。 import turtle の後に turtle.forward(15) と指示すると、向いている方向に (画面上で！) 15 ピクセル進みながら線を描きます。 turtle.right(25) と指示すると、その場で時計回りに 25 度回転します。

タートルグラフィックスは、1967 年に Logo に導入された描画ツールの実装です。教育用のツールとして作られ、結果がすぐに目に見えるため、プログラミングの概念に触れる効果的な学習手段になります。外部ライブラリを導入せずに、簡単な図形を出力する方法としても便利です。

この文書には大きく分けて 4 つの節があります:

チュートリアルでは、タートルによる描画の基本を学びます。
リファレンスでは、このモジュールが定義する関数、メソッド、クラスを説明します。
ハウツー・ガイドでは、特定の作業を行う方法を詳しく説明します。
説明では、オブジェクト指向インターフェースの背景を説明します。

注釈

タートルグラフィックスには、オプションモジュールの tkinter が必要です。 python.org の Windows 用と macOS 用のインストーラには含まれていますが、一部の Linux ディストリビューションや他のプラットフォームでは、別のパッケージになっている場合があります。 import turtle が _tkinter に関するエラーで失敗した場合は、配布元 (Python を提供した組織など) のドキュメントを探してください。学習者とタートルグラフィックスを使う予定であれば、事前に確認しておきましょう。

チュートリアル¶

初めて使う方はここから始めてください。このチュートリアルでは、タートルによる描画の基本をいくつか学びます。

タートルの環境を起動する¶

Python シェルで、turtle モジュールのすべてのオブジェクトをインポートします。

from turtle import *

Standard library module '_tkinter' was not found というエラーが出た場合は、システムに Tk インターフェースのパッケージ をインストールする必要があります。

まだ何も表示されません。タートルを表示して、ウィンドウを開きましょう。

showturtle()

新しいウィンドウが開き、中央に東向きの矢印でタートルが表示されます。

基本的な描画¶

タートルを 100 歩前進させます。

forward(100)

タートルが東に向かって描いた線が見えるはずです。タートルの向きを変え、左に (反時計回りに) 120 度回転させましょう。

left(120)

続けて三角形を描いてみましょう。

forward(100)
left(120)
forward(100)

方向を指示すると、矢印で表されたタートルの向きが変わることに注目してください。

これらのコマンドと、backward()、right() も試してみてください。多くのコマンドには、forward() に対する fd() のような短い別名もあります。

Pen の制御¶

例えば color('blue') で色を、width(3) で線の幅を変えて、もう一度描いてみてください。

移動前に up() でペンを上げると、線を描かずにタートルを移動することもできます。再び描き始めるには down() を使います。

タートルの位置¶

タートルを開始位置に戻します (画面の外に出て見えなくなったときに便利です)。

home()

開始位置はタートルの画面の中央です。タートルの x-y 座標を知りたいときは、次のように取得できます。

pos()

開始位置は (0, 0) です。

しばらく試したら、画面を消去してやり直すとよいでしょう。

clearscreen()

アルゴリズムで模様を描く¶

ループを使うと、幾何学的な模様を描けます。

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

どんな模様ができるかは、もちろん想像力次第です！

このページの一番上にある星形を描いてみましょう。赤い線で描き、中を黄色で塗りつぶします。

color('red')
fillcolor('yellow')

up() と down() で線を描くかどうかを切り替えるのと同じように、塗りつぶしも開始・終了できます。

begin_fill()

次にループを作ります。

start = pos()

while True:
    forward(200)
    left(170)
    if distance(start) < 1:
        break

タートルが開始位置に戻ったかどうかは、distance(start) < 1 でうまく判定できます。

最後に塗りつぶしを完了します。

end_fill()

(実際に塗りつぶされるのは、end_fill() コマンドを実行したときだけです。)

リファレンス¶

タートルのメソッドと関数¶

この節のほとんどの例では turtle という名前の Turtle インスタンスを使います。

移動および描画¶

turtle.forward(distance)¶

turtle.fd(distance)¶

パラメータ:: distance -- 数

タートルが頭を向けている方へ、タートルを距離 distance だけ前進させます。

>>> 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 -- 数

タートルを、向いている方向とは逆に distance だけ後退させます。タートルの向きは変わりません。

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

turtle.right(angle)¶

turtle.rt(angle)¶

パラメータ:: angle -- 数

タートルを指定された angle だけ右に回転させます。角度の単位はデフォルトでは度ですが、degrees() または radians() で変更できます。向きの測り方はタートルのモードによって変わります。 mode() を参照してください。

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

turtle.left(angle)¶

turtle.lt(angle)¶

パラメータ:: angle -- 数

タートルを指定された angle だけ左に回転させます。角度の単位はデフォルトでは度ですが、degrees() または radians() で変更できます。向きの測り方はタートルのモードによって変わります。 mode() を参照してください。

>>> 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 は座標のペア、または pos() が返すような Vec2D でなければなりません。ペンが下りていると線を描きます。タートルの向きは変わりません。

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

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

パラメータ:

x -- 数または None
y -- 数または None
fill_gap -- ブール値

タートルを絶対位置に瞬間移動します。 goto() とは異なり、線は描きません。 x または y を指定しなければ、その座標は元のままです。タートルの向きは変わりません。

図形を塗りつぶしている途中の場合は、それまでに描いた図形を閉じて塗りつぶしてから瞬間移動し、新しい位置で再び塗りつぶしを開始します。 1 つの図形を塗りつぶし続けるには、fill_gap=True を渡してください。この場合、瞬間移動した区間は goto() の場合と同じように図形の辺になります。

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

Added in version 3.12.

turtle.setx(x)¶

パラメータ:: x -- 数

タートルの x 座標を x に設定します。 y 座標は変わりません。

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

turtle.sety(y)¶

パラメータ:: y -- 数

タートルの y 座標を y に設定します。 x 座標は変わりません。

>>> 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 - 西

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

turtle.home()¶

タートルを原点、座標 (0,0) に移動します。向きはモードに応じた初期の向きに設定されます。 mode() を参照してください。

>>> 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 が 1 周分でなければ、円弧の一方の端点は現在のペンの位置になります。 radius が正なら反時計回り、それ以外なら時計回りに円弧を描きます。最後に、タートルの向きは extent だけ変わります。

円は内接する正多角形で近似するため、steps で使うステップ数を指定します。指定しなければ自動的に計算します。正多角形を描くためにも使えます。

>>> 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 -- 正の整数または None
color -- 色を表わす文字列またはタプル

color を使って、直径 size の円形の点を描きます。 size を指定しなければ、pensize + 4 と 2 * pensize の大きい方を使います。 color を指定しなければ、現在のペンの色を使います。

>>> 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) のように呼び出して消すことができます。

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

turtle.clearstamp(stampid)¶

パラメータ:: stampid -- 整数で、先立つ stamp() 呼出しで返された値でなければなりません

stampid に対応するハンコを消します。

>>> 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 が正の場合には最初の n 個、 n が負の場合には最後の n 個を消します。

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

turtle.undo()¶

最後の(繰り返すことにより複数の)タートルの動きを取り消します。取り消しできる動きの最大数は undobuffer のサイズによって決まります。

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

turtle.speed(speed=None)¶

パラメータ:: speed -- 整数、文字列、または None

Return or set the turtle's speed. If speed is not given, return the current speed. Otherwise set the turtle's speed to an integer from 0 to 10. If speed is a number greater than 10 or smaller than 0.5, the speed is set to 0. You can also use these names instead of numbers:

"fastest": 0
"fast": 10
"normal": 6
"slow": 3
"slowest": 1

速度を 1 から 10 へ上げるほど、線を描いたりタートルを回転させたりするアニメーションが速くなります。速度 0 は、アニメーションを行わないことを意味します。 forward() と back() はタートルを瞬間移動させ、left() と right() はその場で瞬時に回転させます。

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

Turtle の状態を知る¶

turtle.position()¶

turtle.pos()¶

タートルの現在の位置 (x,y) を Vec2D ベクトルとして返します。

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

turtle.towards(x, y=None)¶

パラメータ:

x -- 数または数のペア/ベクトルまたはタートルのインスタンス
y -- x が数ならば数、そうでなければ None

タートルの位置から (x,y) に向かう線の角度を返します。 y が None の場合、x は座標のペア、pos() が返すような Vec2D、または別のタートルでなければなりません。角度はタートルの初期の向きから測り、この向きはタートルのモードによって変わります。 mode() を参照してください。

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

turtle.xcor()¶

タートルの x 座標を返します。

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

turtle.ycor()¶

タートルの y 座標を返します。

>>> 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() を参照してください。

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

turtle.distance(x, y=None)¶

パラメータ:

x -- 数または数のペア/ベクトルまたはタートルのインスタンス
y -- x が数ならば数、そうでなければ None

タートルから (x,y) までの距離を、タートルの歩幅を単位として返します。 y が None の場合、x は座標のペア、pos() が返すような Vec2D、または別のタートルでなければなりません。

>>> 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 -- 数

角度の単位を度に設定します。 1 周分の角度は fullcircle に設定され、デフォルトは 360 です。

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

>>> # 角度の単位を grad に変更する (gon、grade、gradian とも呼ばれ、
>>> # 直角の 1/100 に相当する)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0

turtle.radians()¶

角度の単位をラジアンに設定します。 degrees(2 * math.pi) と同等です。

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

Pen の制御¶

描画状態¶

turtle.pendown()¶
turtle.pd()¶
turtle.down()¶: ペンを下ろします。タートルは移動すると線を描きます。

turtle.penup()¶
turtle.pu()¶
turtle.up()¶: ペンを上げます。タートルは移動しても線を描きません。

turtle.pensize(width=None)¶

turtle.width(width=None)¶

パラメータ:: width -- 正の数または None

線の太さを取得または設定します。 width を指定しなければ、現在のペンの太さを返します。 resizemode が "auto" で、タートルの形状が多角形の場合は、その多角形も同じ線の太さで描きます。

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # これ以降は幅 10 の線を描く

turtle.pen(pen=None, **pendict)¶

パラメータ:

pen -- 以下のキーの一部またはすべてを持つ辞書
pendict -- 以下のキーをキーワードとする、1 つ以上のキーワード引数

ペンの属性を "pen-dictionary" に以下のキー/値ペアで設定するかまたは返します:

"shown": True/False
"pendown": True/False
"pencolor": 色文字列または色タプル
"fillcolor": 色文字列または色タプル
"pensize": 正の数
"speed": 0 から 10 までの整数
"resizemode": "auto" または "user" または "noresize"
"stretchfactor": (正の数, 正の数)
"outline": 正の数
"tilt": 数

この辞書を以降の pen() 呼出しに渡して以前のペンの状態に復旧することができます。さらに一つ以上の属性をキーワード引数として渡すこともできます。一つの文で幾つものペンの属性を設定するのに使えます。

>>> 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 を返します。

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

色の制御¶

turtle.pencolor()¶

turtle.pencolor(color, /)

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

ペンの色(pencolor)を設定するかまたは返します。

4種類の入力形式が受け入れ可能です:

pencolor(): 現在のペンの色を、色指定文字列またはタプルとして返します (例を参照)。この値は color()、pencolor()、fillcolor()、bgcolor() の呼び出しに渡せます。
pencolor(colorstring): ペンの色を colorstring に設定します。 colorstring は、"red"、"yellow"、"#33cc8c" などの Tk の色指定文字列です。
pencolor((r, g, b)): ペンの色を、r、g、b のタプルで表す RGB の色に設定します。 r、g、b はそれぞれ 0 から colormode までの値でなければなりません。 colormode は 1.0 または 255 です (colormode() を参照)。
pencolor(r, g, b): ペンの色を、r、g、b で表す RGB の色に設定します。 r、g、b はそれぞれ 0 から colormode までの値でなければなりません。

タートルの形状が多角形の場合は、その輪郭を新しく設定したペンの色で描きます。

>>> 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)を設定するかまたは返します。

4種類の入力形式が受け入れ可能です:

fillcolor(): 現在の塗りつぶしの色を、色指定文字列またはタプルとして返します (例を参照)。この値は color()、pencolor()、fillcolor()、bgcolor() の呼び出しに渡せます。
fillcolor(colorstring): 塗りつぶしの色を colorstring に設定します。 colorstring は、"red"、"yellow"、"#33cc8c" などの Tk の色指定文字列です。
fillcolor((r, g, b)): 塗りつぶしの色を、r、g、b のタプルで表す RGB の色に設定します。 r、g、b はそれぞれ 0 から colormode までの値でなければなりません。 colormode は 1.0 または 255 です (colormode() を参照)。
fillcolor(r, g, b): 塗りつぶしの色を、r、g、b で表す RGB の色に設定します。 r、g、b はそれぞれ 0 から colormode までの値でなければなりません。

タートルの形状が多角形の場合は、その内側を新しく設定した塗りつぶしの色で描きます。

>>> 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() および fillcolor() で返される色指定文字列またはタプルのペアで返します。
color(colorstring), color((r,g,b)), color(r,g,b): 入力は pencolor() と同じです。ペンの色と塗りつぶしの色の両方を、指定された値に設定します。
color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2)): pencolor(colorstring1) および fillcolor(colorstring2) を呼び出すのと等価です。もう一つの入力形式についても同様です。

タートルの形状が多角形の場合は、その輪郭と内側を新しく設定した色で描きます。

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

こちらも参照: スクリーンのメソッド colormode() 。

塗りつぶし¶

turtle.filling()¶

タートルが塗りつぶし中なら True、それ以外なら False を返します。

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

turtle.fill()¶

with turtle.fill(): ブロック内で描いた図形を塗りつぶします。

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

fill() を使うことは、塗りつぶしのブロックの前に begin_fill()、後に end_fill() を追加するのと同等です。

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

Added in version 3.14.

turtle.begin_fill()¶: 塗りつぶす図形を描く直前に呼び出します。

turtle.end_fill()¶

最後に呼び出された begin_fill() の後に描かれた図形を塗りつぶします。

自己交差する多角形や複数の図形で、重なった領域が塗りつぶされるかどうかは、オペレーティングシステムの描画機能や重なり方、重なった回数によって変わります。例えば、上のタートルで描いた星形は、全体が黄色になる場合もあれば、白い領域が残る場合もあります。

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

さらなる描画の制御¶

turtle.reset()¶

タートルが描いたものを消し、タートルを中央に戻します。タートルの設定はデフォルト値に戻ります。

>>> 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 -- 三つ組み (fontname, fontsize, fonttype)

文字を書きます— arg の文字列表現を、現在のタートルの位置に、 align ("left", "center", "right" のどれか) に従って、与えられたフォントで。もし move が真ならば、ペンは書いた文の右下隅に移動します。デフォルトでは、 move は False です。

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

タートルの状態¶

可視性¶

turtle.hideturtle()¶
turtle.ht()¶: タートルを見えなくします。ペンが下りていれば、移動すると引き続き線を描きます。

turtle.showturtle()¶
turtle.st()¶: タートルが見えるようにします。

turtle.isvisible()¶

タートルが表示されていれば True、隠れていれば False を返します。

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

見た目¶

turtle.shape(name=None)¶

パラメータ:: name -- 文字列または None

タートルの形状を、指定された名前の形状に設定します。 name を指定しなければ、現在の形状の名前を返します。形状は TurtleScreen の形状の辞書に登録されていなければなりません。初期状態では "arrow"、"turtle"、"circle"、"square"、"triangle"、"classic" があります。形状の追加については、Screen のメソッド register_shape() を参照してください。

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

turtle.resizemode(rmode=None)¶

パラメータ:: rmode -- 文字列または None

サイズ変更モードを "auto"、"user"、"noresize" のいずれかに設定します。 rmode を指定しなければ、現在のサイズ変更モードを返します。各モードの動作は次のとおりです。

"auto": pensize() の値に応じてタートルのサイズを変更します。
"user": shapesize() で設定した伸縮率と輪郭線の幅に応じて、タートルのサイズを変更します。
"noresize": タートルのサイズを変更しません。

resizemode("user") は shapesize() に引数を渡したときに呼び出されます。

>>> 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 -- 正の数または None
stretch_len -- 正の数または None
outline -- 正の数または None

タートルの伸縮率と輪郭線の幅を取得または設定します。引数を指定しなければ、現在の値を返します。指定した場合はサイズ変更モードを "user" に設定し、伸縮率に従ってタートルを伸縮して表示します。

stretch_wid: タートルの進行方向に垂直な方向の伸縮率
stretch_len: タートルの進行方向の伸縮率
outline: 形状の輪郭線の幅

例えば shapesize(2, 1) は、長さを変えずにタートルの幅を 2 倍にします。 stretch_wid だけを指定した場合は、stretch_len も同じ値に設定されます。

>>> 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 -- 数 (省略可能)

現在のせん断係数を設定または取得します。せん断角の正接である係数 shear に従って、タートルの形状をせん断変形します。タートルの向き (進行方向) は 変わりません。 shear を指定しなければ、現在のせん断係数、つまりタートルの進行方向に平行な線のせん断角の正接を返します。

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

turtle.tilt(angle)¶

パラメータ:: angle -- 数

タートルの形(turtleshape)を現在の傾斜角から角度(angle)だけ回転します。このときタートルの進む方向は 変わりません 。

>>> 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 -- 数 (省略可能)

現在の傾斜角を設定または取得します。 angle を指定すると、現在の傾斜角にかかわらず、タートルの形状を angle の方向に回転させます。タートルの向き (進行方向) は 変わりません。 angle を指定しなければ、現在の傾斜角、つまりタートルの形状の向きと進行方向との間の角度を返します。

>>> 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 要素のタプルとして返します。指定した場合はその要素を設定し、第 1 行が t11、t12、第 2 行が t21、t22 の行列に従ってタートルの形状を変換します。行列式 t11 * t22 - t12 * t21 は 0 であってはならず、0 の場合はエラーを送出します。指定された行列に応じて、伸縮率、せん断係数、傾斜角を変更します。

>>> 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()¶

現在の形状の多角形を、座標ペアのタプルとして返します。新しい形状や、複合形状の構成要素を定義するために使えます。

>>> 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 -- 2 つの引数を取る関数、または None
btn -- 整数
add -- ブール値または None

このタートル上のマウスクリックイベントに fun を束縛します。 fun は、クリックされた点のキャンバス上の座標を引数として呼び出されます。 fun が None の場合は、既存の束縛を削除します。 btn はマウスボタンの番号で、デフォルトは左ボタンを表す 1 です。 add が True の場合は新しい束縛を追加し、それ以外の場合は以前の束縛を置き換えます。以下は、無名のタートルを使う、つまり手続き的な書き方の例です。

>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # タートルをクリックすると向きが変わる
>>> onclick(None)  # イベントの束縛を削除する

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

パラメータ:

fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです
btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)
add -- True または False -- True ならば、新しい束縛が追加されますが、そうでなければ、以前の束縛を置き換えます。

fun をタートルのマウスボタンリリース(mouse-button-release)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

>>> 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 -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです
btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)
add -- True または False -- True ならば、新しい束縛が追加されますが、そうでなければ、以前の束縛を置き換えます。

fun をタートルのマウスムーブ(mouse-move)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

注意: 全てのマウスムーブイベントのシーケンスに先立ってマウスクリックイベントが起こります。

>>> turtle.ondrag(turtle.goto)

この後、タートルをクリックしてドラッグするとタートルはスクリーン上を動きそれによって(ペンが下りていれば)手書きの線ができあがります。

特別な Turtle のメソッド¶

turtle.poly()¶

with turtle.poly(): ブロック内で描いた多角形の頂点を記録します。最初と最後の頂点は結ばれます。

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

Added in version 3.14.

turtle.begin_poly()¶: 多角形の頂点の記録を開始します。タートルの現在の位置が、多角形の最初の頂点になります。

turtle.end_poly()¶: 多角形の頂点の記録を停止します。タートルの現在の位置が最後の頂点となり、最初の頂点と結ばれます。

turtle.get_poly()¶

最後に記録された多角形を返します。

>>> 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()¶

タートルの複製を作成して返します。複製は元のタートルと同じ位置、向き、属性を持ちます。

>>> leonel = Turtle()
>>> marco = leonel.clone()

turtle.getturtle()¶

turtle.getpen()¶

Turtle オブジェクト自身を返します。

getturtle() を呼ぶと、forward() や left() などの関数が使うタートルを取得できます。

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

turtle.getscreen()¶

タートルが描画中の TurtleScreen オブジェクトを返します。 TurtleScreen のメソッドをそのオブジェクトに対して呼び出すことができます。

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

turtle.setundobuffer(size)¶

パラメータ:: size -- 整数または None

取り消し用バッファを設定するか、無効にします。 size が整数の場合は、指定されたサイズの空の取り消し用バッファを設定します。 size は、undo() で取り消せるタートルの操作の最大数です。 size が None の場合は、取り消し用バッファを無効にします。

>>> turtle.setundobuffer(42)

turtle.undobufferentries()¶

取り消し用バッファ内の項目数を返します。

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

Screen のメソッドと関数¶

この節のほとんどの例では screen という名前の TurtleScreen インスタンスを使います。

ウィンドウの制御¶

turtle.bgcolor()¶

turtle.bgcolor(color, /)

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

TurtleScreen の背景色を取得または設定します。

4種類の入力形式が受け入れ可能です:

bgcolor(): 現在の背景色を、色指定文字列またはタプルとして返します (例を参照)。この値は color()、pencolor()、fillcolor()、bgcolor() の呼び出しに渡せます。
bgcolor(colorstring): 背景色を colorstring に設定します。 colorstring は、"red"、"yellow"、"#33cc8c" などの Tk の色指定文字列です。
bgcolor((r, g, b)): 背景色を、r、g、b のタプルで表す RGB の色に設定します。 r、g、b はそれぞれ 0 から colormode までの値でなければなりません。 colormode は 1.0 または 255 です (colormode() を参照)。
bgcolor(r, g, b): 背景色を、r、g、b で表す RGB の色に設定します。 r、g、b はそれぞれ 0 から colormode までの値でなければなりません。

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

背景の画像を設定するかまたは現在の背景画像(backgroundimage)の名前を返します。 picname がファイル名ならば、その画像を背景に設定します。 picname が "nopic" ならば、(もしあれば)背景画像を削除します。 picname が None ならば、現在の背景画像のファイル名を返します。

>>> 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 -- 正の整数でピクセル単位の新しいキャンバス幅(canvaswidth)
canvheight -- 正の整数でピクセル単位の新しいキャンバス高さ(canvasheight)
bg -- 色文字列または色タプルで新しい背景色

引数が渡されなければ、現在の (キャンバス幅, キャンバス高さ) を返します。そうでなければタートルが描画するキャンバスのサイズを変更します。描画ウィンドウには影響しません。キャンバスの隠れた部分を見るためにはスクロールバーを使って下さい。このメソッドを使うと、以前はキャンバスの外にあったそうした図形の一部を見えるようにすることができます。

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

# 逃げ出してしまったタートルを探すためとかね ;-)

turtle.setworldcoordinates(llx, lly, urx, ury)¶

パラメータ:

llx -- 数
lly -- 数
urx -- 数
ury -- 数

ユーザー定義の座標系を設定します。 llx と lly はキャンバスの左下隅の x 座標と y 座標、urx と ury は右上隅の x 座標と y 座標です。必要に応じて "world" モードに切り替え、その際にリセットします。すでに "world" モードであれば、新しい座標に従ってすべての図形を描き直します。ユーザー定義の座標系では、角度が歪んで見えることがあります。 mode() を参照してください。

>>> 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()¶

タートルのアニメーションを一時的に無効にします。 with ブロック内のコードではアニメーションを行わず、ブロックを出ると描画結果が表示されます。最速の設定でも遅すぎる複雑な図形を描くときに便利です。

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

Added in version 3.14.

turtle.delay(delay=None)¶

パラメータ:: delay -- 非負の整数または None

描画の遅延時間をミリ秒単位で取得または設定します。これは、連続するキャンバスの更新の間のおおよその時間です。遅延時間が長いほど、アニメーションは遅くなります。

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

turtle.tracer(n=None, delay=None)¶

パラメータ:

n -- 非負の整数または None
delay -- 非負の整数または None

タートルのアニメーションを有効または無効にし、描画の遅延時間を設定します。 n を指定すると、通常の画面更新のうち n 回に 1 回だけ更新を行います。複雑な図形の描画を速くするために使えます。 n が 0 の場合はアニメーションを無効にし、update() を呼び出したときだけ画面を更新します。 delay を指定すると、描画の遅延時間を設定します (delay() を参照)。引数なしで呼び出すと、現在の n の値を返します。

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

turtle.update()¶: TurtleScreen の更新を実行します。トレーサーがオフの時に使われます。

RawTurtle/Turtle のメソッド speed() も参照して下さい。

スクリーンイベントを利用する¶

turtle.listen(xdummy=None, ydummy=None)¶: TurtleScreen に(キー・イベントを収集するために)フォーカスします。ダミー引数は listen() を onclick メソッドに渡せるようにするためのものです。

turtle.onkey(fun, key)¶

turtle.onkeyrelease(fun, key)¶

パラメータ:

fun -- 引数なしの関数または None
key -- 文字列: キー (例 "a") またはキー・シンボル (例 "space")

fun を指定されたキーのキーリリース(key-release)イベントに束縛します。 fun が None ならばイベント束縛は除かれます。注意: キー・イベントを登録できるようにするためには TurtleScreen はフォーカスを持っていないとなりません(listen() を参照)。

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

turtle.onkeypress(fun, key=None)¶

パラメータ:

fun -- 引数なしの関数または None
key -- 文字列: キー (例 "a") またはキー・シンボル (例 "space")

key を指定した場合はそのキーの押下イベントに、指定しなければ任意のキーの押下イベントに fun を束縛します。キーイベントを受け取るには、TurtleScreen にフォーカスが必要です (listen() を参照)。

>>> 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 -- 2 つの引数を取る関数、または None
btn -- 整数
add -- ブール値または None

この画面上のマウスクリックイベントに fun を束縛します。 fun は、クリックされた点のキャンバス上の座標を引数として呼び出されます。 fun が None の場合は、既存の束縛を削除します。 btn はマウスボタンの番号で、デフォルトは左ボタンを表す 1 です。 add が True の場合は新しい束縛を追加し、それ以外の場合は以前の束縛を置き換えます。

Example for a screen という名の TurtleScreen インスタンスと turtle という名前の Turtle インスタンスの例:

>>> screen.onclick(turtle.goto) # これ以降、TurtleScreen をクリックすると
>>>                             # その点にタートルが移動する
>>> screen.onclick(None)        # イベントの束縛を削除する

注釈

この TurtleScreen メソッドはグローバル関数としては onscreenclick という名前でだけ使えます。グローバル関数 onclick は Turtle メソッドの onclick から派生した別ものです。

turtle.ontimer(fun, t=0)¶

パラメータ:

fun -- 引数なし関数
t -- 数 >= 0

t ミリ秒後に fun を呼び出すタイマーを仕掛けます。

>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### タートルを歩き回らせる
>>> running = False

turtle.mainloop()¶
turtle.done()¶: Tkinter の mainloop() メソッドを呼び出してイベントループを開始します。タートルグラフィックスのプログラムでは最後の文にしなければなりません。 IDLE の -n モードでスクリプトを実行する場合は、使っては いけません (サブプロセスを起こさずに起動するを参照)。

入力メソッド¶

turtle.textinput(title, prompt)¶

パラメータ:

title -- 文字列
prompt -- 文字列

文字列を入力するダイアログウィンドウを表示します。 title はダイアログのタイトル、prompt は入力する情報を説明するテキストです。入力された文字列を返します。ダイアログがキャンセルされた場合は None を返します。

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

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

パラメータ:

title -- 文字列
prompt -- 文字列
default -- 数または None
minval -- 数または None
maxval -- 数または None

数値を入力するダイアログウィンドウを表示します。 title はダイアログのタイトル、prompt は入力する数値情報を説明するテキストです。 default はデフォルト値、minval と maxval は入力の最小値と最大値です。これらを指定した場合、入力する数値は minval から maxval の範囲内でなければなりません。範囲外の値が入力されると、ヒントを表示し、修正できるようにダイアログを開いたままにします。入力された数値を返します。ダイアログがキャンセルされた場合は None を返します。

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

設定と特殊なメソッド¶

turtle.mode(mode=None)¶

パラメータ:: mode -- 文字列または None

タートルのモードを設定し、リセットします。 mode は文字列 "standard"、"logo"、"world" のいずれかです。 mode を指定しなければ、現在のモードを返します。

"standard" モードは古い turtle モジュールと互換性があります。 "logo" モードは多くの Logo のタートルグラフィックスと互換性があります。 "world" モードはユーザー定義のワールド座標を使います (setworldcoordinates() を参照)。このモードでは、x と y の単位の長さが等しくない場合、角度が歪んで見えます。

モード	タートルの向きの初期値	正の角度
"standard"	右 (東) 向き	反時計回り
"logo"	上 (北) 向き	時計回り

>>> mode("logo")  # タートルの向きを北にリセットする
>>> mode()
'logo'

turtle.colormode(cmode=None)¶

パラメータ:: cmode -- 数または None

カラーモードを取得するか、1.0 または 255 に設定します。設定後は、色を表す三つ組の r、g、b の値を 0 から cmode の範囲内にする必要があります。

>>> 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()¶

この TurtleScreen の Canvas を返します。Tkinter の Canvas を使って何をするか知っている人には有用です。

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

turtle.getshapes()¶

現在利用できるすべてのタートルの形状の名前を、リストで返します。

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

turtle.register_shape(name, shape=None)¶

turtle.addshape(name, shape=None)¶

パラメータ:

name -- 文字列
shape -- 文字列、数値ペアのタプル、Shape オブジェクト、または None

TurtleScreen の形状リストに、タートルの形状を追加します。呼び出し方は 4 通りあります。

name が画像ファイル (PNG、GIF、PGM、PPM) の名前で shape が None の場合: 対応する画像の形状を登録します。
```
>>> screen.register_shape("turtle.gif")
```
name が任意の文字列で shape が画像ファイル (PNG、GIF、PGM、PPM) の名前の場合: 対応する画像の形状を登録します。
```
>>> screen.register_shape("turtle", "turtle.gif")
```
name が任意の文字列で shape が座標ペアのタプル: 対応する多角形を取り込みます。
```
>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
```
name が任意の文字列で shape が (合成形の) Shape オブジェクト: 対応する合成形を取り込みます。

画像の形状はタートルの向きを変えても回転しないため、タートルの向きを表しません。登録した形状を使うには、その名前を渡して shape() を呼び出してください。

バージョン 3.14 で変更: PNG、PGM、PPM の画像形式のサポートが追加されました。形状名と画像ファイル名の両方を指定できるようになりました。

turtle.turtles()¶

スクリーン上のタートルのリストを返します。

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

turtle.window_height()¶

タートルウィンドウの高さを返します。

>>> screen.window_height()
480

turtle.window_width()¶

タートルウィンドウの幅を返します。

>>> screen.window_width()
640

Screen 専用のメソッド¶

turtle.bye()¶: タートルグラフィックスのウィンドウを閉じます。

turtle.exitonclick()¶

スクリーン上のマウスクリックに bye() メソッドを束縛します。

設定辞書中の "using_IDLE" の値が False (デフォルトです) の場合、さらにメインループ(mainloop)に入ります。注意: もし IDLE が -n スイッチ(サブプロセスなし)付きで使われているときは、この値は turtle.cfg の中で True とされているべきです。この場合、IDLE のメインループもクライアントスクリプトから見てアクティブです。

turtle.save(filename, overwrite=False)¶

現在のタートルの描画内容 (タートル自身も含む) を PostScript ファイルとして保存します。

パラメータ:

filename -- 保存する PostScript ファイルのパス
overwrite -- False で、指定された名前のファイルがすでに存在する場合は、FileExistsError を送出します。 True の場合は、ファイルを上書きします。

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

Added in version 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 ならば垂直方向に真ん中

>>> 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 に設定します。タイトルはタートルグラフィックスのウィンドウのタイトルバーに表示されます。

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

公開クラス¶

class turtle.RawTurtle(canvas)¶

class turtle.RawPen(canvas)¶

パラメータ:: canvas -- tkinter.Canvas、ScrolledCanvas、または TurtleScreen

タートルを作ります。タートルには上の「Turtle/RawTurtle のメソッド」で説明した全てのメソッドがあります。

class turtle.Turtle¶: RawTurtle のサブクラスで同じインターフェイスを持ちますが、最初に必要になったとき自動的に作られる Screen オブジェクトに描画します。

class turtle.TurtleScreen(cv)¶

パラメータ:: cv -- tkinter.Canvas

上で説明した bgcolor() のようなスクリーン向けのメソッドを提供します。

class turtle.Screen¶: Subclass of TurtleScreen, with four methods added. Calling Screen() returns the single screen object. If it does not exist yet, it is created. Otherwise the existing one is returned.

class turtle.ScrolledCanvas(master)¶

パラメータ:: master -- この ScrolledCanvas すなわちスクロールバーの付いた Tkinter canvas を収める Tkinter ウィジェット

タートルたちが遊び回る場所として自動的に ScrolledCanvas を提供する Screen クラスによって使われます。

class turtle.Shape(type_, data)¶

パラメータ:

type_ -- 文字列
data -- type_ によって異なります

形状を表すデータ構造です。 type_ は文字列 "polygon"、"image"、"compound" のいずれかです。 data に指定する値は type_ によって変わります。 "polygon" では座標ペアのタプル、"image" では画像 (内部でのみ使用)、"compound" では None です。複合形状は addcomponent() メソッドを使って組み立てます。

addcomponent(poly, fill, outline=None)¶

パラメータ:

poly -- 数値ペアのタプル
fill -- 色
outline -- 色または None

"compound" 型の形状に構成要素を追加します。 poly は多角形を表す数値ペアのタプルです。 fill は多角形の塗りつぶしの色、outline は輪郭線の色です。 outline を指定しなければ、輪郭線にも fill を使います。

例:

>>> poly = ((0,0), (10,-5), (0,10), (-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... さらに構成要素を追加してから register_shape() を使う

複合形状を使う方法を参照。

class turtle.Vec2D(x, y)¶

2次元ベクトルのクラスで、タートルグラフィックスを実装するための補助クラス。タートルグラフィックスを使ったプログラムでも有用でしょう。タプルから派生しているので、ベクターはタプルです!

以下の演算が使えます (a, b はベクトル、 k は数):

a + b ベクトル和
a - b ベクトル差
a * b 内積
k * a および a * k スカラー倍
abs(a) a の絶対値
a.rotate(angle) 回転

例外¶

turtle モジュールは次の例外を定義しています。

exception turtle.TurtleGraphicsError¶

無効な引数や操作に対して送出されます。例えば、不正な色文字列を指定した場合です。

>>> turtle.color("blau")
Traceback (most recent call last):
    ...
turtle.TurtleGraphicsError: bad color string: blau

ハウツー・ガイド¶

この節では、タートルの典型的な用途と使い方をいくつか紹介します。

塗りつぶしを自動的に開始・終了する方法¶

Python 3.14 以降では、begin_fill() と end_fill() の代わりに、fill() コンテキストマネージャを使って塗りつぶしを自動的に開始・終了できます。使用例を示します。

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

forward(200)

上のコードは、次と同等です。

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

forward(200)

複合形状を使う方法¶

合成されたタートルの形、つまり幾つかの色の違う多角形から成るような形を使うには、以下のように補助クラス Shape を直接使わなければなりません:

"compound" 型の空の Shape オブジェクトを作成します。

addcomponent() メソッドを使って、好きなだけここにコンポーネントを追加します。

例えば:

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

こうして作った Shape を Screen の形のリスト(shapelist) に追加して使います:
```
>>> register_shape("myshape", s)
>>> shape("myshape")
```

`turtle` モジュールの名前空間を使う方法¶

from turtle import * は便利ですが、多数のオブジェクトをインポートする点には注意してください。タートルグラフィックス以外の処理も行う場合は、名前が衝突するおそれがあります。特に、他のモジュールもインポートする可能性があるスクリプトでタートルグラフィックスを使う場合は、問題になりやすくなります。

解決策は import turtle を使うことです。 fd() は turtle.fd()、width() は turtle.width() というように書きます。 ("turtle" を何度も入力するのが面倒であれば、例えば import turtle as t を使ってください。)

スクリプトでタートルグラフィックスを使う方法¶

すぐ上で説明したように、turtle モジュールの名前空間を使うことを推奨します。例えば、次のように書きます。

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)

ただし、もう 1 つ手順が必要です。スクリプトが終わると、Python はタートルのウィンドウもすぐに閉じてしまいます。次の行を

t.mainloop()

スクリプトの最後に追加してください。これでスクリプトは終了の操作を待つようになり、タートルグラフィックスのウィンドウを閉じるなどして終了させるまで動作し続けます。

オブジェクト指向のタートルグラフィックスを使う方法¶

参考

オブジェクト指向インターフェースの説明

ごく基本的な入門や、すぐに試してみたい場合を除けば、タートルグラフィックスではオブジェクト指向の方法の方が一般的で、はるかに多くのことができます。例えば、画面に複数のタートルを同時に表示できます。

この方法では、さまざまなタートルのコマンドが、主に Turtle オブジェクトのメソッドになります。シェルでもオブジェクト指向の方法を 使えます が、通常は 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 は、Turtle インスタンスが置かれている Screen のインスタンスです。タートルとともに自動的に作成されます。

タートルの画面はカスタマイズできます。例えば次のようにします。

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

`help()` の使い方¶

Screen と Turtle クラスのパブリックメソッドはドキュメント文字列で網羅的に文書化されていますので、Python のヘルプ機能を通じてオンラインヘルプとして利用できます:

IDLE を使っているときは、打ち込んだ関数/メソッド呼び出しのシグニチャとドキュメント文字列の一行目がツールチップとして表示されます。

help() をメソッドや関数に対して呼び出すとドキュメント文字列が表示されます:

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

メソッドに由来する関数のドキュメント文字列は変更された形をとります:

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

これらの変更されたドキュメント文字列はインポート時にメソッドから導出される関数定義と一緒に自動的に作られます。

ドキュメント文字列の翻訳¶

Screen と Turtle クラスのパブリックメソッドについて、キーがメソッド名で値がドキュメント文字列である辞書を作るユーティリティがあります。

turtle.write_docstringdict(filename='turtle_docstringdict')¶

パラメータ:: filename -- ファイル名として使われる文字列

ドキュメント文字列辞書(docstring-dictionary)を作って与えられたファイル名の Python スクリプトに書き込みます。この関数はわざわざ呼び出さなければなりません (タートルグラフィックスのクラスから使われることはありません)。ドキュメント文字列辞書は filename.py という Python スクリプトに書き込まれます。ドキュメント文字列の異なった言語への翻訳に対するテンプレートとして使われることを意図したものです。

自分や学習者の母語で turtle のオンラインヘルプを使いたい場合は、ドキュメント文字列を翻訳し、例えば turtle_docstringdict_german.py という名前でファイルに保存する必要があります。

さらに turtle.cfg ファイルで適切な設定をしておけば、このファイルがインポート時に読み込まれて元の英語のドキュメント文字列を置き換えます。

この文書を書いている時点ではドイツ語とイタリア語のドキュメント文字列辞書が存在します。 ( glingl@aon.at にリクエストして下さい。)

Screen および Turtle の設定方法¶

初期デフォルト設定では古い turtle の見た目と振る舞いを真似るようにして、互換性を最大限に保つようにしています。

このモジュールの特性を反映した、あるいは個々人の必要性 (たとえばクラスルームでの使用)に合致した、異なった設定を使いたい場合、設定ファイル turtle.cfg を用意してインポート時に読み込ませその設定に従わせることができます。

初期設定は以下の turtle.cfg に対応します:

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

いくつかピックアップしたエントリーの短い説明:

最初の4行は Screen.setup メソッドの引数に当たります。
5行目6行目は Screen.screensize メソッドの引数に当たります。
shape は最初から用意されている形ならどれでも使えます(arrow, turtle など)。詳しくは help(shape) をお試し下さい。
塗りつぶしの色(fill color)を使いたくない(つまりタートルを透明にしたい)場合、 fillcolor = "" と書かなければなりません (しかし全ての空でない文字列は cfg ファイル中で引用符を付けてはいけません)。
タートルにその状態を反映させるためには resizemode = auto とします。
例えば language = italian と設定すると、インポート時にドキュメント文字列の辞書 turtle_docstringdict_italian.py を読み込みます (例えば turtle と同じディレクトリなど、インポートパス上に存在する場合)。
exampleturtle および examplescreen はこれらのオブジェクトのドキュメント文字列内での呼び名を決めます。メソッドのドキュメント文字列から関数のドキュメント文字列に変換する際に、これらの名前は取り除かれます。
using_IDLE: IDLE とその -n スイッチ(サブプロセスなし)を常用するならば、この値を True に設定して下さい。これにより exitonclick() がメインループ(mainloop)に入るのを阻止します。

turtle.cfg は turtle が置かれているディレクトリに配置できるほか、カレントディレクトリにも追加で配置できます。後者の設定は前者を上書きします。

Lib/turtledemo ディレクトリにも turtle.cfg ファイルがあります。デモを実際に(できればデモビュワーからでなく)実行してそこに書かれたものとその効果を学びましょう。

説明¶

タートルオブジェクトは画面オブジェクト上に描画します。タートルのオブジェクト指向インターフェースには、これらを作成して関連付けるための主要なクラスがいくつかあります。

Turtle インスタンスは、まだ Screen インスタンスがなければ、自動的に作成します。

Turtle は RawTurtle のサブクラスです。 RawTurtle は描画領域を自動的には作成 しない ため、canvas を渡すか作成する必要があります。 canvas には tkinter.Canvas、ScrolledCanvas、TurtleScreen を使えます。

TurtleScreen はタートルの基本的な描画領域です。 Screen は TurtleScreen のサブクラスで、サイズやタイトルを含む見た目と動作を管理するための追加のメソッドを備えています。 TurtleScreen のコンストラクタには、tkinter.Canvas または ScrolledCanvas を引数として渡す必要があります。

タートルグラフィックスの関数インターフェースは、Turtle と TurtleScreen/Screen のさまざまなメソッドを使っています。内部では、Screen のメソッドに由来する関数を呼び出すと、画面オブジェクトが自動的に作成されます。同様に、Turtle のメソッドに由来する関数を呼び出すと、タートルオブジェクトが自動的に作成されます。

1 つの画面で複数のタートルを使うには、オブジェクト指向インターフェースを使う必要があります。

`turtledemo` --- デモスクリプト¶

turtledemo パッケージには、一連のデモスクリプトが含まれています。付属のデモビュワーを次のように起動すると、スクリプトを実行したり表示したりできます。

python -m turtledemo

あるいは、個別にデモスクリプトを実行できます。たとえば、:

python -m turtledemo.bytedesign

turtledemo パッケージのディレクトリには、次のものが含まれます。

ソースコードを眺めつつスクリプトを実行できるデモビュワー __main__.py 。
turtle モジュールのさまざまな機能を実演する複数のスクリプト。 Examples メニューから開けるほか、単独でも実行できます。
設定ファイルの書き方や使い方の例として参考にできる turtle.cfg ファイル。

デモスクリプトは以下の通りです:

名前	説明	フィーチャー
`bytedesign`	複雑な古典的タートルグラフィックスパターン	`tracer()`, `delay()`, `update()`
`chaos`	verhust 力学系のグラフ化, コンピュータの計算が常識的な予想に反する場合があることを示します。	世界座標系
`clock`	コンピュータの時間を示すアナログ時計	タートルを時計の針として使用、`ontimer()`
`colormixer`	r, g, b の実験	`ondrag()`
`forest`	幅優先で描く 3 本の木	ランダム化
`fractalcurves`	Hilbert & Koch 曲線	再帰
`lindenmayer`	民俗的数学 (インド kolams)	L-システム
`minimal_hanoi`	ハノイの塔	長方形のタートルをハノイの塔の円盤として使用 (`shape()`、`shapesize()`)
`nim`	棒の山を 3 つ使う古典的なニムゲームで、コンピュータと対戦します。	タートルをニムの棒として使用、イベント駆動 (マウス、キーボード)
`paint`	超極小主義的描画プログラム	`onclick()`
`peace`	初歩的	turtle: 見た目とアニメーション
`penrose`	凧と矢による非周期的タイリング	`stamp()`
`planet_and_moon`	重力系のシミュレーション	合成形, `Vec2D`
`rosette`	タートルグラフィックスについての wikipedia の記事の例	`clone()`, `undo()`
`round_dance`	ペアごとに逆向きに回転しながら踊るタートル	複合形状、`clone()`、`shapesize()`、`tilt()`、`get_shapepoly()`、`update()`
`sorting_animate`	さまざまなソート方法を視覚的に実演	単純な整列、ランダム化
`tree`	(図形的) 幅優先木 (ジェネレータを使って)	`clone()`
`two_canvases`	単純な図柄	2 つのキャンバス上のタートル
`yinyang`	もう一つの初歩的な例	`circle()`

楽しんでね!

turtle --- タートルグラフィックス¶

チュートリアル¶

タートルの環境を起動する¶

基本的な描画¶

Pen の制御¶

タートルの位置¶

アルゴリズムで模様を描く¶

リファレンス¶

タートルのメソッドと関数¶

移動および描画¶

Turtle の状態を知る¶

測定の設定¶

Pen の制御¶

描画状態¶

色の制御¶

塗りつぶし¶

さらなる描画の制御¶

タートルの状態¶

可視性¶

見た目¶

イベントを利用する¶

特別な Turtle のメソッド¶

Screen のメソッドと関数¶

ウィンドウの制御¶

アニメーションの制御¶

スクリーンイベントを利用する¶

入力メソッド¶

設定と特殊なメソッド¶

Screen 専用のメソッド¶

公開クラス¶

例外¶

ハウツー・ガイド¶

塗りつぶしを自動的に開始・終了する方法¶

複合形状を使う方法¶

turtle モジュールの名前空間を使う方法¶

スクリプトでタートルグラフィックスを使う方法¶

オブジェクト指向のタートルグラフィックスを使う方法¶

help() の使い方¶

ドキュメント文字列の翻訳¶

Screen および Turtle の設定方法¶

説明¶

turtledemo --- デモスクリプト¶

`turtle` --- タートルグラフィックス¶

`turtle` モジュールの名前空間を使う方法¶

`help()` の使い方¶

`turtledemo` --- デモスクリプト¶