configparser --- 設定ファイルのパーサー¶
ソースコード: Lib/configparser.py
このモジュールは、 Microsoft Windows の INI ファイルに似た構造を持ったベーシックな設定用言語を実装した ConfigParser クラスを提供します。このクラスを使ってユーザーが簡単にカスタマイズできる Python プログラムを作ることができます。
注釈
このライブラリは、Windows レジストリ用に拡張された INI 構文で使われる値の型を表す接頭辞を解釈したり書き込んだりは しません。
警告
信頼できない提供元のデータを解析するときは注意してください。 悪意のある INI ファイルにより、デコーダーが大量の CPU とメモリ資源を消費する可能性があります。 解析するデータのサイズを制限することを推奨します。
参考
クイックスタート¶
次のような、非常に簡単な設定ファイルを例に考えましょう:
[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' # パーサーを変更する
>>> topsecret['ForwardX11'] = 'no' # ここも同様
>>> 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]。
1 つの ConfigParser に複数の設定を読み込むことができ、最後に追加した設定が最も優先されます。
重複するキーには後から読み込んだ設定の値が使われ、重複しない既存のキーは保持されます。
次の例では override.ini ファイルを読み込み、example.ini ファイルと重複するキーの値を上書きします。
[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
この動作は、filenames 引数に複数のファイルを渡して ConfigParser.read() を呼び出す場合と同じです。
サポートされるデータ型¶
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]
代替値¶
辞書と同様に、セクションの get() メソッドを使って代替値を指定できます:
>>> 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'
もう 1 つ注意が必要なのは、パーサーの get() メソッドには、後方互換性のために維持されている独自の、より複雑なインターフェースがあることです。
このメソッドを使う場合、代替値はキーワード専用引数 fallback で指定できます:
>>> 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 ファイルの構造¶
設定ファイルはセクションで構成されます。
各セクションは [section] ヘッダーで始まり、その後に特定の文字列 (デフォルトでは = または : [1]) で区切られたキーと値のエントリーが続きます。
デフォルトでは、セクション名は大文字と小文字を区別しますが、キーは区別しません [1]。
キーと値の前後の空白は取り除かれます。
パーサーの設定で許可されていれば値を省略でき [1]、その場合はキーと値を区切るデリミタも省略できます。
値の最初の行よりも深くインデントすれば、値を複数行にわたって記述することもできます。
パーサーのモードによって、空行は複数行の値の一部として扱われる場合も、無視される場合もあります。
デフォルトでは、'\n' を含まない任意の文字列をセクション名にできます。
これを変更するには ConfigParser.SECTCRE を参照してください。
allow_unnamed_section=True を指定して無名の最上位セクションを許可した場合、最初のセクション名は省略できます。
この場合、config[UNNAMED_SECTION] のように 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]
# このように
; このようにも
# デフォルトでは他の内容がない行にのみ記述できます。
# インラインコメントは、デリミタを値の一部として使えなくするため、
# 問題になることがあります。
# ただし、この動作はカスタマイズできます。
[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
# コメントもインデントできます。
無名セクション¶
最初のセクション (または唯一のセクション) の名前は省略でき、UNNAMED_SECTION 属性を使って値を取得できます。
>>> 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] # %% で % 記号をエスケープします (エスケープが必要なのは % だけです): 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] # $$ で $ 記号をエスケープします (エスケープが必要なのは $ だけです): 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 ABC に従います。
ただし、注意すべき違いがいくつかあります:
デフォルトでは、セクション内の全てのキーは大文字小文字の区別なくアクセスできます [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, デフォルト値:
Falseconfigparserがサポートする構文におおむね従っていても、値のない設定を含む設定ファイルがあります。 そのような値を受け付けるには、コンストラクタの 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 ... # 今回は ACID は不要です ... skip-innodb ... """ >>> config = configparser.ConfigParser(allow_no_value=True) >>> config.read_string(sample_config) >>> # 値のある設定は従来どおりに扱われます: >>> config["mysqld"]["user"] 'mysql' >>> # 値のない設定は None を返します: >>> config["mysqld"]["skip-bdb"] >>> # 指定されていない設定は引き続きエラーになります: >>> 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, デフォルト値:
TrueTrueに設定すると、パーサーは単一のソースから (read_file()、read_string()、read_dict()を使って) 読み込む際に、セクションやオプションの重複を許可しません。 新しいアプリケーションでは、この厳密なパーサーを使うことを推奨します。バージョン 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']
注釈
optionxform()関数はオプション名を正規形に変換します。 この関数は冪等でなければなりません。 つまり、名前がすでに正規形であれば、そのまま返す必要があります。
- 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()
# RawConfigParser の set 関数では、内部的にキーに文字列以外の値も
# 代入できますが、ファイルへの書き出しや raw でないモードでの取得を
# 試みるとエラーになります。
# マップ型プロトコルや ConfigParser の set() による値の設定では、
# このような代入はできません。
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!')
# 設定ファイルを 'example.cfg' に書き出す
with open('example.cfg', 'w') as configfile:
config.write(configfile)
設定ファイルを読み込む例:
import configparser
config = configparser.RawConfigParser()
config.read('example.cfg')
# 値が浮動小数点数でなければ getfloat() は例外を送出します
# getint() と getboolean() もそれぞれの型について同様に動作します
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)
# 次の出力では '%(bar)s' や '%(baz)s' は補間されません。
# これは RawConfigParser() を使用しているためです。
if config.getboolean('Section1', 'a_bool'):
print(config.get('Section1', 'foo'))
補間するには、 ConfigParser を使ってください:
import configparser
cfg = configparser.ConfigParser()
cfg.read('example.cfg')
# 1 回の取得操作で補間を無効にするには、
# get() の省略可能な引数 *raw* を True に設定します。
print(cfg.get('Section1', 'foo', raw=False)) # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True)) # -> "%(bar)s is %(baz)s!"
# 省略可能な引数 *vars* は、補間時に優先される要素を
# 含む辞書です。
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
'baz': 'evil'}))
# 省略可能な引数 *fallback* で代替値を指定できます
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."
# 単に print(cfg.get('Section1', 'monster')) とすると NoOptionError になりますが、
# 次のようにも書けます:
print(cfg.get('Section1', 'monster', fallback=None))
# -> None
どちらの型の ConfigParsers でもデフォルト値が利用できます。使われているオプションがどこにも定義されていなければ、そのデフォルト値が補間に使われます。
import configparser
# 'bar' と 'baz' のデフォルト値がそれぞれ 'Life' と 'hard' の新しいインスタンス
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となり、後端のデリミタを除いてシリアル化されます。default_section を指定すると、ほかのセクションのデフォルト値や補間用の値を保持する特別なセクションの名前 (通常は
"DEFAULT") を設定できます。 この値は、インスタンス属性default_sectionを使って実行時に取得、変更できます。 値を変更しても、すでに解析した設定ファイルは再評価されませんが、解析済みの設定を新しい設定ファイルへ書き出す際に使われます。補間の動作は、 interpolation 引数を通してカスタムハンドラを与えることでカスタマイズできます。
None引数を使うと補間を完全に無効にできます。ExtendedInterpolation()は、zc.buildoutに影響を受けたより高度な補間を提供します。この件に 特化したドキュメントのセクション を参照してください。補間に使われるすべてのオプション名は、他のオプション名参照と同様に、
optionxform()メソッドを通して渡されます。例えば、optionxform()のデフォルトの実装を使うと、値foo %(bar)sとfoo %(BAR)sは等しくなります。converters を指定する場合は、各キーを型コンバーター名、各値を文字列から目的のデータ型への変換を実装する呼び出し可能オブジェクトとする辞書でなければなりません。 各コンバーターに対応する
get*()メソッドが、パーサーオブジェクトとセクションプロキシに追加されます。allow_unnamed_section が
True(デフォルトはFalse) の場合、最初のセクション名を省略できます。 「無名セクション」の節 を参照してください。1 つの
ConfigParserに複数の設定を読み込むことができ、最後に追加した設定が最も優先されます。 重複するキーには後から読み込んだ設定の値が使われ、重複しない既存のキーは保持されます。 次の例ではoverride.iniファイルを読み込み、example.iniファイルと重複するキーの値を上書きします。[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 で変更: defaults 引数は
read_dict()で読み込まれ、パーサー全体で動作が統一されました。 文字列でないキーと値は暗黙に文字列に変換されます。バージョン 3.8 で変更: 挿入順を保持するようになったため、dict_type のデフォルトは
dictになりました。バージョン 3.13 で変更: allow_no_value が
Trueで、値のないキーの後にインデントされた行が続く場合、MultilineContinuationErrorを送出するようになりました。バージョン 3.13 で変更: allow_unnamed_section 引数が追加されました。
- 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 で変更: 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 に使われます。 デフォルトは'<???>'です。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 を指定する場合は辞書でなければなりません。 option は vars (指定されている場合)、section、DEFAULTSECT の順に検索されます。 キーが見つからず、fallback が指定されている場合は、その値を代わりに返します。 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 をブール値に変換する便利なメソッドです。
'1'、'yes'、'true'、'on'に対してはTrueを、'0'、'no'、'false'、'off'に対してはFalseを返します。 これらの文字列値は大文字と小文字を区別せずに調べられます。 その他の値に対しては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 で変更: このパーサーで後から
read()を呼び出したときに正確に解析できない表現を書き込もうとすると、InvalidWriteErrorを送出します。
注釈
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()が呼び出される前に取り除かれます。
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)¶
ConfigParserのレガシーな変種です。 デフォルトで補間が無効になっており、安全でないadd_section、setメソッドと、レガシーなdefaults=キーワード引数の処理を通じて、文字列でないセクション名、オプション名、値を使用できます。バージョン 3.2 で変更: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section および interpolation が追加されました。
バージョン 3.5 で変更: converters 引数が追加されました。
バージョン 3.8 で変更: 挿入順を保持するようになったため、dict_type のデフォルトは
dictになりました。バージョン 3.13 で変更: allow_unnamed_section 引数が追加されました。
注釈
代わりに内部に保存する値の型を検査する
ConfigParserを使うことを検討してください。補間を望まない場合、ConfigParser(interpolation=None)を使用できます。- add_section(section)¶
section という名前のセクション、または
UNNAMED_SECTIONをインスタンスに追加します。指定されたセクションがすでに存在する場合、
DuplicateSectionErrorを送出します。 デフォルトセクション の名前を渡すと、ValueErrorを送出します。UNNAMED_SECTIONを渡し、無名セクションのサポートが無効になっている場合、UnnamedSectionDisabledErrorを送出します。section の型は検査されないため、ユーザーは非文字列の名前付きセクションを作ることができます。この振る舞いはサポートされておらず、内部エラーを起こす可能性があります。
バージョン 3.14 で変更:
UNNAMED_SECTIONのサポートが追加されました。- set(section, option, value)¶
与えられたセクションが存在していれば、オプションを指定された値に設定します。セクションが存在しなければ
NoSectionErrorを発生させます。RawConfigParser(あるいは raw パラメータをセットしたConfigParser) を文字列型でない値の 内部的な 格納場所として使うことは可能ですが、すべての機能 (置換やファイルへの出力を含む) がサポートされるのは文字列を値として使った場合だけです。ユーザーは、このメソッドを使って非文字列の値をキーに代入できます。この振る舞いはサポートされておらず、非rawモードでの値の取得や、ファイルへの書き出しを試みた際にエラーの原因となりえます。このような代入を許さない マッピングプロトコルAPIを使用してください。
例外¶
- exception configparser.Error¶
ほかのすべての
configparser例外の基底クラスです。
- exception configparser.NoSectionError¶
指定したセクションが見つからなかった時に起きる例外です。
- exception configparser.DuplicateSectionError¶
すでに存在するセクションの名前で
add_section()を呼び出した場合、または厳密なパーサーで単一の入力ファイル、文字列、辞書に同じセクションが複数回見つかった場合に送出される例外です。バージョン 3.2 で変更:
__init__()に省略可能な source、lineno 属性と引数が追加されました。
- 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 で変更:
filename属性と__init__()コンストラクタの引数が削除されました。 これらは 3.2 以降、sourceという名前で利用できます。
- exception configparser.MultilineContinuationError¶
対応する値のないキーの後にインデントされた行が続く場合に送出される例外です。
Added in version 3.13.
- exception configparser.UnnamedSectionDisabledError¶
UNNAMED_SECTIONを有効にせずに使おうとした場合に送出される例外です。Added in version 3.14.
- exception configparser.InvalidWriteError¶
ConfigParser.write()で書き込もうとしている内容が、後のConfigParser.read()呼び出しで正確に解析できない場合に送出される例外です。例えば、
ConfigParser.SECTCREのパターンで始まるキーを書き込むと、読み込み時にセクションヘッダーとして解析されます。 このようなキーを書き込もうとすると、この例外を送出します。Added in version 3.14.
脚注