locale — Internationaliseringstjänster

Källkod: Lib/locale.py

---

Modulen locale ger tillgång till POSIX locale-databasen och dess funktioner. POSIX locale-mekanismen gör det möjligt för programmerare att hantera vissa kulturella frågor i en applikation, utan att programmeraren behöver känna till alla detaljer i varje land där programvaran körs.

Modulen locale implementeras ovanpå modulen _locale, som i sin tur använder en ANSI C-localeimplementering om sådan finns tillgänglig.

Modulen locale definierar följande undantag och funktioner:

exception locale.Error

Exception uppstår när den locale som skickas till setlocale() inte känns igen.

locale.setlocale(category, locale=None)

Om locale anges och inte None, ändrar setlocale() locale-inställningen för category. De tillgängliga kategorierna listas i databeskrivningen nedan. locale kan vara en sträng eller en iterabel av två strängar (språkkod och kodning). Om det är en iterabel konverteras den till ett lokalt namn med hjälp av locale aliasing engine. En tom sträng anger användarens standardinställningar. Om modifieringen av locale misslyckas, uppstår undantaget Error. Om det lyckas returneras den nya lokalinställningen.

Om locale utelämnas eller None returneras den aktuella inställningen för category.

setlocale() är inte trådsäkert på de flesta system. Applikationer börjar vanligtvis med ett anrop av

import locale
locale.setlocale(locale.LC_ALL, '')

Detta innebär att alla kategoriers språkinställning ändras till användarens standardinställning (som vanligtvis anges i miljövariabeln LANG). Om lokalinställningen inte ändras därefter bör det inte orsaka problem att använda multithreading.

locale.localeconv()

Returnerar databasen för de lokala konventionerna som en ordbok. Denna ordbok har följande strängar som nycklar:

Kategori	Nyckel	Betydelse
LC_NUMERIC	'decimal_point'	Tecken för decimalpunkt.
	'grouping'	Sekvens av siffror som anger vilka relativa positioner som 'thousands_sep' förväntas. Om sekvensen avslutas med CHAR_MAX, utförs ingen ytterligare gruppering. Om sekvensen avslutas med 0 används den senaste gruppstorleken upprepade gånger.
	'thousands_sep'	Karaktär används mellan grupperna.
LC_MONETARY	'int_curr_symbol'	Internationell valutasymbol.
	'currency_symbol'	Symbol för lokal valuta.
	'p_cs_precedes/n_cs_precedes'	Om valutasymbolen föregår värdet (för positiva resp. negativa värden).
	'p_sep_by_space/n_sep_by_space'	Om valutasymbolen är åtskild från värdet med ett mellanslag (för positiva resp. negativa värden).
	'mon_decimal_point'	Decimalpunkt som används för monetära värden.
	'frac_digits'	Antal fraktionerade siffror som används vid lokal formatering av monetära värden.
	'int_frac_digits'	Antal bråksiffror som används vid internationell formatering av monetära värden.
	'mon_thousands_sep'	Gruppseparator som används för monetära värden.
	'mon_grouping'	Motsvarar 'grouping', används för monetära värden.
	'positive_sign'	Symbol som används för att markera ett positivt penningvärde.
	'negative_sign'	Symbol som används för att markera ett negativt penningvärde.
	'p_sign_posn/n_sign_posn'	Tecknets position (för positiva resp. negativa värden), se nedan.

Alla numeriska värden kan sättas till CHAR_MAX för att ange att det inte finns något värde angivet i denna locale.

De möjliga värdena för 'p_sign_posn' och 'n_sign_posn' anges nedan.

Värde	Förklaring
0	Valuta och värde omges av parenteser.
1	Tecknet ska föregå värde- och valutasymbolen.
2	Tecknet ska följa värde- och valutasymbolen.
3	Tecknet ska omedelbart föregå värdet.
4	Tecknet ska följa omedelbart efter värdet.
CHAR_MAX	Ingenting anges i denna locale.

Funktionen ställer temporärt in LC_CTYPE locale till LC_NUMERIC locale eller LC_MONETARY locale om locale är olika och numeriska eller monetära strängar är icke-ASCII. Denna tillfälliga ändring påverkar andra trådar.

Ändrad i version 3.7: Funktionen ställer nu tillfälligt in LC_CTYPE locale till LC_NUMERIC locale i vissa fall.

locale.nl_langinfo(option)

Returnerar viss lokalspecifik information som en sträng. Denna funktion är inte tillgänglig på alla system, och uppsättningen möjliga alternativ kan också variera mellan olika plattformar. De möjliga argumentvärdena är siffror, för vilka symboliska konstanter finns tillgängliga i locale-modulen.

Funktionen nl_langinfo() accepterar en av följande nycklar. De flesta beskrivningar är hämtade från motsvarande beskrivning i GNU C-biblioteket.

locale.CODESET

Hämta en sträng med namnet på den teckenkodning som används i den valda lokalen.

locale.D_T_FMT

Hämta en sträng som kan användas som formatsträng för time.strftime() för att representera datum och tid på ett lokalspecifikt sätt.

locale.D_FMT

Hämta en sträng som kan användas som formatsträng för time.strftime() för att representera ett datum på ett lokalspecifikt sätt.

locale.T_FMT

Hämta en sträng som kan användas som formatsträng för time.strftime() för att representera en tid på ett lokalspecifikt sätt.

locale.T_FMT_AMPM

Hämta en formatsträng för time.strftime() för att representera tid i am/pm-format.

locale.DAY_1

locale.DAY_2

locale.DAY_3

locale.DAY_4

locale.DAY_5

locale.DAY_6

locale.DAY_7

Hämta namnet på den n:te veckodagen.

Anteckning

Detta följer den amerikanska konventionen att DAY_1 är söndag, inte den internationella konventionen (ISO 8601) att måndag är den första dagen i veckan.

locale.ABDAY_1

locale.ABDAY_2

locale.ABDAY_3

locale.ABDAY_4

locale.ABDAY_5

locale.ABDAY_6

locale.ABDAY_7

Hämta det förkortade namnet på den n:te veckodagen.

locale.MON_1

locale.MON_2

locale.MON_3

locale.MON_4

locale.MON_5

locale.MON_6

locale.MON_7

locale.MON_8

locale.MON_9

locale.MON_10

locale.MON_11

locale.MON_12

Hämta namnet på den n:te månaden.

locale.ABMON_1

locale.ABMON_2

locale.ABMON_3

locale.ABMON_4

locale.ABMON_5

locale.ABMON_6

locale.ABMON_7

locale.ABMON_8

locale.ABMON_9

locale.ABMON_10

locale.ABMON_11

locale.ABMON_12

Hämta det förkortade namnet på den n:te månaden.

locale.RADIXCHAR

Hämta radixtecknet (decimalpunkt, decimalkommatecken etc.).

locale.THOUSEP

Hämta separatortecknet för tusentals (grupper om tre siffror).

locale.YESEXPR

Hämta ett reguljärt uttryck som kan användas med regex-funktionen för att känna igen ett positivt svar på en ja/nej-fråga.

locale.NOEXPR

Hämta ett reguljärt uttryck som kan användas med funktionen regex(3) för att känna igen ett negativt svar på en ja/nej-fråga.

Anteckning

De reguljära uttrycken för YESEXPR och NOEXPR använder syntax som passar för funktionen regex från C-biblioteket, vilket kan skilja sig från den syntax som används i re.

locale.CRNCYSTR

Hämta valutasymbolen, föregången av ”-” om symbolen ska visas före värdet, ”+” om symbolen ska visas efter värdet, eller ”.” om symbolen ska ersätta radixtecknet.

locale.ERA

Hämta en sträng som beskriver hur år räknas och visas för varje era i en lokal.

De flesta lokala språk definierar inte detta värde. Ett exempel på en lokal som definierar detta värde är den japanska. I Japan inkluderar den traditionella representationen av datum namnet på den era som motsvarar den dåvarande kejsarens regeringstid.

Normalt bör det inte vara nödvändigt att använda detta värde direkt. Genom att ange modifieraren E i formatsträngarna får funktionen time.strftime() att använda denna information. Formatet på den returnerade strängen specificeras i The Open Group Base Specifications Issue 8, paragraf 7.3.5.2 LC_TIME C-Language Access.

locale.ERA_D_T_FMT

Hämta en formatsträng för time.strftime() för att representera datum och tid på ett lokalspecifikt tidsbaserat sätt.

locale.ERA_D_FMT

Hämta en formatsträng för time.strftime() för att representera ett datum på ett lokalspecifikt tidsbaserat sätt.

locale.ERA_T_FMT

Hämta en formatsträng för time.strftime() för att representera en tid på ett lokalspecifikt tidsbaserat sätt.

locale.ALT_DIGITS

Hämta en sträng som består av upp till 100 semikolonseparerade symboler som används för att representera värdena 0 till 99 på ett lokalspecifikt sätt. I de flesta lokala språk är detta en tom sträng.

Funktionen ställer tillfälligt in LC_CTYPE locale till locale för den kategori som bestämmer det begärda värdet (LC_TIME, LC_NUMERIC, LC_MONETARY eller LC_MESSAGES) om locales är olika och den resulterande strängen är icke-ASCII. Denna tillfälliga ändring påverkar andra trådar.

Ändrad i version 3.14: Funktionen ställer nu temporärt in LC_CTYPE locale i vissa fall.

locale.getdefaultlocale([envvars])

Försöker fastställa standardinställningarna för locale och returnerar dem som en tupel av formen (språkkod, kodning).

Enligt POSIX körs ett program som inte har anropat setlocale(LC_ALL, '') med den portabla 'C' locale. Genom att anropa setlocale(LC_ALL, '') kan programmet använda den förvalda locale som definieras av variabeln LANG. Eftersom vi inte vill störa den aktuella locale-inställningen emulerar vi alltså beteendet på det sätt som beskrivs ovan.

För att upprätthålla kompatibilitet med andra plattformar testas inte bara variabeln LANG, utan en lista med variabler som anges som envvars-parameter. Den första som definieras kommer att användas. envvars är standard för den sökväg som används i GNU gettext; den måste alltid innehålla variabelnamnet 'LANG. GNU gettexts sökväg innehåller 'LC_ALL', 'LC_CTYPE', 'LANG' och 'LANGUAGE', i den ordningen.

Med undantag för koden 'C' motsvarar språkkoden RFC 1766. language code och encoding kan vara None om deras värden inte kan bestämmas.

Deprecated since version 3.11, will be removed in version 3.15.

locale.getlocale(category=LC_CTYPE)

Returnerar den aktuella inställningen för den angivna locale-kategorin som en sekvens innehållande språkkod, kodning. category kan vara ett av värdena i LC_* förutom LC_ALL. Standardvärdet är LC_CTYPE.

Med undantag för koden 'C' motsvarar språkkoden RFC 1766. language code och encoding kan vara None om deras värden inte kan bestämmas.

locale.getpreferredencoding(do_setlocale=True)

Returnerar den locale encoding som används för textdata, enligt användarens preferenser. Användarens preferenser uttrycks olika på olika system och kanske inte är tillgängliga programmatiskt på vissa system, så den här funktionen returnerar bara en gissning.

På vissa system är det nödvändigt att anropa setlocale() för att få fram användarinställningarna, så denna funktion är inte trådsäker. Om det inte är nödvändigt eller önskvärt att anropa setlocale, bör do_setlocale sättas till False.

På Android eller om Python UTF-8 Mode är aktiverat, returneras alltid 'utf-8', locale encoding och do_setlocale-argumentet ignoreras.

Python preinitialization konfigurerar LC_CTYPE-domänen. Se även filesystem encoding and error handler.

Ändrad i version 3.7: Funktionen returnerar nu alltid "utf-8" på Android eller om Python UTF-8 Mode är aktiverat.

locale.getencoding()

Hämta aktuell locale encoding:

• På Android och VxWorks returneras "utf-8".

• På Unix returneras kodningen för aktuell LC_CTYPE locale. Returnera "utf-8" om nl_langinfo(CODESET) returnerar en tom sträng: till exempel om den aktuella LC_CTYPE-lokalen inte stöds.

• I Windows returneras ANSI-kodsidan.

Python preinitialization konfigurerar LC_CTYPE-domänen. Se även filesystem encoding and error handler.

Den här funktionen liknar getpreferredencoding(False) förutom att den här funktionen ignorerar Python UTF-8 Mode.

Tillagd i version 3.11.

locale.normalize(localename)

Returnerar en normaliserad lokalkod för det angivna lokalnamnet. Den returnerade lokalkoden är formaterad för användning med setlocale(). Om normaliseringen misslyckas returneras det ursprungliga namnet oförändrat.

Om den angivna kodningen inte är känd använder funktionen standardkodningen för den lokala koden, precis som setlocale().

locale.strcoll(string1, string2)

Jämför två strängar enligt den aktuella inställningen för LC_COLLATE. Som alla andra jämförelsefunktioner returneras ett negativt eller positivt värde, eller 0, beroende på om sträng1 kollationerar före eller efter sträng2 eller är lika med den.

locale.strxfrm(string)

Omvandlar en sträng till en sträng som kan användas i lokalanpassade jämförelser. Till exempel är strxfrm(s1) < strxfrm(s2) likvärdigt med strcoll(s1, s2) < 0. Den här funktionen kan användas när samma sträng jämförs upprepade gånger, t.ex. när en sekvens av strängar kollationeras.

locale.format_string(format, val, grouping=False, monetary=False)

Formaterar ett tal val enligt den aktuella inställningen för LC_NUMERIC. Formatet följer konventionerna för operatorn %. För värden med flyttal ändras decimaltecknet om så är lämpligt. Om grouping är True, tas även hänsyn till grupperingen.

Om monetary är true används tusentalsavgränsare och grupperingssträngar i monetära termer vid konverteringen.

Behandlar formateringsangivelser som i format % val, men tar hänsyn till de aktuella lokalinställningarna.

Ändrad i version 3.7: Nyckelordsparametern monetary har lagts till.

locale.currency(val, symbol=True, grouping=False, international=False)

Formaterar ett tal val enligt de aktuella inställningarna för LC_MONETARY.

Den returnerade strängen innehåller valutasymbolen om symbol är true, vilket är standard. Om grouping är True (vilket inte är standard), görs gruppering med värdet. Om international är True (vilket inte är standard) används den internationella valutasymbolen.

Anteckning

Den här funktionen fungerar inte med ’C’ locale, så du måste först ange en locale via setlocale().

locale.str(float)

Formaterar ett flyttal med samma format som den inbyggda funktionen str(float), men tar hänsyn till decimaltecknet.

locale.delocalize(string)

Konverterar en sträng till en normaliserad talsträng, enligt LC_NUMERIC-inställningarna.

Tillagd i version 3.5.

locale.localize(string, grouping=False, monetary=False)

Konverterar en normaliserad talsträng till en formaterad sträng enligt inställningarna för LC_NUMERIC.

Tillagd i version 3.10.

locale.atof(string, func=float)

Konverterar en sträng till ett tal, enligt inställningarna i LC_NUMERIC, genom att anropa func på resultatet av anropet av delocalize() på string.

locale.atoi(string)

Konverterar en sträng till ett heltal, enligt LC_NUMERIC-konventionerna.

locale.LC_CTYPE

Locale-kategori för teckentypsfunktionerna. Viktigast av allt är att den här kategorin definierar textkodningen, dvs. hur byte tolkas som Unicode-kodpunkter. Se PEP 538 och PEP 540 för hur denna variabel automatiskt kan tvingas till C.UTF-8 för att undvika problem som skapas av ogiltiga inställningar i behållare eller inkompatibla inställningar som skickas via SSH-anslutningar på distans.

Python använder inte internt lokalberoende teckenomvandlingsfunktioner från ctype.h. Istället tillhandahåller en intern pyctype.h lokaloberoende motsvarigheter som Py_TOLOWER.

locale.LC_COLLATE

Lokalkategori för sortering av strängar. Funktionerna strcoll() och strxfrm() i modulen locale påverkas.

locale.LC_TIME

Lokalkategori för formatering av tid. Funktionen time.strftime() följer dessa konventioner.

locale.LC_MONETARY

Lokalkategori för formatering av monetära värden. De tillgängliga alternativen är tillgängliga från funktionen localeconv().

locale.LC_MESSAGES

Lokalkategori för visning av meddelanden. Python stöder för närvarande inte applikationsspecifika lokalmedvetna meddelanden. Meddelanden som visas av operativsystemet, som de som returneras av os.strerror() kan påverkas av denna kategori.

Detta värde kanske inte är tillgängligt på operativsystem som inte följer POSIX-standarden, framför allt Windows.

locale.LC_NUMERIC

Lokalkategori för formatering av siffror. Funktionerna format_string(), atoi(), atof() och str() i modulen locale påverkas av denna kategori. Alla andra numeriska formateringsoperationer påverkas inte.

locale.LC_ALL

Kombination av alla lokala inställningar. Om den här flaggan används när språkdräkten ändras, försöker man ställa in språkdräkten för alla kategorier. Om det misslyckas för någon kategori ändras ingen kategori alls. När locale hämtas med hjälp av denna flagga returneras en sträng som anger inställningen för alla kategorier. Denna sträng kan senare användas för att återställa inställningarna.

locale.CHAR_MAX

Detta är en symbolisk konstant som används för olika värden som returneras av localeconv().

Exempel:

>>> import locale
>>> loc = locale.getlocale()  # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale

Bakgrund, detaljer, tips, råd och varningar

C-standarden definierar locale som en egenskap som gäller för hela programmet och som kan vara relativt dyr att ändra. Dessutom är vissa implementationer trasiga på ett sådant sätt att frekventa ändringar av locale kan orsaka core dumps. Detta gör locale något smärtsamt att använda korrekt.

Initialt, när ett program startas, är locale C locale, oavsett vad användaren föredrar för locale. Det finns ett undantag: kategorin LC_CTYPE ändras vid start för att ställa in den aktuella locale-kodningen till den locale-kodning som användaren föredrar. Programmet måste uttryckligen säga att det vill ha användarens föredragna locale-inställningar för andra kategorier genom att anropa setlocale(LC_ALL, '').

Det är i allmänhet en dålig idé att anropa setlocale() i någon biblioteksrutin, eftersom det som en bieffekt påverkar hela programmet. Att spara och återställa är nästan lika illa: det är dyrt och påverkar andra trådar som råkar köras innan inställningarna har återställts.

Om du, när du kodar en modul för allmänt bruk, behöver en localeoberoende version av en operation som påverkas av locale (t.ex. vissa format som används med time.strftime()), måste du hitta ett sätt att göra det utan att använda standardbibliotekets rutin. Ännu bättre är att övertyga sig själv om att det är okej att använda locale-inställningar. Endast som en sista utväg bör du dokumentera att din modul inte är kompatibel med locale-inställningar som inte är C.

Det enda sättet att utföra numeriska operationer enligt locale är att använda de specialfunktioner som definieras av denna modul: atof(), atoi(), format_string(), str().

Det finns inget sätt att konvertera versaler och klassificera tecken enligt lokal språkdräkt. För (Unicode) textsträngar görs dessa endast enligt teckenvärdet, medan för bytesträngar görs konverteringarna och klassificeringarna enligt bytets ASCII-värde, och byte vars höga bit är inställd (dvs. icke-ASCII-byte) konverteras aldrig eller betraktas som en del av en teckenklass som bokstav eller blanksteg.

För skribenter och program som bygger in Python

Tilläggsmoduler bör aldrig anropa setlocale(), förutom för att ta reda på vad den aktuella locale är. Men eftersom returvärdet bara kan användas portabelt för att återställa det, är det inte särskilt användbart (utom kanske för att ta reda på om locale är C eller inte).

När Python-kod använder modulen locale för att ändra locale, påverkar detta även den inbäddande applikationen. Om det inbäddande programmet inte vill att detta ska hända bör det ta bort tilläggsmodulen _locale (som gör allt arbete) från tabellen över inbyggda moduler i filen config.c och se till att modulen _locale inte är tillgänglig som ett delat bibliotek.

Tillgång till meddelandekataloger

locale.gettext(msg)

locale.dgettext(domain, msg)

locale.dcgettext(domain, msg, category)

locale.textdomain(domain)

locale.bindtextdomain(domain, dir)

locale.bind_textdomain_codeset(domain, codeset)

locale-modulen exponerar C-bibliotekets gettext-gränssnitt på system som tillhandahåller detta gränssnitt. Den består av funktionerna gettext(), dgettext(), dcgettext(), textdomain(), bindtextdomain() och bind_textdomain_codeset(). Dessa liknar samma funktioner i modulen gettext, men använder C-bibliotekets binära format för meddelandekataloger och C-bibliotekets sökalgoritmer för att hitta meddelandekataloger.

Python-program bör normalt inte behöva anropa dessa funktioner och bör använda gettext istället. Ett känt undantag från denna regel är program som länkar med ytterligare C-bibliotek som internt anropar C-funktionerna gettext eller dcgettext. För dessa program kan det vara nödvändigt att binda textdomänen, så att biblioteken kan hitta sina meddelandekataloger på rätt sätt.