ドキュメントの探し方

前回はこれまでの復習をした上で、ちょっとした機能を簡単に試せる＋αの機能として「対話モード」を紹介しました。

今回は、対話システムを自分で作るときに直面する問題である「ドキュメントの探し方」について考えてみたいと思います。

作りたいシステムがあるときに何から始めるか?

ある機能を持った対話システムを実装したい場合、Pythonでその機能が提供されているかどうかや、（すでに提供されていることがわかっている場合）具体的な使い方などをどうやって調べたらいいのでしょうか？

これは極めて重要な問題です! 本連載では、「日時を教えてくれる対話システム」や「くじびきをする対話システム」などを題材に、日時を扱うdatetimeモジュールをはじめ、開発に必要となるモジュールを都度、紹介してきました。

では、任意の機能を持った対話システムを自分で開発する場合にはどうしたらよいのでしょうか。当然ながら、必要なモジュールは自分で探す必要があります。しかし、プログラミングを始めて間もない方の多くは、どうやって調べたらいいかわからないのではないでしょうか？

そこで今回は、「カレンダーを表示する対話システム」の開発を想定し、カレンダー機能の実装方法を調べていくプロセスを紹介したいと思います。

「カレンダーを表示する対話システム」は、「カレンダーを表示して」と言う（入力する）と、文字列で以下のようにカレンダー表示を返してくれるものとします。

ユーザー: カレンダーを表示して
システム: カレンダーを表示します
    January 2020
Mo Tu We Th Fr Sa Su
       1  2  3  4  5
 6  7  8  9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30 31

このシステムを実装するために、「カレンダーの内容を取得する方法」を調べたいと思います。なお、今回紹介する調べ方はあくまで一例ですので、参考にした上でぜひ皆さんなりの方法を確立してください!

検索サイトで関連キーワードを知る

この手の問題に取り組む際、障壁となるのは、知りたい事柄に関連するキーワードを知らないことです。もしPythonにカレンダーに関するモジュールがあることを知っていて、そのモジュール名がわかっているならば、初めからその名前をキーワードに公式ドキュメントを検索すればよいのです。しかし、通常はPythonにカレンダーに関するモジュールがあるかどうかもわからないでしょう。

そこで、まずは検索サイトを使って、カレンダーに関連するPythonの情報を手に入れましょう。今回は、Googleを利用して「Python カレンダー」というキーワードで検索してみます。

「Python カレンダー」というキーワードで検索した結果

検索結果を確認すると、「標準ライブラリcalendarモジュール」という記述が目につきます。ここから、「Pythonの標準ライブラリのなかに『calendar』というモジュールがあり、それを使えそうだ」と推測できます。

それではこの「calendar」というモジュールについてより詳しく知るために、Pythonの公式ドキュメントを調べてみましょう!

公式ドキュメントを調べる

Pythonは詳細なドキュメントをバージョンごとに公開しており、ドキュメント一覧は公式サイトから確認できます。このドキュメントのなかでも、Python初心者がよく参照することになるのは次の3つです。

これらのなかから、今回は「ライブラリリファレンス」に注目してみましょう。

ライブラリリファンレスのページでは、Pythonが標準ライブラリとして提供しているモジュールをはじめとしたコンポーネントについて説明されています。今回のように標準ライブラリのモジュールを調べる際は、まずライブラリリファレンスを参照することになるはずです。今後頻繁にこのページを見ることになると思うので、ブックマークしておいてもよいかもしれませんよ!

では早速、ライブラリリファレンスに移動し、先ほど検索サイトで調べた結果の「calendar」という文字列をこのページで検索してみましょう。すると、次のように「calendar」に関する箇所があることがわかります。

では、そのリンクをクリックして「calendar」に関するページに移動してみましょう。

「何やらごちゃごちゃ書いてあるな……」と、初めは面食らうかもしれません。しかし心配無用です。記述形式にさえ慣れれば、内容は難しくありません。早いうちからドキュメントを読むのに慣れておいたほうが、後々役に立つでしょう。

ページの内容をざっと見てみましょう。冒頭には次のように、このモジュールの説明があります。

使えそうな雰囲気ですね。読み進めていくと、まず以下のような「class～」から始まる部分が登場します。

これらの項目では、モジュールで定義されるクラスについて説明しています。「クラス」というのはオブジェクトを生成するためのひな型のようなものなのですが、まだ本連載では扱っていないため、ここは飛ばしてしまいましょう! 自分がわからない部分はひとまず読み飛ばして全体を眺めるのも、ドキュメントを読破する技の一つです。

次に、モジュールに定義された関数に関する項目が登場します。

順に見ていくと、「calendar.month」という関数があることに気づきます。説明には、以下のように書かれています。

「ひと月分のカレンダーを複数行の文字列で返します」とあることから、今回の用途にぴったりの内容のようです。

では早速この関数を使ってみたいところですが、使い方がわかりません。そこで改めて、関数の説明をよく見てみましょう。

初めの行には、関数の定義が書かれています。

この記述から、calendar.month関数は4つの引数をとり、1番目の引数theyearに「年」を、2番目の引数themonthに「月」を指定することがわかります。

3番目と4番目の引数は「オプション引数」という関数の機能で、関数実行時に引数が指定されない場合、「=（イコール）」の右側に指定された値がデフォルト値として使われます。例えば、「calendar.month(2020, 2)」とオプション引数に値を指定しないで関数実行した場合、その挙動は「calendar.month(2020, 2, 0, 0) を実行したのと同じ結果になります。

続く行では、関数の挙動について説明しています。

ここから、この関数は「指定したひと月分のカレンダーの文字列」を戻り値とするということがわかります。

では、関数の概略を把握したところで実際に使ってみましょう。こういうちょっとしたお試し実行をする際は、前回紹介した「対話モード」の出番です! 対話モードを起動して、関数を実行してみましょう。

>>> import calendar
>>> cal = calendar.month(2020, 2)
>>> print(cal)
   February 2020
Mo Tu We Th Fr Sa Su
                1  2
 3  4  5  6  7  8  9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29

期待したような出力が得られていますね! 後は、この関数を使ってカレンダーを表示する対話システムを作成していけばよいことになります。これまでの連載の内容を参考に、皆さん自身で対話システムを完成させてみてください。

*　*　*

以上、今回はドキュメントの探し方を紹介しました。検索サイトでは多くの情報が得られますが、なかでも公式ドキュメントであるライブラリリファレンスはその網羅性が高く、記述の正確さでは最も信頼できるものです。まずはライブラリリファレンスに慣れることで、自分が使いたい機能について手早く調べられるようになります。公式ドキュメントの一覧ページでは、ライブラリリファレンスの説明に「枕の下に置きましょう」と記述されているほどです。常に手元に置いて、時間があるときにパラパラと眺めてみてください。

著者紹介

株式会社NTTドコモ
R&Dイノベーション本部　サービスイノベーション部
阿部憲幸

2015年京都大学大学院理学研究科数学・数理解析専攻修了。 同年、NECに入社。 2016年から国立研究開発法人情報通信研究機構出向。 2018年より現職。 自然言語処理、特に対話システムの研究開発に従事。 毎日話したくなるAIを夢見て日夜コーディングに励む。
GitHub：https://github.com/noriyukipy