io — Kärnverktyg för att arbeta med strömmar

Källkod: Lib/io.py

---

Översikt

Modulen io tillhandahåller Pythons viktigaste funktioner för att hantera olika typer av I/O. Det finns tre huvudtyper av I/O: text-I/O, binär-I/O och raw-I/O. Dessa är generiska kategorier, och olika backing stores kan användas för var och en av dem. Ett konkret objekt som tillhör någon av dessa kategorier kallas för ett filobjekt. Andra vanliga termer är stream och filliknande objekt.

Oberoende av sin kategori kommer varje konkret strömobjekt också att ha olika funktioner: det kan vara skrivskyddat, skrivskyddat eller skrivskyddat. Det kan också tillåta godtycklig slumpmässig åtkomst (sökning framåt eller bakåt till valfri plats), eller endast sekventiell åtkomst (till exempel i fallet med en socket eller pipe).

Alla strömmar är försiktiga med vilken typ av data du ger till dem. Om du till exempel ger ett str-objekt till write()-metoden för en binär ström kommer ett TypeError att uppstå. Detsamma gäller om man ger ett bytes-objekt till write()-metoden för en textström.

Ändrad i version 3.3: Operationer som tidigare gav upphov till IOError ger nu upphov till OSError, eftersom IOError nu är ett alias för OSError.

Text I/O

Text-I/O förväntar sig och producerar str-objekt. Detta innebär att när backing-lagret är uppbyggt av bytes (som i fallet med en fil), sker kodning och avkodning av data på ett transparent sätt, liksom valfri översättning av plattformsspecifika newline-tecken.

Det enklaste sättet att skapa en textström är med open(), med möjlighet att ange en kodning:

f = open("myfile.txt", "r", encoding="utf-8")

Textflöden i minnet finns också tillgängliga som StringIO-objekt:

f = io.StringIO("några inledande textdata")

Anteckning

När du arbetar med en icke-blockerande ström bör du vara medveten om att läsoperationer på text-I/O-objekt kan ge upphov till ett BlockingIOError om strömmen inte kan utföra operationen omedelbart.

API:et för textströmmar beskrivs i detalj i dokumentationen för TextIOBase.

Binär I/O

Binär I/O (även kallad buffrad I/O) förväntar sig bytesliknande objekt och producerar bytes-objekt. Ingen kodning, avkodning eller översättning av nya rader utförs. Denna kategori av strömmar kan användas för alla typer av data som inte är textdata och även när manuell kontroll över hanteringen av textdata önskas.

Det enklaste sättet att skapa en binär ström är med open() med 'b' i läget string:

f = open("minfil.jpg", "rb")

Binära strömmar i minnet finns också tillgängliga som BytesIO-objekt:

f = io.BytesIO(b"några inledande binära data: \x00\x01")

API:et för binära strömmar beskrivs i detalj i dokumentationen för BufferedIOBase.

Andra biblioteksmoduler kan tillhandahålla ytterligare sätt att skapa text- eller binärströmmar. Se socket.socket.makefile() för exempel.

Rå I/O

Raw I/O (även kallat obuffrad I/O) används i allmänhet som en lågnivåbyggsten för binära strömmar och textströmmar; det är sällan användbart att direkt manipulera en raw stream från användarkod. Du kan dock skapa en rå ström genom att öppna en fil i binärt läge med buffring inaktiverad:

f = open("myfile.jpg", "rb", buffring=0)

API:et för råa strömmar beskrivs i detalj i dokumentationen för RawIOBase.

Teckenuppsättning

Standardkodningen för TextIOWrapper och open() är lokalspecifik (locale.getencoding()).

Många utvecklare glömmer dock att ange kodningen när de öppnar textfiler som är kodade i UTF-8 (t.ex. JSON, TOML, Markdown, etc…) eftersom de flesta Unix-plattformar använder UTF-8 locale som standard. Detta orsakar buggar eftersom lokalkodningen inte är UTF-8 för de flesta Windows-användare. Till exempel:

# Fungerar kanske inte på Windows om det finns icke-ASCII-tecken i filen.
med open("README.md") som f:
    long_description = f.read()

Därför rekommenderar vi starkt att du anger kodningen explicit när du öppnar textfiler. Om du vill använda UTF-8, skicka encoding="utf-8". För att använda den aktuella locale-kodningen stöds encoding="locale" sedan Python 3.10.

Se även

Python UTF-8-läge

Python UTF-8 Mode kan användas för att ändra standardkodningen till UTF-8 från lokalspecifik kodning.

PEP 686

Python 3.15 kommer att göra Python UTF-8-läge till standard.

Opt-in-kodningVarning

Tillagd i version 3.10: Se PEP 597 för mer information.

Om du vill veta var standardkodningen för lokala används kan du aktivera kommandoradsalternativet -X warn_default_encoding eller ange miljövariabeln PYTHONWARNDEFAULTENCODING, som skickar ut en EncodingWarning när standardkodningen används.

Om du tillhandahåller ett API som använder open() eller TextIOWrapper och skickar encoding=None som en parameter, kan du använda text_encoding() så att anropare av API:et skickar en EncodingWarning om de inte skickar en encoding. Överväg dock att använda UTF-8 som standard (d.v.s. encoding="utf-8") för nya API:er.

Modulgränssnitt på hög nivå

io.DEFAULT_BUFFER_SIZE

Ett int som innehåller den standardbuffertstorlek som används av modulens buffrade I/O-klasser. open() använder filens blksize (som erhålls av os.stat()) om möjligt.

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Detta är ett alias för den inbyggda funktionen open().

Denna funktion genererar en auditing event open med argumenten path, mode och flags. Argumenten mode och flags kan ha modifierats eller härleds från det ursprungliga anropet.

io.open_code(path)

Öppnar den angivna filen med läget 'rb'. Denna funktion bör användas när avsikten är att behandla innehållet som körbar kod.

path ska vara en str och en absolut sökväg.

Den här funktionens beteende kan åsidosättas av ett tidigare anrop till PyFile_SetOpenCodeHook(). Men om man antar att path är en str och en absolut sökväg, bör open_code(path) alltid bete sig på samma sätt som open(path, 'rb'). Åsidosättande av beteendet är avsett för ytterligare validering eller förbehandling av filen.

Tillagd i version 3.8.

io.text_encoding(encoding, stacklevel=2, /)

Detta är en hjälpfunktion för anropsbara filer som använder open() eller TextIOWrapper och som har en encoding=None parameter.

Denna funktion returnerar encoding om den inte är None. Annars returnerar den "locale" eller "utf-8" beroende på UTF-8 Mode.

Denna funktion skickar ut en EncodingWarning om sys.flags.warn_default_encoding är true och encoding är None. stacklevel anger varifrån varningen skickas. Till exempel:

def läs_text(sökväg, kodning=None):
    encoding = io.text_encoding(encoding) # stacklevel=2
    med open(sökväg, kodning) som f:
        return f.read()

I det här exemplet skickas en EncodingWarning ut till den som anropar read_text().

Se Teckenuppsättning för mer information.

Tillagd i version 3.10.

Ändrad i version 3.11: text_encoding() returnerar ”utf-8” när UTF-8-läget är aktiverat och encoding är None.

exception io.BlockingIOError

Detta är ett kompatibilitetsalias för det inbyggda undantaget BlockingIOError.

exception io.UnsupportedOperation

Ett undantag som ärver OSError och ValueError och som uppstår när en operation som inte stöds anropas på en stream.

Se även

sys

innehåller de vanliga IO-strömmarna: sys.stdin, sys.stdout och sys.stderr.

Klasshierarki

Implementeringen av I/O-strömmar är organiserad som en hierarki av klasser. Först abstrakta basklasser (ABC), som används för att specificera de olika kategorierna av strömmar, sedan konkreta klasser som tillhandahåller standardimplementeringarna av strömmar.

Anteckning

De abstrakta basklasserna tillhandahåller också standardimplementeringar av vissa metoder för att underlätta implementeringen av konkreta strömklasser. Till exempel ger BufferedIOBase ooptimerade implementationer av readinto() och readline().

Överst i I/O-hierarkin finns den abstrakta basklassen IOBase. Den definierar det grundläggande gränssnittet till en stream. Observera dock att det inte finns någon åtskillnad mellan att läsa och skriva till strömmar; implementationer får höja UnsupportedOperation om de inte stöder en viss operation.

ABC:n RawIOBase utökar IOBase. Den hanterar läsning och skrivning av bytes till en ström. FileIO subklassar RawIOBase för att tillhandahålla ett gränssnitt till filer i maskinens filsystem.

ABC för BufferedIOBase utökar IOBase. Den hanterar buffring på en rå binär ström (RawIOBase). Dess underklasser BufferedWriter, BufferedReader och BufferedRWPair buffrar råa binära strömmar som är skrivbara, läsbara respektive både läsbara och skrivbara. BufferedRandom ger ett buffrat gränssnitt till sökbara strömmar. En annan underklass till BufferedIOBase, BytesIO, är en ström av bytes i minnet.

ABC:s TextIOBase utökar IOBase. Den hanterar strömmar vars bytes representerar text och hanterar kodning och avkodning till och från strängar. TextIOWrapper, som utökar TextIOBase, är ett buffrat textgränssnitt till en buffrad råström (BufferedIOBase). Slutligen är StringIO en minnesbaserad ström för text.

Argumentnamn är inte en del av specifikationen, och endast argumenten i open() är avsedda att användas som nyckelordsargument.

I följande tabell sammanfattas de ABC-kunskaper som tillhandahålls av modulen io:

ABC	Ärver	Stubbmetoder	Mixin-metoder och -egenskaper
IOBase		fileno, seek och truncate	close, closed, __enter__, __exit__, flush, isatty, __iter__, __next__, readable, readline, readlines, seekable, tell, writable och writelines
RawIOBase	IOBase	”läsa in i” och ”skriva in i	Ärvde IOBase-metoder, read och readall
BufferedIOBase	IOBase	detach, read, read1 och write	Ärvda IOBase-metoder, readinto och readinto1
TextIOBase	IOBase	detach, read, readline och write	Ärvde IOBase metoder, encoding, errors och newlines

I/O-basklasser

class io.IOBase

Den abstrakta basklassen för alla I/O-klasser.

Denna klass tillhandahåller tomma abstrakta implementeringar för många metoder som härledda klasser kan åsidosätta selektivt; standardimplementeringarna representerar en fil som inte kan läsas, skrivas eller sökas.

Även om IOBase inte deklarerar read() eller write() eftersom deras signaturer kommer att variera, bör implementationer och klienter betrakta dessa metoder som en del av gränssnittet. Implementationer kan också ge upphov till ett ValueError (eller UnsupportedOperation) när operationer som de inte stöder anropas.

Den grundläggande typen som används för binära data som läses från eller skrivs till en fil är bytes. Andra bytes-liknande objekt accepteras också som metodargument. Text-I/O-klasser arbetar med str-data.

Observera att anrop av någon metod (även förfrågningar) på en stängd ström är odefinierat. Implementationer kan ge upphov till ValueError i detta fall.

IOBase (och dess underklasser) stöder iteratorprotokollet, vilket innebär att ett IOBase-objekt kan itereras över, vilket ger raderna i en ström. Rader definieras något olika beroende på om strömmen är en binär ström (ger bytes) eller en textström (ger teckensträngar). Se readline() nedan.

IOBase är också en kontexthanterare och stöder därför with-satsen. I det här exemplet stängs fil efter att with-satsens svit är klar - även om ett undantag inträffar:

med open('spam.txt', 'w') som fil:
    file.write("Skräppost och ägg!")

IOBase tillhandahåller dessa dataattribut och metoder:

close()

Spola och stäng denna ström. Denna metod har ingen effekt om filen redan är stängd. När filen är stängd kommer alla operationer på filen (t.ex. läsning eller skrivning) att ge upphov till ett ValueError.

Som en bekvämlighet är det tillåtet att anropa denna metod mer än en gång; endast det första anropet kommer dock att ha en effekt.

closed

True om strömmen är stängd.

fileno()

Returnerar den underliggande filbeskrivaren (ett heltal) för strömmen om den finns. Ett OSError uppstår om IO-objektet inte använder en fildeskriptor.

flush()

Töm skrivbuffertarna i strömmen om tillämpligt. Detta gör ingenting för skrivskyddade och icke-blockerande strömmar.

isatty()

Returnerar True om strömmen är interaktiv (d.v.s. ansluten till en terminal/tty-enhet).

readable()

Returnerar True om strömmen kan läsas från. Om False, kommer read() att ge upphov till OSError.

readline(size=-1, /)

Läser och returnerar en rad från strömmen. Om size anges kommer högst size byte att läsas.

Radavslutaren är alltid b'\n' för binära filer; för textfiler kan argumentet newline till open() användas för att välja den eller de radavslutare som ska identifieras.

readlines(hint=-1, /)

Läser och returnerar en lista med rader från strömmen. hint kan anges för att styra antalet rader som läses: inga fler rader läses om den totala storleken (i byte/tecken) på alla rader hittills överstiger hint.

hint-värden på 0 eller mindre, liksom None, behandlas som ingen hint.

Observera att det redan är möjligt att iterera på filobjekt med for line in file: ... utan att anropa file.readlines().

seek(offset, whence=os.SEEK_SET, /)

Ändra strömpositionen till den angivna byten offset, tolkad relativt den position som anges av whence, och returnera den nya absoluta positionen. Värden för whence är:

• os.SEEK_SET eller 0 – början på strömmen (standard); offset ska vara noll eller positiv

• os.SEEK_CUR eller 1 – aktuell strömposition; offset kan vara negativ

• os.SEEK_END eller 2 – slutet på strömmen; offset är vanligtvis negativ

Tillagd i version 3.1: Konstanterna SEEK_*.

Tillagd i version 3.3: Vissa operativsystem kan stödja ytterligare värden, t.ex. os.SEEK_HOLE eller os.SEEK_DATA. Vilka värden som är giltiga för en fil kan bero på om den öppnas i text- eller binärläge.

seekable()

Returnerar True om strömmen stöder slumpmässig åtkomst. Om False, kommer seek(), tell() och truncate() att ge upphov till OSError.

tell()

Returnerar den aktuella positionen för strömmen.

truncate(size=None, /)

Ändra storlek på strömmen till den angivna storleken i byte (eller den aktuella positionen om storleken inte anges). Den aktuella strömpositionen ändras inte. Denna storleksändring kan utöka eller minska den aktuella filstorleken. Vid utökning beror innehållet i det nya filområdet på plattformen (på de flesta system är ytterligare byte nollfyllda). Den nya filstorleken returneras.

Ändrad i version 3.5: Windows nollfyller nu filer vid utökning.

writable()

Returnerar True om strömmen stöder skrivning. Om False, kommer write() och truncate() att ge upphov till OSError.

writelines(lines, /)

Skriv en lista med rader till strömmen. Radavgränsare läggs inte till, så det är vanligt att varje rad som tillhandahålls har en radavgränsare i slutet.

__del__()

Förbered för destruktion av objektet. IOBase tillhandahåller en standardimplementering av denna metod som anropar instansens close()-metod.

class io.RawIOBase

Basklass för råa binära strömmar. Den ärver från IOBase.

Råa binära strömmar ger vanligtvis åtkomst på låg nivå till en underliggande OS-enhet eller API och försöker inte kapsla in den i primitiver på hög nivå (denna funktionalitet görs på en högre nivå i buffrade binära strömmar och textströmmar, som beskrivs senare på den här sidan).

RawIOBase tillhandahåller dessa metoder utöver dem från IOBase:

read(size=-1, /)

Läser upp till size bytes från objektet och returnerar dem. Om size är ospecificerad eller -1 returneras alla byte fram till EOF, som en bekvämlighetsåtgärd. I annat fall görs bara ett enda systemanrop. Färre än size byte kan returneras om operativsystemets anrop returnerar färre än size byte.

Om 0 byte returneras och size inte var 0, indikerar detta slutet på filen. Om objektet är i icke-blockerande läge och inga byte är tillgängliga returneras None.

Standardimplementeringen hänvisar till readall() och readinto().

readall()

Läs och returnera alla bytes från strömmen till EOF, med flera anrop till strömmen om det behövs.

readinto(b, /)

Läser in byte i ett förallokerat, skrivbart bytesliknande objekt b, och returnerar antalet lästa byte. Till exempel kan b vara en bytearray. Om objektet är i icke-blockerande läge och inga bytes är tillgängliga returneras None.

write(b, /)

Skriver det angivna bytes-like object, b, till den underliggande råströmmen och returnerar antalet bytes som skrivits. Detta kan vara mindre än längden på b i byte, beroende på detaljerna i den underliggande råströmmen, och särskilt om den är i icke-blockerande läge. None returneras om råströmmen är inställd på att inte blockera och ingen enskild byte lätt kan skrivas till den. Den som anropar kan frigöra eller mutera b efter att denna metod returnerats, så implementationen bör endast komma åt b under metodanropet.

class io.BufferedIOBase

Basklass för binära strömmar som stöder någon form av buffring. Den ärver från IOBase.

Den största skillnaden med RawIOBase är att metoderna read(), readinto() och write() försöker (respektive) läsa så mycket indata som begärs eller att skicka ut all data som tillhandahålls.

Dessutom, om den underliggande råströmmen är i icke-blockerande läge, när systemet återgår skulle blockera write() kommer att ge upphov till BlockingIOError med BlockingIOError.characters_written och read() kommer att returnera data som lästs hittills eller None om inga data finns tillgängliga.

Dessutom har metoden read() inte någon standardimplementering som hänvisar till readinto().

En typisk BufferedIOBase-implementation bör inte ärva från en RawIOBase-implementation, utan omsluta en sådan, som BufferedWriter och BufferedReader gör.

BufferedIOBase tillhandahåller eller åsidosätter dessa dataattribut och metoder utöver dem från IOBase:

raw

Den underliggande råströmmen (en RawIOBase-instans) som BufferedIOBase hanterar. Detta är inte en del av BufferedIOBase API och kanske inte existerar i vissa implementationer.

detach()

Separera den underliggande råströmmen från bufferten och returnera den.

Efter att råströmmen har kopplats bort är bufferten i ett oanvändbart tillstånd.

Vissa buffertar, som BytesIO, har inte konceptet med en enda rå ström att returnera från den här metoden. De ger upphov till UnsupportedOperation.

Tillagd i version 3.1.

read(size=-1, /)

Läser och returnerar upp till size bytes. Om argumentet utelämnas, None, eller negativ läs så mycket som möjligt.

Färre bytes kan returneras än vad som begärts. Ett tomt bytes-objekt returneras om strömmen redan är vid EOF. Mer än en läsning kan göras och anrop kan göras om om specifika fel påträffas, se os.read() och PEP 475 för mer information. Att mindre än en byte returneras betyder inte att EOF är nära förestående.

När man läser så mycket som möjligt kommer standardimplementationen att använda raw.readall om det finns tillgängligt (vilket bör implementera RawIOBase.readall`()), annars kommer den att läsa i en loop tills read returnerar None, en tom bytes, eller ett fel som inte kan retireras. För de flesta flöden är detta till EOF, men för icke-blockerande flöden kan mer data bli tillgänglig.

Anteckning

När den underliggande råströmmen är icke-blockerande kan implementationer antingen ge upphov till BlockingIOError eller returnera None om inga data finns tillgängliga. io-implementationer returnerar None.

read1(size=-1, /)

Läser och returnerar upp till size bytes, anropar readinto() som kan försöka igen om EINTR påträffas enligt PEP 475. Om size är -1 eller inte tillhandahålls, kommer implementationen att välja ett godtyckligt värde för size.

Anteckning

När den underliggande råströmmen är icke-blockerande kan implementationer antingen ge upphov till BlockingIOError eller returnera None om inga data finns tillgängliga. io-implementationer returnerar None.

readinto(b, /)

Läser in bytes i ett förallokerat, skrivbart bytesliknande objekt b och returnerar antalet lästa bytes. Till exempel kan b vara en bytearray.

Liksom read() kan flera läsningar göras av den underliggande råströmmen, såvida inte den senare är interaktiv.

Ett BlockingIOError uppstår om den underliggande råströmmen är i icke-blockerande läge och inte har några data tillgängliga för tillfället.

readinto1(b, /)

Läser in bytes i ett förallokerat, skrivbart bytesliknande objekt b, med högst ett anrop till den underliggande råströmmens read() (eller readinto()) metod. Returnerar antalet lästa byte.

Ett BlockingIOError uppstår om den underliggande råströmmen är i icke-blockerande läge och inte har några data tillgängliga för tillfället.

Tillagd i version 3.5.

write(b, /)

Skriv det angivna bytes-like object, b, och returnera antalet skrivna bytes (alltid lika med längden på b i bytes, eftersom om skrivningen misslyckas kommer ett OSError att uppstå). Beroende på den faktiska implementationen kan dessa byte skrivas direkt till den underliggande strömmen eller hållas i en buffert av prestanda- och latensskäl.

I icke-blockerande läge uppstår ett BlockingIOError om data behöver skrivas till råströmmen men den inte kan ta emot all data utan att blockera.

Anroparen kan frigöra eller mutera b efter att denna metod har returnerats, så implementationen bör endast komma åt b under metodanropet.

I/O för rå fil

class io.FileIO(name, mode='r', closefd=True, opener=None)

En rå binär ström som representerar en fil på OS-nivå som innehåller bytesdata. Den ärver från RawIOBase.

Namnet kan vara en av två saker:

• en teckensträng eller ett bytes-objekt som representerar sökvägen till den fil som ska öppnas. I detta fall måste closefd vara True (standard) annars kommer ett fel att uppstå.

• ett heltal som representerar numret på en befintlig filbeskrivare på OS-nivå som det resulterande FileIO-objektet kommer att ge tillgång till. När FileIO-objektet stängs kommer även denna fd att stängas, såvida inte closefd är satt till False.

mode kan vara 'r', 'w', 'x' eller 'a' för läsning (standard), skrivning, exklusivt skapande eller appending. Filen kommer att skapas om den inte existerar när den öppnas för att skrivas eller läggas till; den kommer att avkortas när den öppnas för att skrivas. FileExistsError kommer att uppstå om den redan existerar när den öppnas för att skapas. Att öppna en fil för skapande innebär skrivning, så detta läge beter sig på ett liknande sätt som 'w'. Lägg till ett '+' till läget för att tillåta samtidig läsning och skrivning.

Metoderna read() (när de anropas med ett positivt argument), readinto() och write() för denna klass kommer endast att göra ett systemanrop.

En anpassad öppnare kan användas genom att skicka en callable som opener. Den underliggande filbeskrivaren för filobjektet erhålls sedan genom att anropa opener med (name, flags). opener måste returnera en öppen filbeskrivare (att skicka os.open som opener resulterar i funktionalitet som liknar att skicka None).

Den nyskapade filen är icke-ärftlig.

Se den inbyggda funktionen open() för exempel på hur parametern opener kan användas.

Ändrad i version 3.3: Parametern opener lades till. Läget 'x' lades till.

Ändrad i version 3.4: Filen är nu inte ärftlig.

FileIO tillhandahåller dessa dataattribut i tillägg till dem från RawIOBase och IOBase:

mode

Det läge som anges i konstruktören.

name

Filens namn. Detta är filbeskrivningen för filen om inget namn anges i konstruktorn.

Buffrade vattendrag

Buffrade I/O-strömmar ger ett gränssnitt på högre nivå till en I/O-enhet än vad rå I/O gör.

class io.BytesIO(initial_bytes=b'')

En binär ström som använder en bytesbuffert i minnet. Den ärver från BufferedIOBase. Bufferten kasseras när metoden close() anropas.

Det valfria argumentet initial_bytes är ett bytesliknande objekt som innehåller initialdata.

BytesIO tillhandahåller eller åsidosätter dessa metoder utöver dem från BufferedIOBase och IOBase:

getbuffer()

Returnerar en läsbar och skrivbar vy över innehållet i bufferten utan att kopiera det. Om du ändrar vyn kommer du också att uppdatera innehållet i bufferten på ett transparent sätt:

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

Anteckning

Så länge vyn finns kan objektet BytesIO inte ändras i storlek eller stängas.

Tillagd i version 3.2.

getvalue()

Returnerar bytes som innehåller hela innehållet i bufferten.

read1(size=-1, /)

I BytesIO är detta samma sak som read().

Ändrad i version 3.7: Argumentet size är nu valfritt.

readinto1(b, /)

I BytesIO är detta samma sak som readinto().

Tillagd i version 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

En buffrad binär ström som ger tillgång på högre nivå till en läsbar, icke sökbar RawIOBase rå binär ström. Den ärver från BufferedIOBase.

När data läses från detta objekt kan en större mängd data begäras från den underliggande råströmmen och förvaras i en intern buffert. Den buffrade datan kan sedan returneras direkt vid efterföljande läsningar.

Konstruktorn skapar en BufferedReader för den givna läsbara raw-strömmen och buffer_size. Om buffer_size utelämnas används DEFAULT_BUFFER_SIZE.

BufferedReader tillhandahåller eller åsidosätter dessa metoder utöver dem från BufferedIOBase och IOBase:

peek(size=0, /)

Returnerar byte från strömmen utan att flytta fram positionen. Antalet bytes som returneras kan vara färre eller fler än vad som begärts. Om den underliggande råströmmen är icke-blockerande och operationen skulle blockera, returneras tomma bytes.

read(size=-1, /)

I BufferedReader är detta samma sak som io.BufferedIOBase.read()

read1(size=-1, /)

I BufferedReader är detta samma sak som io.BufferedIOBase.read1()

Ändrad i version 3.7: Argumentet size är nu valfritt.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

En buffrad binär ström som ger tillgång på högre nivå till en skrivbar, icke sökbar RawIOBase rå binär ström. Den ärver från BufferedIOBase.

När man skriver till detta objekt placeras data normalt i en intern buffert. Bufferten kommer att skrivas ut till det underliggande RawIOBase-objektet under olika förhållanden, inklusive:

• när bufferten blir för liten för alla väntande data;

• när flush() anropas;

• när en seek() begärs (för BufferedRandom-objekt);

• när BufferedWriter-objektet stängs eller förstörs.

Konstruktorn skapar en BufferedWriter för den givna skrivbara raw-strömmen. Om buffer_size inte anges är standardvärdet DEFAULT_BUFFER_SIZE.

BufferedWriter tillhandahåller eller åsidosätter dessa metoder utöver dem från BufferedIOBase och IOBase:

flush()

Tvingar byte som finns i bufferten in i råströmmen. Ett BlockingIOError bör uppstå om den råa strömmen blockeras.

write(b, /)

Skriv det bytes-like object, b, och returnera antalet skrivna byte. I icke-blockerande läge uppstår ett BlockingIOError med BlockingIOError.characters_written inställt om bufferten behöver skrivas ut men råströmmen blockerar.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

En buffrad binär ström som ger tillgång på högre nivå till en sökbar RawIOBase rå binär ström. Den ärver från BufferedReader och BufferedWriter.

Konstruktorn skapar en läsare och skrivare för en sökbar råström, som anges i det första argumentet. Om buffer_size utelämnas är standardvärdet DEFAULT_BUFFER_SIZE.

BufferedRandom kan göra allt som BufferedReader eller BufferedWriter kan göra. Dessutom är seek() och tell() garanterat implementerade.

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

En buffrad binär ström som ger tillgång på högre nivå till två icke sökbara RawIOBase råa binära strömmar—den ena läsbar, den andra skrivbar. Den ärver från BufferedIOBase.

reader och writer är RawIOBase-objekt som är läsbara respektive skrivbara. Om buffer_size utelämnas är standardvärdet DEFAULT_BUFFER_SIZE.

BufferedRWPair implementerar alla BufferedIOBase:s metoder utom detach(), som ger upphov till UnsupportedOperation.

Varning

BufferedRWPair försöker inte synkronisera åtkomst till sina underliggande råströmmar. Du bör inte skicka samma objekt till den som läsare och skrivare; använd BufferedRandom istället.

Text I/O

class io.TextIOBase

Basklass för textströmmar. Denna klass ger ett tecken- och radbaserat gränssnitt för strömmens I/O. Den ärver från IOBase.

TextIOBase tillhandahåller eller åsidosätter dessa dataattribut och metoder utöver dem från IOBase:

encoding

Namnet på den kodning som används för att avkoda strömmens bytes till strängar och för att koda strängar till bytes.

errors

Felinställningen för avkodaren eller kodaren.

newlines

En sträng, en tupel av strängar eller None, som anger de nya linjer som hittills översatts. Beroende på implementationen och de initiala konstruktörsflaggorna kanske detta inte är tillgängligt.

buffer

Den underliggande binära bufferten (en BufferedIOBase eller RawIOBase instans) som TextIOBase hanterar. Detta är inte en del av TextIOBase API och kanske inte finns i vissa implementationer.

detach()

Separera den underliggande binära bufferten från TextIOBase och returnera den.

Efter att den underliggande bufferten har tagits bort är TextIOBase i ett oanvändbart tillstånd.

Vissa TextIOBase implementationer, som StringIO, kanske inte har konceptet med en underliggande buffert och att anropa denna metod kommer att ge upphov till UnsupportedOperation.

Tillagd i version 3.1.

read(size=-1, /)

Läser och returnerar högst storlek tecken från strömmen som en enda str. Om storlek är negativ eller None, läses till EOF.

readline(size=-1, /)

Läser till newline eller EOF och returnerar en enda str. Om strömmen redan är vid EOF returneras en tom sträng.

Om size anges kommer högst size tecken att läsas.

seek(offset, whence=SEEK_SET, /)

Ändra strömpositionen till den angivna offset. Beteendet beror på parametern whence. Standardvärdet för whence är SEEK_SET.

• SEEK_SET eller 0: söker från början av strömmen (standard); offset måste antingen vara ett tal som returneras av TextIOBase.tell(), eller noll. Alla andra offset-värden ger ett odefinierat beteende.

• SEEK_CUR eller 1: ”Sök” till den aktuella positionen; offset måste vara noll, vilket är en no-operation (alla andra värden stöds inte).

• SEEK_END eller 2: sök till slutet av strömmen; offset måste vara noll (alla andra värden stöds inte).

Returnerar den nya absoluta positionen som ett opakt tal.

Tillagd i version 3.1: Konstanterna SEEK_*.

tell()

Returnerar den aktuella strömpositionen som ett ogenomskinligt tal. Numret representerar vanligtvis inte ett antal byte i den underliggande binära lagringen.

write(s, /)

Skriv strängen s till strömmen och returnera antalet tecken som skrivits.

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)

En buffrad textström som ger tillgång på högre nivå till en buffrad binär ström av typen BufferedIOBase. Den ärver från TextIOBase.

encoding anger namnet på den kodning som strömmen ska avkodas eller kodas med. I UTF-8 Mode är standardvärdet UTF-8. Annars är standardvärdet locale.getencoding(). encoding="locale" kan användas för att ange den aktuella lokalens kodning explicit. Se Teckenuppsättning för mer information.

errors är en valfri sträng som anger hur kodnings- och avkodningsfel ska hanteras. Ange 'strict' för att skapa ett ValueError undantag om det finns ett kodningsfel (standardvärdet None har samma effekt), eller ange 'ignore' för att ignorera fel. (Observera att ignorering av kodningsfel kan leda till dataförlust.) 'replace' gör att en ersättningsmarkör (t.ex. '?') infogas där det finns felaktiga data. 'backslashreplace' gör att felaktiga data ersätts med en bakåtstreckad escape-sekvens. Vid skrivning kan 'xmlcharrefreplace' (ersätter med lämplig XML-teckenreferens) eller 'namereplace' (ersätter med N{...} escape-sekvenser) användas. Alla andra felhanteringsnamn som har registrerats med codecs.register_error() är också giltiga.

newline styr hur radavslut ska hanteras. Den kan vara None, '', '\n', '\r' och '\r\n'. Det fungerar på följande sätt:

• Om newline är None aktiveras universal newlines-läget när indata läses från strömmen. Rader i inmatningen kan sluta på '\n', '\r' eller '\r\n', och dessa översätts till '\n' innan de returneras till den som anropar. Om newline är '' aktiveras universal newlines mode, men radavslut returneras till uppringaren oöversatta. Om newline har något av de andra lagliga värdena avslutas inmatningsraderna endast med den angivna strängen, och radavslutningen returneras till den som ringer upp utan att översättas.

• Om newline är None när utdata skrivs till strömmen, översätts alla '\n'-tecken som skrivs till systemets standardradavgränsare, os.linesep. Om newline är '' eller '\n' sker ingen översättning. Om newline är något av de andra lagliga värdena översätts alla '\n'-tecken som skrivs till den angivna strängen.

Om line_buffering är True, är flush() implicit när ett anrop till write innehåller ett tecken för ny rad eller en vagnsretur.

Om write_through är True garanteras att anrop till write() inte buffras: all data som skrivs på TextIOWrapper-objektet hanteras omedelbart till dess underliggande binära buffer.

Ändrad i version 3.3: Argumentet write_through har lagts till.

Ändrad i version 3.3: Standard kodning är nu locale.getpreferredencoding(False) istället för locale.getpreferredencoding(). Ändra inte tillfälligt den lokala kodningen med locale.setlocale(), använd den aktuella lokala kodningen istället för den kodning som användaren föredrar.

Ändrad i version 3.10: Argumentet encoding stöder nu det fiktiva kodningsnamnet "locale".

Anteckning

När den underliggande råströmmen är icke-blockerande kan ett BlockingIOError uppstå om en läsoperation inte kan slutföras omedelbart.

TextIOWrapper tillhandahåller dessa dataattribut och metoder utöver dem från TextIOBase och IOBase:

line_buffering

Om linjebuffring är aktiverad.

write_through

Om skrivningar skickas omedelbart till den underliggande binära bufferten.

Tillagd i version 3.7.

reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)

Omkonfigurera denna textström med nya inställningar för kodning, fel, ny rad, linje_buffring och skrivgenomgång.

Parametrar som inte anges behåller aktuella inställningar, förutom errors='strict' som används när encoding anges men errors inte anges.

Det är inte möjligt att ändra kodning eller newline om data redan har lästs från flödet. Å andra sidan är det möjligt att ändra kodning efter skrivning.

Denna metod gör en implicit strömspolning innan de nya parametrarna ställs in.

Tillagd i version 3.7.

Ändrad i version 3.11: Metoden stöder alternativet encoding="locale".

seek(cookie, whence=os.SEEK_SET, /)

Ställ in strömpositionen. Returnera den nya strömpositionen som en int.

Det finns stöd för fyra operationer, som beskrivs med följande argumentkombinationer:

• seek(0, SEEK_SET): Spola tillbaka till början av strömmen.

• seek(cookie, SEEK_SET): Återställer en tidigare position; cookie måste vara ett nummer som returnerats av tell().

• seek(0, SEEK_END): Snabbspola till slutet av strömmen.

• seek(0, SEEK_CUR): Lämna den aktuella stream-positionen oförändrad.

Alla andra argumentkombinationer är ogiltiga och kan leda till undantag.

Se även

os.SEEK_SET, os.SEEK_CUR, och os.SEEK_END.

tell()

Returnerar strömpositionen som ett opakt tal. Returvärdet för tell() kan ges som indata till seek(), för att återställa en tidigare strömposition.

class io.StringIO(initial_value='', newline='\n')

En textström som använder en textbuffert i minnet. Den ärver från TextIOBase.

Textbufferten kasseras när metoden close() anropas.

Det initiala värdet för bufferten kan ställas in genom att ange initial_value. Om översättning av nya rader är aktiverad kommer nya rader att kodas som om de vore write(). Strömmen placeras i början av bufferten, vilket emulerar öppnandet av en befintlig fil i ett w+-läge, vilket gör den redo för en omedelbar skrivning från början eller för en skrivning som skulle skriva över det initiala värdet. För att emulera öppnandet av en fil i ett a+-läge som är redo att läggas till, använd f.seek(0, io.SEEK_END) för att flytta strömmen till slutet av bufferten.

Argumentet newline fungerar som i TextIOWrapper, förutom att när utdata skrivs till strömmen, om newline är None, skrivs nya linjer som \n på alla plattformar.

StringIO tillhandahåller denna metod utöver de som finns i TextIOBase och IOBase:

getvalue()

Returnerar en str som innehåller hela innehållet i bufferten. Nya rader avkodas som om de vore read(), även om flödespositionen inte ändras.

Exempel på användning:

import io

output = io.StringIO()
output.write('Första raden.\n')
print('Andra raden.', file=output)

# Hämta filinnehållet -- detta kommer att vara
# 'Första raden.\nSekundära raden.\n'
innehåll = output.getvalue()

# Stäng objektet och kasta minnesbufferten --
# .getvalue() kommer nu att ge upphov till ett undantag.
output.close()

class io.IncrementalNewlineDecoder

En hjälpcodec som avkodar newlines för universal newlines-läget. Den ärver från codecs.IncrementalDecoder.

Statisk typning

Följande protokoll kan användas för att annotera funktions- och metodargument för enkla läs- eller skrivoperationer i strömmar. De är dekorerade med @typing.runtime_checkable.

class io.Reader[T]

Generiskt protokoll för att läsa från en fil eller annan inmatningsström. T kommer vanligtvis att vara str eller bytes, men kan vara vilken typ som helst som läses från strömmen.

Tillagd i version 3.14.

read()

read(size, /)

Läser data från inmatningsströmmen och returnerar den. Om size anges ska det vara ett heltal, och högst size objekt (byte/tecken) kommer att läsas.

Till exempel:

def read_it(reader: Läsare[str]):
    data = läsare.läs(11)
    assert isinstance(data, str)

class io.Writer[T]

Generiskt protokoll för att skriva till en fil eller annan utdataström. T kommer vanligtvis att vara str eller bytes, men kan vara vilken typ som helst som kan skrivas till strömmen.

Tillagd i version 3.14.

write(data, /)

Skriv data till utdataströmmen och returnera antalet objekt (bytes/tecken) som skrivits.

Till exempel:

def write_binary(writer: Writer[bytes]):
    writer.write(b"Hej världen!\n")

Se ABC och protokoll för att arbeta med I/O för andra I/O-relaterade protokoll och klasser som kan användas för statisk typkontroll.

Prestanda

I det här avsnittet diskuteras prestandan för de konkreta I/O-implementeringarna.

Binär I/O

Genom att bara läsa och skriva stora bitar data även när användaren ber om en enda byte döljer buffrad I/O ineffektiviteten i anrop och exekvering av operativsystemets obuffrade I/O-rutiner. Vinsten beror på operativsystemet och vilken typ av I/O som utförs. På vissa moderna operativsystem som Linux kan till exempel obuffrad disk-I/O vara lika snabb som buffrad I/O. Slutsatsen är dock att buffrad I/O ger förutsägbar prestanda oavsett plattform och backingenhet. Därför är det nästan alltid att föredra att använda buffrad I/O i stället för obuffrad I/O för binära data.

Text I/O

Text-I/O över en binär lagring (t.ex. en fil) är betydligt långsammare än binär I/O över samma lagring, eftersom det krävs konverteringar mellan unicode och binär data med hjälp av en teckenkodek. Detta kan bli märkbart vid hantering av stora mängder textdata, t.ex. stora loggfiler. Dessutom är både tell() och seek() ganska långsamma på grund av den rekonstruktionsalgoritm som används.

StringIO är dock en inbyggd unicode-behållare i minnet och kommer att uppvisa liknande hastighet som BytesIO.

Multi-threading

FileIO-objekt är trådsäkra i den utsträckning som de anrop från operativsystemet (t.ex. read(2) under Unix) som de omsluter också är trådsäkra.

Binära buffrade objekt (instanser av BufferedReader, BufferedWriter, BufferedRandom och BufferedRWPair) skyddar sina interna strukturer med hjälp av ett lås; det är därför säkert att anropa dem från flera trådar samtidigt.

TextIOWrapper-objekt är inte tråd-säkra.

Reentrancy

Binära buffrade objekt (instanser av BufferedReader, BufferedWriter, BufferedRandom och BufferedRWPair) är inte reentranta. Även om reentranta anrop inte kommer att ske i normala situationer kan de uppstå när I/O görs i en signal-hanterare. Om en tråd försöker återgå till ett buffrat objekt som den redan har tillgång till, uppstår ett RuntimeError. Observera att detta inte hindrar en annan tråd från att komma in i det buffrade objektet.

Ovanstående gäller implicit även textfiler, eftersom funktionen open() kommer att packa in ett buffrat objekt i en TextIOWrapper. Detta inkluderar standardströmmar och påverkar därför även den inbyggda funktionen print().