参考情報: Python turtle との API 対応・差異の一覧

[temoki]

この issue は特定の課題や作業を指すものではありません。 TortoiseGraphics2 の API が
Python turtle と比べて何に対応し、何に対応していないかを一覧にした参考情報です。
機能追加の是非を判断するとき、README / DocC に「Differences from Python turtle」節を
書くとき、利用者からの問い合わせに答えるときの土台として残しておきます。

対象バージョン: 2.2.0 (a5c4f79) 時点。

背景

PR #50（ペン幅のテーパー）のレビューで、「このライブラリのコマンド語彙はどこまでが
Python turtle 由来で、どこからが独自の選択なのか」を整理する必要が出た。調べたところ
Python turtle の部分集合 + 独自機能という構造になっており、除外されているものにも
傾向があることが分かったので、その調査結果を残す。

なお、未対応のものが「意図的な除外」か「単に未着手」かは、本 issue では判定していない。
一覧の提示までに留める。

対応しているもの

Python turtle	TortoiseGraphics2
forward / backward / right / left	forward / backward / right / left
goto / setx / sety / home	setPosition(x:y:) / setX / setY / home()
setheading / heading	heading（get/set）
position / xcor / ycor / towards / distance	position / towards / distance
pendown / penup / isdown	penDown() / penUp() / isPenDown
pensize / pencolor / fillcolor	penWidth / penColor / fillColor
begin_fill / end_fill / filling	beginFill() / endFill() / isFilling
circle(radius, extent)	circle(radius:extent:)
dot(size)	dot(size:)
showturtle / hideturtle / isvisible	showTortoise() / hideTortoise() / isVisible
speed	speed（1〜10、0 = instant も同じ）
bgcolor / clear / reset	backgroundColor / clear() / reset()

circle の負の radius でアークがミラーする挙動まで合わせてあるなど、対応しているもの
の忠実度は高い。

対応しているが挙動が異なるもの

項目	差異
heading の基準	こちらは常に 0 = 北・時計回り正。これは Python turtle の mode("logo") 相当であり、デフォルトの mode("standard")（0 = 東・反時計回り正）とは異なる。mode() 自体が無いため切り替え不可
circle(steps=)	steps 引数が無い。多角形近似で正多角形を描く定番イディオムが使えない
dot(size, color)	色引数が無く、常に現在の penColor を使う
colormode()	無し。Color は常に 0.0〜1.0 の Double。255 指定も色名文字列（"red"）も無い（.red などの定数は有り）
color(pen, fill)	ペンとフィルをまとめて設定する形は無く、個別プロパティのみ
screensize()	canvasSize は init 時に固定。あとから変更できない

対応していないもの

描画プリミティブ

• write() — テキストが描けない。欠落としては最も大きい
• stamp() / clearstamp() / clearstamps()
• begin_poly() / end_poly() / get_poly()

タートルの見た目

• shape() / register_shape() — TortoiseUI の \.tortoiseSprite 環境値が部分的に相当するが、コマンドではないので SVG 出力には影響しない
• shapesize() / tilt() / shearfactor() / shapetransform() / resizemode()

編集・複数タートル

• undo() / setundobuffer() / undobufferentries() — イベントソーシング設計からは実装しやすい位置にあるが、現状無い
• clone() / 複数タートル — 1 Tortoise = 1 コマンドストリーム = 1 キャンバス。同一画面を複数のタートルで描くことはできない
• degrees() / radians() — 角度単位の切り替え

イベント・画面制御

ホストアプリ（SwiftUI）側の責務なので、除外は妥当と思われるもの:

• onclick / onrelease / ondrag / onkey / onkeypress / ontimer / listen
• tracer() / update() / delay() — speed = 0（instant mode）が部分的に代替
• setworldcoordinates() / bgpic() / title() / mainloop() / bye() / exitonclick() / textinput() / numinput()

Python turtle に無い独自機能

• コマンドストリームが第一級の値 — [TortoiseCommand] が Codable、かつ 2.x でフォーマット凍結。保存・再生・テストゴールデンに使える（Sources/TortoiseCore/Documentation.docc/CommandSerialization.md）
• SVG 書き出し — Python turtle は Tk canvas の PostScript 経由しか無い
• 再生制御 — TortoisePlayer（pause / step / seek / speedOverride）と実行中コマンドの追跡
• ViewportMode.autoFit — 描画全体にビューを自動フィット
• サブフレーム補間 — コマンドの途中でタートルが歩いて見える（animationProgress）
• Sendable / strict concurrency 対応の値型、Linux 対応（Core / SVG）、SwiftUI ネイティブ

観察

コマンド語彙は「Python turtle 互換を目指した結果」ではなく、部分集合として選択されている。
write()、stamp()、undo()、shapesize()、複数タートルは Python turtle に存在するが
入っていない。この構造は、新しいコマンドの追加可否を検討する際の基準として参照できる。

使いどころ（すぐに何かをする必要は無い）

• README または DocC に「Differences from Python turtle」節を追加する際の素案
• コマンド追加を検討する PR / issue でのスコープ判断の参照
• Python turtle から移植してくる利用者向けの移行メモ

関連

• Add pen-width taper (forward(_:widthTo:) / circle(radius:extent:widthTo:)) #50（ペン幅テーパー。この調査のきっかけ）