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

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

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

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

注釈:

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

参考:

  モジュール "tomllib"
     TOML is a well-specified format for application configuration
     files. It is specifically designed to be an improved version of
     INI.

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

  "json" モジュール
     The "json" module implements a subset of JavaScript syntax which
     is sometimes used for configuration, but does not support
     comments.


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

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

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

   [forge.example]
   User = hg

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

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

   >>> import configparser
   >>> config = configparser.ConfigParser()
   >>> config['DEFAULT'] = {'ServerAliveInterval': '45',
   ...                      'Compression': 'yes',
   ...                      'CompressionLevel': '9'}
   >>> config['forge.example'] = {}
   >>> config['forge.example']['User'] = 'hg'
   >>> config['topsecret.server.example'] = {}
   >>> topsecret = config['topsecret.server.example']
   >>> 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()
   ['forge.example', 'topsecret.server.example']
   >>> 'forge.example' in config
   True
   >>> 'python.org' in config
   False
   >>> config['forge.example']['User']
   'hg'
   >>> config['DEFAULT']['Compression']
   'yes'
   >>> topsecret = config['topsecret.server.example']
   >>> topsecret['ForwardX11']
   'no'
   >>> topsecret['Port']
   '50022'
   >>> for key in config['forge.example']:
   ...     print(key)
   user
   compressionlevel
   serveraliveinterval
   compression
   forwardx11
   >>> config['forge.example']['ForwardX11']
   'yes'

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

It is possible to read several configurations into a single
"ConfigParser", where the most recently added configuration has the
highest priority. Any conflicting keys are taken from the more recent
configuration while the previously existing keys are retained. The
example below reads in an "override.ini" file, which will override any
conflicting keys from the "example.ini" file.

   [DEFAULT]
   ServerAliveInterval = -1

   >>> config_override = configparser.ConfigParser()
   >>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
   >>> with open('override.ini', 'w') as configfile:
   ...     config_override.write(configfile)
   ...
   >>> config_override = configparser.ConfigParser()
   >>> config_override.read(['example.ini', 'override.ini'])
   ['example.ini', 'override.ini']
   >>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
   -1

This behaviour is equivalent to a "ConfigParser.read()" call with
several files passed to the *filenames* parameter.


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

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['forge.example'].getboolean('ForwardX11')
   True
   >>> config.getboolean('forge.example', 'Compression')
   True

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


代替値
======

As with a dictionary, you can use a section's "get()" method to
provide fallback values:

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

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

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

One more thing to be aware of is that the parser-level "get()" method
provides a custom, more complex interface, maintained for backwards
compatibility.  When using this method, a fallback value can be
provided via the "fallback" keyword-only argument:

   >>> config.get('forge.example', '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 ファイルの構造
==============================

A configuration file consists of sections, each led by a "[section]"
header, followed by key/value entries separated by a specific string
("=" or ":" by default [1]).  By default, section names are case
sensitive but keys are not [1].  Leading and trailing whitespace is
removed from keys and values. Values can be omitted if the parser is
configured to allow it [1], in which case the key/value delimiter may
also be left out.  Values can also span multiple lines, as long as
they are indented deeper than the first line of the value.  Depending
on the parser's mode, blank lines may be treated as parts of multiline
values or ignored.

By default, a valid section name can be any string that does not
contain '\n'. To change this, see "ConfigParser.SECTCRE".

The first section name may be omitted if the parser is configured to
allow an unnamed top level section with "allow_unnamed_section=True".
In this case, the keys/values may be retrieved by "UNNAMED_SECTION" as
in "config[UNNAMED_SECTION]".

設定ファイルには先頭に特定の文字 (デフォルトでは "#" および ";" [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?


Unnamed Sections
================

The name of the first section (or unique) may be omitted and values
retrieved by the "UNNAMED_SECTION" attribute.

   >>> config = """
   ... option = value
   ...
   ... [  Section 2  ]
   ... another = val
   ... """
   >>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
   >>> unnamed.read_string(config)
   >>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
   'value'


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

コア機能に加えて、 "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]
      # use a %% to escape the % sign (% is the only character that needs to be escaped):
      gain: 80%%

   上の例では、 *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]
      # use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
      cost: $$80

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

      [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}


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

Added in version 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 スタイルを
集めた集合をサポートするために、非常に役立ちます。デフォルトの機能は主
に歴史的背景によって決められたので、機能によってはカスタマイズしてお使
いください。

The most common way to change the way a specific config parser works
is to use the "__init__()" options:

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

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

  Hint: if you want to specify default values for a specific section,
  use "read_dict()" before you read the actual file.

* *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"

  When set to "True", the parser will not allow for any section or
  option duplicates while reading from a single source (using
  "read_file()", "read_string()" or "read_dict()").  It is recommended
  to use strict parsers in new applications.

  バージョン 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*, デフォルト値: 未設定

  Config parsers provide option value getters that perform type
  conversion.  By default "getint()", "getfloat()", and "getboolean()"
  are implemented.  Should other getters be desirable, users may
  define them in a subclass or pass a dictionary where each key is a
  name of the converter and each value is a callable implementing said
  conversion.  For instance, passing "{'decimal': decimal.Decimal}"
  would add "getdecimal()" on both the parser object and all section
  proxies.  In other words, it will be possible to write both
  "parser_instance.getdecimal('section', 'key', fallback=0)" and
  "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={}, allow_unnamed_section=False)

   主要な設定パーサーです。*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" となり、後端のデリミタを除いてシリアル
   化されます。

   When *default_section* is given, it specifies the name for the
   special section holding default values for other sections and
   interpolation purposes (normally named ""DEFAULT"").  This value
   can be retrieved and changed at runtime using the "default_section"
   instance attribute. This won't re-evaluate an already parsed config
   file, but will be used when writing parsed settings to a new config
   file.

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

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

   When *converters* is given, it should be a dictionary where each
   key represents the name of a type converter and each value is a
   callable implementing the conversion from string to the desired
   datatype.  Every converter gets its own corresponding "get*()"
   method on the parser object and section proxies.

   When *allow_unnamed_section* is "True" (default: "False"), the
   first section name can be omitted. See the "Unnamed Sections"
   section.

   It is possible to read several configurations into a single
   "ConfigParser", where the most recently added configuration has the
   highest priority. Any conflicting keys are taken from the more
   recent configuration while the previously existing keys are
   retained. The example below reads in an "override.ini" file, which
   will override any conflicting keys from the "example.ini" file.

      [DEFAULT]
      ServerAliveInterval = -1

      >>> config_override = configparser.ConfigParser()
      >>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
      >>> with open('override.ini', 'w') as configfile:
      ...     config_override.write(configfile)
      ...
      >>> config_override = configparser.ConfigParser()
      >>> config_override.read(['example.ini', 'override.ini'])
      ['example.ini', 'override.ini']
      >>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
      -1

   バージョン 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.

   バージョン 3.13 で変更: Raise a "MultilineContinuationError" when
   *allow_no_value* is "True", and a key without a value is continued
   with an indented line.

   バージョン 3.13 で変更: The *allow_unnamed_section* argument was
   added.

   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* が文字列か "bytes" オブジェクトか *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 で変更: Added the *encoding* parameter.
      Previously, all files were read using the default encoding for
      "open()".

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

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

   read_file(f, source=None)

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

      Optional argument *source* specifies the name of the file being
      read.  If not given and *f* has a "name" attribute, that is used
      for *source*; the default is "'<???>'".

      Added in version 3.2: "readfp()" を置き換えます。

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

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

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

      Added in version 3.2.

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

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

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

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

      Added in version 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])

      A convenience method which coerces the *option* in the specified
      *section* to a floating-point number.  See "get()" for
      explanation of *raw*, *vars* and *fallback*.

   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* が真なら、キーと値の間の
      デリミタはスペースで囲まれます。

      バージョン 3.14 で変更: Raises InvalidWriteError if this would
      write a representation which cannot be accurately parsed by a
      future "read()" call from this parser.

   注釈:

     Comments in the original configuration file are not preserved
     when writing the configuration back. What is considered a
     comment, depends on the given values for *comment_prefix* and
     *inline_comment_prefix*.

   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()" が呼び出される前に取り除かれます。

configparser.UNNAMED_SECTION

   A special object representing a section name used to reference the
   unnamed section (see Unnamed Sections).

configparser.MAX_INTERPOLATION_DEPTH

   The maximum depth for recursive interpolation for "get()" when the
   *raw* parameter is false.  This is relevant only when the default
   *interpolation* is used.


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=BasicInterpolation(), converters={}, allow_unnamed_section=False)

   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.2 で変更: *allow_no_value*, *delimiters*,
   *comment_prefixes*, *strict*, *empty_lines_in_values*,
   *default_section* および *interpolation* が追加されました。

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

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

   バージョン 3.13 で変更: The *allow_unnamed_section* argument was
   added.

   注釈:

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

   add_section(section)

      Add a section named *section* or "UNNAMED_SECTION" to the
      instance.

      If the given section already exists, "DuplicateSectionError" is
      raised. If the *default section* name is passed, "ValueError" is
      raised. If "UNNAMED_SECTION" is passed and support is disabled,
      "UnnamedSectionDisabledError" is raised.

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

   バージョン 3.14 で変更: Added support for "UNNAMED_SECTION".

   set(section, option, value)

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

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


例外
====

exception configparser.Error

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

exception configparser.NoSectionError

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

exception configparser.DuplicateSectionError

   Exception raised if "add_section()" is called with the name of a
   section that is already present or in strict parsers when a section
   if found more than once in a single input file, string or
   dictionary.

   バージョン 3.2 で変更: Added the optional *source* and *lineno*
   attributes and parameters to "__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.12 で変更: The "filename" attribute and "__init__()"
   constructor argument were removed.  They have been available using
   the name "source" since 3.2.

exception configparser.MultilineContinuationError

   Exception raised when a key without a corresponding value is
   continued with an indented line.

   Added in version 3.13.

exception configparser.UnnamedSectionDisabledError

   Exception raised when attempting to use the "UNNAMED_SECTION"
   without enabling it.

      Added in version 3.14.

exception configparser.InvalidWriteError

   Exception raised when an attempted "ConfigParser.write()" would not
   be parsed accurately with a future "ConfigParser.read()" call.

   Ex: Writing a key beginning with the "ConfigParser.SECTCRE" pattern
   would parse as a section header when read. Attempting to write this
   will raise this exception.

   Added in version 3.14.

-[ 脚注 ]-

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