モジュール `docutils.frontend`¶

モジュール docutils.frontend について記す。ここにはコマンドライン処理クラス、構成ファイル読み込みクラス、およびそれらを援助するデータクラスと補助関数が実装されている。

クラス図 ¶

モジュール内で定義されている例外クラスを除いたクラス図を示す。Python 標準のクラスおよび説明済みのクラスはグレーアウトで表し、例えば例外クラスのような、本筋とは外れているクラスは省いている。

classDiagram %% 名前空間修飾ができない %% ラベルを association end に与えられない direction BT Option --|> optparseOption ConfigParser --|> configparserRawConfigParser OptionParser --> Option: option_class OptionParser --> ConfigParser: creates OptionParser --|> optparseOptionParser OptionParser --|> SettingsSpec OptionParser --> Values: creates Values --|> optparseValues class Option{ #list ATTRS +process(...) } class ConfigParser{ +read(...) } class Values{ +update(dict, OptionParser) +copy() } class SettingsSpec{ +tuple settings_spec$ +dict settings_defaults$ +dict settings_default_overrides$ +tuple relative_path_settings$ +str config_section$ +tuple config_section_dependencies$ } class OptionParser{ +tuple settings_spec$ +dict settings_defaults$ +dict settings_default_overrides$ +get_standard_config_files() +get_standard_config_settings() +get_config_file_settings(file) }

Docutils で Python 標準のクラスを継承しているモジュールはこれくらいしかない。

クラス `Values`¶

Python 標準の optparse.Values から派生したクラス。目的は、リスト属性を更新するときに、元のものを置き換えるのではなく、元のリストに追加するように振る舞いを変えることらしい。

メソッド update でそれを実現している。両者で共通するキーがあれば、それらを採用しないように項目を操作している。
謎のメンバーデータ self.record_dependencies がある。これはクラス docutils.utils.DependencyList の解読をやってからにしたい。

クラス `Option`¶

Python 標準の optparse.Option から派生したクラス。目的は validator と overrides というオプションを追加すること。

メソッド process を上書きして、それらの属性を受け入れるようにしてある。

クラス `OptionParser`¶

Python 標準の optparse.OptionParser と基礎クラス群で調べた SettingsSpec の両方を継承したクラス。 Docutils がコマンドライン解析をするのに用いる。

クラス `ConfigParser`¶

Python 標準の configparser.RawConfigParser を継承したクラス。メソッド read および optionxform は上書きで、メソッド handle_old_config, validate_settings, get_section はこの派生クラスに固有のもの。

メソッド read に至ってはシグニチャーをも上書きしている。引数に OptionParser オブジェクトを受け取るように改造してある。これがメソッド validate_settings に渡り、オプション値の妥当性確認に機能する。
メソッド optionxform はたいへん分かりやすい上書きで、いわばオプション文字列の正規化をする。オプション文字列内にあるアルファベットは小文字に揃え、マイナス記号はアンダースコアに揃えるだけだ。
メソッド get_section はなぜか標準にない機能なので、仕方なしに実装したということではないだろうか。
唯一「？」なのはメソッド handle_old_config だ。これは構成ファイルに options というセクションがある場合に、メソッド read から呼び出される。

処理内容は警告を表示して general というセクションに置き換えるというようなものらしい。想像するに Docutils の構成ファイルの仕様が過去のある時点で変更があって、それを救うために提供されているメソッドということなのかもしれない。

関数 ¶

関数 validate_xxxx 系は、外部から受け取った設定値を可能な限り「正規化」して返し、どうしてもダメならば例外を送出するという方針で一貫している。
関数 store_multiple は不明。コマンドラインオプション --no-source-link が指定されたときに機能するらしい。
関数 read_config_file はコマンドラインオプション --config が指定されている場合、同時に指定さている文字列を構成ファイルのパスとみなして読み込む処理をする。
関数 make_paths_absolute および make_one_path_absolute は相対パスを絶対パスに変換する。 Python 標準の os.path.abspath と os.path.join を利用している。
関数 filter_settings_spec はある設定値のコレクションを操作する。条件を与えて値を取り除いたり置き換えたりする、フィルターのような働きをする。限定された状況で利用する関数と見られる。

感想 ¶

ちょっとしたコマンドラインベースのプログラムを書くときにいつも考えるのは、コマンドライン引数の処理と構成ファイルの処理をどう上手く同居させるかということだ。ここで見てきた設計を丁寧に分析すれば、今後活きていくはずだ。
個人的には optparse は全く利用せずに argparse でコマンドライン解析をするので、ここで用いられている技法を自作コードに採り入れるのは、わりと頭を使わねばならない。
ConfigParser は旧形式の構成ファイルの変換と、オプション値の妥当性チェックという役割が特徴だというのならば、自分で何かプログラムを書くときには Python 標準のクラスをそのまま利用して十分だ。