Pythonでファイル操作の取り扱い記載場所（公式ドキュメントの歩き方）

私は、Pythonがメインのプログラミング言語です。
とはいえ、まだ未熟なので、調べながら書きます。

GoogleでPythonの内容を検索すると、日本語だと、Qiitaやはてなブログなど出てくるのですが、どうしても断片的だったり、情報が曖昧で、モヤモヤすることが多いです。

ちゃんと公式ドキュメントで調べるようにしているのですが、例えば、ファイルの取り扱いはなかなかドキュメントの場所を見つけにくかったりします。

なので、自分の辿り方をまとめました。
Pythonの関数の検索に困っている方の参考になればと。

何に困るか

今回各きっかけとなったのは、ファイルオブジェクトの扱い方です。
基本的には覚えているのですが、ファイルをopenした後、readしようかreadlineしようか、readlinesしようかなと思った時に、戻り値を忘れていることが時折あります。
その際に、どこに書いているか、分からなくなることあります（自分だけかな？）

手っ取り早く知りたい方

チュートリアルに記載があります。

docs.python.org

詳細なドキュメントを見つける

今回はPython3（2019.03.17時点ではPython3.7.3）のドキュメントを使います。
知りたい（思い出したい）のは、openして、ファイル内容を読み込む際の挙動を知りたいとします。
今回は日本語ドキュメントです。

公式ドキュメントを開く

公式ドキュメントは以下です。

docs.python.org

右上の「クイック検索」でopenと入力

検索結果は以下となりました。

今回必要なのは組み込み関数なので、(Python の関数, in 組み込み関数)のopenを押す。

open

docs.python.org

結局はここが大切なのですが、説明は読みましょう。
後半部分に以下の記載があります。

open() 関数が返す file object の型はモードに依存します。 open() をファイルをテキストモード ('w', 'r', 'wt', 'rt', など) で開くのに使ったときは io.TextIOBase (特に io.TextIOWrapper) のサブクラスを返します。

戻り値はio.TextIOWrapperということなので、リンクへ飛ぶ。

TextIOWrapper

ここには、特に関数が書いておらず、

BufferedIOBase バイナリストリーム上のバッファ付きテキストストリーム。 TextIOBase を継承します。

と書いているので、TextIOBaseへ飛ぶ。

TextIOBase

docs.python.org

TextIOBase には、

read(size=-1)
最大 size 文字をストリームから読み込み、一つの str にして返します。 size が負の値または None ならば、 EOF まで読みます。

readline(size=-1)
改行または EOF まで読み込み、一つの str を返します。ストリームが既に EOF に到達している場合、空文字列が返されます。

size が指定された場合、最大 size 文字が読み込まれます。

があるので、見つけました。
ただ、readlinesもあったなと思い、クラスの記載を読むと

IOBase から継承した属性とメソッドに加えて、 TextIOBase は以下のデータ属性とメソッドを提供しています:

なので、IOBaseへ飛ぶ。

IOBase

docs.python.org

readlines(hint=-1)
ストリームから行のリストを読み込んで返します。 hint を指定することで、読み込む行数を制御できます。もし読み込んだすべての行のサイズ (バイト数、もしくは文字数) が hint の値を超えた場合、読み込みをそこで終了します。

ただし、 file.readlines() を呼びださなくても for line in file: ... のように file オブジェクトを直接イテレートすることができます。

ということで見つけました。
仕方ないとはいえ、長い...

ここまで読むとPythonのテキストオブジェクトの仕組みも、改めてわかってきますねー。

最後に

ドキュメントがわかりにくくて困るなーと思って、改めて書いたのですが、
単純にちゃんと公式ドキュメントを読め、ということに尽きますね。

ただ、プログラミング初学者には、わかりにくい箇所かもしれないですね。
ということで、備忘として書きました。