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 avhome_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, omsection:
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 endastoptionxform
’ed alternativnyckelnamn. Detta innebär att nycklarna som standard har gemener. Samtidigt, för ett avsnitt som innehåller nyckeln'a'
, returnerar båda uttryckenTrue
:"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 ettKeyError
.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 metodernaget()
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 angivensection
, med alla interpoleringar expanderade (om interaw=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 beteendetcomment_prefixes=('#',';')
ochinline_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 (medread_file()
,read_string()
ellerread_dict()
). Det rekommenderas att använda strikta parsers i nya applikationer.Ändrad i version 3.2: I tidigare versioner av
configparser
matchade beteendetstrict=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
ochthis
.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 attributetparser_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 avzc.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()
ochgetboolean()
. 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 tillgetdecimal()
på både parserobjektet och alla sektionsproxies. Med andra ord kommer det att vara möjligt att skriva bådeparser_instance.getdecimal('section', 'key', fallback=0)
ochparser_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 exempletgetdecimal()
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ärdenTrue
:'1'
,'yes'
,'true'
,'on'
och följande värdenFalse
:'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
ellerenabled
/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 gerDuplicateSectionError
ellerDuplicateOptionError
. När empty_lines_in_values ärFalse
(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 ärTrue
(standard:False
) accepteras alternativ utan värden; värdet för dessa ärNone
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 instansattributetdefault_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 avzc.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 avoptionxform()
(som konverterar alternativnamn till gemener), är värdenafoo %(bar)s
ochfoo %(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 namnetoverride.ini
in, som åsidosätter alla motstridiga nycklar från filenexample.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 ärTrue
, 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, genererasValueError
. Namnet på sektionen måste vara en sträng, annars visasTypeError
.Ä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 returnerasFalse
. Om den angivna sektionen ärNone
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 avread_file()
innan den anroparread()
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 returnerarTrue
, och'0'
,'no'
,'false'
och'off'
, som gör att den returnerarFalse
. 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 tillValueError
. Seget()
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årTypeError
.
- 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, returnerasTrue
; annars returnerasFalse
.
- remove_section(section)¶
Tar bort den angivna sektionen från konfigurationen. Om avsnittet faktiskt existerade returneras
True
. Annars returnerasFalse
.
- 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).
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 metoderadd_section
ochset
, samt den äldredefaults=
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ändaConfigParser(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, genererasValueError
. OmUNNAMED_SECTION
anges och stödet är inaktiverat, genererasUnnamedSectionDisabledError
.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ändaRawConfigParser
(ellerConfigParser
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 tillInterpolationError
.
- 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 namnetsource
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 framtidaConfigParser.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