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

注釈

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.

脚注