kodekar — Kodek-register och basklasser

Källkod: Lib/kodekar.py

---

Denna modul definierar basklasser för standard Python-kodekar (kodare och avkodare) och ger tillgång till det interna Python-kodek-registret, som hanterar uppslagningsprocessen för kodek och felhantering. De flesta standardkodeker är textkodningar, som kodar text till byte (och avkodar byte till text), men det finns också kodeker som kodar text till text och byte till byte. Anpassade kodekar kan koda och avkoda mellan godtyckliga typer, men vissa modulfunktioner är begränsade till att användas specifikt med text encodings eller med kodekar som kodar till bytes.

Modulen definierar följande funktioner för kodning och avkodning med valfri kodek:

codecs.encode(obj, encoding='utf-8', errors='strict')

Kodar obj med hjälp av den kodek som registrerats för kodning.

Errors kan anges för att ställa in önskat felhanteringssystem. Standardfelhanteringen är 'strict' vilket innebär att kodningsfel ger upphov till ValueError (eller en mer kodek-specifik underklass, t.ex. UnicodeEncodeError). Se Kodek-basklasser för mer information om felhantering för kodek.

codecs.decode(obj, encoding='utf-8', errors='strict')

Avkodar obj med hjälp av den kodek som registrerats för encoding.

Errors kan anges för att ställa in önskat felhanteringssystem. Standardfelhanteringen är 'strict' vilket innebär att avkodningsfel ger upphov till ValueError (eller en mer kodek-specifik underklass, t.ex. UnicodeDecodeError). Se Kodek-basklasser för mer information om felhantering för kodek.

codecs.charmap_build(string)

Returnerar en mappning som är lämplig för kodning med en anpassad single-byte-kodning. Givet en str string på upp till 256 tecken som representerar en avkodningstabell, returnerar antingen ett kompakt internt mappningsobjekt EncodingMap eller en dictionary som mappar teckenordinaler till bytevärden. Utlöser ett TypeError vid ogiltig indata.

Fullständig information om varje kodek kan också hämtas direkt:

codecs.lookup(encoding, /)

Letar upp kodek-info i Pythons kodek-register och returnerar ett KodekInfo-objekt enligt definitionen nedan.

Kodningar söks först upp i registrets cacheminne. Om de inte hittas genomsöks listan över registrerade sökfunktioner. Om inget KodekInfo-objekt hittas genereras ett LookupError. I annat fall lagras KodekInfo-objektet i cacheminnet och returneras till anroparen.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Kodek-detaljer vid sökning i kodek-registret. Konstruktörens argument lagras i attribut med samma namn:

name

Namnet på kodningen.

encode

decode

De tillståndslösa kodnings- och avkodningsfunktionerna. Dessa måste vara funktioner eller metoder som har samma gränssnitt som metoderna encode() och decode() för Codec-instanser (se Codec Interface). Funktionerna eller metoderna förväntas fungera i ett tillståndslöst läge.

incrementalencoder

incrementaldecoder

Klasser eller fabriksfunktioner för inkrementella kodare och avkodare. Dessa måste tillhandahålla det gränssnitt som definieras av basklasserna IncrementalEncoder respektive IncrementalDecoder. Inkrementella kodekar kan bibehålla tillstånd.

streamwriter

streamreader

Klasser eller fabriksfunktioner för stream writer och reader. Dessa måste tillhandahålla det gränssnitt som definieras av basklasserna StreamWriter respektive StreamReader. Stream kodekar kan upprätthålla tillstånd.

För att förenkla åtkomsten till de olika kodek-komponenterna tillhandahåller modulen dessa ytterligare funktioner som använder lookup() för kodek-uppslagningen:

codecs.getencoder(encoding)

Leta upp kodek för den givna kodningen och returnera dess kodningsfunktion.

Utlöser ett LookupError om kodningen inte kan hittas.

codecs.getdecoder(encoding)

Leta upp kodek för den givna kodningen och returnera dess avkodningsfunktion.

Utlöser ett LookupError om kodningen inte kan hittas.

codecs.getincrementalencoder(encoding)

Leta upp kodek för den angivna kodningen och returnera dess inkrementella kodningsklass eller fabriksfunktion.

Utlöser ett LookupError om kodningen inte kan hittas eller om kodek inte stöder en inkrementell kodare.

codecs.getincrementaldecoder(encoding)

Leta upp kodek för den givna kodningen och returnera dess inkrementella avkodarklass eller fabriksfunktion.

Utlöser ett LookupError om kodningen inte kan hittas eller om kodek inte stöder en inkrementell avkodare.

codecs.getreader(encoding)

Leta upp kodek för den angivna kodningen och returnera dess StreamReader klass eller fabriksfunktion.

Utlöser ett LookupError om kodningen inte kan hittas.

codecs.getwriter(encoding)

Leta upp kodek för den angivna kodningen och returnera dess StreamWriter klass eller fabriksfunktion.

Utlöser ett LookupError om kodningen inte kan hittas.

Anpassade kodekar görs tillgängliga genom att registrera en lämplig kodekarökfunktion:

codecs.register(search_function, /)

Registrera en kodek-sökfunktion. Sökfunktioner förväntas ta ett argument, vilket är kodningsnamnet i gemener med bindestreck och mellanslag konverterade till understreck, och returnera ett CodecInfo-objekt. Om en sökfunktion inte kan hitta en given kodning bör den returnera None.

Ändrad i version 3.9: Bindestreck och mellanslag omvandlas till understreck.

codecs.unregister(search_function, /)

Avregistrera en kodek-sökfunktion och rensa registrets cache. Om sökfunktionen inte är registrerad gör du ingenting.

Tillagd i version 3.10.

Den inbyggda modulen open() och den tillhörande modulen io rekommenderas för arbete med kodade textfiler, men den här modulen innehåller ytterligare funktioner och klasser som gör det möjligt att använda ett större antal kodekar vid arbete med binära filer:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

Öppna en kodad fil med det angivna läget och returnera en instans av StreamReaderWriter, vilket ger transparent kodning/avkodning. Standardläget för filen är 'r', vilket innebär att filen öppnas i läsläge.

Anteckning

Om encoding inte är None öppnas de underliggande kodade filerna alltid i binärt läge. Ingen automatisk konvertering av '\n' görs vid läsning och skrivning. Argumentet mode kan vara vilket binärt läge som helst som är acceptabelt för den inbyggda funktionen open(); 'b' läggs automatiskt till.

encoding anger den kodning som ska användas för filen. Alla kodningar som kodar till och avkodar från bytes är tillåtna, och de datatyper som stöds av filmetoderna beror på vilken kodek som används.

errors kan anges för att definiera felhanteringen. Standardinställningen är 'strict' vilket gör att ett ValueError skapas om ett kodningsfel uppstår.

buffring har samma betydelse som för den inbyggda funktionen open(). Standardvärdet är -1, vilket innebär att standardbuffertstorleken kommer att användas.

Ändrad i version 3.11: Läget 'U har tagits bort.

Föråldrad sedan version 3.14: kodekar.open() har ersatts av open().

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

Returnerar en StreamRecoder-instans, en omsluten version av file som ger transparent omkodning. Originalfilen stängs när den omslutna versionen stängs.

Data som skrivs till den omslutna filen avkodas enligt den angivna data_encoding och skrivs sedan till originalfilen som byte med file_encoding. Bytes som läses från originalfilen avkodas enligt file_encoding och resultatet kodas med hjälp av data_encoding.

Om file_encoding inte anges, används data_encoding som standard.

errors kan anges för att definiera felhanteringen. Standardvärdet är 'strict', vilket gör att ValueError aktiveras om ett kodningsfel inträffar.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

Använder en inkrementell kodare för att iterativt koda indata som tillhandahålls av iterator. iterator måste ge str-objekt. Denna funktion är en generator. Argumentet errors (liksom alla andra nyckelordsargument) skickas vidare till den inkrementella kodaren.

Denna funktion kräver att kodek accepterar text str-objekt att koda. Därför stöder den inte bytes-till-bytes-kodare som base64_codec.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

Använder en inkrementell avkodare för att iterativt avkoda indata som tillhandahålls av iterator. iterator måste ge bytes-objekt. Denna funktion är en generator. Argumentet errors (liksom alla andra nyckelordsargument) skickas vidare till den inkrementella avkodaren.

Denna funktion kräver att kodek accepterar bytes-objekt för avkodning. Därför stöder den inte text-till-text-kodare som rot_13, även om rot_13 kan användas på motsvarande sätt med iterencode().

codecs.readbuffer_encode(buffer, errors=None, /)

Returnerar en tuple som innehåller de råa bytena i buffer, ett buffer-kompatibelt objekt eller str (kodat till UTF-8 före bearbetning), och deras längd i byte.

Argumentet errors ignoreras.

>>> codecs.readbuffer_encode(b"Zito")
(b'Zito', 4)

Modulen innehåller också följande konstanter som är användbara för att läsa och skriva till plattformsberoende filer:

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

Dessa konstanter definierar olika byte-sekvenser och är Unicode byte order marks (BOMs) för flera kodningar. De används i UTF-16- och UTF-32-dataströmmar för att ange den byteordning som används, och i UTF-8 som en Unicode-signatur. BOM_UTF16 är antingen BOM_UTF16_BE eller BOM_UTF16_LE beroende på plattformens inbyggda byteordning, BOM är ett alias för BOM_UTF16, BOM_LE för BOM_UTF16_LE och BOM_BE för BOM_UTF16_BE. De andra representerar BOM i UTF-8- och UTF-32-kodningar.

Kodek-basklasser

Modulen kodekar definierar en uppsättning basklasser som definierar gränssnitten för att arbeta med kodek-objekt och kan också användas som grund för anpassade kodek-implementeringar.

Varje kodek måste definiera fyra gränssnitt för att kunna användas som kodek i Python: stateless encoder, stateless decoder, stream reader och stream writer. Strömläsaren och strömskrivaren återanvänder vanligtvis den tillståndslösa kodaren/avkodaren för att implementera filprotokollen. Kodek-författare måste också definiera hur kodek ska hantera kodnings- och avkodningsfel.

Felhanterare

För att förenkla och standardisera felhanteringen kan kodekar implementera olika felhanteringsscheman genom att acceptera strängargumentet errors:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German ß, ♬'

Följande felhanterare kan användas med alla Python Standardkodningar-kodekar:

Värde	Betydelse
'strict'	Utlöser UnicodeError (eller en underklass), detta är standard. Implementerad i strict_errors().
'ignore'	Ignorera de felaktiga uppgifterna och fortsätt utan ytterligare meddelande. Implementerad i ignore_errors().
'replace'	Ersätt med en ersättningsmarkör. Vid kodning, använd ? (ASCII-tecken). Vid avkodning, använd � (U+FFFD, det officiella ERSÄTTNINGSKARAKTERET). Implementerad i replace_errors().
'backslashreplace'	Ersätt med bakåtstreckade escapesekvenser. Vid kodning, använd hexadecimal form av Unicode kodpunkt med formaten \xhh uxxxx Uxxxxxxxx. Vid avkodning, använd hexadecimal form av bytevärdet med formatet \xhh. Implementerad i backslashreplace_errors().
'surrogatlandskap'	Vid avkodning ersätts byte med individuell surrogatkod från U+DC80 till U+DCFF. Denna kod kommer sedan att omvandlas tillbaka till samma byte när felhanteraren 'surrogateescape' används vid kodning av data. (Se PEP 383 för mer information.)

Följande felhanterare är endast tillämpliga på kodning (inom textkodning):

Värde	Betydelse
'xmlcharrefreplace'	Ersätt med XML/HTML numerisk teckenreferens, som är en decimalform av Unicode kodpunkt med formatet &#num;. Implementerad i xmlcharrefreplace_errors().
'namereplace'	Ersätt med \N{...} escape-sekvenser, det som visas inom hakparenteserna är egenskapen Name från Unicode Character Database. Implementerad i namereplace_errors().

Dessutom är följande felhanterare specifik för de angivna kodekar:

Värde	Kodekar	Betydelse
'surrogatpass	utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le	Tillåt kodning och avkodning av surrogatkodpunkt (U+D800 - U+DFFF) som normal kodpunkt. Annars behandlar dessa kodekar förekomsten av surrogatkodpunkt i str som ett fel.

Tillagd i version 3.1: Felhanterarna 'surrogateescape' och 'surrogatepass'.

Ändrad i version 3.4: Felhanteraren 'surrogatepass' fungerar nu med utf-16* och utf-32* kodekar.

Tillagd i version 3.5: Felhanteraren för 'namereplace'.

Ändrad i version 3.5: Felhanteraren 'backslashreplace' fungerar nu med avkodning och översättning.

Uppsättningen av tillåtna värden kan utökas genom att registrera en ny namngiven felhanterare:

codecs.register_error(name, error_handler, /)

Registrera felhanteringsfunktionen error_handler under namnet name. Argumentet error_handler kommer att anropas under kodning och avkodning i händelse av ett fel, när name anges som felparameter.

För kodning kommer error_handler att anropas med en UnicodeEncodeError-instans, som innehåller information om var felet finns. Felhanteraren måste antingen lyfta detta eller ett annat undantag, eller returnera en tupel med en ersättning för den okodbara delen av indata och en position där kodningen ska fortsätta. Ersättningen kan vara antingen str eller bytes. Om ersättningen är bytes kommer kodaren helt enkelt att kopiera dem till utmatningsbufferten. Om ersättningen är en sträng kommer kodaren att koda ersättningen. Kodningen fortsätter på den ursprungliga inmatningen vid den angivna positionen. Negativa positionsvärden behandlas som om de är i förhållande till slutet av den inmatade strängen. Om den resulterande positionen är utanför gränsen kommer ett IndexError att visas.

Avkodning och översättning fungerar på samma sätt, förutom att UnicodeDecodeError eller UnicodeTranslateError kommer att skickas till felhanteraren och att ersättningen från felhanteraren kommer att läggas in i utdata direkt.

Tidigare registrerade felhanterare (inklusive standardfelhanterare) kan sökas upp med namn:

codecs.lookup_error(name, /)

Returnerar den felhanterare som tidigare registrerats under namnet name.

Utlöser ett LookupError om handläggaren inte kan hittas.

Följande standardfelhanterare är också tillgängliga som funktioner på modulnivå:

codecs.strict_errors(exception)

Implementerar felhanteringen 'strict.

Varje kodnings- eller avkodningsfel ger upphov till ett UnicodeError.

codecs.ignore_errors(exception)

Implementerar felhanteringen 'ignorera'.

Missbildade data ignoreras; kodning eller avkodning fortsätter utan ytterligare meddelande.

codecs.replace_errors(exception)

Implementerar felhanteringen 'replace'.

Ersätter ? (ASCII-tecken) för kodningsfel eller � (U+FFFD, det officiella ERSÄTTNINGSTECKNET) för avkodningsfel.

codecs.backslashreplace_errors(exception)

Implementerar felhanteringen 'backslashreplace'.

Missbildade data ersätts av en bakåtstreckad escape-sekvens. Vid kodning, använd den hexadecimala formen av Unicode code point med formaten \xhh uxxxx Uxxxxxxxx. Vid avkodning används den hexadecimala formen av bytevärdet med formatet \xhh.

Ändrad i version 3.5: Arbetar med avkodning och översättning.

codecs.xmlcharrefreplace_errors(exception)

Implementerar felhanteringen 'xmlcharrefreplace' (endast för kodning inom textkodning).

Det icke-kodbara tecknet ersätts av en lämplig XML/HTML numerisk teckenreferens, som är en decimalform av Unicode-kodpunkt med formatet &#num; .

codecs.namereplace_errors(exception)

Implementerar felhanteringen 'namereplace' (endast för kodning inom textkodning).

Det icke-kodbara tecknet ersätts av en N{...} escape-sekvens. Uppsättningen av tecken som visas inom hakparenteserna är egenskapen Name från Unicode Character Database. Till exempel kommer den tyska gemena bokstaven 'ß' att konverteras till byte-sekvensen \N{LATIN SMALL LETTER SHARP S} .

Tillagd i version 3.5.

Statlös kodning och avkodning

Basklassen Codec definierar dessa metoder som också definierar funktionsgränssnitten för den tillståndslösa kodaren och avkodaren:

class codecs.Codec

encode(input, errors='strict')

Kodar objektet input och returnerar en tupel (utgångsobjekt, förbrukad längd). Till exempel text encoding konverterar ett strängobjekt till ett bytesobjekt med hjälp av en viss teckenuppsättningskodning (t.ex. cp1252 eller iso-8859-1).

Argumentet errors definierar vilken felhantering som ska tillämpas. Standardinställningen är 'strict' hantering.

Metoden får inte lagra tillstånd i Kodek-instansen. Använd StreamWriter för kodekar som måste behålla tillstånd för att göra kodningen effektiv.

Kodaren måste kunna hantera inmatning med noll längd och returnera ett tomt objekt av typen output-objekt i denna situation.

decode(input, errors='strict')

Avkodar objektet input och returnerar en tupel (utgångsobjekt, förbrukad längd). Till exempel, för en text encoding, omvandlar decoding ett bytes-objekt som kodats med en viss teckenuppsättningskodning till ett strängobjekt.

För textkodningar och bytes-till-bytes-kodekar måste input vara ett bytes-objekt eller ett objekt som tillhandahåller gränssnittet för skrivskyddade buffertar - t.ex. buffertobjekt och minnesmappade filer.

Argumentet errors definierar vilken felhantering som ska tillämpas. Standardinställningen är 'strict' hantering.

Metoden får inte lagra tillstånd i Kodek-instansen. Använd StreamReader för kodekar som måste behålla tillstånd för att göra avkodningen effektiv.

Avkodaren måste kunna hantera inmatning med noll längd och returnera ett tomt objekt av typen output-objekt i denna situation.

Inkrementell kodning och avkodning

Klasserna IncrementalEncoder och IncrementalDecoder tillhandahåller det grundläggande gränssnittet för inkrementell kodning och avkodning. Kodning/avkodning av indata görs inte med ett anrop till den tillståndslösa kodar/avkodarfunktionen, utan med flera anrop till encode()/decode()-metoden för den inkrementella kodaren/avkodaren. Den inkrementella kodaren/avkodaren håller reda på kodnings-/avkodningsprocessen under metodanropen.

Det sammanfogade resultatet av anrop till metoden encode()/decode() är detsamma som om alla enskilda indata hade sammanfogats till ett, och detta indata hade kodats/avkodats med den tillståndslösa kodaren/avkodaren.

Objekt för inkrementell kodare

Klassen IncrementalEncoder används för att koda en inmatning i flera steg. Den definierar följande metoder som varje inkrementell kodare måste definiera för att vara kompatibel med Pythons kodek-register.

class codecs.IncrementalEncoder(errors='strict')

Konstruktör för en instans av IncrementalEncoder.

Alla inkrementella kodare måste tillhandahålla detta konstruktörsgränssnitt. De är fria att lägga till ytterligare nyckelordsargument, men endast de som definieras här används av Pythons kodek-register.

IncrementalEncoder kan implementera olika felhanteringssystem genom att tillhandahålla nyckelordsargumentet errors. Se Felhanterare för möjliga värden.

Argumentet errors kommer att tilldelas ett attribut med samma namn. Genom att tilldela detta attribut blir det möjligt att växla mellan olika felhanteringsstrategier under IncrementalEncoder-objektets livstid.

encode(object, final=False)

Kodar objekt (med hänsyn tagen till kodarens aktuella tillstånd) och returnerar det resulterande kodade objektet. Om detta är det sista anropet till encode() måste final vara true (standard är false).

reset()

Återställ kodaren till det ursprungliga tillståndet. Utdata kastas: anropa .encode(object, final=True), och skicka en tom byte- eller textsträng om det behövs, för att återställa kodaren och få utdata.

getstate()

Returnerar det aktuella tillståndet för kodaren som måste vara ett heltal. Implementationen bör se till att 0 är det vanligaste tillståndet. (Tillstånd som är mer komplicerade än heltal kan konverteras till ett heltal genom att marshala/pickla tillståndet och koda bytena i den resulterande strängen till ett heltal)

setstate(state)

Ställ in kodarens tillstånd till state. state måste vara ett kodartillstånd som returneras av getstate().

IncrementalDecoder Objekt

Klassen IncrementalDecoder används för att avkoda en indata i flera steg. Den definierar följande metoder som varje inkrementell avkodare måste definiera för att vara kompatibel med Pythons kodek-register.

class codecs.IncrementalDecoder(errors='strict')

Konstruktör för en instans av IncrementalDecoder.

Alla inkrementella avkodare måste tillhandahålla detta konstruktörsgränssnitt. Det står dem fritt att lägga till ytterligare nyckelordsargument, men endast de som definieras här används av Pythons kodek-register.

IncrementalDecoder kan implementera olika felhanteringssystem genom att tillhandahålla nyckelordsargumentet errors. Se Felhanterare för möjliga värden.

Argumentet errors kommer att tilldelas ett attribut med samma namn. Genom att tilldela detta attribut blir det möjligt att växla mellan olika felhanteringsstrategier under IncrementalDecoder-objektets livstid.

decode(object, final=False)

Avkodar objekt (med hänsyn tagen till avkodarens aktuella tillstånd) och returnerar det avkodade objektet. Om detta är det sista anropet till decode() måste final vara true (standardvärdet är false). Om final är true måste avkodaren avkoda indata helt och hållet och tömma alla buffertar. Om detta inte är möjligt (t.ex. på grund av ofullständiga byte-sekvenser i slutet av indata) måste den initiera felhantering precis som i det tillståndslösa fallet (vilket kan leda till ett undantag).

reset()

Återställer dekodern till utgångsläget.

getstate()

Returnerar avkodarens aktuella tillstånd. Detta måste vara en tupel med två poster, den första måste vara bufferten som innehåller den fortfarande oavkodade inmatningen. Den andra måste vara ett heltal och kan vara ytterligare tillståndsinformation. (Implementationen bör se till att 0 är den vanligaste ytterligare tillståndsinformationen) Om denna ytterligare tillståndsinformation är 0 måste det vara möjligt att ställa in avkodaren till det tillstånd som inte har någon buffrad indata och 0 som ytterligare tillståndsinformation, så att matning av den tidigare buffrade indata till avkodaren återför den till föregående tillstånd utan att producera någon utdata. (Ytterligare tillståndsinformation som är mer komplicerad än heltal kan konverteras till ett heltal genom att marshala/pickla informationen och koda bytena i den resulterande strängen till ett heltal)

setstate(state)

Ställ in avkodarens tillstånd till state. state måste vara ett avkodartillstånd som returneras av getstate().

Kodning och avkodning av strömmar

Klasserna StreamWriter och StreamReader tillhandahåller generiska arbetsgränssnitt som kan användas för att implementera nya kodningsundermoduler mycket enkelt. Se encodings.utf_8 för ett exempel på hur detta görs.

StreamWriter-objekt

Klassen StreamWriter är en underklass till Kodek och definierar följande metoder som alla streamwriters måste definiera för att vara kompatibla med Pythons kodek-register.

class codecs.StreamWriter(stream, errors='strict')

Konstruktör för en StreamWriter-instans.

Alla strömskrivare måste tillhandahålla detta konstruktörsgränssnitt. De är fria att lägga till ytterligare nyckelordsargument, men endast de som definieras här används av Pythons kodek-register.

Argumentet stream måste vara ett filliknande objekt som är öppet för att skriva text eller binära data, beroende på vad som är lämpligt för den specifika kodeken.

Klassen StreamWriter kan implementera olika felhanteringssystem genom att tillhandahålla nyckelordsargumentet errors. Se Felhanterare för de standardfelhanterare som den underliggande stream-kodek kan stödja.

Argumentet errors kommer att tilldelas ett attribut med samma namn. Genom att tilldela detta attribut blir det möjligt att växla mellan olika felhanteringsstrategier under StreamWriter-objektets livstid.

write(object)

Skriver objektets innehåll kodat till strömmen.

writelines(list)

Skriver den konkatenerade iterationen av strängar till strömmen (eventuellt genom att återanvända metoden write()). Oändliga eller mycket stora iterabler stöds inte. De vanliga bytes-till-bytes-kodekerna stöder inte denna metod.

reset()

Återställer kodek-buffertarna som används för att hålla internt tillstånd.

Genom att anropa den här metoden kan man säkerställa att data på utdatasidan försätts i ett rent tillstånd som gör det möjligt att lägga till nya data utan att behöva skanna om hela flödet till ett återställt tillstånd.

Förutom ovanstående metoder måste StreamWriter också ärva alla andra metoder och attribut från den underliggande strömmen.

StreamReader-objekt

Klassen StreamReader är en underklass till Kodek och definierar följande metoder som varje strömläsare måste definiera för att vara kompatibel med Pythons kodek-register.

class codecs.StreamReader(stream, errors='strict')

Konstruktor för en StreamReader-instans.

Alla strömläsare måste tillhandahålla detta konstruktörsgränssnitt. De är fria att lägga till ytterligare nyckelordsargument, men endast de som definieras här används av Pythons kodek-register.

Argumentet stream måste vara ett filliknande objekt som är öppet för läsning av text eller binära data, beroende på vad som är lämpligt för den specifika kodeken.

Klassen StreamReader kan implementera olika felhanteringssystem genom att tillhandahålla nyckelordsargumentet errors. Se Felhanterare för de standardfelhanterare som den underliggande stream-kodek kan stödja.

Argumentet errors kommer att tilldelas ett attribut med samma namn. Genom att tilldela detta attribut blir det möjligt att växla mellan olika felhanteringsstrategier under StreamReader-objektets livstid.

Uppsättningen av tillåtna värden för argumentet errors kan utökas med register_error().

read(size=-1, chars=-1, firstline=False)

Avkodar data från strömmen och returnerar det resulterande objektet.

Argumentet chars anger antalet avkodade kodpunkter eller byte som ska returneras. Metoden read() kommer aldrig att returnera mer data än vad som begärts, men den kan returnera mindre om det inte finns tillräckligt med data tillgängligt.

Argumentet size anger det ungefärliga maximala antalet kodade bytes eller kodpunkter som ska läsas för avkodning. Avkodaren kan ändra denna inställning på lämpligt sätt. Standardvärdet -1 anger att så mycket som möjligt ska läsas och avkodas. Denna parameter är avsedd att förhindra att stora filer måste avkodas i ett steg.

Flaggan firstline anger att det skulle räcka att bara returnera den första raden om det finns avkodningsfel på senare rader.

Metoden bör använda en girig lässtrategi, vilket innebär att den bör läsa så mycket data som tillåts inom definitionen av kodningen och den givna storleken, t.ex. om valfria kodningsändelser eller tillståndsmarkörer finns tillgängliga i strömmen, bör dessa också läsas.

readline(size=None, keepends=True)

Läs en rad från inmatningsflödet och returnera de avkodade data.

size, om den anges, skickas som size-argument till strömningens read()-metod.

Om keepends är false kommer radavslut att tas bort från de returnerade raderna.

readlines(sizehint=None, keepends=True)

Läs alla tillgängliga rader i inmatningsströmmen och returnera dem som en lista med rader.

Radavslut implementeras med hjälp av kodek:ens metod decode() och inkluderas i listans poster om keepends är true.

sizehint, om den anges, skickas som argumentet size till strömningens metod read().

reset()

Återställer kodek-buffertarna som används för att hålla internt tillstånd.

Observera att ingen ompositionering av strömmen ska ske. Denna metod är främst avsedd för att kunna återhämta sig efter avkodningsfel.

Förutom ovanstående metoder måste StreamReader också ärva alla andra metoder och attribut från den underliggande strömmen.

StreamReaderWriter-objekt

StreamReaderWriter är en bekvämlighetsklass som gör det möjligt att paketera strömmar som fungerar i både läs- och skrivläge.

Designen är sådan att man kan använda de fabriksfunktioner som returneras av lookup()-funktionen för att konstruera instansen.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

Skapar en instans av StreamReaderWriter. stream måste vara ett filliknande objekt. Reader och Writer måste vara fabriksfunktioner eller klasser som tillhandahåller gränssnittet StreamReader respektive StreamWriter. Felhantering sker på samma sätt som definierats för stream-läsare och -skrivare.

StreamReaderWriter-instanser definierar de kombinerade gränssnitten för klasserna StreamReader och StreamWriter. De ärver alla andra metoder och attribut från den underliggande strömmen.

StreamRecoder-objekt

StreamRecoder översätter data från en kodning till en annan, vilket ibland är användbart när man har att göra med olika kodningsmiljöer.

Designen är sådan att man kan använda de fabriksfunktioner som returneras av lookup()-funktionen för att konstruera instansen.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Skapar en StreamRecoder-instans som implementerar en tvåvägskonvertering: encode och decode arbetar på frontend - data som är synlig för kod som anropar read() och write(), medan Reader och Writer arbetar på backend - data i stream.

Du kan använda dessa objekt för att göra transparenta omkodningar, t.ex. från Latin-1 till UTF-8 och tillbaka.

Argumentet stream måste vara ett filliknande objekt.

Argumenten encode och decode måste följa gränssnittet Kodek. Reader och Writer måste vara fabriksfunktioner eller klasser som tillhandahåller objekt av gränssnittet StreamReader respektive StreamWriter.

Felhanteringen sker på samma sätt som definierats för strömläsare och strömskrivare.

StreamRecoder-instanser definierar de kombinerade gränssnitten för klasserna StreamReader och StreamWriter. De ärver alla andra metoder och attribut från den underliggande strömmen.

Kodningar och Unicode

Strängar lagras internt som sekvenser av kodpunkter i intervallet U+0000–U+10FFFF. (Se PEP 393 för mer information om implementeringen.) När ett strängobjekt används utanför CPU och minne blir endianness och hur dessa arrayer lagras som byte ett problem. Precis som med andra kodekar kallas serialisering av en sträng till en sekvens av byte för encoding och återskapande av strängen från sekvensen av byte för decoding. Det finns en mängd olika kodekar för textserialisering, som kollektivt kallas text encodings.

Den enklaste textkodningen (kallad 'latin-1' eller 'iso-8859-1') mappar kodpunkterna 0–255 till byte 0x0–0xff, vilket innebär att ett strängobjekt som innehåller kodpunkter över U+00FF inte kan kodas med denna kodek. Om du gör det uppstår ett UnicodeEncodeError som ser ut så här (även om detaljerna i felmeddelandet kan variera): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256)

Det finns en annan grupp av kodningar (de s.k. charmap-kodningarna) som väljer en annan delmängd av alla Unicode-kodpunkter och hur dessa kodpunkter mappas till bytena 0x0–0xff. För att se hur detta görs är det bara att öppna t.ex. encodings/cp1252.py (som är en kodning som används främst på Windows). Där finns en strängkonstant med 256 tecken som visar vilket tecken som är mappat till vilket bytevärde.

Alla dessa kodningar kan bara koda 256 av de 1114112 kodpunkter som definieras i Unicode. Ett enkelt och okomplicerat sätt att lagra varje Unicode-kodpunkt är att lagra varje kodpunkt som fyra på varandra följande byte. Det finns två möjligheter: lagra bytena i big endian- eller little endian-ordning. Dessa två kodningar kallas UTF-32-BE respektive UTF-32-LE. Nackdelen med dem är att om man t.ex. använder UTF-32-BE på en little endian-maskin måste man alltid byta byte vid kodning och avkodning. UTF-32 undviker detta problem: byte kommer alltid att vara i naturlig endian. När dessa byte läses av en CPU med en annan endianness, måste byte dock bytas ut. För att kunna upptäcka endianness för en UTF-16 eller UTF-32 byte-sekvens, finns det så kallade BOM (”Byte Order Mark”). Detta är Unicode-tecknet U+FEFF. Detta tecken kan prependlas till varje UTF-16 eller UTF-32 byte-sekvens. Den byteväxlade versionen av detta tecken (0xFFFE) är ett olagligt tecken som inte får förekomma i en Unicode-text. Så när det första tecknet i en UTF-16 eller UTF-32 byte-sekvens ser ut att vara en U+FFFE måste bytena bytas vid avkodningen. Tyvärr hade tecknet U+FEFF ett andra syfte som ett ZERO WIDTH NO-BREAK SPACE: ett tecken som inte har någon bredd och inte tillåter att ett ord delas upp. Det kan t.ex. användas för att ge ledtrådar till en ligaturalgoritm. Med Unicode 4.0 har användningen av U+FEFF som ett ZERO WIDTH NO-BREAK SPACE utgått (med U+2060 (WORD JOINER) som tar över denna roll). Unicode-programvara måste dock fortfarande kunna hantera U+FEFF i båda rollerna: som BOM är det en enhet för att bestämma lagringslayouten för de kodade byte, och försvinner när byte-sekvensen har avkodats till en sträng; som ZERO WIDTH NO-BREAK SPACE är det ett normalt tecken som kommer att avkodas som alla andra.

Det finns en annan kodning som kan koda hela Unicode-teckensnittet: UTF-8. UTF-8 är en 8-bitars kodning, vilket innebär att det inte finns några problem med byteordning i UTF-8. Varje byte i en UTF-8-byte-sekvens består av två delar: markörbitar (de mest signifikanta bitarna) och nyttolastbitar. Markörbitarna är en sekvens av noll till fyra 1 -bitar följt av en 0 -bit. Unicode-tecken kodas på detta sätt (där x är nyttolastbitar, som när de sammanfogas ger Unicode-tecknet):

Intervall	Avkodning
U-00000000 … U-0000007F	0xxxxxxx
U-00000080 … U-000007FF	110xxxxx 10xxxxxx
U-00000800 … U-0000FFFF	1110xxxx 10xxxxxx 10xxxxxx
U-00010000 … U-0010FFFF	11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

Den minst signifikanta biten i Unicode-tecknet är den längst till höger liggande x-biten.

Eftersom UTF-8 är en 8-bitars kodning krävs ingen BOM och alla tecken U+FEFF i den avkodade strängen (även om det är det första tecknet) behandlas som ett ZERO WIDTH NO-BREAK SPACE.

Utan extern information är det omöjligt att på ett tillförlitligt sätt avgöra vilken kodning som användes för att koda en sträng. Varje charmap-kodning kan avkoda vilken slumpmässig byte-sekvens som helst. Det är dock inte möjligt med UTF-8, eftersom UTF-8-bytessekvenser har en struktur som inte tillåter godtyckliga bytessekvenser. För att öka tillförlitligheten med vilken en UTF-8-kodning kan upptäckas uppfann Microsoft en variant av UTF-8 (som Python kallar "utf-8-sig") för sitt Notepad-program: Innan något av Unicode-tecknen skrivs till filen, skrivs en UTF-8-kodad BOM (som ser ut så här som en byte-sekvens: 0xef, 0xbb, 0xbf). Eftersom det är ganska osannolikt att någon charmap-kodad fil börjar med dessa bytevärden (som t.ex. skulle motsvara

LATINSKA LILLA BOKSTAVEN I MED DIACERESE

HÖGERPEKANDE DUBBELVINKELCITATIONSTECKEN

INVERTERAT FRÅGETECKEN

i iso-8859-1), ökar detta sannolikheten att en utf-8-sig -kodning kan gissas korrekt från byte-sekvensen. Här används alltså inte BOM för att kunna bestämma byte-ordningen som används för att generera byte-sekvensen, utan som en signatur som hjälper till att gissa kodningen. Vid kodning skriver utf-8-sig-kodeken 0xef, 0xbb, 0xbf som de tre första byte till filen. Vid avkodning hoppar utf-8-sig över dessa tre byte om de förekommer som de tre första byte i filen. I UTF-8 avråds användning av BOM och bör i allmänhet undvikas.

Standardkodningar

Python kommer med ett antal inbyggda kodekar, antingen implementerade som C-funktioner eller med lexikon som mappningstabeller. I följande tabell listas kodekar med namn, tillsammans med några vanliga alias och de språk som kodningen sannolikt används för. Varken listan över alias eller listan över språk är avsedd att vara uttömmande. Observera att stavningsalternativ som endast skiljer sig åt i versaler eller använder bindestreck istället för understreck också är giltiga alias eftersom de är likvärdiga när de normaliseras med normalize_encoding(). Till exempel är 'utf-8' ett giltigt alias för kodek 'utf_8'.

Anteckning

I tabellen nedan listas de vanligaste alias, en fullständig lista finns i filen source aliases.py.

På Windows finns kodekar av typen cpXXX tillgängliga för alla kodsidor. Men endast kodekar som anges i följande tabell finns garanterat på andra plattformar.

Vissa vanliga kodningar kan kringgå kodekar-uppslagningsmaskineriet för att förbättra prestandan. Dessa optimeringsmöjligheter känns bara igen av CPython för en begränsad uppsättning (skiftlägesokänsliga) alias: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (endast Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, och samma sak med understreck istället för bindestreck. Om du använder alternativa alias för dessa kodningar kan det leda till långsammare körning.

Ändrad i version 3.6: Optimeringsmöjlighet erkänd för us-ascii.

Många av teckenuppsättningarna stöder samma språk. De varierar i fråga om enskilda tecken (t.ex. om EURO-tecknet stöds eller inte) och i fråga om tilldelningen av tecken till kodpositioner. I synnerhet för de europeiska språken finns normalt följande varianter:

• en ISO 8859-kodset

• en Microsoft Windows-kodsida som vanligtvis härrör från en 8859-kod, men som ersätter kontrolltecken med ytterligare grafiska tecken

• en IBM EBCDIC-kodsida

• en IBM PC-kodsida, som är ASCII-kompatibel

Kodek	Alias	Språk
ascii	646, us-ascii	Engelska
big5	big5-tw, csbig5	Traditionell kinesiska
big5hkscs	big5-hkscs, hkscs	Traditionell kinesiska
cp037	IBM037, IBM039	Engelska
cp273	273, IBM273, csIBM273	Tyska Tillagd i version 3.4.
cp424	EBCDIC-CP-HE, IBM424	Hebreiska
cp437	437, IBM437	Engelska
cp500	EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500	Västeuropa
cp720		Arabiska
cp737		Grekiska
cp775	IBM775	Baltiska språk
cp850	850, IBM850	Västeuropa
cp852	852, IBM852	Central- och Östeuropa
cp855	855, IBM855	Vitryska, bulgariska, makedonska, ryska, serbiska
cp856		Hebreiska
cp857	857, IBM857	Turkiska
cp858	858, IBM858	Västeuropa
cp860	860, IBM860	Portugisiska
cp861	861, CP-IS, IBM861	Icelandic
cp862	862, IBM862	Hebreiska
cp863	863, IBM863	Canadian
cp864	IBM864	Arabiska
cp865	865, IBM865	Danska, Norska
cp866	866, IBM866	Russian
cp869	869, CP-GR, IBM869	Grekiska
cp874		Thai
cp875		Grekiska
cp932	932, ms932, mskanji, ms-kanji, windows-31j	Japanska
cp949	949, ms949, uhc	Koreanska
cp950	950, ms950	Traditionell kinesiska
cp1006		Urdu
cp1026	ibm1026	Turkiska
cp1125	1125, ibm1125, cp866u, ruscii	Ukrainian Tillagd i version 3.4.
cp1140	ibm1140	Västeuropa
cp1250	windows-1250	Central- och Östeuropa
cp1251	windows-1251	Vitryska, bulgariska, makedonska, ryska, serbiska
cp1252	windows-1252	Västeuropa
cp1253	windows-1253	Grekiska
cp1254	windows-1254	Turkiska
cp1255	windows-1255	Hebreiska
cp1256	windows-1256	Arabiska
cp1257	windows-1257	Baltiska språk
cp1258	windows-1258	Vietnamesisk
euc_jp	eucjp, ujis, u-jis	Japanska
euc_jis_2004	jisx0213, eucjis2004	Japanska
euc_jisx0213	eucjisx0213	Japanska
euc_kr	euckr, koreanska, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001	Koreanska
gb2312	kinesiska, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58	Förenklad kinesiska
gbk	936, cp936, ms936	Unifierad kinesiska
gb18030	gb18030-2000	Unifierad kinesiska
hz	hzgb, hz-gb, hz-gb-2312	Förenklad kinesiska
iso2022_jp	csiso2022jp, iso2022jp, iso-2022-jp	Japanska
iso2022_jp_1	iso2022jp-1, iso-2022-jp-1	Japanska
iso2022_jp_2	iso2022jp-2, iso-2022-jp-2	Japanska, koreanska, förenklad kinesiska, Västeuropa, grekiska
iso2022_jp_2004	iso2022jp-2004, iso-2022-jp-2004	Japanska
iso2022_jp_3	iso2022jp-3, iso-2022-jp-3	Japanska
iso2022_jp_ext	iso2022jp-ext, iso-2022-jp-ext	Japanska
iso2022_kr	csiso2022kr, iso2022kr, iso-2022-kr	Koreanska
latin_1	iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1	Västeuropa
iso8859_2	iso-8859-2, latin2, L2	Central- och Östeuropa
iso8859_3	iso-8859-3, latin3, L3	Esperanto, Maltese
iso8859_4	iso-8859-4, latin4, L4	Baltiska språk
iso8859_5	iso-8859-5, cyrillic	Vitryska, bulgariska, makedonska, ryska, serbiska
iso8859_6	iso-8859-6, arabic	Arabiska
iso8859_7	iso-8859-7, greek, greek8	Grekiska
iso8859_8	iso-8859-8, hebrew	Hebreiska
iso8859_9	iso-8859-9, latin5, L5	Turkiska
iso8859_10	iso-8859-10, latin6, L6	Nordiska språk
iso8859_11	iso-8859-11, thai	Thailändska språk
iso8859_13	iso-8859-13, latin7, L7	Baltiska språk
iso8859_14	iso-8859-14, latin8, L8	Keltiska språk
iso8859_15	iso-8859-15, latin9, L9	Västeuropa
iso8859_16	iso-8859-16, latin10, L10	Sydöstra Europa
johab	cp1361, ms1361	Koreanska
koi8_r		Russian
koi8_t		Tadzjikiska Tillagd i version 3.5.
koi8_u		Ukrainian
kz1048	kz_1048, strk1048_2002, rk1048	Kazakiskt Tillagd i version 3.5.
mac_cyrillic	maccyrillic	Vitryska, bulgariska, makedonska, ryska, serbiska
mac_greek	macgreek	Grekiska
mac_iceland	maciceland	Icelandic
mac_latin2	maclatin2, maccentraleurope, mac_centeuro	Central- och Östeuropa
mac_roman	macroman, macintosh	Västeuropa
mac_turkish	macturkish	Turkiska
ptcp154	csptcp154, pt154, cp154, cyrillic-asian	Kazakiskt
shift_jis	csshiftjis, shiftjis, sjis, s_jis	Japanska
shift_jis_2004	shiftjis2004, sjis_2004, sjis2004	Japanska
shift_jisx0213	shiftjisx0213, sjisx0213, s_jisx0213	Japanska
utf_32	U32, utf32	alla språk
utf_32_be	UTF-32BE	alla språk
utf_32_le	UTF-32LE	alla språk
utf_16	U16, utf16	alla språk
utf_16_be	UTF-16BE	alla språk
utf_16_le	UTF-16LE	alla språk
utf_7	U7, unicode-1-1-utf-7	alla språk
utf_8	U8, UTF, utf8, cp65001	alla språk
utf_8_sig		alla språk

Ändrad i version 3.4: Kodarna utf-16* och utf-32* tillåter inte längre att surrogatkodpunkter (U+D800–U+DFFF) kodas. Avkodarna utf-32* avkodar inte längre byte-sekvenser som motsvarar surrogatkodpunkter.

Ändrad i version 3.8: cp65001 är nu ett alias till utf_8.

Ändrad i version 3.14: I Windows är kodekar av typen cpXXX nu tillgängliga för alla kodsidor.

Python-specifika kodningar

Ett antal fördefinierade kodekar är specifika för Python, så deras kodek-namn har ingen betydelse utanför Python. Dessa listas i tabellerna nedan baserat på de förväntade in- och utdatatyperna (notera att även om textkodningar är det vanligaste användningsområdet för kodekar, stöder den underliggande kodek-infrastrukturen godtyckliga datatransformationer snarare än bara textkodningar). För asymmetriska kodekar beskriver den angivna betydelsen kodningsriktningen.

Kodning av text

Följande kodekar ger str till bytes-kodning och bytes-like object till str-avkodning, på samma sätt som Unicodes textkodning.

Kodek	Alias	Betydelse
idna		Implementera RFC 3490, se även encodings.idna. Endast errors='strict' stöds.
mbcs	ansi, dbcs	Endast för Windows: Koda operanden enligt ANSI-kodsidan (CP_ACP).
original		Endast för Windows: Koda operanden enligt OEM-kodsidan (CP_OEMCP). Tillagd i version 3.6.
palmos		Kodning av PalmOS 3.5.
punycode		Implementera RFC 3492. Stateful kodekar stöds inte.
raw_unicode_escape		Latin-1-kodning med \uXXXX och \UXXXXXXXX för andra kodpunkter. Befintliga backslashes escapas inte på något sätt. Det används i Pythons pickle-protokoll.
odefinerad		Denna kodek bör endast användas för teständamål. Utlös ett undantag för alla konverteringar, även tomma strängar. Felhanteraren ignoreras.
unicode_escape		Kodning lämplig som innehållet i en Unicode-litteral i ASCII-kodad Python-källkod, förutom att citattecken inte escapas. Avkodning från Latin-1-källkod. Tänk på att Python-källkod faktiskt använder UTF-8 som standard.

Ändrad i version 3.8: kodek ”unicode_internal” har tagits bort.

Binära transformationer

Följande kodekar tillhandahåller binära transformationer: bytes-like object till bytes mappningar. De stöds inte av bytes.decode() (som endast producerar str utdata).

Kodek	Alias	Betydelse	Kodare / avkodare
base64_codec [1]	base64, base_64	Konverterar operanden till multiline MIME base64 (resultatet innehåller alltid en efterföljande '\n'). Ändrad i version 3.4: accepterar alla bytes-like object som indata för kodning och avkodning	base64.encodebytes() / base64.decodebytes()
bz2_codec	bz2	Komprimera operanden med hjälp av bz2.	bz2.compress() / bz2.decompress()
hex_codec	hex	Konvertera operanden till hexadecimal representation, med två siffror per byte.	binascii.b2a_hex() / binascii.a2b_hex()
quopri_codec	quopri, citerat tryckbart, citerat_tryckbart	Konvertera operanden till MIME quoted printable.	quopri.encode() med quotetabs=True / quopri.decode()
uu_codec	uu	Konvertera operanden med hjälp av uuencode.
zlib_codec	zip, zlib	Komprimera operanden med hjälp av gzip.	zlib.compress() / zlib.decompress()

[1]

Förutom bytesliknande objekt accepterar 'base64_codec' även ASCII-instanser av str för avkodning

Tillagd i version 3.2: Återställning av de binära transformationerna.

Ändrad i version 3.4: Återställande av alias för de binära transformationerna.

Text omvandlas

Följande kodek tillhandahåller en texttransformation: en mappning från str till str. Den stöds inte av str.encode() (som bara producerar bytes).

Kodek	Alias	Betydelse
rot_13	rot13	Returnerar Caesar-cypherkrypteringen av operanden.

Tillagd i version 3.2: Återställande av textomvandlingen rot_13.

Ändrad i version 3.4: Återskapande av aliaset rot13.

encodings — Paket för kodning

Denna modul implementerar följande funktioner:

encodings.normalize_encoding(encoding)

Normalisera kodningsnamnet encoding.

Normalisering fungerar på följande sätt: alla icke-alfanumeriska tecken utom punkten som används för Python-paketnamn kollapsar och ersätts med ett enda understreck, ledande och efterföljande understreck tas bort. Till exempel, ' -;#' blir '_'.

Observera att kodning endast ska vara ASCII.

Anteckning

Följande funktioner bör inte användas direkt, förutom för teständamål; kodekar.lookup() bör användas istället.

encodings.search_function(encoding)

Sök efter den kodek-modul som motsvarar det angivna kodningsnamnet encoding.

Den här funktionen normaliserar först kodningen med normalize_encoding() och letar sedan efter ett motsvarande alias. Den försöker importera en kodek-modul från encodings-paketet med hjälp av antingen aliaset eller det normaliserade namnet. Om modulen hittas och definierar en giltig getregentry()-funktion som returnerar ett codecs.CodecInfo-objekt, cachelagras kodeken och returneras.

Om kodek-modulen definierar en getaliases()-funktion registreras alla returnerade alias för framtida användning.

encodings.win32_code_page_search_function(encoding)

Sök efter en Windows-kodsideskodning encoding av formen cpXXXX.

Om kodsidan är giltig och stöds, returneras ett kodekar.KodekInfo-objekt för den.

Tillgänglighet: Windows.

Tillagd i version 3.14.

Denna modul implementerar följande undantag:

exception encodings.CodecRegistryError

Utlöses när en kodek är ogiltig eller inkompatibel.

encodings.idna — Internationaliserade domännamn i applikationer

Denna modul implementerar RFC 3490 (Internationalized Domain Names in Applications) och RFC 3492 (Nameprep: En strängprep-profil för internationaliserade domännamn (IDN)). Den bygger på kodningen punycode och stringprep.

Om du behöver IDNA 2008-standarden från RFC 5891 och RFC 5895, använd tredjepartsmodulen idna.

Dessa RFC:er definierar tillsammans ett protokoll för att stödja icke-ASCII-tecken i domännamn. Ett domännamn som innehåller icke-ASCII-tecken (t.ex. www.Alliancefrançaise.nu) konverteras till en ASCII-kompatibel kodning (ACE, t.ex. www.xn--alliancefranaise-npb.nu). ACE-formen av domännamnet används sedan på alla ställen där godtyckliga tecken inte tillåts av protokollet, t.ex. DNS-frågor, HTTP Host-fält och så vidare. Denna konvertering utförs i applikationen och är om möjligt osynlig för användaren: Programmet bör på ett transparent sätt konvertera Unicode-domänetiketter till IDNA på kabeln och konvertera tillbaka ACE-etiketter till Unicode innan de presenteras för användaren.

Python stöder denna konvertering på flera sätt: kodeken idna utför konvertering mellan Unicode och ACE, separerar en inmatningssträng i etiketter baserat på de separatortecken som definieras i section 3.1 of RFC 3490 och konverterar varje etikett till ACE efter behov, och omvänt separerar en inmatad bytesträng i etiketter baserat på separatorn . och konverterar alla ACE-etiketter som hittas till Unicode. Modulen socket konverterar dessutom Unicode-värdnamn till ACE på ett transparent sätt, så att program inte behöver bekymra sig om att konvertera värdnamn själva när de skickar dem till socket-modulen. Dessutom accepterar moduler som har värdnamn som funktionsparametrar, t.ex. http.client och ftplib, Unicode-värdnamn (http.client skickar då också på ett transparent sätt ett IDNA-värdnamn i fältet Host om den alls skickar det fältet).

När värdnamn tas emot från kabeln (t.ex. vid omvänd namnuppslagning) sker ingen automatisk konvertering till Unicode: program som vill presentera sådana värdnamn för användaren måste avkoda dem till Unicode.

Modulen encodings.idna implementerar också nameprep-proceduren, som utför vissa normaliseringar på värdnamn, för att uppnå skiftlägesokänslighet för internationella domännamn och för att förena liknande tecken. Nameprep-funktionerna kan användas direkt om så önskas.

encodings.idna.nameprep(label)

Returnerar den namnpreppade versionen av label. Implementationen förutsätter för närvarande frågesträngar, så AllowUnassigned är sant.

encodings.idna.ToASCII(label)

Konverterar en etikett till ASCII, enligt specifikationen i RFC 3490. UseSTD3ASCIIRules antas vara false.

encodings.idna.ToUnicode(label)

Konverterar en etikett till Unicode, enligt specifikationen i RFC 3490.

encodings.mbcs — Windows ANSI-kodning

Denna modul implementerar ANSI-kodsidan (CP_ACP).

Tillgänglighet: Windows.

Ändrad i version 3.2: Före 3.2 ignorerades argumentet errors; 'replace' användes alltid för kodning och 'ignore' för avkodning.

Ändrad i version 3.3: Stödjer alla felhanterare.

encodings.utf_8_sig — UTF-8-kodek med BOM-signatur

Denna modul implementerar en variant av UTF-8-kodek. Vid kodning kommer en UTF-8-kodad BOM att prependlas till de UTF-8-kodade bytena. För den stateful-kodaren görs detta endast en gång (vid den första skrivningen till byteflödet). Vid avkodning kommer en valfri UTF-8-kodad BOM i början av datan att hoppas över.