質問: ### 前提・実現したいこと 現在、「ゲームを作りながら楽しく学べる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でのコメントやメソッドの説明時の慣習だったりするのでしょうか? それとも、規約などがあったりするのでしょうか? よろしくお願いします。
回答: ``` 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関数などでは書くべきではありません。 では、 `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 は規約、文法の規定があります。 * * * *