configparser —構成ファイルパーサー—Pythonドキュメント

提供:Dev Guides
< PythonPython/docs/3.8/library/configparser
移動先:案内検索

configparser —構成ファイルパーサー

ソースコード: :source: `Lib / configparser.py`



このモジュールは、 ConfigParser クラスを提供します。このクラスは、Microsoft WindowsINIファイルにあるものと同様の構造を提供する基本的な構成言語を実装します。 これを使用して、エンドユーザーが簡単にカスタマイズできるPythonプログラムを作成できます。

ノート

このライブラリは、Windowsレジストリ拡張バージョンのINI構文で使用される値型プレフィックスを解釈または書き込みません


も参照してください

モジュール shlex
アプリケーション構成ファイルの代替形式として使用できるUnixシェルのようなミニ言語の作成のサポート。
モジュール json
jsonモジュールは、この目的にも使用できるJavaScript構文のサブセットを実装します。


クイックスタート

次のような非常に基本的な構成ファイルを見てみましょう。

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

[bitbucket.org]
User = hg

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

INIファイルの構造については、次のセクションで説明します。 基本的に、ファイルはセクションで構成され、各セクションには値を持つキーが含まれています。 configparser クラスは、このようなファイルの読み取りと書き込みを行うことができます。 プログラムで上記の構成ファイルを作成することから始めましょう。

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

上記のように、APIは非常に単純です。 ほんの少しの魔法は、他のすべてのセクション 1 のデフォルト値を提供するDEFAULTセクションに関係しています。 セクション内のキーでは大文字と小文字が区別されず、小文字の 1 で格納されることにも注意してください。


サポートされているデータ型

構成パーサーは、構成ファイル内の値のデータ型を推測せず、常に内部的に文字列として格納します。 つまり、他のデータ型が必要な場合は、自分で変換する必要があります。

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0

このタスクは非常に一般的であるため、configパーサーは、整数、浮動小数点数、およびブール値を処理するためのさまざまな便利なゲッターメソッドを提供します。 bool('False')はまだTrueであるため、値をbool()に渡すだけでは効果がないため、最後の1つが最も興味深いものです。 これが、構成パーサーが getboolean()も提供する理由です。 このメソッドは大文字と小文字を区別せず、'yes' / 'no''on' / 'off''true' / [からブール値を認識します。 X123X]および'1' / '0' 1 。 例えば:

>>> topsecret.getboolean('ForwardX11')
False
>>> config['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', 'Compression')
True

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.com'から取得しようとすると、フォールバックを指定した場合でも、常にデフォルトが取得されます。

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

もう1つ注意すべき点は、パーサーレベルのget()メソッドは、下位互換性のために維持された、カスタムのより複雑なインターフェイスを提供することです。 この方法を使用する場合、フォールバック値はfallbackキーワードのみの引数を介して提供できます。

>>> config.get('bitbucket.org', '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 )が前に付いたコメントが含まれる場合があります。 コメントは、それ以外の場合は空の行に単独で表示される場合があり、インデントされる可能性があります。 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?

値の補間

コア機能に加えて、 ConfigParser は補間をサポートします。 これは、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%%  # use a %% to escape the % sign (% is the only character that needs to be escaped)

上記の例では、補間BasicInterpolation()に設定された ConfigParser は、%(home_dir)shome_dir/Users)。 %(my_dir)sは、事実上/Users/lumberjackに解決されます。 すべての補間はオンデマンドで実行されるため、参照のチェーンで使用されるキーは、構成ファイルで特定の順序で指定する必要はありません。

interpolationNoneに設定すると、パーサーはmy_picturesの値として%(my_dir)s/Picturesを返し、my_dir

class configparser.ExtendedInterpolation

たとえばzc.buildoutで使用される、より高度な構文を実装する補間の代替ハンドラー。 拡張補間では、${section:option}を使用して、外部セクションからの値を示します。 補間は複数のレベルにまたがることができます。 便宜上、section:の部分を省略した場合、補間はデフォルトで現在のセクション(および場合によっては特別なセクションのデフォルト値)になります。

たとえば、基本的な補間を使用して上記で指定した構成は、拡張補間を使用すると次のようになります。

[Paths]
home_dir: /Users
my_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Pictures

[Escape]
cost: $$80  # use a $$ to escape the $ sign ($ is the only character that needs to be escaped)

他のセクションからの値もフェッチできます。

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


マッピングプロトコルアクセス

バージョン3.2の新機能。


マッピングプロトコルアクセスは、カスタムオブジェクトを辞書であるかのように使用できるようにする機能の総称です。 configparser の場合、マッピングインターフェイスの実装はparser['section']['option']表記を使用しています。

特にparser['section']は、パーサー内のセクションのデータのプロキシを返します。 これは、値がコピーされないが、オンデマンドで元のパーサーから取得されることを意味します。 さらに重要なのは、セクションプロキシで値が変更されると、元のパーサーで実際に値が変更されることです。

configparser オブジェクトは、実際の辞書にできるだけ近い動作をします。 マッピングインターフェイスは完全で、 MutableMapping ABCに準拠しています。 ただし、考慮すべきいくつかの違いがあります。

  • デフォルトでは、セクション内のすべてのキーは大文字と小文字を区別しない方法でアクセスできます 1 。 例えば for option in parser["section"]は、optionxformのオプションキー名のみを生成します。 これは、デフォルトで小文字のキーを意味します。 同時に、キー'a'を保持するセクションの場合、両方の式はTrueを返します。

    "a" in parser["section"]
    "A" in parser["section"]
  • すべてのセクションにはDEFAULTSECT値も含まれています。つまり、セクションの.clear()は、セクションを視覚的に空のままにしない場合があります。 これは、デフォルト値をセクションから削除できないためです(技術的にはデフォルト値がないため)。 セクションでオーバーライドされている場合、削除するとデフォルト値が再び表示されます。 デフォルト値を削除しようとすると、 KeyError が発生します。

  • DEFAULTSECTをパーサーから削除できません。

    • 削除しようとすると ValueError が発生し、

    • parser.clear()はそのままにします、

    • parser.popitem()はそれを返しません。

  • parser.get(section, option, **kwargs) -2番目の引数はではなくフォールバック値です。 ただし、セクションレベルのget()メソッドは、マッピングプロトコルと従来のconfigparserAPIの両方と互換性があることに注意してください。

  • parser.items()はマッピングプロトコルと互換性があります(DEFAULTSECTを含む section_namesection_proxy ペアのリストを返します)。 ただし、このメソッドは引数parser.items(section, raw, vars)を使用して呼び出すこともできます。 後者の呼び出しは、指定されたsectionoptionvalue ペアのリストを返し、すべての補間が展開されます(raw=Trueが提供されている場合を除く)。

マッピングプロトコルは既存のレガシーAPIの上に実装されているため、元のインターフェイスをオーバーライドするサブクラスでも、期待どおりにマッピングが機能するはずです。


パーサーの動作のカスタマイズ

INI形式のバリエーションは、それを使用するアプリケーションとほぼ同じです。 configparser は、利用可能なINIスタイルの最大の実用的なセットのサポートを提供するのに大いに役立ちます。 デフォルトの機能は主に歴史的背景によって決定され、一部の機能をカスタマイズする可能性が非常に高くなります。

特定の構成パーサーの動作方法を変更する最も一般的な方法は、__init__()オプションを使用することです。

  • デフォルト、デフォルト値:None

    このオプションは、最初にDEFAULTセクションに配置されるキーと値のペアのディクショナリを受け入れます。 これにより、文書化されたデフォルトと同じ値を指定しない簡潔な構成ファイルをサポートするための洗練された方法が実現します。

    ヒント:特定のセクションのデフォルト値を指定する場合は、実際のファイルを読み取る前にread_dict()を使用してください。

  • dict_type 、デフォルト値: dict

    このオプションは、マッピングプロトコルの動作と、書き込まれた構成ファイルの外観に大きな影響を与えます。 標準辞書では、すべてのセクションがパーサーに追加された順序で格納されます。 セクション内のオプションについても同じことが言えます。

    代替の辞書タイプを使用して、たとえば、書き戻しのセクションとオプションを並べ替えることができます。

    注意:1回の操作でキーと値のペアのセットを追加する方法があります。 これらの操作で通常の辞書を使用すると、キーの順序が並べられます。 例えば:

    >>> 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'
  • 区切り文字、デフォルト値:('=', ':')

    区切り文字は、セクション内の値からキーを区切る部分文字列です。 行で最初に出現する区切り文字列は、区切り文字と見なされます。 これは、値(キーではない)に区切り文字を含めることができることを意味します。

    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

    Trueに設定すると、パーサーは、単一のソースからの読み取り中にセクションまたはオプションの重複を許可しません(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'

    これは、ユーザーがプロポーショナルフォントを使用してファイルを編集しているかどうかを確認するのに特に問題になる可能性があります。 そのため、アプリケーションで空行の値が必要ない場合は、それらを禁止することを検討する必要があります。 これにより、空の行が毎回キーを分割します。 上記の例では、keythisの2つのキーが生成されます。

  • default_section 、デフォルト値:configparser.DEFAULTSECT(つまり、"DEFAULT"

    他のセクションまたは補間の目的でデフォルト値の特別なセクションを許可するという規則は、このライブラリの強力な概念であり、ユーザーが複雑な宣言型構成を作成できるようにします。 このセクションは通常"DEFAULT"と呼ばれますが、他の有効なセクション名を指すようにカスタマイズできます。 一般的な値には、"general"または"common"があります。 指定された名前は、任意のソースから読み取るときにデフォルトセクションを認識するために使用され、構成をファイルに書き戻すときに使用されます。 その現在の値は、parser_instance.default_section属性を使用して取得でき、実行時に変更できます(つまり、 ファイルをある形式から別の形式に変換するため)。

  • 補間、デフォルト値:configparser.BasicInterpolation

    補間動作は、 interpolation 引数を介してカスタムハンドラーを提供することでカスタマイズできます。 Noneは、補間を完全にオフにするために使用できます。ExtendedInterpolation()は、zc.buildoutに触発されたより高度なバリアントを提供します。 このテーマの詳細については、専用ドキュメントセクションをご覧ください。 RawConfigParser のデフォルト値はNoneです。

  • コンバーター、デフォルト値:未設定

    構成パーサーは、型変換を実行するオプション値ゲッターを提供します。 デフォルトでは、 getint()getfloat()、および getboolean()が実装されています。 他のゲッターが望ましい場合、ユーザーはサブクラスでそれらを定義するか、各キーがコンバーターの名前であり、各値がその変換を実装する呼び出し可能である辞書を渡すことができます。 たとえば、{'decimal': decimal.Decimal}を渡すと、パーサーオブジェクトとすべてのセクションプロキシの両方にgetdecimal()が追加されます。 つまり、parser_instance.getdecimal('section', 'key', fallback=0)parser_instance['section'].getdecimal('key', 0)の両方を書き込むことが可能になります。

    コンバーターがパーサーの状態にアクセスする必要がある場合は、構成パーサーサブクラスのメソッドとして実装できます。 このメソッドの名前がgetで始まる場合、すべてのセクションプロキシで、dict互換形式で使用できます(上記のgetdecimal()の例を参照)。

これらのパーサー属性のデフォルト値をオーバーライドすることで、より高度なカスタマイズを実現できます。 デフォルトはクラスで定義されているため、サブクラスまたは属性の割り当てによってオーバーライドされる場合があります。

ConfigParser.BOOLEAN_STATES

デフォルトでは、 getboolean()を使用する場合、構成パーサーは次の値Trueを考慮します:'1''yes''true'、[X134X ] および次の値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()

# 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={})

メイン構成パーサー。 defaults が指定されると、組み込みデフォルトのディクショナリに初期化されます。 dict_type を指定すると、セクションのリスト、セクション内のオプション、およびデフォルト値のディクショナリオブジェクトを作成するために使用されます。

区切り文字を指定すると、キーと値を分割するサブストリングのセットとして使用されます。 comment_prefixes を指定すると、空の行のコメントの前に付けるサブストリングのセットとして使用されます。 コメントはインデントできます。 inline_comment_prefixes を指定すると、空でない行のコメントの前に付けるサブストリングのセットとして使用されます。

strictTrue(デフォルト)の場合、パーサーは単一のソース(ファイル、文字列、または辞書)からの読み取り中にセクションまたはオプションの重複を許可せず、を発生させます。 DuplicateSectionError または DuplicateOptionErrorempty_lines_in_valuesFalse(デフォルト:True)の場合、空の各行はオプションの終わりを示します。 それ以外の場合、複数行オプションの内部空行は値の一部として保持されます。 allow_no_valueTrue(デフォルト:False)の場合、値のないオプションが受け入れられます。 これらに保持される値はNoneであり、末尾の区切り文字なしでシリアル化されます。

default_section を指定すると、他のセクションおよび補間の目的でデフォルト値を保持する特別なセクションの名前が指定されます(通常は"DEFAULT"という名前)。 この値は、default_sectionインスタンス属性を使用して、実行時に取得および変更できます。

補間動作は、 interpolation 引数を介してカスタムハンドラーを提供することでカスタマイズできます。 Noneは、補間を完全にオフにするために使用できます。ExtendedInterpolation()は、zc.buildoutに触発されたより高度なバリアントを提供します。 このテーマの詳細については、専用ドキュメントセクションをご覧ください。

補間で使用されるすべてのオプション名は、他のオプション名参照と同様に、 optionxform()メソッドを介して渡されます。 たとえば、 optionxform()(オプション名を小文字に変換する)のデフォルトの実装を使用すると、値foo %(bar)sfoo %(BAR)sは同等になります。

コンバーターが指定されている場合、各キーが型コンバーターの名前を表し、各値が文字列から目的のデータ型への変換を実装する呼び出し可能である辞書である必要があります。 すべてのコンバーターは、パーサーオブジェクトとセクションプロキシで対応するget*()メソッドを取得します。

バージョン3.1で変更:デフォルトの dict_typecollections.OrderedDict です。

バージョン3.2で変更: allow_no_value区切り文字comment_prefixesstrictempty_lines_in_valuesdefault_section および補間が追加されました。

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

バージョン3.7で変更: defaults 引数は read_dict()で読み取られ、パーサー全体で一貫した動作を提供します。文字列以外のキーと値は暗黙的にに変換されます。文字列。

バージョン3.8で変更:デフォルトの dict_typedict です。これは、挿入順序が保持されるようになったためです。

defaults()

インスタンス全体のデフォルトを含むディクショナリを返します。

sections()

利用可能なセクションのリストを返します。 デフォルトセクションはリストに含まれていません。

add_section(section)

section という名前のセクションをインスタンスに追加します。 指定された名前のセクションがすでに存在する場合、 DuplicateSectionError が発生します。 デフォルトセクション名が渡されると、 ValueError が発生します。 セクションの名前は文字列である必要があります。 そうでない場合は、 TypeError が発生します。

バージョン3.2で変更:非文字列セクション名は TypeError を発生させます。

has_section(section)

指定されたセクションが構成に存在するかどうかを示します。 デフォルトセクションは確認されません。

options(section)

指定されたセクションで使用可能なオプションのリストを返します。

has_option(section, option)

指定されたセクションが存在し、指定されたオプションが含まれている場合は、 True を返します。 それ以外の場合は、 False を返します。 指定されたセクションなしまたは空の文字列の場合、DEFAULTが想定されます。

read(filenames, encoding=None)

反復可能なファイル名の読み取りと解析を試み、正常に解析されたファイル名のリストを返します。

filenames が文字列、 bytes オブジェクト、または path-like object の場合、単一のファイル名として扱われます。 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 パラメーターは、パスのようなオブジェクトを受け入れます。

バージョン3.7の新機能: filenames パラメーターは bytes オブジェクトを受け入れます。

read_file(f, source=None)

f から構成データを読み取って解析します。これは、反復可能で、Unicode文字列を生成する必要があります(たとえば、テキストモードで開かれたファイル)。

オプションの引数 source は、読み取られるファイルの名前を指定します。 指定されておらず、 fname属性がある場合、これはソースに使用されます。 デフォルトは'<???>'です。

バージョン3.2の新機能: readfp()を置き換えます。

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

文字列から構成データを解析します。

オプションの引数 source は、渡される文字列のコンテキスト固有の名前を指定します。 指定しない場合は、'<string>'が使用されます。 これは通常、ファイルシステムパスまたはURLである必要があります。

バージョン3.2の新機能。

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

dictのようなitems()メソッドを提供する任意のオブジェクトから構成をロードします。 キーはセクション名であり、値はセクションに存在する必要のあるキーと値を含む辞書です。 使用する辞書タイプが順序を保持している場合、セクションとそのキーが順番に追加されます。 値は自動的に文字列に変換されます。

オプションの引数 source は、渡される辞書のコンテキスト固有の名前を指定します。 指定しない場合は、<dict>が使用されます。

このメソッドは、パーサー間で状態をコピーするために使用できます。

バージョン3.2の新機能。

get(section, option, *, raw=False, vars=None[, fallback])

名前付きセクションオプション値を取得します。 vars が提供されている場合、それは辞書である必要があります。 オプションは、 vars (提供されている場合)、セクションDEFAULTSECT の順に検索されます。 キーが見つからず、フォールバックが指定されている場合、そのキーはフォールバック値として使用されます。 Noneは、フォールバック値として提供できます。

raw 引数が真でない限り、すべての'%'補間は戻り値で展開されます。 補間キーの値は、オプションと同じ方法で検索されます。

バージョン3.2で変更:引数 rawvarsfallback は、ユーザーが3番目の引数をフォールバックフォールバック(特にマッピングプロトコルを使用する場合)。

getint(section, option, *, raw=False, vars=None[, fallback])

指定されたセクションオプションを整数に強制する便利なメソッド。 rawvars 、および fallback の説明については、 get()を参照してください。

getfloat(section, option, *, raw=False, vars=None[, fallback])

指定されたセクションオプションを浮動小数点数に強制する便利な方法。 rawvars 、および fallback の説明については、 get()を参照してください。

getboolean(section, option, *, raw=False, vars=None[, fallback])

指定されたセクションオプションをブール値に強制する便利なメソッド。 オプションで受け入れられる値は'1''yes''true'、および'on'であるため、このメソッドはTrueを返すことに注意してください。 、および'0''no''false'、および'off'により、Falseが返されます。 これらの文字列値は、大文字と小文字を区別しない方法でチェックされます。 その他の値を指定すると、 ValueError が発生します。 rawvars 、および fallback の説明については、 get()を参照してください。

items(raw=False, vars=None)
items(section, raw=False, vars=None)

section が指定されていない場合は、DEFAULTSECTを含む section_namesection_proxy ペアのリストを返します。

それ以外の場合は、指定されたセクションのオプションの名前のペアのリストを返します。 オプションの引数は、 get()メソッドの場合と同じ意味です。

バージョン3.8で変更: vars に存在するアイテムは結果に表示されなくなりました。 以前の動作では、実際のパーサーオプションと補間用に提供された変数が混在していました。

set(section, option, value)

指定されたセクションが存在する場合は、指定されたオプションを指定された値に設定します。 それ以外の場合は、 NoSectionError を発生させます。 option および value は文字列である必要があります。 そうでない場合は、 TypeError が発生します。

write(fileobject, space_around_delimiters=True)

指定されたファイルオブジェクトに構成の表現を書き込みます。これは、テキストモードで開く必要があります(文字列を受け入れる)。 この表現は、将来の read()呼び出しによって解析できます。 space_around_delimiters がtrueの場合、キーと値の間の区切り文字はスペースで囲まれます。

remove_option(section, option)

指定されたセクションから指定されたオプションを削除します。 セクションが存在しない場合は、 NoSectionError を発生させます。 削除するオプションが存在する場合は、 True を返します。 それ以外の場合は、 False を返します。

remove_section(section)

指定されたセクションを構成から削除します。 セクションが実際に存在した場合は、Trueを返します。 それ以外の場合は、Falseを返します。

optionxform(option)

入力ファイルで見つかった、またはクライアントコードによって渡されたオプション名 option を、内部構造で使用する必要のある形式に変換します。 デフォルトの実装は、 option の小文字バージョンを返します。 サブクラスがこれをオーバーライドする場合や、クライアントコードがインスタンスにこの名前の属性を設定して、この動作に影響を与える場合があります。

このメソッドを使用するためにパーサーをサブクラス化する必要はありません。インスタンスで、文字列引数を取り、文字列を返す関数に設定することもできます。 たとえば、strに設定すると、オプション名で大文字と小文字が区別されます。

cfgparser = ConfigParser()
cfgparser.optionxform = str

構成ファイルを読み取る場合、 optionxform()が呼び出される前に、オプション名の前後の空白が削除されることに注意してください。

readfp(fp, filename=None)

バージョン3.2以降非推奨:代わりに read_file()を使用してください。

バージョン3.2で変更: readfp()は、fp.readline()を呼び出す代わりに、 fp で反復するようになりました。

反復をサポートしない引数を使用して readfp()を呼び出す既存のコードの場合、次のジェネレーターをファイルのようなオブジェクトのラッパーとして使用できます。

def readline_generator(fp):
    line = fp.readline()
    while line:
        yield line
        line = fp.readline()

parser.readfp(fp)の代わりにparser.read_file(readline_generator(fp))を使用してください。

configparser.MAX_INTERPOLATION_DEPTH
raw パラメーターがfalseの場合の、get()の再帰的補間の最大深度。 これは、デフォルトの補間が使用されている場合にのみ関係します。


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])

ConfigParser のレガシーバリアント。 デフォルトでは補間が無効になっており、安全でないadd_sectionおよびsetメソッド、および従来のdefaults=キーワードを介して、文字列以外のセクション名、オプション名、値を使用できます。引数の処理。

バージョン3.8で変更:デフォルトの dict_typedict です。これは、挿入順序が保持されるようになったためです。

ノート

代わりに ConfigParser を使用することを検討してください。これは、内部に格納される値のタイプをチェックします。 補間が必要ない場合は、ConfigParser(interpolation=None)を使用できます。

add_section(section)

section という名前のセクションをインスタンスに追加します。 指定された名前のセクションがすでに存在する場合、 DuplicateSectionError が発生します。 デフォルトセクション名が渡されると、 ValueError が発生します。

セクションのタイプはチェックされていないため、ユーザーは文字列以外の名前のセクションを作成できます。 この動作はサポートされておらず、内部エラーが発生する可能性があります。

set(section, option, value)

指定されたセクションが存在する場合は、指定されたオプションを指定された値に設定します。 それ以外の場合は、 NoSectionError を発生させます。 非文字列値の内部ストレージに RawConfigParser (または raw パラメーターをtrueに設定した ConfigParser )を使用することは可能ですが、完全な機能(補間とファイルへの出力を含む)は、文字列値を使用してのみ実現できます。

このメソッドを使用すると、ユーザーは文字列以外の値をキーに内部的に割り当てることができます。 この動作はサポートされておらず、ファイルへの書き込みまたは非rawモードでの取得を試みるとエラーが発生します。 そのような割り当てを許可しないマッピングプロトコルAPI を使用してください。


例外

exception configparser.Error
他のすべての configparser 例外の基本クラス。
exception configparser.NoSectionError
指定されたセクションが見つからない場合に発生する例外。
exception configparser.DuplicateSectionError

add_section()がすでに存在するセクションの名前で呼び出された場合、またはセクションが単一の入力ファイル、文字列、または辞書で複数回見つかった場合に厳密なパーサーで呼び出された場合に例外が発生します。

バージョン3.2の新機能:オプションのsourceおよびlineno属性と__init__()への引数が追加されました。

exception configparser.DuplicateOptionError
単一のファイル、文字列、または辞書からの読み取り中に単一のオプションが2回表示される場合、厳密なパーサーによって例外が発生します。 これにより、スペルミスや大文字と小文字の区別に関連するエラーが検出されます。 辞書には、大文字と小文字を区別しない同じ構成キーを表す2つのキーが含まれる場合があります。
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.2で変更: filename属性と__init__()引数は、一貫性を保つためにsourceに名前が変更されました。

脚注

1123456 、[ X67X] 7 、 8910
構成パーサーは、大幅なカスタマイズを可能にします。 脚注の参照で概説されている動作の変更に興味がある場合は、パーサーの動作のカスタマイズセクションを参照してください。