pygameソース内のコメントの->の意味は？

Question

###前提・実現したいこと
現在、「ゲームを作りながら楽しく学べるPythonプログラミング」という本で
pygameを使って学習しています。

例として円を描画するcircle()メソッドがあるのですが、IDEで定義を見ると
以下のように書かれています。

def circle(Surface, color, pos, radius, width=0): # real signature unknown; restored from __doc__
    """
    circle(Surface, color, pos, radius, width=0) -> Rect
    draw a circle around a point
    """
    pass

"""に囲まれている部分は、コメントでメソッドの説明だと思うのですが
「-> Rect」
の部分の意味がはっきりと分かりません。

おそらく、返り値の種類などを示しているのではと思うのですが。
この書き方は、pythonでのコメントやメソッドの説明時の慣習だったりするのでしょうか？
それとも、規約などがあったりするのでしょうか？

よろしくお願いします。

Answer 1

    circle(Surface, color, pos, radius, width=0) -> Rect

このように 関数シグネチャ -> 返すもの 形式でdocstringを提供するのは、pythonのC実装関数（主に組み込み関数等）で関数のヘルプドキュメントを提供するときの書き方です。規約は見つけられませんでした（知ってる方いたら教えてください）ので、おそらく慣習ということになります。

例えばstrのdocstringを見ると以下のように表示されます。

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str

これはPython本体での例ですが、pygameなどのC実装された関数を提供するライブラリでは、この記法で表示するようにdocstringを合わせていると思います。

---

以下、オマケ情報です。

Pythonの関数、メソッドは常にこのようにdocstringを書くのが正しいかというと、C実装ではないPure Python関数などでは書くべきではありません。
https://www.python.org/dev/peps/pep-0257/ では、 The one-line docstring should NOT be a "signature" reiterating the function/method parameters (which can be obtained by introspection) という説明があり、書くべきでは無いとされています。

---

他の方が書かれているように、Pure Pythonの関数宣言に型情報を書けるようになったのが、型アノテーション、型ヒント、type hintsと呼ばれるものです。これはpygameのdocstringとは別ですが、これによって、Pure Pythonの世界で ->
の記法を文法化して、コードの一部として書けるようになりました。（一次情報が見つからなかったので推測ですが、CPython関数で -> のように慣習(?)で書かれていた記法の影響を受けているんじゃないかなあ。）

初めは、文法だけがPython3で導入され、Python 3.5ではtype hintsが正式に導入されました。以下のように書けます。

def get_something(age:int) -> str:
    ...

type hints は規約、文法の規定があります。

• https://docs.python.org/ja/3/library/typing.html
• https://www.python.org/dev/peps/pep-0483/
• https://www.python.org/dev/peps/pep-0484/
• https://www.python.org/dev/peps/pep-3107/

Answer 2

Pythonは動的型付け言語です。
たまに勘違いする人がいるのですが、型自体は確かに存在します。

コーディングをする際、型を明示したいときに、型ヒントが用いられます。
こちらのページが非常に参考になります。

def greeting(name: str) -> str:
   return 'Hello ' + name

このように、引数の型と戻り値の型を明示することが出来るのです。
(使い方を間違えてもエラーは出ませんが、IDEが警告を出すことはあります。)

この型ヒントをベースに、戻り値の型をコメントしているのでしょう。

追記
型ヒントは便利ですが、あんまり多用するとPythonらしい型の簡潔さを失います。
ほどほどに使うのが良いでしょうね。

Answer 3

pygameのオブジェクトの意味だと思います。rectangleの略だと思います。

参考
http://westplain.sakuraweb.com/translate/pygame/Rect.cgi

Comments

[palm-t]

回答ありがとうございます。
ということはpygameを作った人がこういう書き方をしているだけで
->が返り値を示す規約などは特にないのですね。