ナビゲーション
- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.7ja1 documentation »
- Python 標準ライブラリ »
- 13. ファイルフォーマット »
ノート
ConfigParser モジュールは Python 3.0 で configparser に改名されました。 2to3 ツールが自動的にソース内の import を修正します。
このモジュールでは、 ConfigParser クラスを定義しています。 ConfigParser クラスは、Microsoft Windows の INI ファイルに見られるような構造をもつ、基礎的な設定ファイルを実装しています。このモジュールを使って、エンドユーザーが簡単にカスタマイズできるような Python プログラムを書くことができます。
ノート
このライブラリでは、Windowsのレジストリ用に拡張された INI 文法はサポート していません 。
参考
設定ファイルは 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)に展開されます。参照の展開は必要に応じて実行されます。
デフォルト値は ConfigParser のコンストラクタに辞書として渡すことで設定できます。追加の(他の値をオーバーライドする)デフォルト値は get() メソッドに渡すことができます。
セクションは通常、組み込みの辞書型に格納されます。 ConfigParser コンストラクタの引数として、代替の辞書型を渡すことができます。例えば、キーをソートするような辞書型が渡された場合、iniファイルに書き戻すときにセクションはソートされます。
基本的な設定オブジェクトです。 defaults が与えられた場合、オブジェクトに固有のデフォルト値がその値で初期化されます。 dict_type が与えられた場合、それが、セクションのリストの格納、セクション内のオプションの格納、デフォルト値のために利用されます。
allow_no_value (デフォルト: False) が真の時、値のないオプションが許可されます。この場合の値は None になります。
このクラスは値の置換をサポートしません。
全てのオプション名が optionxform() メソッドに渡されます。このメソッドのデフォルトの実装では、オプション名を小文字に変換します。
バージョン 2.3 で追加.
バージョン 2.6 で変更: dict_type が追加されました。
バージョン 2.7 で変更: デフォルトの dict_type は collections.OrderedDict です。 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 が追加されました。
ConfigParser の派生クラスでより安全な値の置換を実装しています。この実装はより予測可能性が高くなっています。新規に書くアプリケーションでは、古いバージョンのPythonと互換性を持たせる必要がない限り、このバージョンを利用することが望ましいです。
バージョン 2.3 で追加.
バージョン 2.6 で変更: dict_type が追加されました。
バージョン 2.7 で変更: デフォルトの dict_type は collections.OrderedDict です。 allow_no_value が追加されました。
他の全ての configparser の例外の基底クラスです。
指定したセクションが見つからなかった時に起きる例外です。
すでに存在するセクション名に対して add_section() が呼び出された際に起きる例外です。
指定したオプションが指定したセクションに存在しなかった時に起きる例外です。
文字列の置換中に問題が起きた時に発生する例外の基底クラスです。
InterpolationError の派生クラスで、文字列の置換回数が MAX_INTERPOLATION_DEPTH を越えたために完了しなかった場合に発生する例外です。
InterpolationError の派生クラスで、値が参照しているオプションが見つからない場合に発生する例外です。
InterpolationError の派生クラスで、指定された構文で値を置換することができなかった場合に発生する例外です。
バージョン 2.3 で追加.
セクションヘッダを持たないファイルを構文解析しようとした時に起きる例外です。
ファイルの構文解析中にエラーが起きた場合に発生する例外です。
raw が偽だった場合の get() による再帰的な文字列置換の繰り返しの最大値です。 ConfigParser クラスだけに関係します。
参考
RawConfigParser クラスのインスタンスは以下のメソッドを持ちます:
インスタンス全体で使われるデフォルト値の辞書を返します。
利用可能なセクションのリストを返します。 DEFAULT はこのリストに含まれません。
section という名前のセクションをインスタンスに追加します。同名のセクションが存在した場合、 DuplicateSectionError が発生します。 DEFAULT (もしくは大文字小文字が違うもの)が渡された場合、 ValueError が発生します。
指定したセクションがコンフィグレーションファイルに存在するかを返します。 DEFAULT セクションは存在するとみなされません。
section で指定したセクションで利用できるオプションのリストを返します。
与えられたセクションが存在してかつオプションが与えられていれば True を返し、そうでなければ False を返します。
バージョン 1.6 で追加.
ファイル名のリストを読んで解析をこころみ、うまく解析できたファイル名のリストを返します。もし filenames が文字列かユニコード文字列なら、1つのファイル名として扱われます。 filenames で指定されたファイルが開けない場合、そのファイルは無視されます。この挙動は設定ファイルが置かれる可能性のある場所(例えば、カレントディレクトリ、ホームディレクトリ、システム全体の設定を行うディレクトリ)を設定して、そこに存在する設定ファイルを読むことを想定して設計されています。設定ファイルが存在しなかった場合、 ConfigParser のインスタンスは空のデータセットを持ちます。初期値の設定ファイルを先に読み込んでおく必要があるアプリケーションでは、 readfp() を read() の前に呼び出すことでそのような動作を実現できます:
import ConfigParser, os
config = ConfigParser.ConfigParser()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
バージョン 2.4 で変更: うまく解析できたファイル名のリストを返す.
fp で与えられるファイルかファイルのようなオブジェクトを読み込んで構文解析します(readline() メソッドだけを使います)。もし filename が省略されて fp が name 属性を持っていれば filename の代わりに使われます。ファイル名の初期値は <???> です。
section の option 変数を取得します。
section の option を整数として評価する関数です。
section の option を浮動小数点数として評価する関数です。
指定した section の option 値をブール値に型強制する便宜メソッドです。 option として受理できる値は、真 (True) としては "1" 、 "yes" 、 "true" 、 "on" 、偽 (False) としては "0" 、 "no" 、 "false" 、 "off" です。これらの文字列値に対しては大文字小文字の区別をしません。その他の値の場合には ValueError を送出します。
与えられた section のそれぞれのオプションについて (name, value) ペアのリストを返します。
与えられたセクションが存在していれば、オプションを指定された値に設定します。セクションが存在しなければ NoSectionError を発生させます。 RawConfigParser (あるいは raw パラメータをセットした ConfigParser) を文字列型でない値の 内部的な 格納場所として使うことは可能ですが、すべての機能 (置換やファイルへの出力を含む) がサポートされるのは文字列を値として使った場合だけです。
バージョン 1.6 で追加.
設定を文字列表現に変換してファイルオブジェクトに書き出します。この文字列表現は read() で読み込むことができます。
バージョン 1.6 で追加.
指定された section から指定された option を削除します。セクションが存在しなければ、 NoSectionError を起こします。存在するオプションを削除した時は True を、そうでない時は False を返します。
バージョン 1.6 で追加.
指定された section を設定から削除します。もし指定されたセクションが存在すれば True 、そうでなければ False を返します。
入力ファイル中に見つかったオプション名か、クライアントコードから渡されたオプション名 option を、内部で利用する形式に変換します。デフォルトでは option を全て小文字に変換した名前が返されます。サブルクラスではこの関数をオーバーライドすることでこの振舞いを替えることができます。
振舞いを替えるために ConfigParser を継承して新たにクラスを作る必要はありません、あるインスタンスのメソッドを文字列を引数に取る関数で置き換えることもできます。たとえば、このメソッドを str() に設定することで大小文字の差を区別するように変更することができます:
cfgparser = ConfigParser()
...
cfgparser.optionxform = str
設定ファイルを読み込むときには、 optionxform() が呼ばれる前にオプション名の前後の空白文字が取り除かれることに注意してください。
ConfigParser クラスは RawConfigParser のインターフェースをいくつかのメソッドについて拡張し、省略可能な引数を追加しています。
section の option 変数を取得します。このメソッドに渡される vars は辞書でなくてはいけません。 (もし渡されているならば) vars 、 section 、 defaults の順に option が探されます。
raw が真でない時には、全ての '%' 置換は展開されてから返されます。置換後の値はオプションと同じ順序で探されます
指定した section 内の各オプションに対して、 (name, value) のペアからなるリストを返します。省略可能な引数は get() メソッドと同じ意味を持ちます。
バージョン 2.3 で追加.
SafeConfigParser は ConfigParser と同様の拡張インターフェイスをもっていますが、以下のような機能が追加されています:
もし与えられたセクションが存在している場合は、指定された値を与えられたオプションに設定します。そうでない場合は NoSectionError を発生させます。 value は文字列 (str または unicode) でなければならず、そうでない場合には TypeError が発生します。
バージョン 2.4 で追加.
configurationファイルを書き出す例:
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', 'int', '15')
config.set('Section1', 'bool', 'true')
config.set('Section1', '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)
configurationファイルを読み込む例:
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
float = config.getfloat('Section1', 'float')
int = config.getint('Section1', 'int')
print float + 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', 'bool'):
print config.get('Section1', 'foo')
置換機能を利用するには、 ConfigParser か 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'