"configparser" --- 設定ファイルのパーサー
*****************************************

**ソースコード:** Lib/configparser.py

======================================================================

このモジュールは、 Microsoft Windows の INI ファイルに似た構造を持った
ベーシックな設定用言語を実装した "ConfigParser" クラスを提供します。こ
のクラスを使ってユーザーが簡単にカスタマイズできる Python プログラムを
作ることができます。

注釈:

  このライブラリでは、Windowsのレジストリ用に拡張された INI 文法はサポ
  ート *していません* 。

参考:

  "shlex" モジュール
     アプリケーション設定ファイルのフォーマットとして使える、Unix シェ
     ルに似たミニ言語の作成を支援します。

  "json" モジュール
     json モジュールは、同じ目的に利用できる JavaScript の文法のサブセ
     ットを実装しています。


クイックスタート
================

次のような、非常に簡単な設定ファイルを例に考えましょう:

   [DEFAULT]
   ServerAliveInterval = 45
   Compression = yes
   CompressionLevel = 9
   ForwardX11 = yes

   [bitbucket.org]
   User = hg

   [topsecret.server.com]
   Port = 50022
   ForwardX11 = no

INI ファイルの構造は 下のセクション で解説します。 基本的に、ファイル
は複数のセクションからなり、各セクションは複数のキーと値を持ちます。
"configparser" のクラス群はそれらのファイルを読み書きできます。 まずは
上のような設定ファイルをプログラムから作成してみましょう。

   >>> import configparser
   >>> config = configparser.ConfigParser()
   >>> config['DEFAULT'] = {'ServerAliveInterval': '45',
   ...                      'Compression': 'yes',
   ...                      'CompressionLevel': '9'}
   >>> config['bitbucket.org'] = {}
   >>> config['bitbucket.org']['User'] = 'hg'
   >>> config['topsecret.server.com'] = {}
   >>> topsecret = config['topsecret.server.com']
   >>> topsecret['Port'] = '50022'     # mutates the parser
   >>> topsecret['ForwardX11'] = 'no'  # same here
   >>> config['DEFAULT']['ForwardX11'] = 'yes'
   >>> with open('example.ini', 'w') as configfile:
   ...   config.write(configfile)
   ...

この例でわかるように、config parser は辞書のように扱うことができます。
辞書との違いは 後に 説明しますが、このインターフェイスは辞書に対して期
待するのととても近い動作をします。

これで設定ファイルを作成して保存できました。次はこれを読み込み直して、
中のデータを取り出してみましょう。

   >>> config = configparser.ConfigParser()
   >>> config.sections()
   []
   >>> config.read('example.ini')
   ['example.ini']
   >>> config.sections()
   ['bitbucket.org', 'topsecret.server.com']
   >>> 'bitbucket.org' in config
   True
   >>> 'bytebong.com' in config
   False
   >>> config['bitbucket.org']['User']
   'hg'
   >>> config['DEFAULT']['Compression']
   'yes'
   >>> topsecret = config['topsecret.server.com']
   >>> topsecret['ForwardX11']
   'no'
   >>> topsecret['Port']
   '50022'
   >>> for key in config['bitbucket.org']:  
   ...     print(key)
   user
   compressionlevel
   serveraliveinterval
   compression
   forwardx11
   >>> config['bitbucket.org']['ForwardX11']
   'yes'

上の例からわかるように、API はとても直感的です。唯一の魔術は、
"DEFAULT" セクションが他の全てのセクションのためのデフォルト値を提供し
ていることです [1]。 また、セクション内の各キーは大文字小文字を区別せ
ず、全て小文字で保存されていることにも注意してください [1]。


サポートされるデータ型
======================

Config parser は値のデータ型について何も推論せず、常に文字列のまま内部
に保存します。他のデータ型が必要な場合は自分で変換する必要があります:

   >>> int(topsecret['Port'])
   50022
   >>> float(topsecret['CompressionLevel'])
   9.0

このタスクはとても一般的なため、設定パーサーでは整数、浮動小数点数、真
偽値を扱うための手頃なゲッターメソッドが提供されています。真偽値の扱い
は一筋縄ではいきません。文字列を "bool()" に渡しても、 "bool('False')"
が "True" になってしまいます。そこで config parser は "getboolean()"
を提供しています。このメソッドは大文字小文字を区別せず、
"'yes'"/"'no'"、"'on'"/"'off'"、"'true'"/"'false'"、"'1'"/"'0'" を真偽
値として認識します [1]。例えば:

   >>> topsecret.getboolean('ForwardX11')
   False
   >>> config['bitbucket.org'].getboolean('ForwardX11')
   True
   >>> config.getboolean('bitbucket.org', 'Compression')
   True

config parser では、 "getboolean()" 以外に "getint()" と "getfloat()"
メソッドも提供されています。独自のコンバーターの登録、提供されたメソッ
ドのカスタマイズもできます。 [1]


代替値
======

辞書と同じように、セクションの "get()" メソッドは代替値を提供していま
す:

   >>> topsecret.get('Port')
   '50022'
   >>> topsecret.get('CompressionLevel')
   '9'
   >>> topsecret.get('Cipher')
   >>> topsecret.get('Cipher', '3des-cbc')
   '3des-cbc'

デフォルト値は代替値よりも優先されることに注意してください。例えば上の
例では、"'CompressionLevel'" キーは "'DEFAULT'" セクションにしか存在し
ません。その値を "'topsecret.server.com'" から取得しようとした場合、代
替値を指定しても常にデフォルト値を返します:

   >>> topsecret.get('CompressionLevel', '3')
   '9'

もう一つ注意すべき点は、パーサーレベルの (訳注: ConfigParserクラスの)
"get()" メソッドは、後方互換性のために、カスタムのより複雑なインターフ
ェースを提供します。 このメソッドを使用する際には、フォールバック値は
キーワード専用引数 "fallback" を介して提供されます:

   >>> config.get('bitbucket.org', 'monster',
   ...            fallback='No such things as monsters')
   'No such things as monsters'

同様の "fallback" 引数を、"getint()" 、 "getfloat()" と "getboolean()"
メソッドでも使えます。例えば:

   >>> 'BatchMode' in topsecret
   False
   >>> topsecret.getboolean('BatchMode', fallback=True)
   True
   >>> config['DEFAULT']['BatchMode'] = 'no'
   >>> topsecret.getboolean('BatchMode', fallback=True)
   False


サポートするINI ファイルの構造
==============================

設定ファイルは複数のセクションから構成されます。セクションは、
"[section]" ヘッダに続いた、特定の文字列(デフォルトでは "=" または ":"
[1] )で区切られたキーと値のエントリです。デフォルトでは、セクション名
は大文字と小文字を区別しますが、キーはそうではありません [1]。キーと値
、それぞれの先頭と末尾の空白は取り除かれます。値は省略することができ、
その際でも、キーと値の区切り文字は残しておけます。値はまた、値の先頭の
行より深くインデントされていれば、複数の行にまたがっても構いません。パ
ーサーのモードによって、空白行は、複数行からなる値の一部として扱われる
か、無視されます。

設定ファイルには先頭に特定の文字 (デフォルトでは "#" および ";" [1])
をつけてコメントをつけることができます。コメントは、他の内容がない行に
置くことができ、インデントされていても構いません。[1]

例えば:

   [Simple Values]
   key=value
   spaces in keys=allowed
   spaces in values=allowed as well
   spaces around the delimiter = obviously
   you can also use : to delimit keys from values

   [All Values Are Strings]
   values like this: 1000000
   or this: 3.14159265359
   are they treated as numbers? : no
   integers, floats and booleans are held as: strings
   can use the API to get converted values directly: true

   [Multiline Values]
   chorus: I'm a lumberjack, and I'm okay
       I sleep all night and I work all day

   [No Values]
   key_without_value
   empty string value here =

   [You can use comments]
   # like this
   ; or this

   # By default only in an empty line.
   # Inline comments can be harmful because they prevent users
   # from using the delimiting characters as parts of values.
   # That being said, this can be customized.

       [Sections Can Be Indented]
           can_values_be_as_well = True
           does_that_mean_anything_special = False
           purpose = formatting for readability
           multiline_values = are
               handled just fine as
               long as they are indented
               deeper than the first line
               of a value
           # Did I mention we can indent comments, too?


値の補間
========

コア機能に加えて、 "ConfigParser" は補間(interpolation, 内挿とも)をサ
ポートします。これは "get()" コールが値を返す前に、その値に対して前処
理を行えることを意味します。

class configparser.BasicInterpolation

   "ConfigParser" が使用するデフォルト実装です。値に、同じセクションか
   特別なデフォルトセクション中 [1] の他の値を参照するフォーマット文字
   列を含めることができます。追加のデフォルト値を初期化時に提供できま
   す。

   例えば:

      [Paths]
      home_dir: /Users
      my_dir: %(home_dir)s/lumberjack
      my_pictures: %(my_dir)s/Pictures

      [Escape]
      gain: 80%%  # use a %% to escape the % sign (% is the only character that needs to be escaped)

   上の例では、 *interpolation* に "BasicInterpolation()" を設定した
   "ConfigParser" が "%(home_dir)s" を "home_dir" の値(このケースでは
   "/Users" )として解決しています、その結果 "%(my_dir)s" は
   "/Users/lumberjack" になります。全ての補間は必要に応じて実行される
   ため、設定ファイル中で参照の連鎖をもつキーを特定の順序で記述する必
   要はありません。

   "interpolation" に "None" を設定すれば、パーサーは単に
   "my_pictures" の値として  "%(my_dir)s/Pictures" を返し、"my_dir" の
   値として "%(home_dir)s/lumberjack" を返します。

class configparser.ExtendedInterpolation

   "zc.buildout" で使用されるような、より高度な文法を実装した補間ハン
   ドラの別の選択肢です。拡張された補間は、他のセクション中の値を示す
   のに "${section:option}" と書けます。補間は複数のレベルに及べます、
   利便性のために、もし "section:" の部分が省略されると、現在のセクシ
   ョンがデフォルト値となります(スペシャルセクション中のデフォルト値を
   使用することもできます)。

   たとえば、上記の basic interpolation で指定した設定は、extended
   interpolation を使うと下記のようになります:

      [Paths]
      home_dir: /Users
      my_dir: ${home_dir}/lumberjack
      my_pictures: ${my_dir}/Pictures

      [Escape]
      cost: $$80  # use a $$ to escape the $ sign ($ is the only character that needs to be escaped)

   他のセクションから値を持ってくることもできます:

      [Common]
      home_dir: /Users
      library_dir: /Library
      system_dir: /System
      macports_dir: /opt/local

      [Frameworks]
      Python: 3.2
      path: ${Common:system_dir}/Library/Frameworks/

      [Arthur]
      nickname: Two Sheds
      last_name: Jackson
      my_dir: ${Common:home_dir}/twosheds
      my_pictures: ${my_dir}/Pictures
      python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}


マップ型プロトコルアクセス
==========================

バージョン 3.2 で追加.

マップ型プロトコルアクセスは、カスタムオブジェクトを辞書であるかのよう
に使うための機能の総称です。 "configparser" の場合、マップ型インタフェ
ースの実装は "parser['section']['option']" 表記を使います。

とくに、"parser['section']" はパーサー内のそのセクションのデータへのプ
ロキシを返します。つまり、値はコピーされるのではなく必要に応じてオリジ
ナルのパーサーから取られます。さらに重要なことに、セクションのプロキシ
の値が変更されると、オリジナルのパーサー中の値が実際に変更されます。

"configparser" は可能な限り実際の辞書と近い振る舞いをします。マップ型
インタフェースは "MutableMapping" を矛盾なく完成します。しかし、考慮す
るべき違いがいくつかあります:

* デフォルトでは、セクション内の全てのキーは大文字小文字の区別なくアク
  セスできます [1]。例えば、"for option in parser["section"]" は
  "optionxform" されたオプションキー名のみを yield します。つまり小文
  字のキーがデフォルトです。同時に、キー "'a'" を含むセクションにおい
  て、どちらの式も "True" を返します:

     "a" in parser["section"]
     "A" in parser["section"]

* 全てのセクションは "DEFAULTSECT" 値を持ち、すなわちセクションで
  ".clear()" してもセクションは見た目上空になりません。これは、デフォ
  ルト値は (技術的にはそこにないので) セクションから削除できないためで
  す。デフォルト値が上書きされた場合、それが削除されるとデフォルト値が
  再び見えるようになります。デフォルト値を削除しようとすると
  "KeyError" が発生します。

* "DEFAULTSECT" はパーサーから取り除けません:

  * 削除しようとすると "ValueError" が発生します。

  * "parser.clear()" はこれをそのまま残し、

  * "parser.popitem()" がこれを返すことはありません。

* "parser.get(section, option, **kwargs)" - 第二引数は代替値では *あり
  ません*。ただし、セクションごとの "get()" メソッドはマップ型プロトコ
  ルと旧式の configparser API の両方に互換です。

* "parser.items()" はマップ型プロトコルと互換です (DEFAULTSECT を含む
  *section_name*, *section_proxy* 対のリストを返します)。ただし、この
  メソッドは "parser.items(section, raw, vars)" のようにして引数を与え
  ることでも呼び出せます。後者の呼び出しは指定された "section" の
  *option*, *value* 対のリストを、("raw=True" が与えられない限り) 全て
  の補間を展開して返します。

マップ型プロトコルは、既存のレガシーな API の上に実装されているので、
オリジナルのインタフェースを上書きする派生クラスもまたは期待どおりには
たらきます。


パーサーの振る舞いをカスタマイズする
====================================

INI フォーマットの変種は、それを使うアプリケーションの数と同じくらい多
く存在します。 "configparser" は、可能な限り広い範囲の INI スタイルを
集めた集合をサポートするために、非常に役立ちます。デフォルトの機能は主
に歴史的背景によって決められたので、機能によってはカスタマイズしてお使
いください。

特定の設定パーサーのはたらきを変える最も一般的な方法は "__init__()" オ
プションを使うことです:

* *defaults*, デフォルト値: "None"

  このオプションは最初に "DEFAULT" セクションに加えられるキー-値の対の
  辞書を受け付けます。

  ヒント: 特定のセクションにデフォルト値を指定したいなら、実際のファイ
  ルを読み込む前に "read_dict()" を使ってください。

* *dict_type*, デフォルト値: "dict"

  このオプションはマップ型プロトコルの振る舞い方や書き込まれる設定ファ
  イルの見た目に大きく影響します。標準の辞書では、全てのセクションはパ
  ーサーに加えられた順に並びます。同じことがセクション内のオプションに
  も言えます。

  セクションとオプションをライトバック時にソートするためなどに、別の辞
  書型も使えます。

  注意: 一度の操作でキー-値の対を複数追加する方法もあります。そのよう
  な操作に普通の辞書を使うと、キーの並びは挿入順になります。例えば:

     >>> parser = configparser.ConfigParser()
     >>> parser.read_dict({'section1': {'key1': 'value1',
     ...                                'key2': 'value2',
     ...                                'key3': 'value3'},
     ...                   'section2': {'keyA': 'valueA',
     ...                                'keyB': 'valueB',
     ...                                'keyC': 'valueC'},
     ...                   'section3': {'foo': 'x',
     ...                                'bar': 'y',
     ...                                'baz': 'z'}
     ... })
     >>> parser.sections()
     ['section1', 'section2', 'section3']
     >>> [option for option in parser['section3']]
     ['foo', 'bar', 'baz']

* *allow_no_value*, デフォルト値: "False"

  一部の設定ファイルには値のない設定項目がありますが、それ以外は
  "ConfigParser" がサポートする文法に従います。コンストラクタの
  *allow_no_value* 引数で、そのような値を許可することができます。

     >>> import configparser

     >>> sample_config = """
     ... [mysqld]
     ...   user = mysql
     ...   pid-file = /var/run/mysqld/mysqld.pid
     ...   skip-external-locking
     ...   old_passwords = 1
     ...   skip-bdb
     ...   # we don't need ACID today
     ...   skip-innodb
     ... """
     >>> config = configparser.ConfigParser(allow_no_value=True)
     >>> config.read_string(sample_config)

     >>> # Settings with values are treated as before:
     >>> config["mysqld"]["user"]
     'mysql'

     >>> # Settings without values provide None:
     >>> config["mysqld"]["skip-bdb"]

     >>> # Settings which aren't specified still raise an error:
     >>> config["mysqld"]["does-not-exist"]
     Traceback (most recent call last):
       ...
     KeyError: 'does-not-exist'

* *delimiters*, デフォルト値: "('=', ':')"

  デリミタはセクション内でキーを値から区切る部分文字列です。行中で最初
  に現れた区切り部分文字列がデリミタと見なされます。つまり値にはデリミ
  タを含めることができます (キーには含めることができません)。

  "ConfigParser.write()" の *space_around_delimiters* 引数も参照してく
  ださい。

* *comment_prefixes*, デフォルト値: "('#', ';')"

* *inline_comment_prefixes*, デフォルト値: "None"

  コメント接頭辞は設定ファイル中で有効なコメントの開始を示す文字列です
  。*comment_prefixes* は他の内容がない行 (インデントは自由) にのみ使
  用でき、*inline_comment_prefixes* は任意の有効な値 (例えば、セクショ
  ン名、オプション、空行も可能) の後に使えます。デフォルトではインライ
  ンコメントは無効化されていて、"'#'" と "';'" を行全体のコメントに使
  用します。

  バージョン 3.2 で変更: 以前のバージョンの "configparser" の振る舞い
  は "comment_prefixes=('#',';')" および
  "inline_comment_prefixes=(';',)" に該当します。

  設定パーサーはコメント接頭辞のエスケープをサポートしないので、
  *inline_comment_prefixes* はユーザーがコメント接頭辞として使われる文
  字を含むオプション値を指定するのを妨げる可能性があります。疑わしい場
  合には、*inline_comment_prefixes* を設定しないようにしてください。ど
  のような状況でも、複数行にわたる値で、行の先頭にコメント接頭辞文字を
  保存する唯一の方法は、次の例のように接頭辞を補間することです:

     >>> from configparser import ConfigParser, ExtendedInterpolation
     >>> parser = ConfigParser(interpolation=ExtendedInterpolation())
     >>> # the default BasicInterpolation could be used as well
     >>> parser.read_string("""
     ... [DEFAULT]
     ... hash = #
     ...
     ... [hashes]
     ... shebang =
     ...   ${hash}!/usr/bin/env python
     ...   ${hash} -*- coding: utf-8 -*-
     ...
     ... extensions =
     ...   enabled_extension
     ...   another_extension
     ...   #disabled_by_comment
     ...   yet_another_extension
     ...
     ... interpolation not necessary = if # is not at line start
     ... even in multiline values = line #1
     ...   line #2
     ...   line #3
     ... """)
     >>> print(parser['hashes']['shebang'])

     #!/usr/bin/env python
     # -*- coding: utf-8 -*-
     >>> print(parser['hashes']['extensions'])

     enabled_extension
     another_extension
     yet_another_extension
     >>> print(parser['hashes']['interpolation not necessary'])
     if # is not at line start
     >>> print(parser['hashes']['even in multiline values'])
     line #1
     line #2
     line #3

* *strict*, デフォルト値: "True"

  "True" に設定された場合、パーサーは単一のソースから ("read_file()",
  "read_string()" または "read_dict()" を使って) 読み込むときにセクシ
  ョンやオプションの重複を許さなくなります。新しいアプリケーションには
  strict なパーサーを使うことが推奨されます。

  バージョン 3.2 で変更: 以前のバージョンの "configparser" の振る舞い
  は "strict=False" に該当します。

* *empty_lines_in_values*, デフォルト値: "True"

  設定パーサーでは、キーよりもその値を深くインデントするかぎり、複数行
  にまたがる値を使えます。デフォルトのパーサーはさらにその値の間に空行
  を置けます。同時に、キーは読みやすくするため任意にインデントできます
  。結果として、設定ファイルが大きく複雑になったとき、ユーザーがファイ
  ル構造を見失いやすいです。この例をご覧ください:

     [Section]
     key = multiline
       value with a gotcha

      this = is still a part of the multiline value of 'key'

  これは特にプロポーショナルフォントを使ってファイルを編集しているユー
  ザーにとって問題になることがあります。だから、アプリケーションの値に
  空行が必要ないなら、空行を認めないべきです。これによって空行で必ずキ
  ーが分かれます。上の例では、2 つのキー、"key" および "this" が作られ
  ます。

* *default_section*, デフォルト値: "configparser.DEFAULTSECT" (すなわ
  ち: ""DEFAULT"")

  他のセクションのデフォルト値や補間目的での特別なセクションを認める慣
  行はこのライブラリの明確なコンセプトの一つで、ユーザーは複雑で宣言的
  な設定を作成できます。このセクションは通常 ""DEFAULT"" と呼ばれます
  が、任意の有効なセクション名を指すようにカスタマイズできます。典型的
  な値には ""general"" や ""common"" があります。与えられた名前はソー
  スを読み込む際にデフォルトセクションを認識するのに使われ、設定をファ
  イルに書き戻すときにも使われます。現在の値は
  "parser_instance.default_section" 属性から取り出すことができ、実行時
  (すなわちファイルを別のフォーマットに変換するとき) に変更することも
  できます。

* *interpolation*, デフォルト値: "configparser.BasicInterpolation"

  補間の振る舞いは、 *interpolation* 引数を通してカスタムハンドラを与
  えることでカスタマイズできます。 "None" 引数を使うと補間を完全に無効
  にできます。 "ExtendedInterpolation()" は、 "zc.buildout" に影響を受
  けたより高度な補間を提供します。この話題に 特化したドキュメントのセ
  クション をご覧ください。 "RawConfigParser" のデフォルト値は "None"
  です。

* *converters*, デフォルト値: 未設定

  設定パーサーは、型変換を実行するオプションの値ゲッターを提供します。
  デフォルトでは、 "getint()"、 "getfloat()"、 "getboolean()" が実装さ
  れています。他のゲッターが必要な場合、ユーザーはそれらをサブクラスで
  定義するか、辞書を渡します。辞書を渡す場合、各キーはコンバーターの名
  前で、値は当該変換を実装する呼び出し可能オブジェクトです。例えば、
  "{'decimal': decimal.Decimal}" を渡すと、パーサーオブジェクトとすべ
  てのセクションプロキシの両方に、 "getdecimal()" が追加されます。つま
  り、"parser_instance.getdecimal('section', 'key', fallback=0)" と
  "parser_instance['section'].getdecimal('key', 0)" の両方の方法で書く
  ことができます。

  コンバーターがパーサーの状態にアクセスする必要がある場合、設定パーサ
  ーサブクラスでメソッドとして実装することができます。このメソッドの名
  前が "get" から始まる場合、すべてのセクションプロキシで、辞書と互換
  性のある形式で利用できます (上記の "getdecimal()"  の例を参照)。

これらのパーサー引数のデフォルト値を上書きすれば、さらに進んだカスタマ
イズができます。デフォルトはクラスで定義されているので、派生クラスや属
性の代入で上書きできます。

ConfigParser.BOOLEAN_STATES

   デフォルトでは、 "getboolean()" を使うことで、設定パーサーは以下の
   値を "True" と見なします: "'1'", "'yes'", "'true'", "'on'" 。以下の
   値を "False" と見なします: "'0'", "'no'", "'false'", "'off'" 。文字
   列と対応するブール値のカスタム辞書を指定することでこれを上書きでき
   ます。たとえば:

      >>> custom = configparser.ConfigParser()
      >>> custom['section1'] = {'funky': 'nope'}
      >>> custom['section1'].getboolean('funky')
      Traceback (most recent call last):
      ...
      ValueError: Not a boolean: nope
      >>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
      >>> custom['section1'].getboolean('funky')
      False

   ほかの典型的なブール値ペアには "accept"/"reject" や
   "enabled"/"disabled" などがあります。

ConfigParser.optionxform(option)

   このメソッドは読み込み、取得、設定操作のたびにオプション名を変換し
   ます。デフォルトでは名前を小文字に変換します。従って設定ファイルが
   書き込まれるとき、すべてのキーは小文字になります。それがふさわしく
   なければ、このメソッドを上書きしてください。例えば:

      >>> config = """
      ... [Section1]
      ... Key = Value
      ...
      ... [Section2]
      ... AnotherKey = Value
      ... """
      >>> typical = configparser.ConfigParser()
      >>> typical.read_string(config)
      >>> list(typical['Section1'].keys())
      ['key']
      >>> list(typical['Section2'].keys())
      ['anotherkey']
      >>> custom = configparser.RawConfigParser()
      >>> custom.optionxform = lambda option: option
      >>> custom.read_string(config)
      >>> list(custom['Section1'].keys())
      ['Key']
      >>> list(custom['Section2'].keys())
      ['AnotherKey']

   注釈:

     The optionxform function transforms option names to a canonical
     form. This should be an idempotent function: if the name is
     already in canonical form, it should be returned unchanged.

ConfigParser.SECTCRE

   セクションヘッダを解析するのに使われる、コンパイルされた正規表現で
   す。デフォルトでは "[section]" が ""section"" という名前にマッチし
   ます。空白はセクション名の一部と見なされるので、"[  larch  ]" は ""
   larch  "" という名のセクションとして読み込まれます。これがふさわし
   くない場合、このメソッドを上書きしてください。例えば:

      >>> import re
      >>> config = """
      ... [Section 1]
      ... option = value
      ...
      ... [  Section 2  ]
      ... another = val
      ... """
      >>> typical = configparser.ConfigParser()
      >>> typical.read_string(config)
      >>> typical.sections()
      ['Section 1', '  Section 2  ']
      >>> custom = configparser.ConfigParser()
      >>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
      >>> custom.read_string(config)
      >>> custom.sections()
      ['Section 1', 'Section 2']

   注釈:

     ConfigParser オブジェクトはオプション行の認識に "OPTCRE" 属性も使
     いますが、これを上書きすることは推奨されません。上書きするとコン
     ストラクタオプション *allow_no_value* および *delimiters* に干渉
     します。


レガシーな API の例
===================

主に後方互換性問題の理由から、 "configparser" は "get"/"set" メソッド
を明示するレガシーな API も提供します。メソッドを以下に示すように使う
こともできますが、新しいプロジェクトではマップ型プロトコルでアクセスす
るのが望ましいです。レガシーな API は時折高度で、低レベルで、まったく
直感的ではありません。

設定ファイルを書き出す例:

   import configparser

   config = configparser.RawConfigParser()

   # Please note that using RawConfigParser's set functions, you can assign
   # non-string values to keys internally, but will receive an error when
   # attempting to write to a file or when you get it in non-raw mode. Setting
   # values using the mapping protocol or ConfigParser's set() does not allow
   # such assignments to take place.
   config.add_section('Section1')
   config.set('Section1', 'an_int', '15')
   config.set('Section1', 'a_bool', 'true')
   config.set('Section1', 'a_float', '3.1415')
   config.set('Section1', 'baz', 'fun')
   config.set('Section1', 'bar', 'Python')
   config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

   # Writing our configuration file to 'example.cfg'
   with open('example.cfg', 'w') as configfile:
       config.write(configfile)

設定ファイルを読み込む例:

   import configparser

   config = configparser.RawConfigParser()
   config.read('example.cfg')

   # getfloat() raises an exception if the value is not a float
   # getint() and getboolean() also do this for their respective types
   a_float = config.getfloat('Section1', 'a_float')
   an_int = config.getint('Section1', 'an_int')
   print(a_float + an_int)

   # Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
   # This is because we are using a RawConfigParser().
   if config.getboolean('Section1', 'a_bool'):
       print(config.get('Section1', 'foo'))

補間するには、 "ConfigParser" を使ってください:

   import configparser

   cfg = configparser.ConfigParser()
   cfg.read('example.cfg')

   # Set the optional *raw* argument of get() to True if you wish to disable
   # interpolation in a single get operation.
   print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
   print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

   # The optional *vars* argument is a dict with members that will take
   # precedence in interpolation.
   print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                          'baz': 'evil'}))

   # The optional *fallback* argument can be used to provide a fallback value
   print(cfg.get('Section1', 'foo'))
         # -> "Python is fun!"

   print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
         # -> "Python is fun!"

   print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
         # -> "No such things as monsters."

   # A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
   # but we can also use:

   print(cfg.get('Section1', 'monster', fallback=None))
         # -> None

どちらの型の ConfigParsers でもデフォルト値が利用できます。使われてい
るオプションがどこにも定義されていなければ、そのデフォルト値が補間に使
われます。

   import configparser

   # New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
   config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
   config.read('example.cfg')

   print(config.get('Section1', 'foo'))     # -> "Python is fun!"
   config.remove_option('Section1', 'bar')
   config.remove_option('Section1', 'baz')
   print(config.get('Section1', 'foo'))     # -> "Life is hard!"


ConfigParser オブジェクト
=========================

class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={})

   主要な設定パーサーです。*defaults* が与えられれば、その辞書の持つ初
   期値で初期化されます。*dict_type* が与えられれば、それがセクション
   の一覧、セクション中のオプション、およびデフォルト値の辞書オブジェ
   クトを作成するのに使われます。

   *delimiters* が与えられた場合、キーと値を分割する部分文字列の組み合
   わせとして使われます。*comment_prefixes* が与えられた場合、他の内容
   がない行のコメントに接頭する部分文字列の組み合わせとして使われます
   。コメントはインデントできます。*inline_comment_prefixes* が与えら
   れた場合、非空行のコメントに接頭する部分文字列としての組み合わせと
   して使われます。

   *strict* が "True" (デフォルト) であれば、パーサーは単一のソース (
   ファイル、文字列、辞書) 中にセクションやオプションの重複を認めず、
   "DuplicateSectionError" や "DuplicateOptionError" を送出します。
   *empty_lines_in_values* が "False" (デフォルト: "True") なら、空行
   はそれぞれオプションの終わりを示します。 *allow_no_value* が "True"
   (デフォルト: "False") なら、値のないオプションが受け付けられます。
   そのオプションの値は "None" となり、後端のデリミタを除いてシリアル
   化されます。

   *default_section* が与えられた場合、他のセクションへのデフォルト値
   や補間のためのデフォルト値を保持する特別なセクションの名前を指定し
   ます (通常は ""DEFAULT"" という名前です)。この値は実行時に
   "default_section" インスタンス属性を使って取得や変更ができます。

   補間の動作は、 *interpolation* 引数を通してカスタムハンドラを与える
   ことでカスタマイズできます。 "None" 引数を使うと補間を完全に無効に
   できます。 "ExtendedInterpolation()" は、 "zc.buildout" に影響を受
   けたより高度な補間を提供します。この件に 特化したドキュメントのセク
   ション を参照してください。

   補間に使われるすべてのオプション名は、他のオプション名参照と同様に
   、 "optionxform()" メソッドを通して渡されます。例えば、
   "optionxform()" のデフォルトの実装を使うと、値 "foo %(bar)s" と
   "foo %(BAR)s" は等しくなります。

   *converters* が与えられた場合、各キーが型コンバーターの名前を表し、
   各値が文字列から目的のデータ型への変換を実装する呼び出し可能オブジ
   ェクトです。各コンバーターは、自身の対応する "get*()" メソッドをパ
   ーサーオブジェクトとセクションプロキシで取得します。

   バージョン 3.1 で変更: デフォルトの *dict_type* は
   "collections.OrderedDict" です。

   バージョン 3.2 で変更: *allow_no_value*, *delimiters*,
   *comment_prefixes*, *strict*, *empty_lines_in_values*,
   *default_section* および *interpolation* が追加されました。

   バージョン 3.5 で変更: *converters* 引数が追加されました。

   バージョン 3.7 で変更: The *defaults* argument is read with
   "read_dict()", providing consistent behavior across the parser:
   non-string keys and values are implicitly converted to strings.

   バージョン 3.8 で変更: The default *dict_type* is "dict", since it
   now preserves insertion order.

   defaults()

      インスタンス全体で使われるデフォルト値の辞書を返します。

   sections()

      利用できるセクションのリストを返します。*default section* はリス
      トに含まれません。

   add_section(section)

      *section* という名のセクションをインスタンスに追加します。与えら
      れた名前のセクション名がすでに存在したら、
      "DuplicateSectionError" が送出されます。 *default section* 名が
      渡されたら、 "ValueError" が送出されます。セクションの名前は文字
      列でなければなりません。そうでなければ、 "TypeError" が送出され
      ます。

      バージョン 3.2 で変更: 文字列でないセクション名は "TypeError" を
      送出します。

   has_section(section)

      指名された *section* が設定中に存在するかを示します。*default
      section* は認識されません。

   options(section)

      指定された *section* 中で利用できるオプションのリストを返します
      。

   has_option(section, option)

      与えられた *section* が存在し、与えられた *option* を含む場合、
      "True" を返します。それ以外の場合には、 "False" を返します。指定
      された *section* が "None" または空文字列の場合、 DEFAULT が仮定
      されます。

   read(filenames, encoding=None)

      ファイル名の iterable を読み込んでパースしようと試みます。正常に
      パースできたファイル名のリストを返します。

      もし *filenames* が文字列か *path-like object* なら、この引数は1
      つのファイル名として扱われます。 *filenames* 中に開けないファイ
      ルがある場合、そのファイルは無視されます。この挙動は、設定ファイ
      ルが置かれる可能性のある場所(例えば、 カレントディレクトリ、ホー
      ムディレクトリ、システム全体の設定を行うディレクトリ)のイテラブ
      ルを指定して、イテラブルの中で存在する全ての設定ファイルを読むこ
      とを想定して設計されています。

      どの設定ファイルも存在しなかった場合、 "ConfigParser" のインスタ
      ンスは 空のデータセットを持ちます。初期値の設定ファイルを先に読
      み込んでおく必要があるアプリケーションでは、 オプションのファイ
      ルを読み込むために "read()" を呼ぶ前に 、まず "read_file()" を用
      いて必要なファイルを読み込んでください:

         import configparser, os

         config = configparser.ConfigParser()
         config.read_file(open('defaults.cfg'))
         config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
                     encoding='cp1250')

      バージョン 3.2 で追加: *encoding* 引数。以前は、すべてのファイル
      が "open()" のデフォルトエンコーディングを使って読まれていました
      。

      バージョン 3.6.1 で追加: *filenames* 引数が *path-like object*
      を受け入れるようになりました。

      バージョン 3.7 で追加: *filenames* 引数が "bytes" オブジェクトを
      受け入れるようになりました。

   read_file(f, source=None)

      設定データを *f* から読み込んで解析します。*f* は Unicode 文字列
      を yield するイテラブル (例えばテキストモードで開かれたファイル)
      です。

      オプションの引数 *source* は読み込まれるファイルの名前を指定しま
      す。与えられず、 *f* に "name" 属性があれば、それが *source* と
      して使われます。デフォルトは "'<???>'" です。

      バージョン 3.2 で追加: "readfp()" を置き換えます。

   read_string(string, source='<string>')

      設定データを文字列から解析します。

      オプションの引数 *source* はコンテキストにおける渡された文字列の
      名前を指定します。与えられなければ、"'<string>'" が使われます。
      これは一般にファイルシステムパスや URL にします。

      バージョン 3.2 で追加.

   read_dict(dictionary, source='<dict>')

      辞書的な "items()" メソッドを提供する任意のオブジェクトから設定
      を読み込みます。キーはセクション名で、値はそのセクションに現れる
      キーと値をもつ辞書です。使われた辞書型が順序を保存するなら、セク
      ションおよびそのキーは順に加えられます。値は自動で文字列に変換さ
      れます。

      オプションの引数 *source* はコンテキストにおける渡された辞書の名
      前を指定します。与えられなければ、"<dict>" が使われます。

      このメソッドを使ってパーサー間で状態をコピーできます。

      バージョン 3.2 で追加.

   get(section, option, *, raw=False, vars=None[, fallback])

      指名された *section* の *option* の値を取得します。*vars* が提供
      されるなら、それは辞書でなければならず、(与えられたなら) *vars*,
      *section*, *DEFAULTSECT* 内からこの順で *option* が探索されます
      。*fallback* の値として "None" を与えられます。

      *raw* が真でない時には、全ての "'%'" 置換は展開されてから返され
      ます。置換後の値はオプションと同じ順序で探されます。

      バージョン 3.2 で変更: 引数 *raw*, *vars* および *fallback* は、
      (特にマッピングプロトコルを使用するときに) ユーザーが第 3 引数を
      *fallback* フォールバックとして使おうとしないように、キーワード
      専用となりました。

   getint(section, option, *, raw=False, vars=None[, fallback])

      指定された *section* 中の *option* を整数に型強制する補助メソッ
      ドです。 *raw*, *vars* および *fallback* の説明は "get()" を参照
      してください。

   getfloat(section, option, *, raw=False, vars=None[, fallback])

      指定された *section* 中の *option* を浮動小数点数に型強制する補
      助メソッドです。 *raw*, *vars* および *fallback* の説明は
      "get()" を参照してください。

   getboolean(section, option, *, raw=False, vars=None[, fallback])

      指定された *section* 中の *option* をブール値に型強制する補助メ
      ソッドです。なお、このオプションで受け付けられる値はこのメソッド
      が "True" を返す "'1'", "'yes'", "'true'", および "'on'",と、こ
      のメソッドが "False" を返す "'0'", "'no'", "'false'", and
      "'off'" です。その他のいかなる値も "ValueError" を送出します。
      *raw*, *vars* および *fallback* の説明は "get()" を参照してくだ
      さい。

   items(raw=False, vars=None)
   items(section, raw=False, vars=None)

      *section* が与えられなければ、DEFAULTSECT を含めた
      *section_name*, *section_proxy* の対のリストを返します。

      与えられれば、与えられた *section* 中のオプションの *name*,
      *value* の対のリストを返します。オプションの引数は "get()" メソ
      ッドに与えるものと同じ意味を持ちます。

      バージョン 3.8 で変更: *vars* に現れる項目は結果に表れなくなりま
      した。以前の挙動は、実際のパーサーオプションを補間のために与えら
      れた変数と混合していました。

   set(section, option, value)

      与えられたセクションが存在すれば、与えられたオプションを指定され
      た値に設定します。そうでなければ "NoSectionError" を送出します。
      *option* および *value* は文字列でなければなりません。そうでなけ
      れば "TypeError" が送出されます。

   write(fileobject, space_around_delimiters=True)

      設定の表現を指定された *file object* に書き込みます。
      *fileobject* は (文字列を受け付ける) テキストモードで開かれてい
      なければなりません。この表現は後で "read()" を呼び出すことでパー
      スできます。 *space_around_delimiters* が真なら、キーと値の間の
      デリミタはスペースで囲まれます。

   remove_option(section, option)

      指定された *option* を指定された *section* から削除します。セク
      ションが存在しなければ、 "NoSectionError" を送出します。オプショ
      ンが存在して削除されれば、 "True" を返します。そうでなければ
      "False" を返します。

   remove_section(section)

      指定された *section* を設定から削除します。セクションが実際に存
      在すれば、"True" を返します。そうでなければ "False" を返します。

   optionxform(option)

      入力ファイルに現れた、またはクライアントコードで渡されたオプショ
      ン名 *option* を内部構造で実際に使われる形式に変換します。デフォ
      ルトの実装では *option* の小文字版を返します。派生クラスでこれを
      上書きするか、クライアントコードでインスタンス上のこの名前の属性
      を設定して、この動作に影響を与えることができます。

      このメソッドを使うためにパーサーを派生クラス化させる必要はなく、
      インスタンス上で、これを文字列引数をとって文字列を返す関数に設定
      できます。例えば、これを "str" に設定すると、オプション名に大文
      字小文字の区別をつけられます:

         cfgparser = ConfigParser()
         cfgparser.optionxform = str

      なお、設定ファイルを読み込むとき、オプション名の周りの空白は
      "optionxform()" が呼び出される前に取り除かれます。

   readfp(fp, filename=None)

      バージョン 3.2 で非推奨: 代わりに "read_file()" を使ってください
      。

      バージョン 3.2 で変更: "readfp()" は "fp.readline()" を呼び出す
      代わりに *fp* をイテレートするようになりました。

      "readfp()" をイテレーションをサポートしない引数で呼び出す既存の
      コードには、ファイル的なオブジェクトまわりのラッパーとして以下の
      ジェネレーターが使えます:

         def readline_generator(fp):
             line = fp.readline()
             while line:
                 yield line
                 line = fp.readline()

      "parser.readfp(fp)" の代わりに
      "parser.read_file(readline_generator(fp))" を使ってください。

configparser.MAX_INTERPOLATION_DEPTH

   "get()" の *raw* が偽であるときの再帰的な補間の最大の深さです。これ
   はデフォルトの *interpolation* を使うときのみ関係します。


RawConfigParser オブジェクト
============================

class configparser.RawConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT[, interpolation])

   Legacy variant of the "ConfigParser".  It has interpolation
   disabled by default and allows for non-string section names, option
   names, and values via its unsafe "add_section" and "set" methods,
   as well as the legacy "defaults=" keyword argument handling.

   バージョン 3.8 で変更: The default *dict_type* is "dict", since it
   now preserves insertion order.

   注釈:

     代わりに内部に保存する値の型を検査する "ConfigParser" を使うこと
     を検討してください。補間を望まない場合、
     "ConfigParser(interpolation=None)" を使用できます。

   add_section(section)

      インスタンスに *section* という名のセクションを追加します。与え
      られた名前のセクションがすでに存在すれば、
      "DuplicateSectionError" が送出されます。 *default section* 名が
      渡されると、 "ValueError" が送出されます。

      *section* の型は検査されないため、ユーザーは非文字列の名前付きセ
      クションを作ることができます。この振る舞いはサポートされておらず
      、内部エラーを起こす可能性があります。

   set(section, option, value)

      与えられたセクションが存在していれば、オプションを指定された値に
      設定します。セクションが存在しなければ "NoSectionError" を発生さ
      せます。 "RawConfigParser" (あるいは *raw* パラメータをセットし
      た "ConfigParser") を文字列型でない値の *内部的な* 格納場所とし
      て使うことは可能ですが、すべての機能 (置換やファイルへの出力を含
      む) がサポートされるのは文字列を値として使った場合だけです。

      ユーザーは、このメソッドを使って非文字列の値をキーに代入できます
      。この振る舞いはサポートされておらず、非rawモードでの値の取得や
      、ファイルへの書き出しを試みた際にエラーの原因となりえます。この
      ような代入を許さない  **マッピングプロトコルAPIを使用してくださ
      い**。


例外
====

exception configparser.Error

   他の全ての "configparser" 例外の基底クラスです。

exception configparser.NoSectionError

   指定したセクションが見つからなかった時に起きる例外です。

exception configparser.DuplicateSectionError

   "add_section()" がすでに存在するセクションの名前で呼び出された場合
   や、strict なパーサーで単一の入力ファイル、文字列、辞書中に同じセク
   ションが複数回現れたときに送出される例外です。

   バージョン 3.2 で追加: オプションの "source" と "lineno" が属性およ
   び "__init__()" への引数として加えられました。

exception configparser.DuplicateOptionError

   strict なパーサーで、単一の入力ファイル、文字列、辞書中に同じオプシ
   ョンが複数回現れたときに送出される例外です。これはミススペルや大文
   字小文字の区別に関係するエラー、例えば辞書の二つのキーが同じ大文字
   小文字の区別のない設定キーを表すこと、を捕捉します。

exception configparser.NoOptionError

   指定されたオプションが指定されたセクションに見つからないときに送出
   される例外です。

exception configparser.InterpolationError

   文字列の補間中に問題が起きた時に発生する例外の基底クラスです。

exception configparser.InterpolationDepthError

   繰り返しの回数が "MAX_INTERPOLATION_DEPTH" を超えたために文字列補間
   が完了しなかったときに送出される例外です。 "InterpolationError" の
   派生クラスです。

exception configparser.InterpolationMissingOptionError

   "InterpolationError" の派生クラスで、値が参照しているオプションが見
   つからない場合に発生する例外です。

exception configparser.InterpolationSyntaxError

   置換がなされるソーステキストが要求された文法を満たさないときに送出
   される例外です。 "InterpolationError" の派生クラスです。

exception configparser.MissingSectionHeaderError

   セクションヘッダを持たないファイルを構文解析しようとした時に起きる
   例外です。

exception configparser.ParsingError

   ファイルの構文解析中にエラーが起きた場合に発生する例外です。

   バージョン 3.2 で変更: "filename" という属性および "__init__()" の
   引数は "source" に名前が変更されました。

-[ 脚注 ]-

[1] 設定パーサーは大々的にカスタマイズできます。脚注の参照で概説された
    挙動の変更に関心がある場合、Customizing Parser Behaviour セクショ
    ンを参照してください。
