configparser — Configuration file parser

소스 코드: Lib/configparser.py


이 모듈은 마이크로소프트 윈도우 INI 파일과 유사한 구조를 제공하는 기본 구성 언어를 구현하는 ConfigParser 클래스를 제공합니다. 이를 사용하여 최종 사용자가 쉽게 사용자 정의 할 수 있는 파이썬 프로그램을 작성할 수 있습니다.

참고

이 라이브러리는 윈도우 레지스트리 확장 버전의 INI 문법에 사용된 값-형 접두사를 해석하거나 기록하지 않습니다.

더 보기

Module tomllib

TOML is a well-specified format for application configuration files. It is specifically designed to be an improved version of INI.

모듈 shlex

Support for creating Unix shell-like mini-languages which can also be used for application configuration files.

모듈 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 = 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.

지원되는 데이터형

구성 구문 분석기는 구성 파일에 있는 값의 데이터형을 추측하지 않고, 항상 내부적으로 문자열로 저장합니다. 이것은 다른 데이터형이 필요하면, 직접 변환해야 함을 뜻합니다:

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

이 작업이 매우 흔하기 때문에, 구성 구문 분석기는 정수, 부동 소수점 및 불리언을 처리하는 편리한 게터(getter) 메서드를 제공합니다. 마지막 것이 가장 흥미로운데, bool('False') 가 여전히 True이기 때문에 bool() 에 값을 전달하는 것만으로는 충분치 않기 때문입니다. 이것이 구성 구문 분석기가 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

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'

Please note that default values have precedence over fallback values. For instance, in our example the 'CompressionLevel' key was specified only in the 'DEFAULT' section. If we try to get it from the section 'topsecret.server.example', we will always get the default, even if we specify a fallback:

>>> 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'

getint(), getfloat()getboolean() 메서드에 같은 fallback 인자를 사용할 수 있습니다. 예를 들면:

>>> '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%%

위의 예에서, interpolationBasicInterpolation() 으로 설정된 ConfigParser%(home_dir)shome_dir의 값(이 경우 /Users)으로 해석합니다. 결과적으로 %(my_dir)s/Users/lumberjack으로 해석됩니다. 모든 보간은 요청 시 수행되므로 참조 체인에 사용된 키를 구성 파일에서 특정 순서로 지정할 필요는 없습니다.

interpolationNone으로 설정하면, 구문 분석기는 my_pictures의 값을 %(my_dir)s/Pictures로, my_dir의 값을 %(home_dir)s/lumberjack으로 반환합니다.

class configparser.ExtendedInterpolation

예를 들어 zc.buildout에서 사용되는 고급 문법을 구현하는 보간 대체 처리기. 확장 보간은 ${section:option}을 사용하여 외부 섹션의 값을 나타냅니다. 보간은 여러 수준으로 확장될 수 있습니다. 편의상, section: 부분을 생략하면, 보간은 현재 섹션(그리고 가능하면 특수 섹션의 기본값)으로 기본 설정됩니다.

예를 들어, 기본 보간으로 위에서 지정한 구성은, 확장 보간으로는 다음과 같습니다:

[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 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) - 두 번째 인자는 대체 값이 아닙니다. 그러나 섹션 수준 get() 메서드는 매핑 프로토콜과 클래식 configparser API와 모두 호환됨에 유의하십시오.

  • parser.items()는 매핑 프로토콜과 호환됩니다 (DEFAULTSECT를 포함하여 section_name, section_proxy 쌍의 리스트를 반환합니다). 그러나, 이 메서드는 인자와 함께 호출 할 수도 있습니다: parser.items(section, raw, vars). 후자의 호출은 지정된 section에 대한 option, value 쌍의 리스트를 반환하며, 모든 보간이 확장됩니다 (raw=True가 제공되지 않는 한).

매핑 프로토콜은 기존 레거시 API 위에 구현되므로 원래 인터페이스를 재정의하는 서브 클래스에서도 여전히 매핑이 작동해야 합니다.

구문 분석기 동작 사용자 정의

INI 형식을 사용하는 응용 프로그램만큼이나 많은 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, 기본값: ('=', ':')

    구분자(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'
    

    이것은 사용자가 가변 폭 글꼴을 사용하여 파일을 편집하고 있다면, 보는 데 특히 문제가 될 수 있습니다. 따라서 응용 프로그램에 빈 줄이 있는 값이 필요하지 않으면, 허용하지 않는 것이 좋습니다. 이렇게 하면 빈 줄이 매번 키를 분리합니다. 위의 예에서는, keythis의 두 키를 생성합니다.

  • 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으로 시작하면, 모든 섹션 프락시에서 dict 호환 형식으로 사용할 수 있습니다 (위의 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/rejectenabled/disabled가 포함됩니다.

ConfigParser.optionxform(option)

이 메서드는 모든 읽기, get 또는 set 연산에서 옵션 이름을 변환합니다. 기본값은 이름을 소문자로 변환합니다. 이는 또한 구성 파일을 기록할 때 모든 키가 소문자가 됨을 의미합니다. 이것이 부적절하다면 이 메서드를 재정의하십시오. 예를 들면:

>>> 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 함수는 옵션 이름을 규범적 형식으로 변환합니다. 이 함수는 멱등적(idempotent) 함수여야 합니다: 이름이 이미 규범적 형식이면, 변경되지 않은 상태로 반환해야 합니다.

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_valuedelimiters를 방해하기 때문에 재정의하지 않는 것이 좋습니다.

레거시 API 예제

주로 이전 버전과의 호환성 문제로 인해, configparser는 명시적인 get/set 메서드로 레거시 API도 제공합니다. 아래에 설명된 메서드에 대한 유효한 사용 사례가 있지만, 새 프로젝트에는 매핑 프로토콜 액세스가 선호됩니다. 레거시 API는 때때로 더 고급이고, 저수준(low-level)이며 완전히 반 직관적입니다.

구성 파일에 쓰는 예:

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

기본값은 두 가지 유형의 ConfigParser 모두에서 사용할 수 있습니다. 사용된 옵션이 다른 곳에 정의되어 있지 않으면 보간에 사용됩니다.

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이 제공되면, 섹션 리스트, 섹션 내의 옵션 및 기본값에 대한 딕셔너리 객체를 만드는 데 사용됩니다.

delimiters가 주어지면, 키를 값과 나누는 부분 문자열 집합으로 사용됩니다. comment_prefixes가 주어지면, 주석이 없다면 빈 줄일 곳에서 주석을 시작하는 접두사의 부분 문자열 집합으로 사용됩니다. 주석은 들여 쓸 수 있습니다. inline_comment_prefixes가 주어지면, 비어 있지 않은 줄에서 주석을 시작하는 접두사의 부분 문자열 집합으로 사용됩니다.

strictTrue(기본값)이면, 구문 분석기는 단일 소스(파일, 문자열 또는 딕셔너리)에서 읽는 동안 섹션이나 옵션의 중복을 허용하지 않고, DuplicateSectionErrorDuplicateOptionError를 발생시킵니다. empty_lines_in_valuesFalse이면 (기본값: True), 각 빈 줄은 옵션의 끝을 나타냅니다. 그렇지 않으면, 여러 줄 옵션의 내부 빈 줄이 값의 일부로 유지됩니다. allow_no_valueTrue이면 (기본값: 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)sfoo %(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.

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_typecollections.OrderedDict입니다.

버전 3.2에서 변경: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_sectioninterpolation이 추가되었습니다.

버전 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에서 변경: 이제 삽입 순서를 유지하므로, 기본 dict_typedict입니다.

버전 3.13에서 변경: Raise a MultilineContinuationError when allow_no_value is True, and a key without a value is continued with an indented line.

defaults()

인스턴스 전체 기본값을 포함하는 딕셔너리를 반환합니다.

sections()

사용 가능한 섹션 리스트를 반환합니다; 기본값 섹션은 리스트에 포함되지 않습니다.

add_section(section)

section이라는 섹션을 인스턴스에 추가합니다. 주어진 이름의 섹션이 이미 존재하면, DuplicateSectionError 가 발생합니다. 기본값 섹션 이름이 전달되면, ValueError가 발생합니다. 섹션의 이름은 문자열이어야 합니다; 그렇지 않으면, TypeError가 발생합니다.

버전 3.2에서 변경: 문자열이 아닌 섹션 이름은 TypeError를 발생시킵니다.

has_section(section)

이름 지정된 section이 구성에 있는지를 나타냅니다. 기본값 섹션은 인정되지 않습니다.

options(section)

지정된 section에서 사용 가능한 옵션 리스트를 반환합니다.

has_option(section, option)

주어진 section이 존재하고, 주어진 option을 포함하면, True를 반환합니다; 그렇지 않으면 False를 반환합니다. 지정된 sectionNone이거나 빈 문자열이면, DEFAULT로 가정합니다.

read(filenames, encoding=None)

파일명들의 이터러블을 읽고 구문 분석하여, 성공적으로 구문 분석된 파일명의 리스트를 반환합니다.

filenames가 문자열, bytes 객체 또는 경로류 객체이면 단일 파일명으로 처리됩니다. 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 매개 변수는 경로류 객체를 받아들입니다.

버전 3.7에서 변경: filenames 매개 변수는 bytes 객체를 받아들입니다.

read_file(f, source=None)

f에서 구성 데이터를 읽고 구문 분석합니다. f는 유니코드 문자열을 산출하는 이터러블 이어야 합니다 (예를 들어 텍스트 모드로 열린 파일).

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: Replaces readfp().

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

문자열에서 구성 데이터를 구문 분석합니다.

선택적 인자 source는 전달된 string의 문맥 특정 이름을 지정합니다. 지정하지 않으면, '<string>'이 사용됩니다. 일반적으로 파일 시스템 경로나 URL이어야 합니다.

Added in version 3.2.

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

딕셔너리와 같은 items() 메서드를 제공하는 임의의 객체에서 구성을 로드합니다. 키는 섹션 이름이며, 값은 섹션에 있어야 하는 키와 값이 들어 있는 딕셔너리입니다. 사용된 딕셔너리 형이 순서를 유지하면, 섹션과 해당 키가 순서대로 추가됩니다. 값은 자동으로 문자열로 변환됩니다.

선택적 인자 source는 전달된 dictionary의 문맥 특정 이름을 지정합니다. 지정하지 않으면, <dict>가 사용됩니다.

이 메서드를 사용하면 구문 분석 기간에 상태를 복사할 수 있습니다.

Added in version 3.2.

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

명명된 section에서 option 값을 가져옵니다. vars가 제공되면, 딕셔너리이어야 합니다. optionvars (제공되면), sectionDEFAULTSECT 에서 순서대로 조회됩니다. 키를 찾을 수 없고 fallback이 제공되면, 대체 값으로 사용됩니다. Nonefallback 값으로 제공될 수 있습니다.

raw 인자가 참이 아닌 한, 모든 '%' 보간이 반환 값에서 확장됩니다. 보간 키의 값은 옵션과 같은 방식으로 조회됩니다.

버전 3.2에서 변경: 인자 raw, varsfallback은 사용자가 세 번째 인자를 fallback 폴 백으로 사용하지 못하도록 하기 위해 키워드 전용입니다 (특히 매핑 프로토콜을 사용할 때).

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

지정된 sectionoption을 정수로 강제 변환하는 편의 메서드. raw, varsfallback에 대한 설명은 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])

지정된 sectionoption을 불리언 값으로 강제 변환하는 편의 메서드. 옵션에 허용되는 값은 이 메서드가 True를 반환하게 하는 '1', 'yes', 'true''on'False를 반환하게 하는 '0', 'no', 'false''off'입니다. 이 문자열 값은 대소 문자를 구분하지 않고 확인됩니다. 다른 모든 값은 ValueError를 발생시킵니다. raw, varsfallback에 대한 설명은 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를 발생시킵니다. optionvalue는 문자열이어야 합니다; 그렇지 않으면, TypeError가 발생합니다.

write(fileobject, space_around_delimiters=True)

텍스트 모드로 열렸어야 하는 (문자열을 받아들이는), 지정된 파일 객체에 구성의 표현을 기록합니다. 이 표현은 향후 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)

지정된 section에서 지정된 option을 제거합니다. 섹션이 존재하지 않으면, 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])

ConfigParser의 레거시 변형. 기본적으로 보간이 비활성화되어 있으며 레거시 defaults= 키워드 인자 처리뿐만 아니라 안전하지 않은 add_sectionset 메서드를 통해 문자열이 아닌 섹션 이름, 옵션 이름 및 값을 허용합니다.

버전 3.8에서 변경: 이제 삽입 순서를 유지하므로, 기본 dict_typedict입니다.

참고

내부에 저장되는 값의 형을 검사하는 ConfigParser를 대신 사용하는 것을 고려하십시오. 보간을 원하지 않으면, ConfigParser(interpolation=None) 을 사용할 수 있습니다.

add_section(section)

section이라는 이름의 섹션을 인스턴스에 추가합니다. 주어진 이름의 섹션이 이미 존재하면, DuplicateSectionError 가 발생합니다. 기본값 섹션 이름이 전달되면, ValueError가 발생합니다.

section의 형을 검사하지 않아서 사용자가 문자열이 아닌 섹션을 만들 수 있도록 합니다. 이 동작은 지원되지 않으며 내부 에러를 일으킬 수 있습니다.

set(section, option, value)

주어진 섹션이 존재하면, 주어진 옵션을 지정된 값으로 설정합니다; 그렇지 않으면 NoSectionError를 발생시킵니다. 문자열이 아닌 값을 내부에 저장하도록 RawConfigParser(또는 raw 매개 변수가 참으로 설정된 ConfigParser)를 사용할 수 있지만, 전체 기능(보간과 파일로의 출력을 포함하는)은 문자열 값으로만 수행할 수 있습니다.

이 메서드를 사용하면 문자열이 아닌 값을 키에 내부적으로 대입할 수 있습니다. 이 동작은 지원되지 않으며 파일에 쓰려고 하거나 비 원시 모드에서 가져오려고 할 때 에러가 발생합니다. 이러한 대입을 허용하지 않는 매핑 프로토콜 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.

각주