`configparser` — Parser für Konfigurationsdateien¶

Quellcode: Lib/configparser.py

Dieses Modul stellt die Klasse ConfigParser bereit, die eine grundlegende Konfigurationssprache implementiert, die eine Struktur ähnlich der in Microsoft Windows INI-Dateien aufweist. Sie können dies verwenden, um Python-Programme zu schreiben, die von Endbenutzern einfach angepasst werden können.

Hinweis

Diese Bibliothek interpretiert oder schreibt *nicht* die Werttyp-Präfixe, die in der Windows Registry-Erweiterung der INI-Syntax verwendet werden.

Siehe auch

Modul tomllib: TOML ist ein gut spezifiziertes Format für Konfigurationsdateien von Anwendungen. Es wurde speziell entwickelt, um eine verbesserte Version von INI zu sein.
Modul shlex: Unterstützung für die Erstellung von Mini-Sprachen im Stil der Unix-Shell, die auch für Konfigurationsdateien von Anwendungen verwendet werden können.
Modul json: Das Modul json implementiert eine Teilmenge der JavaScript-Syntax, die manchmal für Konfigurationen verwendet wird, unterstützt jedoch keine Kommentare.

Schnellstart¶

Nehmen wir eine sehr einfache Konfigurationsdatei, die wie folgt aussieht

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

[forge.example]
User = hg

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

Die Struktur von INI-Dateien wird im folgenden Abschnitt beschrieben. Im Wesentlichen besteht die Datei aus Abschnitten, von denen jeder Schlüssel mit Werten enthält. Die Klassen von configparser können solche Dateien lesen und schreiben. Beginnen wir damit, die obige Konfigurationsdatei programmatisch zu erstellen.

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

Wie Sie sehen können, können wir einen Config-Parser wie ein Wörterbuch behandeln. Es gibt Unterschiede, die später erläutert werden, aber das Verhalten ist dem sehr ähnlich, was Sie von einem Wörterbuch erwarten würden.

Nachdem wir nun eine Konfigurationsdatei erstellt und gespeichert haben, lesen wir sie zurück und untersuchen die darin enthaltenen Daten.

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

Wie wir oben sehen können, ist die API ziemlich einfach. Der einzige magische Teil betrifft den Abschnitt DEFAULT, der Standardwerte für alle anderen Abschnitte liefert [1]. Beachten Sie auch, dass Schlüssel in Abschnitten nicht zwischen Groß- und Kleinschreibung unterscheiden und in Kleinbuchstaben gespeichert werden [1].

Es ist möglich, mehrere Konfigurationen in ein einziges ConfigParser zu lesen, wobei die zuletzt hinzugefügte Konfiguration die höchste Priorität hat. Alle widersprüchlichen Schlüssel werden aus der neueren Konfiguration übernommen, während die zuvor vorhandenen Schlüssel beibehalten werden. Das folgende Beispiel liest eine Datei namens override.ini, die widersprüchliche Schlüssel aus der Datei example.ini überschreiben wird.

[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

Dieses Verhalten ist gleichbedeutend mit einem Aufruf von ConfigParser.read() mit mehreren Dateien, die dem Parameter *filenames* übergeben werden.

Unterstützte Datentypen¶

Config-Parser erraten nicht die Datentypen von Werten in Konfigurationsdateien, sondern speichern sie intern immer als Strings. Das bedeutet, dass Sie, wenn Sie andere Datentypen benötigen, diese selbst konvertieren müssen

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

Da diese Aufgabe so häufig vorkommt, bieten Config-Parser eine Reihe nützlicher Getter-Methoden für Integer, Floats und Booleans. Letzteres ist am interessantesten, da das einfache Übergeben des Wertes an bool() nichts nützen würde, da bool('False') immer noch True ist. Deshalb bieten Config-Parser auch getboolean(). Diese Methode unterscheidet nicht zwischen Groß- und Kleinschreibung und erkennt boolesche Werte aus 'yes'/'no', 'on'/'off', 'true'/'false' und '1'/'0' [1]. Zum Beispiel

>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True

Neben getboolean() bieten Config-Parser auch entsprechende Methoden getint() und getfloat(). Sie können Ihre eigenen Konverter registrieren und die bereitgestellten anpassen. [1]

Fallback-Werte¶

Wie bei einem Wörterbuch können Sie die Methode get() eines Abschnitts verwenden, um Fallback-Werte anzugeben

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

Bitte beachten Sie, dass Standardwerte Vorrang vor Fallback-Werten haben. Wenn beispielsweise in unserem Beispiel der Schlüssel 'CompressionLevel' nur im Abschnitt 'DEFAULT' angegeben war. Wenn wir versuchen, ihn aus dem Abschnitt 'topsecret.server.example' abzurufen, erhalten wir immer den Standardwert, auch wenn wir einen Fallback angeben

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

Eine weitere Sache, die zu beachten ist, ist, dass die Methode get() auf Parser-Ebene eine benutzerdefinierte, komplexere Schnittstelle bietet, die aus Gründen der Abwärtskompatibilität beibehalten wird. Wenn diese Methode verwendet wird, kann ein Fallback-Wert über das Schlüsselwortargument *fallback* bereitgestellt werden

>>> config.get('forge.example', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'

Das gleiche Argument fallback kann mit den Methoden getint(), getfloat() und getboolean() verwendet werden, zum Beispiel

>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False

Unterstützte INI-Dateistruktur¶

Eine Konfigurationsdatei besteht aus Abschnitten, die jeweils von einer Kopfzeile [section] eingeleitet werden, gefolgt von Schlüssel/Wert-Einträgen, die durch eine bestimmte Zeichenkette getrennt sind (standardmäßig = oder : [1]). Standardmäßig sind Abschnittsnamen case-sensitiv, Schlüssel jedoch nicht [1]. Führende und nachfolgende Leerzeichen werden von Schlüsseln und Werten entfernt. Werte können weggelassen werden, wenn der Parser so konfiguriert ist, dass er dies zulässt [1], in diesem Fall kann auch der Schlüssel/Wert-Trennzeichen weggelassen werden. Werte können sich auch über mehrere Zeilen erstrecken, solange sie tiefer eingerückt sind als die erste Zeile des Wertes. Abhängig vom Modus des Parsers können Leerzeilen als Teil von mehrzeiligen Werten behandelt oder ignoriert werden.

Standardmäßig kann ein gültiger Abschnittsname jede Zeichenkette sein, die kein '\n' enthält. Um dies zu ändern, siehe ConfigParser.SECTCRE.

Der erste Abschnittsname kann weggelassen werden, wenn der Parser so konfiguriert ist, dass er einen unbenannten Top-Level-Abschnitt mit allow_unnamed_section=True zulässt. In diesem Fall können die Schlüssel/Werte über UNNAMED_SECTION abgerufen werden, wie in config[UNNAMED_SECTION].

Konfigurationsdateien können Kommentare enthalten, die durch bestimmte Zeichen mit Präfix versehen sind (standardmäßig # und ; [1]). Kommentare können auf einer ansonsten leeren Zeile, möglicherweise eingerückt, allein stehen. [1]

Zum Beispiel

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

Unbenannte Abschnitte¶

Der Name des ersten (oder einzigen) Abschnitts kann weggelassen werden und Werte über das Attribut UNNAMED_SECTION abgerufen werden.

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

Interpolation von Werten¶

Zusätzlich zur Kernfunktionalität unterstützt ConfigParser die Interpolation. Das bedeutet, dass Werte vor der Rückgabe aus get()-Aufrufen vorverarbeitet werden können.

class configparser.BasicInterpolation¶

Die Standardimplementierung, die von ConfigParser verwendet wird. Sie ermöglicht es Werten, Formatierungsstrings zu enthalten, die sich auf andere Werte im selben Abschnitt oder auf Werte im speziellen Standardabschnitt beziehen [1]. Zusätzliche Standardwerte können bei der Initialisierung bereitgestellt werden.

Zum Beispiel

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

Im obigen Beispiel würde ConfigParser mit *interpolation* auf BasicInterpolation() gesetzt, %(home_dir)s in den Wert von home_dir auflösen (in diesem Fall /Users). %(my_dir)s würde effektiv zu /Users/lumberjack aufgelöst werden. Alle Interpolationen erfolgen bei Bedarf, sodass Schlüssel, die in der Referenzkette verwendet werden, in der Konfigurationsdatei nicht in einer bestimmten Reihenfolge angegeben werden müssen.

Wenn *interpolation* auf None gesetzt ist, würde der Parser einfach %(my_dir)s/Pictures als Wert für my_pictures und %(home_dir)s/lumberjack als Wert für my_dir zurückgeben.

class configparser.ExtendedInterpolation¶

Ein alternativer Handler für die Interpolation, der eine fortgeschrittenere Syntax implementiert, die beispielsweise in zc.buildout verwendet wird. Die erweiterte Interpolation verwendet ${section:option}, um einen Wert aus einem fremden Abschnitt zu bezeichnen. Interpolation kann mehrere Ebenen umfassen. Der Bequemlichkeit halber wird, wenn der Teil section: weggelassen wird, die Interpolation standardmäßig auf den aktuellen Abschnitt (und möglicherweise die Standardwerte aus dem speziellen Abschnitt) angewendet.

Zum Beispiel würde die obige Konfiguration mit einfacher Interpolation wie folgt aussehen mit erweiterter 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

Werte aus anderen Abschnitten können ebenfalls abgerufen werden

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

Zugriff über das Mapping-Protokoll¶

Hinzugefügt in Version 3.2.

Mapping-Protokollzugriff ist ein generischer Name für Funktionalität, die die Verwendung von benutzerdefinierten Objekten wie Wörterbüchern ermöglicht. Im Fall von configparser verwendet die Implementierung der Mapping-Schnittstelle die Notation parser['section']['option'].

parser['section'] gibt insbesondere einen Proxy für die Daten des Abschnitts im Parser zurück. Das bedeutet, dass die Werte nicht kopiert werden, sondern bei Bedarf vom ursprünglichen Parser bezogen werden. Noch wichtiger ist, dass beim Ändern von Werten in einem Abschnitts-Proxy diese tatsächlich im ursprünglichen Parser modifiziert werden.

configparser-Objekte verhalten sich so nah wie möglich an tatsächlichen Wörterbüchern. Die Mapping-Schnittstelle ist vollständig und entspricht der MutableMapping ABC. Es gibt jedoch einige Unterschiede, die berücksichtigt werden sollten

Standardmäßig sind alle Schlüssel in Abschnitten case-insensitiv zugänglich [1]. Zum Beispiel liefert for option in parser["section"] nur die optionxform'ed Optionsschlüsselnamen. Das bedeutet standardmäßig kleingeschriebene Schlüssel. Gleichzeitig geben für einen Abschnitt, der den Schlüssel 'a' enthält, beide Ausdrücke True zurück
```
"a" in parser["section"]
"A" in parser["section"]
```
Alle Abschnitte enthalten auch DEFAULTSECT-Werte, was bedeutet, dass .clear() auf einem Abschnitt den Abschnitt möglicherweise nicht sichtbar leer lässt. Dies liegt daran, dass Standardwerte nicht aus dem Abschnitt gelöscht werden können (da sie technisch gesehen nicht dort vorhanden sind). Wenn sie im Abschnitt überschrieben werden, führt das Löschen dazu, dass der Standardwert wieder sichtbar wird. Der Versuch, einen Standardwert zu löschen, führt zu einem KeyError.
DEFAULTSECT kann nicht aus dem Parser entfernt werden
- der Versuch, ihn zu löschen, löst einen ValueError aus,
- parser.clear() lässt ihn unberührt,
- parser.popitem() gibt ihn nie zurück.
parser.get(section, option, **kwargs) — das zweite Argument ist *nicht* ein Fallback-Wert. Beachten Sie jedoch, dass die get()-Methoden auf Abschnittsebene sowohl mit dem Mapping-Protokoll als auch mit der klassischen ConfigParser-API kompatibel sind.
parser.items() ist mit dem Mapping-Protokoll kompatibel (gibt eine Liste von Paaren aus *section_name*, *section_proxy* zurück, einschließlich DEFAULTSECT). Diese Methode kann jedoch auch mit Argumenten aufgerufen werden: parser.items(section, raw, vars). Der letztere Aufruf gibt eine Liste von *option*, *value*-Paaren für einen bestimmten section zurück, wobei alle Interpolationen erweitert werden (es sei denn, raw=True wird bereitgestellt).

Das Mapping-Protokoll wird auf der bestehenden Legacy-API implementiert, sodass Unterklassen, die die ursprüngliche Schnittstelle überschreiben, weiterhin erwartungsgemäß Mappings haben sollten.

Anpassen des Parser-Verhaltens¶

Es gibt fast so viele INI-Formatvarianten, wie es Anwendungen gibt, die es verwenden. configparser leistet viel, um die Unterstützung für die größte sinnvolle Menge der verfügbaren INI-Stile zu bieten. Die Standardfunktionalität wird hauptsächlich durch historische Hintergründe diktiert und es ist sehr wahrscheinlich, dass Sie einige der Funktionen anpassen möchten.

Der gängigste Weg, die Funktionsweise eines bestimmten Config-Parsers zu ändern, ist die Verwendung der Optionen in __init__()

defaults, Standardwert: None

Diese Option akzeptiert ein Wörterbuch von Schlüssel-Wert-Paaren, die anfänglich in den Abschnitt DEFAULT eingefügt werden. Dies ist eine elegante Möglichkeit, prägnante Konfigurationsdateien zu unterstützen, die keine Werte angeben, die mit dem dokumentierten Standard übereinstimmen.

Tipp: Wenn Sie Standardwerte für einen bestimmten Abschnitt angeben möchten, verwenden Sie read_dict(), bevor Sie die eigentliche Datei lesen.

dict_type, Standardwert: dict

Diese Option hat einen erheblichen Einfluss darauf, wie das Mapping-Protokoll funktioniert und wie die geschriebenen Konfigurationsdateien aussehen. Mit dem Standardwörterbuch wird jeder Abschnitt in der Reihenfolge gespeichert, in der er dem Parser hinzugefügt wurde. Dasselbe gilt für Optionen innerhalb von Abschnitten.

Ein alternatives Wörterbuch kann beispielsweise verwendet werden, um Abschnitte und Optionen beim Zurückschreiben zu sortieren.

Bitte beachten Sie: Es gibt Möglichkeiten, eine Reihe von Schlüssel-Wert-Paaren in einem einzigen Vorgang hinzuzufügen. Wenn Sie in diesen Operationen ein reguläres Wörterbuch verwenden, werden die Schlüssel sortiert. Zum Beispiel

>>> 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, Standardwert: False

Einige Konfigurationsdateien enthalten Einstellungen ohne Werte, die aber ansonsten der von configparser unterstützten Syntax entsprechen. Der Konstruktorparameter *allow_no_value* kann verwendet werden, um anzuzeigen, dass solche Werte akzeptiert werden sollten

>>> 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, Standardwert: ('=', ':')

Trennzeichen sind Zeichenketten, die Schlüssel von Werten innerhalb eines Abschnitts trennen. Das erste Vorkommen einer Trennzeichenkette in einer Zeile gilt als Trennzeichen. Das bedeutet, dass Werte (aber nicht Schlüssel) die Trennzeichen enthalten können.

Siehe auch das Argument *space_around_delimiters* in ConfigParser.write().
comment_prefixes, Standardwert: ('#', ';')
inline_comment_prefixes, Standardwert: None

Kommentarpräfixe sind Zeichenketten, die den Beginn eines gültigen Kommentars in einer Konfigurationsdatei anzeigen. *comment_prefixes* werden nur auf ansonsten leeren Zeilen (optional eingerückt) verwendet, während *inline_comment_prefixes* nach jedem gültigen Wert (z. B. Abschnittsnamen, Optionen und auch leeren Zeilen) verwendet werden können. Standardmäßig sind Inline-Kommentare deaktiviert und '#' und ';' werden als Präfixe für ganze Kommentarzeilen verwendet.

Geändert in Version 3.2: In früheren Versionen von configparser entsprach das Verhalten comment_prefixes=('#',';') und inline_comment_prefixes=(';',).

Bitte beachten Sie, dass Config-Parser keine Escape-Sequenzen für Kommentarpräfixe unterstützen. Daher kann die Verwendung von *inline_comment_prefixes* dazu führen, dass Benutzer Optionswerte mit Zeichen angeben können, die als Kommentarpräfixe verwendet werden. Im Zweifelsfall vermeiden Sie die Einstellung von *inline_comment_prefixes*. In jedem Fall ist die einzige Möglichkeit, Kommentarpräfixzeichen am Anfang einer Zeile in mehrzeiligen Werten zu speichern, die Interpolation des Präfixes, zum Beispiel
```
>>> 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, Standardwert: True

Wenn True gesetzt ist, erlaubt der Parser beim Lesen aus einer einzelnen Quelle (mit read_file(), read_string() oder read_dict()) keine doppelten Abschnitte oder Optionen. Es wird empfohlen, strenge Parser in neuen Anwendungen zu verwenden.

Geändert in Version 3.2: In früheren Versionen von configparser entsprach das Verhalten strict=False.
empty_lines_in_values, Standardwert: True

In Config-Parsern können sich Werte über mehrere Zeilen erstrecken, solange sie stärker eingerückt sind als der Schlüssel, der sie enthält. Standardmäßig erlauben Parser auch, dass Leerzeilen Teil von Werten sind. Gleichzeitig können Schlüssel beliebig eingerückt sein, um die Lesbarkeit zu verbessern. Infolgedessen, wenn Konfigurationsdateien groß und komplex werden, verliert der Benutzer leicht den Überblick über die Dateistruktur. Nehmen Sie zum Beispiel
```
[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'
```
Dies kann für den Benutzer besonders problematisch sein, wenn sie eine proportionale Schriftart verwendet, um die Datei zu bearbeiten. Deshalb sollten Sie, wenn Ihre Anwendung keine Werte mit Leerzeilen benötigt, erwägen, diese zu verbieten. Dadurch werden Leerzeilen jedes Mal Schlüssel trennen. Im obigen Beispiel würden zwei Schlüssel erzeugt: key und this.
default_section, Standardwert: configparser.DEFAULTSECT (d. h.: "DEFAULT")

Die Konvention, einen speziellen Abschnitt mit Standardwerten für andere Abschnitte oder zu Interpolationszwecken zu erlauben, ist ein leistungsfähiges Konzept dieser Bibliothek, das es Benutzern ermöglicht, komplexe deklarative Konfigurationen zu erstellen. Dieser Abschnitt heißt normalerweise "DEFAULT", kann aber angepasst werden, um auf jeden anderen gültigen Abschnittsnamen zu verweisen. Einige typische Werte sind: "general" oder "common". Der angegebene Name wird verwendet, um Standardabschnitte beim Lesen aus jeder Quelle zu erkennen und wird beim Zurückschreiben der Konfiguration in eine Datei verwendet. Sein aktueller Wert kann über das Attribut parser_instance.default_section abgerufen und zur Laufzeit geändert werden (d. h. um Dateien von einem Format in ein anderes zu konvertieren).
interpolation, Standardwert: configparser.BasicInterpolation

Das Interpolationsverhalten kann durch Bereitstellung eines benutzerdefinierten Handlers über das Argument *interpolation* angepasst werden. None kann verwendet werden, um die Interpolation vollständig zu deaktivieren, ExtendedInterpolation() bietet eine fortgeschrittenere Variante, die von zc.buildout inspiriert ist. Mehr dazu im dedizierten Dokumentationsabschnitt. RawConfigParser hat einen Standardwert von None.
converters, Standardwert: nicht gesetzt

Config-Parser bieten Getter für Optionen, die eine Typumwandlung durchführen. Standardmäßig sind getint(), getfloat() und getboolean() implementiert. Sollten andere Getter erwünscht sein, können Benutzer diese in einer Unterklasse definieren oder ein Dictionary übergeben, wobei jeder Schlüssel ein Name des Konverters und jeder Wert ein Aufruf ist, der die genannte Konvertierung implementiert. Zum Beispiel würde die Übergabe von {'decimal': decimal.Decimal} getdecimal() sowohl auf dem Parser-Objekt als auch auf allen Section-Proxies hinzufügen. Mit anderen Worten, es wird möglich sein, sowohl parser_instance.getdecimal('section', 'key', fallback=0) als auch parser_instance['section'].getdecimal('key', 0) zu schreiben.

Wenn der Konverter auf den Zustand des Parsers zugreifen muss, kann er als Methode einer Config-Parser-Unterklasse implementiert werden. Wenn der Name dieser Methode mit get beginnt, ist sie auf allen Section-Proxies verfügbar, in der dict-kompatiblen Form (siehe das getdecimal()-Beispiel oben).

Fortgeschrittenere Anpassungen können durch Überschreiben der Standardwerte dieser Parser-Attribute erreicht werden. Die Standardwerte sind auf den Klassen definiert, daher können sie durch Unterklassen oder durch Attributzuweisung überschrieben werden.

ConfigParser.BOOLEAN_STATES¶

Standardmäßig berücksichtigt der Config-Parser bei der Verwendung von getboolean() die folgenden Werte als True: '1', 'yes', 'true', 'on' und die folgenden Werte als False: '0', 'no', 'false', 'off'. Sie können dies überschreiben, indem Sie ein benutzerdefiniertes Dictionary mit Zeichenketten und ihren booleschen Ergebnissen angeben. Zum Beispiel:

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

Andere typische boolesche Paare sind accept/reject oder enabled/disabled.

ConfigParser.optionxform(option)

Diese Methode transformiert Optionsnamen bei jedem Lese-, Lese- oder Schreibvorgang. Standardmäßig wird der Name in Kleinbuchstaben umgewandelt. Das bedeutet auch, dass beim Schreiben einer Konfigurationsdatei alle Schlüssel Kleinbuchstaben sein werden. Überschreiben Sie diese Methode, wenn dies nicht geeignet ist. Zum Beispiel:

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

Hinweis

Die Funktion optionxform transformiert Optionsnamen in eine kanonische Form. Dies sollte eine idempotente Funktion sein: Wenn der Name bereits in kanonischer Form vorliegt, sollte er unverändert zurückgegeben werden.

ConfigParser.SECTCRE¶

Ein kompilierter regulärer Ausdruck, der zum Parsen von Abschnittsüberschriften verwendet wird. Der Standardwert passt [section] auf den Namen "section". Leerzeichen gelten als Teil des Abschnittsnamens, daher wird [ larch ] als Abschnitt mit dem Namen " larch " gelesen. Überschreiben Sie dieses Attribut, wenn dies nicht geeignet ist. Zum Beispiel:

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

Hinweis

Obwohl ConfigParser-Objekte auch ein OPTCRE-Attribut zur Erkennung von Optionszeilen verwenden, wird davon abgeraten, dieses zu überschreiben, da dies die Konstruktoroptionen allow_no_value und delimiters beeinträchtigen würde.

Legacy-API-Beispiele¶

Hauptsächlich aus Gründen der Abwärtskompatibilität bietet configparser auch eine Legacy-API mit expliziten get/set-Methoden. Obwohl es gültige Anwendungsfälle für die unten beschriebenen Methoden gibt, wird für neue Projekte die Abbildungsprotokoll-Zugriff bevorzugt. Die Legacy-API ist manchmal fortschrittlicher, low-level und geradezu unintuitiv.

Ein Beispiel für das Schreiben in eine Konfigurationsdatei

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)

Ein Beispiel für das erneute Lesen der Konfigurationsdatei

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

Um Interpolation zu erhalten, verwenden Sie 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

Standardwerte sind in beiden Arten von ConfigParsers verfügbar. Sie werden bei der Interpolation verwendet, wenn eine verwendete Option nicht an anderer Stelle definiert ist.

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-Objekte¶

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

Der Haupt-Konfigurationsparser. Wenn defaults angegeben wird, wird es in das Dictionary der intrinsischen Standardwerte initialisiert. Wenn dict_type angegeben wird, wird es verwendet, um die Dictionary-Objekte für die Liste der Abschnitte, die Optionen innerhalb eines Abschnitts und die Standardwerte zu erstellen.

Wenn delimiters angegeben wird, wird es als Menge von Zeichenketten verwendet, die Schlüssel von Werten trennen. Wenn comment_prefixes angegeben wird, wird es als Menge von Zeichenketten verwendet, die Kommentare in ansonsten leeren Zeilen voranstellen. Kommentare können eingerückt sein. Wenn inline_comment_prefixes angegeben wird, wird es als Menge von Zeichenketten verwendet, die Kommentare in nicht leeren Zeilen voranstellen.

Wenn strict True (Standard) ist, erlaubt der Parser keine doppelten Abschnitte oder Optionen beim Lesen aus einer einzigen Quelle (Datei, Zeichenkette oder Dictionary) und löst DuplicateSectionError oder DuplicateOptionError aus. Wenn empty_lines_in_values False (Standard: True) ist, markiert jede leere Zeile das Ende einer Option. Andernfalls werden interne leere Zeilen einer mehrzeiligen Option als Teil des Wertes beibehalten. Wenn allow_no_value True (Standard: False) ist, werden Optionen ohne Werte akzeptiert; der Wert für diese ist None und sie werden ohne das abschließende Trennzeichen serialisiert.

Wenn default_section angegeben wird, legt es den Namen für den speziellen Abschnitt fest, der Standardwerte für andere Abschnitte und Interpolationszwecke enthält (normalerweise benannt "DEFAULT"). Dieser Wert kann zur Laufzeit über das Instanzattribut default_section abgerufen und geändert werden. Dies wird eine bereits geparste Konfigurationsdatei nicht neu auswerten, sondern wird verwendet, wenn geparste Einstellungen in eine neue Konfigurationsdatei geschrieben werden.

Das Interpolationsverhalten kann durch die Bereitstellung eines benutzerdefinierten Handlers über das Argument interpolation angepasst werden. None kann verwendet werden, um die Interpolation vollständig zu deaktivieren, ExtendedInterpolation() bietet eine fortgeschrittenere Variante, die von zc.buildout inspiriert ist. Mehr zu diesem Thema im dedizierten Dokumentationsabschnitt.

Alle Optionsnamen, die in der Interpolation verwendet werden, werden wie jeder andere Optionsnamen-Verweis durch die Methode optionxform() geleitet. Zum Beispiel sind bei Verwendung der Standardimplementierung von optionxform() (die Optionsnamen in Kleinbuchstaben umwandelt) die Werte foo %(bar)s und foo %(BAR)s äquivalent.

Wenn converters angegeben wird, sollte es ein Dictionary sein, bei dem jeder Schlüssel den Namen eines Typkonverters darstellt und jeder Wert ein Aufruf ist, der die Konvertierung von einer Zeichenkette in den gewünschten Datentyp implementiert. Jeder Konverter erhält seine eigene entsprechende get*()-Methode auf dem Parser-Objekt und den Section-Proxies.

Wenn allow_unnamed_section True (Standard: False) ist, kann der erste Abschnittsname weggelassen werden. Siehe den Abschnitt „Unnamed Sections“.

Es ist möglich, mehrere Konfigurationen in ein einziges ConfigParser zu lesen, wobei die zuletzt hinzugefügte Konfiguration die höchste Priorität hat. Alle widersprüchlichen Schlüssel werden aus der neueren Konfiguration übernommen, während die zuvor vorhandenen Schlüssel beibehalten werden. Das folgende Beispiel liest eine Datei namens override.ini, die widersprüchliche Schlüssel aus der Datei example.ini überschreiben wird.

[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

Geändert in Version 3.1: Der Standard-dict_type ist collections.OrderedDict.

Geändert in Version 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section und interpolation wurden hinzugefügt.

Geändert in Version 3.5: Das Argument converters wurde hinzugefügt.

Geändert in Version 3.7: Das Argument defaults wird mit read_dict() gelesen, was ein konsistentes Verhalten über den Parser hinweg bietet: Nicht-Zeichenketten-Schlüssel und -Werte werden implizit in Zeichenketten konvertiert.

Geändert in Version 3.8: Der Standard-dict_type ist dict, da dieser nun die Einfügungsreihenfolge beibehält.

Geändert in Version 3.13: Löst MultilineContinuationError aus, wenn allow_no_value True ist und ein Schlüssel ohne Wert mit einer eingerückten Zeile fortgesetzt wird.

Geändert in Version 3.13: Das Argument allow_unnamed_section wurde hinzugefügt.

defaults()¶: Gibt ein Dictionary mit den instanzweiten Standardwerten zurück.

sections()¶: Gibt eine Liste der verfügbaren Abschnitte zurück; der Standardabschnitt ist nicht in der Liste enthalten.

add_section(section)¶: Fügt einen Abschnitt namens section zur Instanz hinzu. Wenn ein Abschnitt mit dem angegebenen Namen bereits existiert, wird DuplicateSectionError ausgelöst. Wenn der Name des Standardabschnitts übergeben wird, wird ValueError ausgelöst. Der Name des Abschnitts muss eine Zeichenkette sein; andernfalls wird TypeError ausgelöst.

Geändert in Version 3.2: Nicht-Zeichenketten-Abschnittsnamen lösen TypeError aus.

has_section(section)¶: Zeigt an, ob der benannte section in der Konfiguration vorhanden ist. Der Standardabschnitt wird nicht berücksichtigt.

options(section)¶: Gibt eine Liste der im angegebenen section verfügbaren Optionen zurück.

has_option(section, option)¶: Wenn der angegebene section existiert und die angegebene option enthält, wird True zurückgegeben; andernfalls wird False zurückgegeben. Wenn der angegebene section None oder eine leere Zeichenkette ist, wird DEFAULT angenommen.

read(filenames, encoding=None)¶

Versucht, eine Menge von Dateinamen zu lesen und zu parsen, und gibt eine Liste der erfolgreich geparsten Dateinamen zurück.

Wenn filenames eine Zeichenkette, ein bytes-Objekt oder ein pfadähnliches Objekt ist, wird es als einzelner Dateiname behandelt. Wenn eine in filenames genannte Datei nicht geöffnet werden kann, wird diese Datei ignoriert. Dies ist so konzipiert, dass Sie eine Menge von potenziellen Konfigurationsdateispeicherorten angeben können (z. B. das aktuelle Verzeichnis, das Home-Verzeichnis des Benutzers und ein systemweites Verzeichnis) und alle vorhandenen Konfigurationsdateien in der Menge gelesen werden.

Wenn keiner der genannten Dateien existiert, enthält die ConfigParser-Instanz ein leeres Dataset. Eine Anwendung, die anfängliche Werte aus einer Datei laden muss, sollte die erforderliche(n) Datei(en) mit read_file() laden, bevor read() für optionale Dateien aufgerufen wird.

import configparser, os

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

Geändert in Version 3.2: Der Parameter encoding wurde hinzugefügt. Zuvor wurden alle Dateien mit der Standardkodierung für open() gelesen.

Geändert in Version 3.6.1: Der Parameter filenames akzeptiert ein pfadähnliches Objekt.

Geändert in Version 3.7: Der Parameter filenames akzeptiert ein bytes-Objekt.

read_file(f, source=None)¶

Liest und parst Konfigurationsdaten aus f, das eine Menge von Unicode-Zeichenketten ergeben muss (z. B. im Textmodus geöffnete Dateien).

Das optionale Argument source gibt den Namen der gelesenen Datei an. Wenn es nicht gegeben ist und f ein Attribut name hat, wird dieses für source verwendet; der Standardwert ist '<???>'.

Hinzugefügt in Version 3.2: Ersetzt readfp().

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

Parst Konfigurationsdaten aus einer Zeichenkette.

Das optionale Argument source gibt einen kontextspezifischen Namen der übergebenen Zeichenkette an. Wenn es nicht gegeben ist, wird '<string>' verwendet. Dies sollte üblicherweise ein Dateipfad oder eine URL sein.

Hinzugefügt in Version 3.2.

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

Lädt Konfigurationen aus einem beliebigen Objekt, das eine dict-ähnliche items()-Methode bereitstellt. Schlüssel sind Abschnittsnamen, Werte sind Dictionaries mit Schlüsseln und Werten, die im Abschnitt vorhanden sein sollten. Wenn der verwendete Dictionary-Typ die Reihenfolge beibehält, werden Abschnitte und ihre Schlüssel in der Reihenfolge hinzugefügt. Werte werden automatisch in Zeichenketten konvertiert.

Das optionale Argument source gibt einen kontextspezifischen Namen des übergebenen Dictionaries an. Wenn es nicht gegeben ist, wird <dict> verwendet.

Diese Methode kann verwendet werden, um Zustände zwischen Parsern zu kopieren.

Hinzugefügt in Version 3.2.

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

Ruft den Wert einer option für den benannten section ab. Wenn vars bereitgestellt wird, muss es ein Dictionary sein. Die option wird in vars (falls bereitgestellt), im section und im DEFAULTSECT in dieser Reihenfolge gesucht. Wenn der Schlüssel nicht gefunden wird und fallback bereitgestellt wird, wird dieser als Fallback-Wert verwendet. None kann als fallback-Wert angegeben werden.

Alle '%'-Interpolationen werden in den Rückgabewerten erweitert, es sei denn, das Argument raw ist wahr. Werte für Interpolationsschlüssel werden auf die gleiche Weise gesucht wie die Option.

Geändert in Version 3.2: Die Argumente raw, vars und fallback sind nur als Schlüsselwortargumente zulässig, um Benutzer davor zu schützen, das dritte Argument als fallback-Fallback zu verwenden (insbesondere bei Verwendung des Mapping-Protokolls).

getint(section, option, *, raw=False, vars=None[, fallback])¶: Eine Komfortmethode, die die option im angegebenen section in einen Integer umwandelt. Siehe get() für die Erklärung von raw, vars und fallback.

getfloat(section, option, *, raw=False, vars=None[, fallback])¶: Eine Komfortmethode, die die option im angegebenen section in eine Gleitkommazahl umwandelt. Siehe get() für die Erklärung von raw, vars und fallback.

getboolean(section, option, *, raw=False, vars=None[, fallback])¶: Eine Komfortmethode, die die option im angegebenen section in einen booleschen Wert umwandelt. Beachten Sie, dass die akzeptierten Werte für die Option '1', 'yes', 'true' und 'on' sind, was dazu führt, dass diese Methode True zurückgibt, und '0', 'no', 'false' und 'off', was dazu führt, dass sie False zurückgibt. Diese Zeichenkettenwerte werden nicht-fallend geprüft. Jeder andere Wert führt dazu, dass ValueError ausgelöst wird. Siehe get() für die Erklärung von raw, vars und fallback.

items(raw=False, vars=None)¶

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

Wenn section nicht angegeben ist, wird eine Liste von section_name, section_proxy-Paaren zurückgegeben, einschließlich DEFAULTSECT.

Andernfalls wird eine Liste von name, value-Paaren für die Optionen im angegebenen section zurückgegeben. Optionale Argumente haben die gleiche Bedeutung wie für die get()-Methode.

Geändert in Version 3.8: In vars vorhandene Elemente erscheinen nicht mehr im Ergebnis. Das frühere Verhalten vermischte tatsächliche Parser-Optionen mit Variablen, die für die Interpolation bereitgestellt wurden.

set(section, option, value)¶: Wenn der angegebene Abschnitt existiert, wird die angegebene Option auf den angegebenen Wert gesetzt; andernfalls wird NoSectionError ausgelöst. option und value müssen Zeichenketten sein; andernfalls wird TypeError ausgelöst.

write(fileobject, space_around_delimiters=True)¶: Schreibt eine Darstellung der Konfiguration in das angegebene Datei-Objekt, das im Textmodus geöffnet sein muss (Zeichenketten akzeptierend). Diese Darstellung kann von einem zukünftigen read()-Aufruf gelesen werden. Wenn space_around_delimiters wahr ist, werden Trennzeichen zwischen Schlüsseln und Werten von Leerzeichen umgeben.

Geändert in Version 3.14: Löst InvalidWriteError aus, wenn dies eine Darstellung schreiben würde, die von einem zukünftigen read()-Aufruf dieses Parsers nicht korrekt gelesen werden kann.

Hinweis

Kommentare in der ursprünglichen Konfigurationsdatei werden beim Zurückschreiben der Konfiguration nicht beibehalten. Was als Kommentar gilt, hängt von den angegebenen Werten für comment_prefix und inline_comment_prefix ab.

remove_option(section, option)¶: Entfernt die angegebene Option aus dem angegebenen Abschnitt. Wenn der Abschnitt nicht existiert, wird eine NoSectionError ausgelöst. Wenn die zu entfernende Option existierte, wird True zurückgegeben; andernfalls wird False zurückgegeben.

remove_section(section)¶: Entfernt den angegebenen Abschnitt aus der Konfiguration. Wenn der Abschnitt tatsächlich existierte, wird True zurückgegeben. Andernfalls wird False zurückgegeben.

optionxform(option)¶

Transformiert den Optionsnamen option, wie er in einer Eingabedatei gefunden oder vom Client-Code übergeben wird, in die Form, die intern verwendet werden soll. Die Standardimplementierung gibt eine kleingeschriebene Version von option zurück; Unterklassen können dies überschreiben oder der Client-Code kann ein Attribut dieses Namens auf Instanzen setzen, um dieses Verhalten zu beeinflussen.

Sie müssen den Parser nicht unterklassifizieren, um diese Methode zu verwenden. Sie können sie auch auf einer Instanz als Funktion festlegen, die ein String-Argument entgegennimmt und einen String zurückgibt. Das Setzen auf str würde beispielsweise dafür sorgen, dass Optionsnamen Groß- und Kleinschreibung beachten.

cfgparser = ConfigParser()
cfgparser.optionxform = str

Beachten Sie, dass beim Lesen von Konfigurationsdateien Whitespace um die Optionsnamen herum entfernt wird, bevor optionxform() aufgerufen wird.

configparser.UNNAMED_SECTION¶: Ein spezielles Objekt, das einen Abschnittsnamen repräsentiert und verwendet wird, um auf den unbenannten Abschnitt zu verweisen (siehe Unbenannte Abschnitte).

configparser.MAX_INTERPOLATION_DEPTH¶: Die maximale Tiefe für die rekursive Interpolation für get(), wenn der Parameter raw falsch ist. Dies ist nur relevant, wenn die Standard-Interpolation verwendet wird.

RawConfigParser Objekte¶

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

Eine ältere Variante des ConfigParser. Sie hat standardmäßig keine Interpolation und erlaubt Nicht-String-Abschnittsnamen, Optionsnamen und Werte über ihre unsicheren Methoden add_section und set sowie die ältere Behandlung des Schlüsselwortarguments defaults=.

Geändert in Version 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section und interpolation wurden hinzugefügt.

Geändert in Version 3.5: Das Argument converters wurde hinzugefügt.

Geändert in Version 3.8: Der Standard-dict_type ist dict, da dieser nun die Einfügungsreihenfolge beibehält.

Geändert in Version 3.13: Das Argument allow_unnamed_section wurde hinzugefügt.

Hinweis

Ziehen Sie in Betracht, stattdessen ConfigParser zu verwenden, der die Typen der intern zu speichernden Werte prüft. Wenn Sie keine Interpolation wünschen, können Sie ConfigParser(interpolation=None) verwenden.

add_section(section)¶

Fügt der Instanz einen Abschnitt namens section oder UNNAMED_SECTION hinzu.

Wenn der angegebene Abschnitt bereits existiert, wird eine DuplicateSectionError ausgelöst. Wenn der Standardabschnittsname übergeben wird, wird eine ValueError ausgelöst. Wenn UNNAMED_SECTION übergeben wird und die Unterstützung deaktiviert ist, wird eine UnnamedSectionDisabledError ausgelöst.

Der Typ von section wird nicht geprüft, was Benutzern die Erstellung von Abschnitten mit Nicht-String-Namen ermöglicht. Dieses Verhalten wird nicht unterstützt und kann zu internen Fehlern führen.

Geändert in Version 3.14: Unterstützung für UNNAMED_SECTION hinzugefügt.

set(section, option, value)¶

Wenn der angegebene Abschnitt existiert, wird die angegebene Option auf den spezifizierten Wert gesetzt; andernfalls wird eine NoSectionError ausgelöst. Obwohl es möglich ist, RawConfigParser (oder ConfigParser mit auf raw gesetztem Parameter) für die interne Speicherung von Nicht-String-Werten zu verwenden, kann die volle Funktionalität (einschließlich Interpolation und Ausgabe in Dateien) nur mit String-Werten erreicht werden.

Diese Methode ermöglicht es Benutzern, Nicht-String-Werte intern Schlüsseln zuzuweisen. Dieses Verhalten wird nicht unterstützt und führt zu Fehlern, wenn versucht wird, in eine Datei zu schreiben oder sie im Nicht-Raw-Modus abzurufen. Verwenden Sie die Mapping-Protokoll-API, die solche Zuweisungen nicht zulässt.

Ausnahmen¶

exception configparser.Error¶: Basisklasse für alle anderen configparser-Ausnahmen.

exception configparser.NoSectionError¶: Ausnahme, die ausgelöst wird, wenn ein angegebener Abschnitt nicht gefunden wird.

exception configparser.DuplicateSectionError¶: Ausnahme, die ausgelöst wird, wenn add_section() mit dem Namen eines bereits vorhandenen Abschnitts aufgerufen wird oder in strikten Parsern, wenn ein Abschnitt in einer einzelnen Eingabedatei, einem String oder einem Wörterbuch mehrmals gefunden wird.

Geändert in Version 3.2: Optionale Attribute und Parameter source und lineno für __init__() hinzugefügt.

exception configparser.DuplicateOptionError¶: Ausnahme, die von strikten Parsern ausgelöst wird, wenn eine einzelne Option beim Lesen aus einer einzelnen Datei, einem String oder einem Wörterbuch zweimal vorkommt. Dies fängt Tippfehler und fehlerbedingte Probleme mit Groß-/Kleinschreibung ab, z. B. kann ein Wörterbuch zwei Schlüssel haben, die denselben case-insensitiven Konfigurationsschlüssel darstellen.

exception configparser.NoOptionError¶: Ausnahme, die ausgelöst wird, wenn eine angegebene Option im angegebenen Abschnitt nicht gefunden wird.

exception configparser.InterpolationError¶: Basisklasse für Ausnahmen, die bei Problemen mit der String-Interpolation ausgelöst werden.

exception configparser.InterpolationDepthError¶: Ausnahme, die ausgelöst wird, wenn die String-Interpolation nicht abgeschlossen werden kann, weil die Anzahl der Iterationen MAX_INTERPOLATION_DEPTH überschreitet. Unterklasse von InterpolationError.

exception configparser.InterpolationMissingOptionError¶: Ausnahme, die ausgelöst wird, wenn eine aus einem Wert referenzierte Option nicht existiert. Unterklasse von InterpolationError.

exception configparser.InterpolationSyntaxError¶: Ausnahme, die ausgelöst wird, wenn der Quelltext, in den Ersetzungen vorgenommen werden, nicht der erforderlichen Syntax entspricht. Unterklasse von InterpolationError.

exception configparser.MissingSectionHeaderError¶: Ausnahme, die ausgelöst wird, wenn versucht wird, eine Datei zu parsen, die keine Abschnittsüberschriften hat.

exception configparser.ParsingError¶: Ausnahme, die ausgelöst wird, wenn beim Parsen einer Datei Fehler auftreten.

Geändert in Version 3.12: Das Attribut filename und das Konstruktorargument __init__() wurden entfernt. Sie waren seit 3.2 unter dem Namen source verfügbar.

exception configparser.MultilineContinuationError¶: Ausnahme, die ausgelöst wird, wenn ein Schlüssel ohne entsprechenden Wert mit einer eingerückten Zeile fortgesetzt wird.

Hinzugefügt in Version 3.13.

exception configparser.UnnamedSectionDisabledError¶: Ausnahme, die ausgelöst wird, wenn versucht wird, UNNAMED_SECTION zu verwenden, ohne es zu aktivieren.

Hinzugefügt in Version 3.14.

exception configparser.InvalidWriteError¶

Ausnahme, die ausgelöst wird, wenn ein Versuch mit ConfigParser.write() mit einem zukünftigen ConfigParser.read()-Aufruf nicht korrekt geparst werden könnte.

Beispiel: Das Schreiben eines Schlüssels, der mit dem Muster von ConfigParser.SECTCRE beginnt, wird beim Lesen als Abschnittsüberschrift geparst. Der Versuch, dies zu schreiben, löst diese Ausnahme aus.

Hinzugefügt in Version 3.14.

Fußnoten

`configparser` — Parser für Konfigurationsdateien¶

Schnellstart¶

Unterstützte Datentypen¶

Fallback-Werte¶

Unterstützte INI-Dateistruktur¶

Unbenannte Abschnitte¶

Interpolation von Werten¶

Zugriff über das Mapping-Protokoll¶

Anpassen des Parser-Verhaltens¶

Legacy-API-Beispiele¶

ConfigParser-Objekte¶

RawConfigParser Objekte¶

Ausnahmen¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

configparser — Parser für Konfigurationsdateien¶

Schnellstart¶

Unterstützte Datentypen¶

Fallback-Werte¶

Unterstützte INI-Dateistruktur¶

Unbenannte Abschnitte¶

Interpolation von Werten¶

Zugriff über das Mapping-Protokoll¶

Anpassen des Parser-Verhaltens¶

Legacy-API-Beispiele¶

ConfigParser-Objekte¶

RawConfigParser Objekte¶

Ausnahmen¶

`configparser` — Parser für Konfigurationsdateien¶