Table of Contents(目次)
Pythonプロジェクト全体にDocstringを追加する方法
これまで作ってきたフォーチュンクッキーのプロジェクトにDocstringを追加してみましょう。モジュールや関数の目的を記述します。
モジュールに関するDocstring（モジュールDocstring）は、ファイルの先頭に記述します。
# fortune.py
'''
フォーチュンクッキーアプリのメインプログラム。
言語選択とメッセージ表示の流れを制御します。
'''
import random
import manager.language_manager as lang_manager
def main():
'''フォーチュンクッキーアプリのメイン処理を実行します。
言語選択を行い、ユーザーの選択に応じてランダムな
フォーチュンメッセージを表示します。
フロー概要:
1. ユーザーに言語（日本語 / 英語）の選択を促す。
2. 対応する言語モジュールからメッセージとおみくじ文を取得。
3. 「クッキーを開きますか？」の質問に対して、
「y」と答えた場合のみおみくじ結果を表示。
Raises:
KeyError: 言語モジュール内の `MESSAGES` 辞書に
必要なキーが存在しない場合に発生。
Exception: 想定外のエラーが発生した場合に発生。
'''
try:
# 言語を選択
lang_code = input('言語を選んでください (jp/en): ')
# 言語コードに対応したモジュールが返される
lang_module = lang_manager.get_language_module(lang_code)
messages = lang_module.MESSAGES
fortunes = lang_module.FORTUNES
# ~~~ 以下、略 ~~~ #
# manager/language_manager.py
'''
メッセージを言語ごとに管理するモジュール。
このモジュールは、指定された言語コード（例: 'jp', 'en'）に基づいて
対応するメッセージモジュールを動的にインポートし、返します。
'''
import sys
def get_language_module(lang_code):
'''指定された言語コードに応じて対応するメッセージモジュールを返します。
与えられた言語コード (`lang_code`) に基づいて、
対応する言語モジュール（`message.language_en` または `message.language_jp`）を
動的にインポートします。
対応していない言語コードが指定された場合は、
デフォルトとして日本語モジュールを返します。
Args:
lang_code (str): 言語コード。'en' または 'jp' を指定します。
Returns:
module: 指定された言語コードに対応するモジュールオブジェクト。
Raises:
SystemExit: メッセージモジュールのインポートに失敗した場合に、異常終了を示すために送出されます。
'''
try:
if lang_code == 'en':
from message import language_en
return language_en
elif lang_code == 'jp':
from message import language_jp
return language_jp
else:
print('対応していない言語コードです。日本語を使用します。')
from message import language_jp
return language_jp
except ImportError as e:
print('ImportError: 必要なメッセージモジュールが見つかりません。')
print('詳しい情報:', e)
print('プログラムを終了します')
sys.exit(1) # 非ゼロで終了（エラーを示す）
# ~~~ 以下、略 ~~~ #
# message/language_en.py
'''
英語のメッセージを管理するモジュール。
このモジュールでは、フォーチュンクッキーアプリで使用する
英語のメッセージとおみくじ文（運勢）を定義します。
'''
# MESSAGES はアプリ内で使う文言をdictでまとめたもの:
MESSAGES = {
'app_title': 'Fortune Cookie', # アプリのタイトル表示に使う文字列
'prompt_open': 'Would you like to open a cookie? (y/n): ', # ユーザーに操作を促すプロンプト
'fortune_prefix': 'Your fortune for today is:', # 運勢表示の前につける接頭文
'goodbye': 'See you tomorrow with more luck!' # プログラム終了時の挨拶
}
# FORTUNES はランダムに表示する運勢のlist
FORTUNES = [
'Great Fortune! A wonderful day awaits you.',
'Fair Fortune. Keep steady progress.',
'Little Fortune. Stay patient and try again.',
'Bad Fortune... but tomorrow is another chance.'
]
# message/language_jp.py
'''
日本語のメッセージを管理するモジュール。
このモジュールでは、フォーチュンクッキーアプリで使用する
日本語のメッセージとおみくじ文（運勢）を定義します。
'''
# MESSAGES はアプリ内で使う文言をdictでまとめたもの
MESSAGES = {
'app_title': 'フォーチュンクッキー', # アプリのタイトル表示に使う文字列
'prompt_open': 'クッキーを開きますか？ (y/n): ', # ユーザーに操作を促すプロンプト
'fortune_prefix': 'あなたの今日の運勢は：', # 運勢表示の前につける接頭文
'goodbye': 'また明日も幸運を！', # プログラム終了時の挨拶
}
# FORTUNES はランダムに表示する運勢のlist
FORTUNES = [
'大吉！最高の一日になりそうです！',
'中吉。ちょっとした幸運が訪れるでしょう。',
'小吉。小さな努力が実を結びます。',
'凶...でも心配しすぎないでください。'
]
このように、プロジェクト全体にDocstringを記述しておくことで、チーム開発や引き継ぎ時にも大いに役立ちます。 「どんな関数やクラスがあるのか」「何をするものなのか」が一覧できるため、保守性と可読性が大幅に向上します。
Docstringの確認方法とhelp()の活用
help()を使ったDocstringの読み方
次のように各モジュールを読み込み、help()で内容を確認してみましょう。
fortune.pyのif __name__ == '__main__':ブロック内に次のコードを記述し、情報を確認してみましょう。
if __name__ == '__main__':
# fortuneモジュール
import sys
help(sys.modules['__main__'])
# language_managerモジュール
from manager import language_manager
help(language_manager)
# language_enモジュール
from message import language_en
help(language_en)
fortuneモジュール(現在、'__main__'として実行中のスクリプト)のhelp()を見るには、sys.modules['__main__']を使います。
help()で取得できるDocstringの実例
fortuneの結果：
Help on module __main__:
NAME
__main__
DESCRIPTION
フォーチュンクッキーアプリのメインプログラム。
言語選択とメッセージ表示の流れを制御します。
FUNCTIONS
main()
フォーチュンクッキーアプリのメイン処理を実行します。
言語選択を行い、ユーザーの選択に応じてランダムな
フォーチュンメッセージを表示します。
フロー概要:
1. ユーザーに言語（日本語 / 英語）の選択を促す。
2. 対応する言語モジュールからメッセージとおみくじ文を取得。
3. 「クッキーを開きますか？」の質問に対して、
「y」と答えた場合のみおみくじ結果を表示。
Raises:
KeyError: 言語モジュール内の `MESSAGES` 辞書に
必要なキーが存在しない場合に発生。
Exception: 想定外のエラーが発生した場合に発生。
FILE
c:\users\xxx\documents\python101\fortune_cookie\fortune.py
manager.language_managerの結果：
Help on module manager.language_manager in manager:
NAME
manager.language_manager - メッセージを言語ごとに管理するモジュール。
DESCRIPTION
このモジュールは、指定された言語コード（例: 'jp', 'en'）に基づいて
対応するメッセージモジュールを動的にインポートし、返します。
FUNCTIONS
get_language_module(lang_code)
指定された言語コードに応じて対応するメッセージモジュールを返します。
与えられた言語コード (`lang_code`) に基づいて、
対応する言語モジュール（`message.language_en` または `message.language_jp`）を
動的にインポートします。
対応していない言語コードが指定された場合は、
デフォルトとして日本語モジュールを返します。
Args:
lang_code (str): 言語コード。'en' または 'jp' を指定します。
Returns:
module: 指定された言語コードに対応するモジュールオブジェクト。
Raises:
SystemExit: メッセージモジュールのインポートに失敗した場合に、異常終了を示すために送出されます。
FILE
c:\users\xxx\documents\python101\fortune_cookie\manager\language_manager.py
message.language_enの結果：
Help on module message.language_en in message:
NAME
message.language_en - 英語のメッセージを管理するモジュール。
DESCRIPTION
このモジュールでは、フォーチュンクッキーアプリで使用する
英語のメッセージとおみくじ文（運勢）を定義します。
DATA
FORTUNES = ['Great Fortune! A wonderful day awaits you.', 'Fair Fortun...
MESSAGES = {'app_title': 'Fortune Cookie', 'fortune_prefix': 'Your for...
FILE
c:\users\xxx\documents\python101\fortune_cookie\message\language_en.py
