13.2. ConfigParser --- 設定ファイルの構文解析器

注釈

ConfigParser モジュールは Python 3 で configparser に改名されました。 2to3 ツールが自動的にソース内の import を修正します。

This module defines the class ConfigParser. The ConfigParser class implements a basic configuration file parser language which provides a structure similar to what you would find on Microsoft Windows INI files. You can use this to write Python programs which can be customized by end users easily.

注釈

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

参考

shlex モジュール

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

json モジュール

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

設定ファイルは 1 つ以上のセクションからなり、セクションは [section] ヘッダとそれに続く RFC 822 形式の name: value エントリからなっています。(section 3.1.1 "LONG HEADER FIELDS" を参照) name=value という形式も使えます。値の先頭にある空白文字は削除されるので注意してください。オプションの値には、同じセクションか DEFAULT セクションにある値を参照するような書式化文字列を含めることができます。初期化時や検索時に別のデフォルト値を与えることもできます。 '#' か ';' ではじまる行は無視され、コメントを書くために利用できます。

設定ファイルは、特定の文字 (# と ;) で始まるコメントを含んでいることがあります。コメントはある行の中に単独で書かれる場合もありますし、値やセクション名のある行に書かれる場合もあります。後者がコメントとして認識されるためには、その前に空白文字が入っている必要があります。 (後方互換性のために、 # ではなく ; で一行コメントを書いてください。)

最も高機能なクラス SafeConfigParser は置換機能をサポートします。これは同じセクション内の値や DEFAULT という特別なセクションの値を参照するフォーマット文字列を使うことができるという意味です。さらに初期化のときにデフォルトの値を追加することもできます。

例えば:

[My Section]
foodir: %(dir)s/whatever
dir=frob
long: this value continues
   in the next line

この場合 %(dir)s は変数 dir (この場合は frob)に展開されます。参照の展開は必要に応じて実行されます。

Default values can be specified by passing them into the ConfigParser constructor as a dictionary. Additional defaults may be passed into the get() method which will override all others.

Sections are normally stored in a built-in dictionary. An alternative dictionary type can be passed to the ConfigParser constructor. For example, if a dictionary type is passed that sorts its keys, the sections will be sorted on write-back, as will be the keys within each section.

class ConfigParser.RawConfigParser([defaults[, dict_type[, allow_no_value]]])

基本的な設定オブジェクトです。 defaults が与えられた場合、オブジェクトに固有のデフォルト値がその値で初期化されます。 dict_type が与えられた場合、それが、セクションのリストの格納、セクション内のオプションの格納、デフォルト値のために利用されます。 allow_no_value (デフォルト: False) が真の時、値のないオプションが許可されます。この場合の値は None になります。

このクラスは値の置換をサポートしません。

全てのオプション名が optionxform() メソッドに渡されます。このメソッドのデフォルトの実装では、オプション名を小文字に変換します。

バージョン 2.3 で追加.

バージョン 2.6 で変更: dict_type が追加されました。

バージョン 2.7 で変更: dict_type のデフォルトが collections.OrderedDict になりました。 allow_no_value が追加されました。

class ConfigParser.ConfigParser([defaults[, dict_type[, allow_no_value]]])

RawConfigParser の派生クラスで値の置換を実装しており、 get() メソッドと items() メソッドに省略可能な引数を追加しています。 defaults に含まれる値は %()s による値の置換に適当なものである必要があります。 __name__ は組み込みのデフォルト値で、セクション名が含まれるので defaults で設定してもオーバーライドされます。

置換で使われるすべてのオプション名は、ほかのオプション名への参照と同様に optionxform() メソッドを介して渡されます。 optionxform() のデフォルト実装を使うと、値 foo %(bar)s および foo %(BAR)s は同一になります。

バージョン 2.3 で追加.

バージョン 2.6 で変更: dict_type が追加されました。

バージョン 2.7 で変更: dict_type のデフォルトが collections.OrderedDict になりました。 allow_no_value が追加されました。

class ConfigParser.SafeConfigParser([defaults[, dict_type[, allow_no_value]]])

Derived class of ConfigParser that implements a more-sane variant of the magical interpolation feature. This implementation is more predictable as well. New applications should prefer this version if they don't need to be compatible with older versions of Python.

バージョン 2.3 で追加.

バージョン 2.6 で変更: dict_type が追加されました。

バージョン 2.7 で変更: dict_type のデフォルトが collections.OrderedDict になりました。 allow_no_value が追加されました。

exception ConfigParser.Error

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

exception ConfigParser.NoSectionError

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

exception ConfigParser.DuplicateSectionError

すでに存在するセクション名に対して add_section() が呼び出された際に起きる例外です。

exception ConfigParser.NoOptionError

指定したオプションが指定したセクションに存在しなかった時に起きる例外です。

exception ConfigParser.InterpolationError

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

exception ConfigParser.InterpolationDepthError

InterpolationError の派生クラスで、文字列の置換回数が MAX_INTERPOLATION_DEPTH を越えたために完了しなかった場合に発生する例外です。

exception ConfigParser.InterpolationMissingOptionError

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

バージョン 2.3 で追加.

exception ConfigParser.InterpolationSyntaxError

InterpolationError の派生クラスで、指定された構文で値を置換することができなかった場合に発生する例外です。

バージョン 2.3 で追加.

exception ConfigParser.MissingSectionHeaderError

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

exception ConfigParser.ParsingError

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

ConfigParser.MAX_INTERPOLATION_DEPTH

The maximum depth for recursive interpolation for get() when the raw parameter is false. This is relevant only for the ConfigParser class.

参考

shlex モジュール

アプリケーション用の設定ファイルフォーマットとして使える、 Unix シェルライクなミニ言語の作成を支援します。

13.2.1. RawConfigParser オブジェクト

RawConfigParser クラスのインスタンスは以下のメソッドを持ちます:

RawConfigParser.defaults()

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

RawConfigParser.sections()

利用可能なセクションのリストを返します。 DEFAULT はこのリストに含まれません。

RawConfigParser.add_section(section)

section という名前のセクションをインスタンスに追加します。同名のセクションが存在した場合、 DuplicateSectionError が発生します。 DEFAULT (もしくは大文字小文字が違うもの)が渡された場合、 ValueError が発生します。

RawConfigParser.has_section(section)

指定したセクションがコンフィグレーションファイルに存在するかを返します。 DEFAULT セクションは存在するとみなされません。

RawConfigParser.options(section)

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

RawConfigParser.has_option(section, option)

与えられたセクションが存在してかつオプションが与えられていれば True を返し、そうでなければ False を返します。

バージョン 1.6 で追加.

RawConfigParser.read(filenames)

Attempt to read and parse a list of filenames, returning a list of filenames which were successfully parsed. If filenames is a string or Unicode string, it is treated as a single filename. If a file named in filenames cannot be opened, that file will be ignored. This is designed so that you can specify a list of potential configuration file locations (for example, the current directory, the user's home directory, and some system-wide directory), and all existing configuration files in the list will be read. If none of the named files exist, the ConfigParser instance will contain an empty dataset. An application which requires initial values to be loaded from a file should load the required file or files using readfp() before calling read() for any optional files:

import ConfigParser, os

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

バージョン 2.4 で変更: 解析に成功したファイル名のリストを返します。

RawConfigParser.readfp(fp[, filename])

fp で与えられるファイルかファイルのようなオブジェクトを読み込んで構文解析します(readline() メソッドだけを使います)。もし filename が省略されて fp が name 属性を持っていれば filename の代わりに使われます。ファイル名の初期値は <???> です。

RawConfigParser.get(section, option)

section の option 変数を取得します。

RawConfigParser.getint(section, option)

section の option を整数として評価する関数です。

RawConfigParser.getfloat(section, option)

section の option を浮動小数点数として評価する関数です。

RawConfigParser.getboolean(section, option)

指定した section の option 値をブール値に型強制する便宜メソッドです。 option として受理できる値は、真 (True) としては "1" 、 "yes" 、 "true" 、 "on" 、偽 (False) としては "0" 、 "no" 、 "false" 、 "off" です。これらの文字列値に対しては大文字小文字の区別をしません。その他の値の場合には ValueError を送出します。

RawConfigParser.items(section)

与えられた section のそれぞれのオプションについて (name, value) ペアのリストを返します。

RawConfigParser.set(section, option, value)

If the given section exists, set the given option to the specified value; otherwise raise NoSectionError. While it is possible to use RawConfigParser (or ConfigParser with raw parameters set to true) for internal storage of non-string values, full functionality (including interpolation and output to files) can only be achieved using string values.

バージョン 1.6 で追加.

RawConfigParser.write(fileobject)

設定を文字列表現に変換してファイルオブジェクトに書き出します。この文字列表現は read() で読み込むことができます。

バージョン 1.6 で追加.

RawConfigParser.remove_option(section, option)

指定された section から指定された option を削除します。セクションが存在しなければ、 NoSectionError を起こします。存在するオプションを削除した時は True を、そうでない時は False を返します。

バージョン 1.6 で追加.

RawConfigParser.remove_section(section)

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

RawConfigParser.optionxform(option)

入力ファイル中に見つかったオプション名か、クライアントコードから渡されたオプション名 option を、内部で利用する形式に変換します。デフォルトでは option を全て小文字に変換した名前が返されます。サブルクラスではこの関数をオーバーライドすることでこの振舞いを替えることができます。

振舞いを替えるために ConfigParser を継承して新たにクラスを作る必要はありません、あるインスタンスのメソッドを文字列を引数に取る関数で置き換えることもできます。たとえば、このメソッドを str() に設定することで大小文字の差を区別するように変更することができます:

cfgparser = ConfigParser()
...
cfgparser.optionxform = str

設定ファイルを読み込むときには、 optionxform() が呼ばれる前にオプション名の前後の空白文字が取り除かれることに注意してください。

13.2.2. ConfigParser オブジェクト

The ConfigParser class extends some methods of the RawConfigParser interface, adding some optional arguments.

ConfigParser.get(section, option[, raw[, vars]])

section の option 変数を取得します。このメソッドに渡される vars は辞書でなくてはいけません。 (もし渡されているならば) vars 、 section 、 defaults の順に option が探されます。

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

ConfigParser.items(section[, raw[, vars]])

指定した section 内の各オプションに対して、 (name, value) のペアからなるリストを返します。省略可能な引数は get() メソッドと同じ意味を持ちます。

バージョン 2.3 で追加.

13.2.3. SafeConfigParser オブジェクト

The SafeConfigParser class implements the same extended interface as ConfigParser, with the following addition:

SafeConfigParser.set(section, option, value)

もし与えられたセクションが存在している場合は、指定された値を与えられたオプションに設定します。そうでない場合は NoSectionError を発生させます。 value は文字列 (str または unicode) でなければならず、そうでない場合には TypeError が発生します。

バージョン 2.4 で追加.

13.2.4. 使用例

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

import ConfigParser

config = ConfigParser.RawConfigParser()

# When adding sections or items, add them in the reverse order of
# how you want them to be displayed in the actual file.
# In addition, please note that using RawConfigParser's and the raw
# mode of ConfigParser's respective 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. SafeConfigParser 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', 'wb') 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')

To get interpolation, you will need to use a ConfigParser or SafeConfigParser:

import ConfigParser

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

# Set the third, optional argument of get to 1 if you wish to use raw mode.
print config.get('Section1', 'foo', 0)  # -> "Python is fun!"
print config.get('Section1', 'foo', 1)  # -> "%(bar)s is %(baz)s!"

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

3 種類全ての ConfigParser クラスで、デフォルト値を利用できます。別にオプションが指定されていなかった場合、このデフォルト値は置換機能でも利用されます:

import ConfigParser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = ConfigParser.SafeConfigParser({'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!"

opt_move 関数は、オプションをセクション間で移動することができます:

def opt_move(config, section1, section2, option):
    try:
        config.set(section2, option, config.get(section1, option, 1))
    except ConfigParser.NoSectionError:
        # Create non-existent section
        config.add_section(section2)
        opt_move(config, section1, section2, option)
    else:
        config.remove_option(section1, option)

いくつかの設定ファイルでは、値のない設定項目がある以外は ConfigParser の文法と同じ文法になっています。コンストラクタの allow_no_value 引数で、そのような値を許可することができます。

>>> import ConfigParser
>>> import io

>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))

>>> # Settings with values are treated as before:
>>> config.get("mysqld", "user")
'mysql'

>>> # Settings without values provide None:
>>> config.get("mysqld", "skip-bdb")

>>> # Settings which aren't specified still raise an error:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
  ...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'