configparser — Parser för konfigurationsfiler

Källkod: Lib/configparser.py


Denna modul tillhandahåller ConfigParser-klassen som implementerar ett grundläggande konfigurationsspråk som ger en struktur som liknar den som finns i Microsoft Windows INI-filer. Du kan använda detta för att skriva Python-program som enkelt kan anpassas av slutanvändare.

Anteckning

Det här biblioteket tolkar eller skriver inte de prefix för värdetyper som används i Windows-registrets utökade version av INI-syntax.

Se även

Modul tomllib

TOML är ett väl specificerat format för konfigurationsfiler för program. Det är särskilt utformat för att vara en förbättrad version av INI.

Modul shlex

Stöd för att skapa Unix shell-liknande minispråk som också kan användas för konfigurationsfiler för applikationer.

Modul json

Modulen json implementerar en delmängd av JavaScript-syntax som ibland används för konfiguration, men stöder inte kommentarer.

Snabbstart

Låt oss ta en mycket grundläggande konfigurationsfil som ser ut så här:

[DEFAULT]
ServerAliveInterval = 45
Komprimering = ja
Komprimeringsnivå = 9
ForwardX11 = ja

[forge.exempel]
Användare = hg

[topsecret.server.exempel]
Port = 50022
ForwardX11 = nej

INI-filernas struktur beskrivs i följande avsnitt. I huvudsak består filen av sektioner, som var och en innehåller nycklar med värden. configparser-klasser kan läsa och skriva sådana filer. Låt oss börja med att skapa ovanstående konfigurationsfil programmatiskt.

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

Som du kan se kan vi behandla en config-parser ungefär som en ordbok. Det finns skillnader, ”beskrivs senare <#mapping-protocol-access>”, men beteendet ligger mycket nära vad du kan förvänta dig av en ordbok.

Nu när vi har skapat och sparat en konfigurationsfil ska vi läsa upp den och utforska vilka data den innehåller.

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

Som vi kan se ovan är API:et ganska okomplicerat. Det enda magiska är avsnittet DEFAULT som innehåller standardvärden för alla andra avsnitt [1]. Observera också att nycklar i sektioner är skiftlägesokänsliga och lagras med gemener [1].

Det är möjligt att läsa in flera konfigurationer i en enda ConfigParser, där den senast tillagda konfigurationen har högsta prioritet. Eventuella motstridiga nycklar hämtas från den senaste konfigurationen medan de tidigare befintliga nycklarna behålls. I exemplet nedan läses en fil med namnet override.ini in, som åsidosätter alla motstridiga nycklar från filen example.ini.

[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

Detta beteende motsvarar ett anrop av ConfigParser.read() med flera filer som skickas till parametern filnamn.

Datatyper som stöds

Config-parsers gissar inte datatyperna för värden i konfigurationsfiler, utan lagrar dem alltid internt som strängar. Detta innebär att om du behöver andra datatyper bör du konvertera på egen hand:

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

Eftersom den här uppgiften är så vanlig tillhandahåller config-parsers en rad praktiska getter-metoder för att hantera heltal, flottörer och booleaner. Den sista är den mest intressanta eftersom det inte skulle vara bra att bara skicka värdet till bool() eftersom bool('False') fortfarande är True. Det är därför som config-parsers också tillhandahåller getboolean(). Denna metod är skiftlägesokänslig och känner igen booleska värden från 'yes'/'no', 'on'/'off', 'true'/'false' och '1'/'0' [1]. Till exempel:

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

Förutom getboolean() tillhandahåller config-parser också motsvarande metoder getint() och getfloat(). Du kan registrera dina egna omvandlare och anpassa de som tillhandahålls. [1]

Reservvärden

Precis som med en ordbok kan du använda en sektions get()-metod för att tillhandahålla reservvärden:

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

Observera att standardvärden har företräde framför reservvärden. I vårt exempel har nyckeln 'CompressionLevel' endast angetts i avsnittet 'DEFAULT'. Om vi försöker hämta den från avsnittet 'topsecret.server.example' får vi alltid standardvärdet, även om vi anger ett reservvärde:

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

Ytterligare en sak att vara medveten om är att metoden get() på parser-nivå ger ett anpassat, mer komplext gränssnitt, som bibehålls för bakåtkompatibilitet. När du använder den här metoden kan ett reservvärde anges via det enda nyckelordsargumentet fallback:

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

Samma fallback-argument kan t.ex. användas med metoderna getint(), getfloat() och getboolean():

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

INI-filstruktur som stöds

En konfigurationsfil består av sektioner, var och en inledd med en rubrik [section], följt av nyckel-/värdeposter åtskilda av en specifik sträng (= eller : som standard [1]). Som standard är avsnittsnamn skiftlägeskänsliga, men nycklar är det inte [1]. Ledande och efterföljande blanksteg tas bort från nycklar och värden. Värden kan utelämnas om parsern är konfigurerad att tillåta det [1], i vilket fall avgränsaren för nyckel/värde också kan utelämnas. Värden kan också sträcka sig över flera rader, så länge de är indragna djupare än den första raden i värdet. Beroende på parserns läge kan tomma rader behandlas som delar av värden på flera rader eller ignoreras.

Som standard kan ett giltigt sektionsnamn vara en sträng som inte innehåller ”\n”. För att ändra detta, se ConfigParser.SECTCRE.

Det första sektionsnamnet kan utelämnas om parsern är konfigurerad att tillåta en icke namngiven sektion på högsta nivån med allow_unnamed_section=True. I detta fall kan nycklarna/värdena hämtas med UNNAMED_SECTION som i config[UNNAMED_SECTION].

Konfigurationsfiler kan innehålla kommentarer, som inleds med specifika tecken (# och ; som standard [1]). Kommentarer kan visas separat på en i övrigt tom rad, eventuellt indragna. [1]

Till exempel:

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

Icke namngivna sektioner

Namnet på den första (eller unika) sektionen kan utelämnas och värden hämtas med attributet UNNAMED_SECTION.

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

Interpolering av värden

Utöver kärnfunktionaliteten har ConfigParser stöd för interpolering. Detta innebär att värden kan förbehandlas innan de returneras från get()-anrop.

class configparser.BasicInterpolation

Standardimplementationen som används av ConfigParser. Den gör det möjligt för värden att innehålla formatsträngar som hänvisar till andra värden i samma avsnitt, eller värden i det speciella standardavsnittet [1]. Ytterligare standardvärden kan anges vid initiering.

Till exempel:

[Sökvägar]
hem_dir: /Användare
min_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Bilder

[Escape]
# använd en %% för att undkomma % sign (% i är det enda tecken som behöver undkommas):
vinst: 80%%

I exemplet ovan skulle ConfigParser med interpolation inställd på BasicInterpolation() lösa %(home_dir)s till värdet av home_dir (/Users i det här fallet). %(my_dir)s skulle i praktiken motsvara /Users/lumberjack. Alla interpoleringar görs på begäran så nycklar som används i kedjan av referenser behöver inte anges i någon specifik ordning i konfigurationsfilen.

Med interpolation inställd på None skulle parsern helt enkelt returnera %(my_dir)s/Pictures som värdet på my_pictures och %(home_dir)s/lumberjack som värdet på my_dir.

class configparser.ExtendedInterpolation

En alternativ hanterare för interpolering som implementerar en mer avancerad syntax, som t.ex. används i zc.buildout. Utökad interpolering är att använda ${section:option} för att beteckna ett värde från en utländsk sektion. Interpolering kan sträcka sig över flera nivåer. För enkelhetens skull, om section: utelämnas, blir standardvärdet för interpolering det aktuella avsnittet (och eventuellt standardvärdena från specialavsnittet).

Den konfiguration som anges ovan med grundläggande interpolering skulle t.ex. se ut så här med utökad interpolering:

[Sökvägar]
hem_dir: /Användare
min_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Bilder

[Escape]
# använd en $$ för att undkomma tecknet $ ($ är det enda tecken som behöver undkommas):
kostnad: $$80

Värden från andra sektioner kan också hämtas:

[Vanlig]
hem_dir: /Användare
bibliotek_dir: /Bibliotek
system_dir: /System
macports_dir: /opt/lokal

[Ramverk]
Python: 3.2
sökväg: ${Common:system_dir}/Bibliotek/Framverk/

[Arthur]
smeknamn: Two Sheds
efternamn: Jackson
min_dir: ${Common:home_dir}/twosheds
mina_bilder: ${my_dir}/Bilder
python_dir: ${Frameworks:path}/Python/Versioner/${Frameworks:Python}

Mappning Protokoll Åtkomst

Tillagd i version 3.2.

Mappningsprotokollåtkomst är ett generiskt namn för funktionalitet som gör det möjligt att använda anpassade objekt som om de vore lexikon. I fallet med configparser använder implementationen av mappningsgränssnittet notationen parser['section']['option'].

parser['section'] returnerar i synnerhet en proxy för sektionens data i parsern. Detta innebär att värdena inte kopieras utan hämtas från den ursprungliga parsern på begäran. Vad som är ännu viktigare är att när värden ändras på en sektionsproxy, så ändras de faktiskt i den ursprungliga parsern.

configparser-objekt beter sig så nära faktiska ordböcker som möjligt. Mappningsgränssnittet är komplett och följer MutableMapping ABC. Det finns dock några skillnader som bör tas med i beräkningen:

  • Som standard är alla nycklar i sektioner tillgängliga på ett skiftlägesokänsligt sätt [1]. T.ex. for option in parser["section"] ger endast optionxform’ed alternativnyckelnamn. Detta innebär att nycklarna som standard har gemener. Samtidigt, för ett avsnitt som innehåller nyckeln 'a', returnerar båda uttrycken True:

    "a" i parser["section"]
    "A" i parser["section"]
    
  • Alla sektioner innehåller även DEFAULTSECT -värden, vilket innebär att .clear() på en sektion inte nödvändigtvis gör sektionen synligt tom. Detta beror på att standardvärden inte kan raderas från sektionen (eftersom de tekniskt sett inte finns där). Om de åsidosätts i sektionen blir standardvärdet synligt igen när de raderas. Om du försöker radera ett standardvärde uppstår ett KeyError.

  • DEFAULTSECT kan inte tas bort från parsern:

    • försök att ta bort det ger ValueError,

    • parser.clear() lämnar den intakt,

    • parser.popitem() returnerar den aldrig.

  • parser.get(section, option, **kwargs) - det andra argumentet är inte ett fallback-värde. Observera dock att metoderna get() på sektionsnivå är kompatibla både med mappningsprotokollet och det klassiska configparser-API:et.

  • parser.items() är kompatibel med mappningsprotokollet (returnerar en lista med paren section_name, section_proxy inklusive DEFAULTSECT). Den här metoden kan dock också anropas med argument: parser.items(section, raw, vars). Det senare anropet returnerar en lista med paren option, value för en angiven section, med alla interpoleringar expanderade (om inte raw=True anges).

Mappningsprotokollet implementeras ovanpå det befintliga äldre API:et så att subklasser som åsidosätter det ursprungliga gränssnittet fortfarande bör ha mappningar som fungerar som förväntat.

Anpassa parserns beteende

Det finns nästan lika många INI-formatvarianter som det finns applikationer som använder det. configparser gör mycket för att ge stöd för den största möjliga uppsättningen INI-stilar som finns tillgängliga. Standardfunktionaliteten dikteras huvudsakligen av historisk bakgrund och det är mycket troligt att du kommer att vilja anpassa några av funktionerna.

Det vanligaste sättet att ändra hur en specifik konfigurationsparser fungerar är att använda __init__()-alternativen:

  • defaults, standardvärde: None

    Detta alternativ accepterar en ordlista med nyckel-värdepar som initialt kommer att placeras i avsnittet DEFAULT. Detta är ett elegant sätt att stödja kortfattade konfigurationsfiler som inte anger värden som är desamma som den dokumenterade standardinställningen.

    Tips: Om du vill ange standardvärden för ett visst avsnitt använder du read_dict() innan du läser den faktiska filen.

  • dict_type, standardvärde: dict

    Detta alternativ har stor inverkan på hur mappningsprotokollet kommer att bete sig och hur de skrivna konfigurationsfilerna ser ut. Med standardordboken lagras varje avsnitt i den ordning som de lades till i parsern. Detsamma gäller för alternativ inom avsnitt.

    En alternativ ordbokstyp kan t.ex. användas för att sortera sektioner och alternativ på write-back.

    Observera: Det finns sätt att lägga till en uppsättning nyckel-värdepar i en enda operation. När du använder en vanlig ordbok i dessa operationer kommer ordningen på nycklarna att vara ordnad. Till exempel:

    >>> 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, standardvärde: False

    Det är känt att vissa konfigurationsfiler innehåller inställningar utan värden, men som i övrigt överensstämmer med den syntax som stöds av configparser. Parametern allow_no_value till konstruktören kan användas för att ange att sådana värden ska accepteras:

    >>> 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'
    
  • avgränsningstecken, standardvärde: ('=', ':')

    Avgränsare är substrängar som avgränsar nycklar från värden inom ett avsnitt. Den första förekomsten av en avgränsande substräng på en rad betraktas som en avgränsare. Detta innebär att värden (men inte nycklar) kan innehålla avgränsare.

    Se även argumentet space_around_delimiters till ConfigParser.write().

  • comment_prefixes, standardvärde: ('#', ';')

  • inline_comment_prefixes, standardvärde: None

    Comment prefixes är strängar som anger början på en giltig kommentar i en konfigurationsfil. comment_prefixes används endast på annars tomma rader (eventuellt indragna) medan inline_comment_prefixes kan användas efter varje giltigt värde (t.ex. sektionsnamn, alternativ och även tomma rader). Som standard är inline-kommentarer inaktiverade och '#' och ';' används som prefix för kommentarer på hela rader.

    Ändrad i version 3.2: I tidigare versioner av configparser matchade beteendet comment_prefixes=('#',';') och inline_comment_prefixes=(';',).

    Observera att konfigurationsanalysatorer inte stöder escaping av kommentarprefix, så om du använder inline_comment_prefixes kan det hindra användare från att ange alternativvärden med tecken som används som kommentarprefix. Undvik att ange inline_comment_prefixes när du är osäker. Under alla omständigheter är det enda sättet att lagra prefixtecken för kommentarer i början av en rad i flerradiga värden att interpolera prefixet, t.ex.:

    >>> 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, standardvärde: True

    När inställningen är True tillåter inte parsern att avsnitt eller alternativ dupliceras när den läser från en enda källa (med read_file(), read_string() eller read_dict()). Det rekommenderas att använda strikta parsers i nya applikationer.

    Ändrad i version 3.2: I tidigare versioner av configparser matchade beteendet strict=False.

  • empty_lines_in_values, standardvärde: True

    I config-parsers kan värden sträcka sig över flera rader så länge de är indragna mer än den nyckel som innehåller dem. Som standard låter parsers även tomma rader vara delar av värden. Samtidigt kan nycklarna själva vara godtyckligt indragna för att förbättra läsbarheten. När konfigurationsfiler blir stora och komplexa är det därför lätt för användaren att tappa bort filstrukturen. Ta till exempel:

    [Sektion]
    nyckel = multilinje
      värde med en gotcha
    
     detta = är fortfarande en del av det flerledade värdet av 'nyckel'
    

    Detta kan vara särskilt problematiskt för användaren att se om hon använder ett proportionellt teckensnitt för att redigera filen. Det är därför du bör överväga att inte tillåta värden med tomma rader när din applikation inte behöver dem. Detta kommer att göra att tomma rader delar tangenter varje gång. I exemplet ovan skulle det ge två nycklar, key och this.

  • default_section, standardvärde: configparser.DEFAULTSECT (det vill säga: "DEFAULT")

    Konventionen att tillåta ett speciellt avsnitt med standardvärden för andra avsnitt eller interpoleringsändamål är ett kraftfullt koncept i detta bibliotek, vilket gör det möjligt för användare att skapa komplexa deklarativa konfigurationer. Detta avsnitt kallas normalt "DEFAULT" men det kan anpassas så att det pekar på vilket annat giltigt avsnittsnamn som helst. Några typiska värden är t.ex: "general" eller "common". Det angivna namnet används för att känna igen standardavsnitt när man läser från en källa och används när man skriver tillbaka konfigurationen till en fil. Dess aktuella värde kan hämtas med hjälp av attributet parser_instance.default_section och kan ändras under körning (t.ex. för att konvertera filer från ett format till ett annat).

  • interpolation, standardvärde: configparser.BasicInterpolation

    Interpolationsbeteendet kan anpassas genom att tillhandahålla en anpassad hanterare via argumentet interpolation. None kan användas för att stänga av interpolering helt, ExtendedInterpolation() ger en mer avancerad variant inspirerad av zc.buildout. Mer om ämnet i det dedikerade dokumentationsavsnittet. RawConfigParser har ett standardvärde på None.

  • omvandlare, standardvärde: inte inställt

    Config-parsers tillhandahåller getters för alternativvärden som utför typkonvertering. Som standard implementeras getint(), getfloat() och getboolean(). Om andra getters är önskvärda kan användare definiera dem i en subklass eller skicka en dictionary där varje nyckel är ett namn på omvandlaren och varje värde är en anropsbar som implementerar omvandlingen. Till exempel, om man skickar {'decimal': decimal.Decimal} skulle man lägga till getdecimal() på både parserobjektet och alla sektionsproxies. Med andra ord kommer det att vara möjligt att skriva både parser_instance.getdecimal('section', 'key', fallback=0) och parser_instance['section'].getdecimal('key', 0).

    Om omvandlaren behöver komma åt parserns tillstånd kan det implementeras som en metod i en config parser-underklass. Om namnet på denna metod börjar med get kommer den att vara tillgänglig på alla sektionsproxyer, i den dict-kompatibla formen (se exemplet getdecimal() ovan).

Mer avancerad anpassning kan uppnås genom att åsidosätta standardvärdena för dessa parserattribut. Standardvärdena definieras för klasserna, så de kan åsidosättas av subklasser eller genom attributtilldelning.

ConfigParser.BOOLEAN_STATES

Som standard när getboolean() används, beaktar config-parser följande värden True: '1', 'yes', 'true', 'on' och följande värden False: '0', 'no', 'false', 'off'. Du kan åsidosätta detta genom att ange en anpassad ordlista med strängar och deras booleska resultat. Till exempel:

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

Andra typiska booleska par är accept/reject eller enabled/disabled.

ConfigParser.optionxform(option)

Denna metod omvandlar optionsnamn vid varje read-, get- eller set-operation. Som standard konverteras namnet till gemener. Detta innebär också att när en konfigurationsfil skrivs kommer alla nycklar att vara gemener. Åsidosätt denna metod om det är olämpligt. Till exempel:

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

Anteckning

Funktionen optionxform omvandlar optionsnamn till en kanonisk form. Detta bör vara en idempotent funktion: om namnet redan är i kanonisk form bör det returneras oförändrat.

ConfigParser.SECTCRE

Ett kompilerat reguljärt uttryck som används för att analysera sektionsrubriker. Standardvärdet matchar [section] till namnet "section". Whitespace anses vara en del av sektionsnamnet, så [ larch ] kommer att läsas som en sektion med namnet " larch". Åsidosätt detta attribut om det är olämpligt. Exempelvis:

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

Anteckning

Även om ConfigParser-objekt också använder ett OPTCRE-attribut för att känna igen optionsrader rekommenderas det inte att åsidosätta det eftersom det skulle störa konstruktoralternativen allow_no_value och delimiters.

Exempel på äldre API

Främst på grund av bakåtkompatibilitet tillhandahåller configparser också ett äldre API med explicita get/set-metoder. Även om det finns giltiga användningsfall för de metoder som beskrivs nedan, föredras åtkomst via mappningsprotokoll för nya projekt. Det äldre API:et är ibland mer avancerat, på låg nivå och rent av kontraintuitivt.

Ett exempel på hur man skriver till en konfigurationsfil:

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)

Ett exempel på att läsa konfigurationsfilen igen:

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

För att få interpolation, använd 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

Standardvärden finns tillgängliga i båda typerna av ConfigParsers. De används vid interpolering om ett alternativ som används inte är definierat någon annanstans.

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

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)

Den huvudsakliga konfigurationsparsern. När defaults anges initialiseras den till en ordbok med inneboende standardvärden. När dict_type anges kommer den att användas för att skapa ordboksobjekt för listan över avsnitt, för alternativen inom ett avsnitt och för standardvärdena.

När delimiters anges används det som den uppsättning substrängar som skiljer nycklar från värden. När comment_prefixes anges kommer det att användas som en uppsättning substrängar som prefixar kommentarer i annars tomma rader. Kommentarer kan vara indragna. När inline_comment_prefixes anges kommer det att användas som den uppsättning substrängar som prefixar kommentarer på icke-tomma rader.

När strict är True (standard) kommer parsern inte att tillåta dubbletter av avsnitt eller alternativ när den läser från en enda källa (fil, sträng eller ordbok), vilket ger DuplicateSectionError eller DuplicateOptionError. När empty_lines_in_values är False (standard: True) markerar varje tom rad slutet på ett alternativ. Annars behålls interna tomma rader i ett flerradigt alternativ som en del av värdet. När allow_no_value är True (standard: False) accepteras alternativ utan värden; värdet för dessa är None och de serialiseras utan den efterföljande avgränsaren.

När default_section anges, specificeras namnet på det speciella avsnitt som innehåller standardvärden för andra avsnitt och för interpoleringsändamål (normalt benämnt "DEFAULT"). Detta värde kan hämtas och ändras vid körning med hjälp av instansattributet default_section. Detta kommer inte att omvärdera en redan analyserad konfigurationsfil, men kommer att användas när du skriver analyserade inställningar till en ny konfigurationsfil.

Interpolationsbeteendet kan anpassas genom att tillhandahålla en anpassad hanterare via argumentet interpolation. None kan användas för att stänga av interpolering helt, ExtendedInterpolation() ger en mer avancerad variant inspirerad av zc.buildout. Mer om ämnet i det dedikerade dokumentationsavsnittet.

Alla alternativnamn som används i interpoleringen skickas genom metoden optionxform() precis som alla andra referenser till alternativnamn. Till exempel, med standardimplementeringen av optionxform() (som konverterar alternativnamn till gemener), är värdena foo %(bar)s och foo %(BAR)s likvärdiga.

När converters anges bör det vara en dictionary där varje nyckel representerar namnet på en typomvandlare och varje värde är en anropsbar som implementerar omvandlingen från sträng till önskad datatyp. Varje omvandlare får sin egen motsvarande get*()-metod på parserobjektet och sektionsproxyerna.

När allow_unnamed_section är True (standard: False) kan det första sektionsnamnet utelämnas. Se avsnittet ”Unnamed Sections”.

Det är möjligt att läsa in flera konfigurationer i en enda ConfigParser, där den senast tillagda konfigurationen har högsta prioritet. Eventuella motstridiga nycklar hämtas från den senaste konfigurationen medan de tidigare befintliga nycklarna behålls. I exemplet nedan läses en fil med namnet override.ini in, som åsidosätter alla motstridiga nycklar från filen example.ini.

[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

Ändrad i version 3.1: Standardvärdet för dict_type är collections.OrderedDict.

Ändrad i version 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section och interpolation har lagts till.

Ändrad i version 3.5: Argumentet konverterare har lagts till.

Ändrad i version 3.7: Argumentet defaults läses med read_dict(), vilket ger ett konsekvent beteende i hela parsern: nycklar och värden som inte är strängar konverteras implicit till strängar.

Ändrad i version 3.8: Standard dict_type är dict, eftersom den nu bevarar inmatningsordningen.

Ändrad i version 3.13: Skapar ett MultilineContinuationError när allow_no_value är True, och en nyckel utan värde fortsätter med en indragen rad.

Ändrad i version 3.13: Argumentet allow_unnamed_section har lagts till.

defaults()

Returnerar en ordbok som innehåller de instansövergripande standardvärdena.

sections()

Returnerar en lista över tillgängliga sektioner; standardsektionen ingår inte i listan.

add_section(section)

Lägger till en sektion med namnet section till instansen. Om en sektion med det angivna namnet redan existerar, DuplicateSectionError tas upp. Om default section-namnet anges, genereras ValueError. Namnet på sektionen måste vara en sträng, annars visas TypeError.

Ändrad i version 3.2: Icke-strängade sektionsnamn ger upphov till TypeError.

has_section(section)

Indikerar om den namngivna sektionen finns i konfigurationen. Standardavsnittet default section bekräftas inte.

options(section)

Returnerar en lista över alternativ som är tillgängliga i den angivna sektionen.

has_option(section, option)

Om den angivna sektionen finns och innehåller den angivna optionen, returneras True; annars returneras False. Om den angivna sektionen är None eller en tom sträng, antas DEFAULT.

read(filenames, encoding=None)

Försöker läsa och analysera en iterabel med filnamn och returnerar en lista med filnamn som analyserats framgångsrikt.

Om filnamn är en sträng, ett bytes-objekt eller ett path-like object, behandlas det som ett enda filnamn. Om en fil som anges i filnamn inte kan öppnas ignoreras den filen. Detta är utformat så att du kan ange en iterabel av potentiella platser för konfigurationsfiler (till exempel den aktuella katalogen, användarens hemkatalog och någon systemomfattande katalog), och alla befintliga konfigurationsfiler i den iterabla kommer att läsas.

Om ingen av de namngivna filerna finns, kommer ConfigParser-instansen att innehålla en tom dataset. En applikation som kräver att initiala värden laddas från en fil bör ladda den eller de filer som krävs med hjälp av read_file() innan den anropar read() för eventuella valfria filer:

import configparser, os

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

Ändrad i version 3.2: Parametern encoding har lagts till. Tidigare lästes alla filer med hjälp av standardkodningen för open().

Ändrad i version 3.6.1: Parametern filnamn accepterar en path-like object.

Ändrad i version 3.7: Parametern filnamn accepterar ett bytes-objekt.

read_file(f, source=None)

Läser och analyserar konfigurationsdata från f som måste vara en iterabel som ger Unicode-strängar (t.ex. filer som öppnas i textläge).

Det valfria argumentet källa anger namnet på den fil som läses. Om det inte anges och f har attributet name, används det för source; standardvärdet är '<???>'.

Tillagd i version 3.2: Ersätter readfp().

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

Analyserar konfigurationsdata från en sträng.

Det valfria argumentet source anger ett kontextspecifikt namn på den sträng som skickas. Om det inte anges används '<string>'. Detta bör vanligtvis vara en filsystemssökväg eller en URL.

Tillagd i version 3.2.

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

Ladda konfiguration från ett objekt som tillhandahåller en diktliknande metod items(). Nycklar är namn på sektioner, värden är ordböcker med nycklar och värden som ska finnas i sektionen. Om den använda ordbokstypen bevarar ordningen kommer sektioner och deras nycklar att läggas till i ordning. Värden konverteras automatiskt till strängar.

Det valfria argumentet source anger ett kontextspecifikt namn på den ordbok som skickas. Om det inte anges används <dict>.

Denna metod kan användas för att kopiera tillstånd mellan parsers.

Tillagd i version 3.2.

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

Hämta ett option-värde för den namngivna section. Om vars anges måste det vara en ordbok. Alternativet söks upp i vars (om det finns), section och DEFAULTSECT i den ordningen. Om nyckeln inte hittas och fallback anges, används den som ett reservvärde. None kan anges som ett fallback-värde.

Alla '%'-interpoleringar expanderas i returvärdena, såvida inte argumentet raw är true. Värden för interpolationsnycklar söks upp på samma sätt som för alternativet.

Ändrad i version 3.2: Argumenten raw, vars och fallback är nyckelord endast för att skydda användare från att försöka använda det tredje argumentet som fallback-fallback (särskilt vid användning av mappningsprotokollet).

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

En praktisk metod som omvandlar alternativet i den angivna sektionen till ett heltal. Se get() för förklaring av raw, vars och fallback.

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

En praktisk metod som omvandlar alternativet i den angivna sektionen till ett flyttal. Se get() för förklaring av raw, vars och fallback.

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

En bekvämlighetsmetod som tvingar alternativet i den angivna sektionen till ett booleskt värde. Observera att de accepterade värdena för alternativet är '1', 'yes', 'true' och 'on', som gör att denna metod returnerar True, och '0', 'no', 'false' och 'off', som gör att den returnerar False. Dessa strängvärden kontrolleras på ett sätt som inte tar hänsyn till skiftlägesskillnader. Alla andra värden kommer att ge upphov till ValueError. Se get() för förklaring av raw, vars och fallback.

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

Om section inte anges, returneras en lista med paren section_name, section_proxy, inklusive DEFAULTSECT.

I annat fall returneras en lista med paren namn, värde för alternativen i den angivna sektionen. Valfria argument har samma betydelse som för metoden get().

Ändrad i version 3.8: Objekt som finns i vars visas inte längre i resultatet. Det tidigare beteendet blandade faktiska parseralternativ med variabler som tillhandahölls för interpolering.

set(section, option, value)

Om det givna avsnittet finns, sätt det givna alternativet till det angivna värdet; annars uppstår NoSectionError. option och value måste vara strängar; om inte, uppstår TypeError.

write(fileobject, space_around_delimiters=True)

Skriver en representation av konfigurationen till det angivna file object, som måste öppnas i textläge (accepterar strängar). Denna representation kan analyseras av ett framtida read()-anrop. Om space_around_delimiters är true, omges avgränsningar mellan nycklar och värden av mellanslag.

Ändrad i version 3.14: Utlöser InvalidWriteError om detta skulle skriva en representation som inte kan analyseras korrekt av ett framtida read()-anrop från denna analysator.

Anteckning

Kommentarer i den ursprungliga konfigurationsfilen bevaras inte när konfigurationen skrivs tillbaka. Vad som betraktas som en kommentar beror på de angivna värdena för comment_prefix och inline_comment_prefix.

remove_option(section, option)

Tar bort det angivna alternativet från det angivna avsnittet. Om sektionen inte finns, returneras NoSectionError. Om alternativet existerade för att tas bort, returneras True; annars returneras False.

remove_section(section)

Tar bort den angivna sektionen från konfigurationen. Om avsnittet faktiskt existerade returneras True. Annars returneras False.

optionxform(option)

Transformerar optionsnamnet option som finns i en indatafil eller som skickas in av klientkod till den form som ska användas i de interna strukturerna. Standardimplementeringen returnerar en version av option med små bokstäver; subklasser kan åsidosätta detta eller så kan klientkoden ange ett attribut med detta namn på instanser för att påverka detta beteende.

Du behöver inte underklassa parsern för att använda den här metoden, du kan också ställa in den på en instans, till en funktion som tar ett strängargument och returnerar en sträng. Att ställa in den till str, till exempel, skulle göra alternativnamn skiftlägeskänsliga:

cfgparser = ConfigParser()
cfgparser.optionxform = str

Observera att vid läsning av konfigurationsfiler tas blanksteg runt alternativnamnen bort innan optionxform() anropas.

configparser.UNNAMED_SECTION

Ett specialobjekt som representerar ett sektionsnamn som används för att referera till en icke namngiven sektion (se Icke namngivna sektioner).

configparser.MAX_INTERPOLATION_DEPTH

Det maximala djupet för rekursiv interpolation för get() när parametern raw är false. Detta är endast relevant när standardvärdet interpolation används.

RawConfigParser-objekt

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)

Äldre variant av ConfigParser. Den har interpolering inaktiverad som standard och tillåter icke-strängade sektionsnamn, alternativnamn och värden via dess osäkra metoder add_section och set, samt den äldre defaults= nyckelordsargumenthanteringen.

Ändrad i version 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section och interpolation har lagts till.

Ändrad i version 3.5: Argumentet konverterare har lagts till.

Ändrad i version 3.8: Standard dict_type är dict, eftersom den nu bevarar inmatningsordningen.

Ändrad i version 3.13: Argumentet allow_unnamed_section har lagts till.

Anteckning

Överväg att använda ConfigParser istället, som kontrollerar typerna för de värden som ska lagras internt. Om du inte vill ha interpolering kan du använda ConfigParser(interpolation=None).

add_section(section)

Lägg till en sektion med namnet section eller UNNAMED_SECTION till instansen.

Om den angivna sektionen redan existerar, DuplicateSectionError. Om standardnamnet på sektionen anges, genereras ValueError. Om UNNAMED_SECTION anges och stödet är inaktiverat, genereras UnnamedSectionDisabledError.

Type of section kontrolleras inte, vilket gör det möjligt för användare att skapa avsnitt med namn som inte är strängnamn. Detta beteende stöds inte och kan orsaka interna fel.

Ändrad i version 3.14: Lagt till stöd för UNNAMED_SECTION.

set(section, option, value)

Om den givna sektionen finns, sätt det givna alternativet till det angivna värdet; annars uppstår NoSectionError. Det är möjligt att använda RawConfigParser (eller ConfigParser med raw-parametrar inställda på true) för intern lagring av värden som inte är strängvärden, men full funktionalitet (inklusive interpolering och utmatning till filer) kan endast uppnås med strängvärden.

Med den här metoden kan användare tilldela icke-strängvärden till nycklar internt. Detta beteende stöds inte och kommer att orsaka fel när man försöker skriva till en fil eller hämta den i icke-rått läge. Använd mappningsprotokollets API som inte tillåter att sådana tilldelningar sker.

Undantag

exception configparser.Error

Basklass för alla andra configparser-undantag.

exception configparser.NoSectionError

Undantag som uppstår när ett angivet avsnitt inte hittas.

exception configparser.DuplicateSectionError

Undantag om add_section() anropas med namnet på ett avsnitt som redan finns eller i strikta parsers när ett avsnitt hittas mer än en gång i en enda indatafil, sträng eller ordbok.

Ändrad i version 3.2: Lagt till de valfria attributen och parametrarna source och lineno till __init__().

exception configparser.DuplicateOptionError

Undantag som tas upp av strikta parsers om ett enda alternativ visas två gånger under läsning från en enda fil, sträng eller ordbok. Detta fångar upp felstavningar och fel relaterade till skiftlägeskänslighet, t.ex. kan en ordbok ha två nycklar som representerar samma skiftlägesokänsliga konfigurationsnyckel.

exception configparser.NoOptionError

Undantag som uppstår när ett angivet alternativ inte finns i det angivna avsnittet.

exception configparser.InterpolationError

Basklass för undantag som uppstår när det uppstår problem vid stränginterpolering.

exception configparser.InterpolationDepthError

Undantag som uppstår när stränginterpolering inte kan slutföras eftersom antalet iterationer överstiger MAX_INTERPOLATION_DEPTH. Underklass till InterpolationError.

exception configparser.InterpolationMissingOptionError

Undantag som uppstår när ett alternativ som refereras från ett värde inte finns. Underklass till InterpolationError.

exception configparser.InterpolationSyntaxError

Undantag som uppstår när källtexten i vilken substitutioner görs inte överensstämmer med den syntax som krävs. Underklass till InterpolationError.

exception configparser.MissingSectionHeaderError

Exception vid försök att analysera en fil som inte har några avsnittsrubriker.

exception configparser.ParsingError

Undantag som uppstår när fel inträffar vid försök att analysera en fil.

Ändrad i version 3.12: Attributet filnamn och __init__()-konstruktörsargumentet togs bort. De har varit tillgängliga med namnet source sedan 3.2.

exception configparser.MultilineContinuationError

Undantag när en tangent utan motsvarande värde fortsätter med en indragen rad.

Tillagd i version 3.13.

exception configparser.UnnamedSectionDisabledError

Exception uppstod när man försökte använda UNNAMED_SECTION utan att aktivera den.

Tillagd i version 3.14.

exception configparser.InvalidWriteError

Exception uppstod när ett försök till ConfigParser.write() inte skulle tolkas korrekt med ett framtida ConfigParser.read()-anrop.

Ex: Att skriva en nyckel som börjar med mönstret ConfigParser.SECTCRE skulle tolkas som en sektionsrubrik när den läses. Försök att skriva detta kommer att ge upphov till detta undantag.

Tillagd i version 3.14.

Fotnoter