Händelseslinga

Källkod: Lib/asyncio/events.py, Lib/asyncio/base_events.py

Förord

Händelseslingan är kärnan i varje asyncio-applikation. Händelseslingor kör asynkrona uppgifter och återuppringningar, utför IO-operationer i nätverket och kör underprocesser.

Programutvecklare bör vanligtvis använda asynciofunktionerna på hög nivå, till exempel asyncio.run(), och bör sällan behöva referera till loopobjektet eller anropa dess metoder. Det här avsnittet är främst avsett för författare av kod på lägre nivå, bibliotek och ramverk som behöver finare kontroll över händelseslingans beteende.

Få fram händelseslingan

Följande lågnivåfunktioner kan användas för att hämta, ställa in eller skapa en händelseslinga:

asyncio.get_running_loop()

Returnerar den pågående händelseslingan i den aktuella OS-tråden.

Skapa ett RuntimeError om det inte finns någon pågående händelseslinga.

Denna funktion kan endast anropas från en coroutine eller en callback.

Tillagd i version 3.7.

asyncio.get_event_loop()

Hämta den aktuella händelseslingan.

När den här funktionen anropas från en coroutine eller en callback (t.ex. schemalagd med call_soon eller liknande API) returnerar den alltid den pågående händelseslingan.

Om det inte finns någon pågående händelseslinga inställd, returnerar funktionen resultatet av anropet get_event_loop_policy().get_event_loop().

Eftersom den här funktionen har ett ganska komplext beteende (särskilt när anpassade policys för händelseslingor används) är det bättre att använda funktionen get_running_loop() än get_event_loop() i coroutines och callbacks.

Som nämnts ovan bör du överväga att använda funktionen asyncio.run() på högre nivå istället för att använda dessa funktioner på lägre nivå för att manuellt skapa och stänga en händelseslinga.

Ändrad i version 3.14: Utlöser ett RuntimeError om det inte finns någon aktuell händelseslinga.

Anteckning

Policysystemet asyncio är föråldrat och kommer att tas bort i Python 3.16; från och med då kommer denna funktion att returnera den aktuella pågående händelseslingan om den finns annars kommer den att returnera den slinga som ställts in av set_event_loop().

asyncio.set_event_loop(loop)

Ange loop som aktuell händelseslinga för den aktuella OS-tråden.

asyncio.new_event_loop()

Skapa och returnera ett nytt objekt för händelseslingan.

Observera att beteendet hos funktionerna get_event_loop(), set_event_loop() och new_event_loop() kan ändras genom setting a custom event loop policy.

Innehåll

Denna dokumentationssida innehåller följande avsnitt:

Metoder för händelseslingor

Händelseslingor har lågnivå API:er för följande:

Starta och stoppa slingan

loop.run_until_complete(future)

Kör tills future (en instans av Future) har slutförts.

Om argumentet är ett coroutine-objekt schemaläggs det implicit för att köras som en asyncio.Task.

Returnera Framtidens resultat eller ta upp dess undantag.

loop.run_forever()

Kör händelseslingan tills stop() anropas.

Om stop() anropas innan run_forever() anropas, kommer loopen att fråga I/O-väljaren en gång med en timeout på noll, köra alla callbacks som är schemalagda som svar på I/O-händelser (och de som redan var schemalagda) och sedan avsluta.

Om stop() anropas medan run_forever() körs, kommer loopen att köra den aktuella batchen av callbacks och sedan avslutas. Observera att nya återuppringningar som schemalagts av återuppringningar inte kommer att köras i det här fallet; istället kommer de att köras nästa gång run_forever() eller run_until_complete() anropas.

loop.stop()

Stoppa händelseslingan.

loop.is_running()

Returnerar True om händelseslingan körs för närvarande.

loop.is_closed()

Returnerar True om händelseslingan stängdes.

loop.close()

Stäng händelseslingan.

Slingan får inte vara igång när denna funktion anropas. Alla väntande återuppringningar kommer att kasseras.

Den här metoden rensar alla köer och stänger av exekveraren, men väntar inte på att exekveraren ska bli klar.

Denna metod är idempotent och irreversibel. Inga andra metoder bör anropas efter att händelseslingan har stängts.

async loop.shutdown_asyncgens()

Schemalägger alla öppna asynchronous generator-objekt att stängas med ett aclose()-anrop. Efter anrop av denna metod kommer händelseslingan att utfärda en varning om en ny asynkron generator itereras. Detta bör användas för att på ett tillförlitligt sätt avsluta alla schemalagda asynkrona generatorer.

Observera att det inte finns något behov av att anropa denna funktion när asyncio.run() används.

Exempel:

försök:
    loop.run_forever()
finally: kör
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()

Tillagd i version 3.6.

async loop.shutdown_default_executor(timeout=None)

Schemalägg stängningen av standardutföraren och vänta på att den ska ansluta sig till alla trådar i ThreadPoolExecutor. När denna metod har anropats, kommer användning av standardutföraren med loop.run_in_executor() att ge upphov till ett RuntimeError.

Parametern timeout anger hur lång tid (i float-sekunder) som köraren får på sig att avsluta anslutningen. Med standardvärdet None får exekutören obegränsad tid på sig.

Om timeout uppnås skickas en RuntimeWarning ut och standardkörningen avslutas utan att vänta på att dess trådar ska ansluta sig.

Anteckning

Anropa inte den här metoden när du använder asyncio.run(), eftersom den senare hanterar standardavstängning av exekveraren automatiskt.

Tillagd i version 3.9.

Ändrad i version 3.12: Parametern timeout har lagts till.

Schemaläggning av återuppringningar

loop.call_soon(callback, *args, context=None)

Schemalägg callback callback så att den anropas med args-argument vid nästa iteration av händelseslingan.

Returnerar en instans av asyncio.Handle, som kan användas senare för att avbryta återuppringningen.

Callbacks anropas i den ordning som de registrerades. Varje callback kommer att anropas exakt en gång.

Det valfria argumentet context, som endast innehåller nyckelord, anger en anpassad contextvars.Context som callback ska köras i. Återkallelser använder den aktuella kontexten när ingen kontext anges.

Till skillnad från call_soon_threadsafe() är den här metoden inte trådsäker.

loop.call_soon_threadsafe(callback, *args, context=None)

En trådsäker variant av call_soon(). Vid schemaläggning av callbacks från en annan tråd måste denna funktion användas, eftersom call_soon() inte är trådsäker.

Denna funktion är säker att anropa från en reentrant kontext eller signalhanterare, men det är inte säkert eller fruktbart att använda det returnerade handtaget i sådana sammanhang.

Utlöser RuntimeError om den anropas i en loop som har stängts. Detta kan hända i en sekundär tråd när huvudapplikationen stängs ner.

Se concurrency and multithreading i dokumentationen.

Ändrad i version 3.7: Parametern context (endast nyckelord) har lagts till. Se PEP 567 för mer information.

Anteckning

De flesta asyncio-schemaläggningsfunktioner tillåter inte att nyckelordsargument skickas. För att göra det, använd functools.partial():

# kommer att schemalägga "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))

Att använda partiella objekt är vanligtvis mer praktiskt än att använda lambdas, eftersom asyncio kan göra partiella objekt bättre i felsöknings- och felmeddelanden.

Schemaläggning av fördröjda återuppringningar

Event loop tillhandahåller mekanismer för att schemalägga callback-funktioner som ska anropas vid någon tidpunkt i framtiden. Händelseslingan använder monotona klockor för att hålla reda på tiden.

loop.call_later(delay, callback, *args, context=None)

Schemalägg callback som ska anropas efter det angivna delay-antalet sekunder (kan vara antingen ett int eller ett float).

En instans av asyncio.TimerHandle returneras som kan användas för att avbryta återuppringningen.

callback kommer att anropas exakt en gång. Om två callbacks är schemalagda för exakt samma tid, är ordningen i vilken de anropas odefinierad.

De valfria positionella args kommer att skickas till callbacken när den anropas. Om du vill att återuppringningen ska anropas med nyckelordsargument använder du functools.partial().

Ett valfritt argument context med endast nyckelord gör det möjligt att ange en anpassad contextvars.Context som callback ska köras i. Den aktuella kontexten används när ingen kontext anges.

Anteckning

För prestanda kan återanrop som schemalagts med loop.call_later() köras upp till en klockupplösning för tidigt (se time.get_clock_info('monotonic').resolution).

Ändrad i version 3.7: Parametern context (endast nyckelord) har lagts till. Se PEP 567 för mer information.

Ändrad i version 3.8: I Python 3.7 och tidigare med standardimplementeringen av händelseslingan kunde fördröjningen inte överstiga en dag. Detta har åtgärdats i Python 3.8.

loop.call_at(when, callback, *args, context=None)

Schemalägg callback så att den anropas vid den angivna absoluta tidsstämpeln when (en int eller en float), med samma tidsreferens som loop.time().

Den här metodens beteende är detsamma som call_later().

En instans av asyncio.TimerHandle returneras som kan användas för att avbryta återuppringningen.

Anteckning

För prestanda kan återanrop som schemalagts med loop.call_at() köras upp till en klockupplösning för tidigt (se time.get_clock_info('monotonic').resolution).

Ändrad i version 3.7: Parametern context (endast nyckelord) har lagts till. Se PEP 567 för mer information.

Ändrad i version 3.8: I Python 3.7 och tidigare med standardimplementeringen av händelseslingan kunde skillnaden mellan when och aktuell tid inte överstiga en dag. Detta har åtgärdats i Python 3.8.

loop.time()

Returnerar aktuell tid, som ett float-värde, enligt händelseslingans interna monotona klocka.

Anteckning

Ändrad i version 3.8: I Python 3.7 och tidigare skulle timeouts (relativ delay eller absolut when) inte överstiga en dag. Detta har åtgärdats i Python 3.8.

Se även

Funktionen asyncio.sleep().

Skapa framtidsutsikter och uppgifter

loop.create_future()

Skapa ett asyncio.Future-objekt som är kopplat till händelseslingan.

Detta är det föredragna sättet att skapa Futures i asyncio. Detta gör det möjligt för tredjeparts händelseslingor att tillhandahålla alternativa implementeringar av Future-objektet (med bättre prestanda eller instrumentering).

Tillagd i version 3.5.2.

loop.create_task(coro, *, name=None, context=None, eager_start=None, **kwargs)

Schemalägg utförandet av coroutine coro. Returnerar ett Task-objekt.

Händelseslingor från tredje part kan använda sin egen subklass av Task för interoperabilitet. I det här fallet är resultattypen en subklass av Task.

Den fullständiga funktionssignaturen är i stort sett densamma som för Task-konstruktören (eller fabriken) - alla nyckelordsargument till denna funktion skickas vidare till det gränssnittet.

Om argumentet name anges och inte None, anges det som namnet på uppgiften med hjälp av Task.set_name().

Ett valfritt argument context med endast nyckelord gör det möjligt att ange en anpassad contextvars.Context som coro ska köras i. Den aktuella kontextkopian skapas när ingen kontext anges.

Ett valfritt argument eager_start, som endast innehåller nyckelord, gör det möjligt att ange om uppgiften ska utföras ivrigt under anropet till create_task eller schemaläggas senare. Om eager_start inte anges kommer det läge som anges av loop.set_task_factory() att användas.

Ändrad i version 3.8: Parametern name har lagts till.

Ändrad i version 3.11: Parametern context har lagts till.

Ändrad i version 3.13.3: Lagt till kwargs som skickar vidare godtyckliga extra parametrar, inklusive name och context.

Ändrad i version 3.13.4: Återställde ändringen som skickar vidare name och context (om det är None), men som fortfarande skickar vidare andra godtyckliga nyckelordsargument (för att undvika att bryta bakåtkompatibiliteten med 3.13.3).

Ändrad i version 3.14: Alla kwargs skickas nu vidare. Parametern eager_start fungerar med ”eager task factories”.

loop.set_task_factory(factory)

Ange en uppgiftsfabrik som ska användas av loop.create_task().

Om factory är None kommer standarduppgiftsfabriken att ställas in. Annars måste factory vara en callable med en signatur som matchar (loop, coro, **kwargs), där loop är en referens till den aktiva händelseslingan och coro är ett coroutine-objekt. Callable måste skicka vidare alla kwargs och returnera ett asyncio.Task-kompatibelt objekt.

Ändrad i version 3.13.3: Kräver att alla kwargs skickas vidare till asyncio.Task.

Ändrad i version 3.13.4: name skickas inte längre till uppgiftsfabriker. context skickas inte längre till uppgiftsfabriker om det är None.

Ändrad i version 3.14: name och context skickas nu ovillkorligen vidare till uppgiftsfabrikerna igen.

loop.get_task_factory()

Returnerar en uppgiftsfabrik eller None om standardfabriken används.

Öppna nätverksanslutningar

async loop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None, all_errors=False)

Öppna en anslutning för strömmande transport till en given adress som specificeras av host och port.

Socketfamiljen kan vara antingen AF_INET eller AF_INET6 beroende på host (eller argumentet family, om det anges).

Socket-typen kommer att vara SOCK_STREAM.

protocol_factory måste vara en anropsbar som returnerar en asyncio protocol-implementering.

Denna metod försöker upprätta anslutningen i bakgrunden. Om det lyckas returnerar den ett par (transport, protokoll).

Den kronologiska sammanfattningen av den underliggande transaktionen är följande:

  1. Anslutningen upprättas och en transport skapas för den.

  2. protocol_factory anropas utan argument och förväntas returnera en protocol-instans.

  3. Protokollinstansen kopplas till transporten genom att anropa dess metod connection_made().

  4. En tupel (transport, protocol) returneras vid framgång.

Den skapade transporten är en implementationsberoende dubbelriktad ström.

Övriga argument:

  • ssl: om den anges och inte är false, skapas en SSL/TLS-transport (som standard skapas en vanlig TCP-transport). Om ssl är ett ssl.SSLContext-objekt används detta sammanhang för att skapa transporten; om ssl är True används ett standardkontext som returneras från ssl.create_default_context().

    Se även

    SSL/TLS säkerhetsaspekter

  • server_hostname anger eller åsidosätter det värdnamn som målserverns certifikat ska matchas mot. Ska endast skickas om ssl inte är None. Som standard används värdet för host-argumentet. Om host är tomt finns det inget standardvärde och du måste ange ett värde för server_hostname. Om server_hostname är en tom sträng inaktiveras matchning av värdnamn (vilket är en allvarlig säkerhetsrisk eftersom det möjliggör potentiella man-in-the-middle-attacker).

  • family, proto, flags är den valfria adressfamiljen, protokollet och flaggorna som ska skickas vidare till getaddrinfo() för upplösning av host. Om de anges bör de alla vara heltal från motsvarande socket-modulkonstanter.

  • happy_eyeballs_delay, om det anges, aktiverar Happy Eyeballs för den här anslutningen. Det bör vara ett flyttal som representerar den tid i sekunder som ska vänta på att ett anslutningsförsök ska slutföras innan nästa försök påbörjas parallellt. Detta är ”Connection Attempt Delay” enligt definitionen i RFC 8305. Ett förnuftigt standardvärde som rekommenderas av RFC är 0,25 (250 millisekunder).

  • interleave styr omordning av adresser när ett värdnamn kopplas till flera IP-adresser. Om 0 eller ospecificerat görs ingen omordning och adresserna prövas i den ordning som returneras av getaddrinfo(). Om ett positivt heltal anges, sammanflätas adresserna efter adressfamilj och det angivna heltalet tolkas som ”First Address Family Count” enligt definitionen i RFC 8305. Standardvärdet är 0 om happy_eyeballs_delay inte har angetts och 1 om så är fallet.

  • sock, om det anges, ska vara ett befintligt, redan anslutet socket.socket -objekt som ska användas av transporten. Om sock anges ska inget av host, port, family, proto, flags, happy_eyeballs_delay, interleave eller local_addr specificeras.

    Anteckning

    Argumentet sock överför ägandet av sockeln till den transport som skapats. För att stänga sockeln anropar du transportens close()-metod.

  • local_addr, om angivet, är en tupel (local_host, local_port) som används för att binda socketen lokalt. local_host och local_port söks upp med hjälp av getaddrinfo(), på samma sätt som host och port.

  • ssl_handshake_timeout är (för en TLS-anslutning) den tid i sekunder som ska vänta på att TLS-handskakningen ska slutföras innan anslutningen avbryts. 60,0 sekunder om None (standard).

  • ssl_shutdown_timeout är den tid i sekunder som ska vänta på att SSL-avstängningen ska slutföras innan anslutningen avbryts. 30.0 sekunder om None (standard).

  • all_errors avgör vilka undantag som tas upp när en anslutning inte kan skapas. Som standard genereras endast ett enda Exception: det första undantaget om det bara finns ett eller om alla fel har samma meddelande, eller ett enda OSError med felmeddelandena kombinerade. När all_errors är True kommer en ExceptionGroup att skapas som innehåller alla undantag (även om det bara finns ett).

Ändrad i version 3.5: Lagt till stöd för SSL/TLS i ProactorEventLoop.

Ändrad i version 3.6: Socket-alternativet socket.TCP_NODELAY är inställt som standard för alla TCP-anslutningar.

Ändrad i version 3.7: Parametern ssl_handshake_timeout har lagts till.

Ändrad i version 3.8: Lagt till parametrarna happy_eyeballs_delay och interleave.

Algoritm för glada ögonbollar: Framgång med Dual-Stack-värdar. När en servers IPv4-sökväg och -protokoll fungerar, men serverns IPv6-sökväg och -protokoll inte fungerar, upplever en dual-stack-klientapplikation en betydande anslutningsfördröjning jämfört med en klient med enbart IPv4. Detta är inte önskvärt eftersom det leder till att dual-stack-klienten får en sämre användarupplevelse. Detta dokument specificerar krav för algoritmer som minskar denna för användaren synliga fördröjning och tillhandahåller en algoritm.

För mer information: https://datatracker.ietf.org/doc/html/rfc6555

Ändrad i version 3.11: Parametern ssl_shutdown_timeout har lagts till.

Ändrad i version 3.12: all_errors har lagts till.

Se även

Funktionen open_connection() är ett alternativt API på hög nivå. Den returnerar ett par (StreamReader, StreamWriter) som kan användas direkt i async/await-kod.

async loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_port=None, allow_broadcast=None, sock=None)

Skapa en datagramanslutning.

Socketfamiljen kan vara antingen AF_INET, AF_INET6 eller AF_UNIX, beroende på host (eller argumentet family, om det anges).

Socket-typen är SOCK_DGRAM.

protocol_factory måste vara en callable som returnerar en protocol implementation.

En tupel av (transport, protokoll) returneras vid framgång.

Övriga argument:

  • local_addr, om den anges, är en (local_host, local_port)-tupel som används för att binda socket lokalt. local_host och local_port söks upp med hjälp av getaddrinfo().

    Anteckning

    I Windows, när du använder proactor-händelseslingan med local_addr=None, kommer ett OSError med errno.WSAEINVAL att uppstå när du kör det.

  • remote_addr, om den anges, är en (remote_host, remote_port)-tupel som används för att ansluta sockeln till en fjärradress. remote_host och remote_port söks upp med hjälp av getaddrinfo().

  • family, proto, flags är den valfria adressfamiljen, protokollet och flaggorna som ska skickas vidare till getaddrinfo() för host-upplösning. Om de anges bör de alla vara heltal från motsvarande socket-modulkonstanter.

  • reuse_port talar om för kärnan att den här ändpunkten får vara bunden till samma port som andra befintliga ändpunkter är bundna till, så länge de alla sätter denna flagga när de skapas. Detta alternativ stöds inte av Windows och vissa Unix. Om konstanten socket.SO_REUSEPORT inte är definierad stöds inte denna funktion.

  • allow_broadcast talar om för kärnan att den här slutpunkten får skicka meddelanden till broadcast-adressen.

  • sock kan eventuellt anges för att använda ett befintligt, redan anslutet, socket.socket-objekt som ska användas av transporten. Om detta anges ska local_addr och remote_addr utelämnas (måste vara None).

    Anteckning

    Argumentet sock överför ägandet av sockeln till den transport som skapats. För att stänga sockeln anropar du transportens close()-metod.

Se UDP echo client protocol och UDP echo server protocol exempel.

Ändrad i version 3.4.4: Parametrarna family, proto, flags, reuse_address, reuse_port, allow_broadcast och sock har lagts till.

Ändrad i version 3.8: Stöd för Windows har lagts till.

Ändrad i version 3.8.1: Parametern reuse_address stöds inte längre, eftersom användning av socket.SO_REUSEADDR utgör ett betydande säkerhetsproblem för UDP. Om du uttryckligen skickar reuse_address=True kommer ett undantag att uppstå.

När flera processer med olika UID:er tilldelar uttag till en identisk UDP-socketadress med SO_REUSEADDR kan inkommande paket fördelas slumpmässigt mellan uttagen.

För plattformar som stöds kan reuse_port användas som ersättning för liknande funktionalitet. Med reuse_port används istället socket.SO_REUSEPORT, vilket specifikt förhindrar att processer med olika UID:n tilldelar uttag till samma uttagsadress.

Ändrad i version 3.11: Parametern reuse_address, som varit inaktiverad sedan Python 3.8.1, 3.7.6 och 3.6.10, har tagits bort helt.

async loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Skapa en Unix-anslutning.

Socket-familjen är AF_UNIX; socket-typen är SOCK_STREAM.

En tupel av (transport, protokoll) returneras vid framgång.

path är namnet på ett Unix-domänuttag och är obligatoriskt om inte parametern sock har angetts. Abstrakta Unix-sockets, str, bytes och Path-sökvägar stöds.

Se dokumentationen för metoden loop.create_connection() för information om argument till denna metod.

Tillgänglighet: Unix.

Ändrad i version 3.7: Parametern ssl_handshake_timeout har lagts till. Parametern path kan nu vara en path-like object.

Ändrad i version 3.11: Parametern ssl_shutdown_timeout har lagts till.

Skapa nätverksservrar

async loop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, keep_alive=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Skapa en TCP-server (socket-typ SOCK_STREAM) som lyssnar på port på host-adressen.

Returnerar ett Server-objekt.

Argument:

  • protocol_factory måste vara en callable som returnerar en protocol implementation.

  • Parametern host kan ställas in på flera olika typer som avgör var servern ska lyssna:

    • Om host är en sträng är TCP-servern bunden till ett enda nätverksgränssnitt som anges av host.

    • Om host är en sekvens av strängar, är TCP-servern bunden till alla nätverksgränssnitt som anges av sekvensen.

    • Om host är en tom sträng eller None antas alla gränssnitt och en lista med flera socklar returneras (troligen en för IPv4 och en annan för IPv6).

  • Parametern port kan användas för att ange vilken port som servern ska lyssna på. Om 0 eller None (standard) väljs en slumpmässig oanvänd port (observera att om host är kopplad till flera nätverksgränssnitt väljs en slumpmässig port för varje gränssnitt).

  • family kan sättas till antingen socket.AF_INET eller AF_INET6 för att tvinga uttaget att använda IPv4 eller IPv6. Om den inte anges kommer familjen att bestämmas utifrån värdnamnet (standard är AF_UNSPEC).

  • flags är en bitmask för getaddrinfo().

  • sock kan eventuellt anges för att använda ett redan befintligt socket-objekt. Om host och port anges får de inte specificeras.

    Anteckning

    Argumentet sock överför äganderätten till sockeln till den server som skapats. För att stänga sockeln anropar du serverns close()-metod.

  • backlog är det maximala antalet anslutningar i kö som skickas till listen() (standardvärde 100).

  • ssl kan sättas till en SSLContext-instans för att aktivera TLS över de accepterade anslutningarna.

  • reuse_address talar om för kärnan att återanvända en lokal socket i TIME_WAIT -läge utan att vänta på att dess naturliga timeout löper ut. Om detta inte anges kommer det automatiskt att sättas till True på Unix.

  • reuse_port talar om för kärnan att den här ändpunkten får vara bunden till samma port som andra befintliga ändpunkter är bundna till, så länge de alla sätter denna flagga när de skapas. Detta alternativ stöds inte i Windows.

  • keep_alive satt till True håller anslutningar aktiva genom att möjliggöra periodisk överföring av meddelanden.

Ändrad i version 3.13: Parametern keep_alive har lagts till.

  • ssl_handshake_timeout är (för en TLS-server) den tid i sekunder som ska vänta på att TLS-handskakningen ska slutföras innan anslutningen avbryts. 60,0 sekunder om None (standard).

  • ssl_shutdown_timeout är den tid i sekunder som ska vänta på att SSL-avstängningen ska slutföras innan anslutningen avbryts. 30.0 sekunder om None (standard).

  • start_serving satt till True (standard) gör att den skapade servern börjar ta emot anslutningar omedelbart. När den är inställd på False bör användaren vänta på Server.start_serving() eller Server.serve_forever() för att få servern att börja acceptera anslutningar.

Ändrad i version 3.5: Lagt till stöd för SSL/TLS i ProactorEventLoop.

Ändrad i version 3.5.1: Parametern host kan vara en sekvens av strängar.

Ändrad i version 3.6: Parametrarna ssl_handshake_timeout och start_serving har lagts till. Socket-alternativet socket.TCP_NODELAY är inställt som standard för alla TCP-anslutningar.

Ändrad i version 3.11: Parametern ssl_shutdown_timeout har lagts till.

Se även

Funktionen start_server() är ett alternativt API på högre nivå som returnerar ett par av StreamReader och StreamWriter som kan användas i en async/await-kod.

async loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True, cleanup_socket=True)

Liknar loop.create_server() men fungerar med socketfamiljen AF_UNIX.

path är namnet på ett Unix-domänuttag och är obligatoriskt om inte ett sock-argument anges. Abstrakta Unix-sockets, str, bytes och Path-sökvägar stöds.

Om cleanup_socket är true kommer Unix-sockeln automatiskt att tas bort från filsystemet när servern stängs, såvida inte sockeln har bytts ut efter att servern skapades.

Se dokumentationen för metoden loop.create_server() för information om argument till den här metoden.

Tillgänglighet: Unix.

Ändrad i version 3.7: Parametrarna ssl_handshake_timeout och start_serving har lagts till. Parametern path kan nu vara ett Path-objekt.

Ändrad i version 3.11: Parametern ssl_shutdown_timeout har lagts till.

Ändrad i version 3.13: Parametern cleanup_socket har lagts till.

async loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Omhänderta en redan accepterad anslutning till ett transport/protokoll-par.

Den här metoden kan användas av servrar som accepterar anslutningar utanför asyncio men som använder asyncio för att hantera dem.

Parametrar:

  • protocol_factory måste vara en callable som returnerar en protocol implementation.

  • sock är ett redan existerande socket-objekt som returneras från socket.accept.

    Anteckning

    Argumentet sock överför ägandet av sockeln till den transport som skapats. För att stänga sockeln anropar du transportens close()-metod.

  • ssl kan sättas till en SSLContext för att aktivera SSL över de accepterade anslutningarna.

  • ssl_handshake_timeout är (för en SSL-anslutning) den tid i sekunder som ska vänta på att SSL-handskakningen ska slutföras innan anslutningen avbryts. 60,0 sekunder om None (standard).

  • ssl_shutdown_timeout är den tid i sekunder som ska vänta på att SSL-avstängningen ska slutföras innan anslutningen avbryts. 30.0 sekunder om None (standard).

Returnerar ett par (transport, protokoll).

Tillagd i version 3.5.3.

Ändrad i version 3.7: Parametern ssl_handshake_timeout har lagts till.

Ändrad i version 3.11: Parametern ssl_shutdown_timeout har lagts till.

Överföring av filer

async loop.sendfile(transport, file, offset=0, count=None, *, fallback=True)

Skicka en fil över en transport. Returnera det totala antalet bytes som skickats.

Metoden använder högpresterande os.sendfile() om sådan finns tillgänglig.

file måste vara ett vanligt filobjekt som öppnas i binärt läge.

offset anger varifrån filen ska börja läsas. Om det anges är count det totala antalet byte som ska överföras i motsats till att skicka filen tills EOF nås. Filens position uppdateras alltid, även om metoden ger upphov till ett fel, och file.tell() kan användas för att få fram det faktiska antalet byte som skickats.

fallback satt till True gör att asyncio manuellt läser och skickar filen när plattformen inte stöder systemanropet sendfile (t.ex. Windows eller SSL-socket på Unix).

Utlöser SendfileNotAvailableError om systemet inte stöder syscallen sendfile och fallback är False.

Tillagd i version 3.7.

TLS-uppgradering

async loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Uppgradera en befintlig transportbaserad anslutning till TLS.

Skapa en TLS-kodare/avkodare-instans och infoga den mellan transport och protokoll. Kodaren/avkodaren implementerar både protokoll som vetter mot transport och transport som vetter mot protokoll.

Returnerar den skapade instansen med två gränssnitt. Efter await måste protokollet sluta använda den ursprungliga transporten och kommunicera med det returnerade objektet endast eftersom kodaren cachar data på protokollsidan och sporadiskt utbyter extra TLS-sessionspaket med transport.

I vissa situationer (t.ex. när den passerade transporten redan är stängd) kan detta returnera None.

Parametrar:

  • transport och protocol instanser som metoder som create_server() och create_connection() returnerar.

  • sslcontext: en konfigurerad instans av SSLContext.

  • server_side passerar True när en anslutning på serversidan uppgraderas (som den som skapades av create_server()).

  • server_hostname: anger eller åsidosätter det värdnamn som målserverns certifikat ska matchas mot.

  • ssl_handshake_timeout är (för en TLS-anslutning) den tid i sekunder som ska vänta på att TLS-handskakningen ska slutföras innan anslutningen avbryts. 60,0 sekunder om None (standard).

  • ssl_shutdown_timeout är den tid i sekunder som ska vänta på att SSL-avstängningen ska slutföras innan anslutningen avbryts. 30.0 sekunder om None (standard).

Tillagd i version 3.7.

Ändrad i version 3.11: Parametern ssl_shutdown_timeout har lagts till.

Titta på filbeskrivningar

loop.add_reader(fd, callback, *args)

Börja övervaka filbeskrivaren fd för lästillgänglighet och anropa callback med de angivna argumenten när fd är tillgänglig för läsning.

Eventuella tidigare registrerade callbacks för fd avbryts och ersätts av callback.

loop.remove_reader(fd)

Slutar övervaka filbeskrivaren fd för lästillgänglighet. Returnerar True om fd tidigare övervakades för läsningar.

loop.add_writer(fd, callback, *args)

Börja övervaka filbeskrivaren fd för skrivtillgänglighet och anropa callback med de angivna argumenten när fd är tillgänglig för skrivning.

Eventuella tidigare registrerade callbacks för fd avbryts och ersätts av callback.

Använd functools.partial() för att skicka nyckelordsargument till callback.

loop.remove_writer(fd)

Slutar övervaka filbeskrivaren fd för skrivtillgänglighet. Returnerar True om fd tidigare övervakades för skrivningar.

Se även Platformstöd för vissa begränsningar av dessa metoder.

Arbeta direkt med socket-objekt

I allmänhet är protokollimplementeringar som använder transportbaserade API:er som loop.create_connection() och loop.create_server() snabbare än implementeringar som arbetar direkt med sockets. Det finns dock vissa användningsfall när prestanda inte är avgörande och det är bekvämare att arbeta med socket-objekt direkt.

async loop.sock_recv(sock, nbytes)

Ta emot upp till nbytes från sock. Asynkron version av socket.recv().

Returnerar den mottagna datan som ett bytesobjekt.

sock måste vara ett icke-blockerande uttag.

Ändrad i version 3.7: Även om den här metoden alltid har dokumenterats som en coroutine-metod, returnerade utgåvor före Python 3.7 en Future. Sedan Python 3.7 är detta en async def-metod.

async loop.sock_recv_into(sock, buf)

Tar emot data från sock till bufferten buf. Modellerad efter den blockerande socket.recv_into()-metoden.

Returnerar antalet bytes som skrivits till bufferten.

sock måste vara ett icke-blockerande uttag.

Tillagd i version 3.7.

async loop.sock_recvfrom(sock, bufsize)

Ta emot ett datagram på upp till bufsize från sock. Asynkron version av socket.recvfrom().

Returnera en tupel av (mottagna data, fjärradress).

sock måste vara ett icke-blockerande uttag.

Tillagd i version 3.11.

async loop.sock_recvfrom_into(sock, buf, nbytes=0)

Ta emot ett datagram på upp till nbytes från sock till buf. Asynkron version av socket.recvfrom_into().

Returnera en tupel av (antal mottagna byte, fjärradress).

sock måste vara ett icke-blockerande uttag.

Tillagd i version 3.11.

async loop.sock_sendall(sock, data)

Skicka data till sock socket. Asynkron version av socket.sendall().

Denna metod fortsätter att skicka till uttaget tills antingen all data i data har skickats eller ett fel inträffar. None returneras vid framgång. Vid fel uppstår ett undantag. Dessutom finns det inget sätt att avgöra hur mycket data, om någon, som framgångsrikt behandlades av den mottagande änden av anslutningen.

sock måste vara ett icke-blockerande uttag.

Ändrad i version 3.7: Även om metoden alltid dokumenterats som en coroutine-metod, returnerade den före Python 3.7 en Future. Sedan Python 3.7 är detta en async def-metod.

async loop.sock_sendto(sock, data, address)

Skicka ett datagram från sock till address. Asynkron version av socket.sendto().

Returnera antalet bytes som skickats.

sock måste vara ett icke-blockerande uttag.

Tillagd i version 3.11.

async loop.sock_connect(sock, address)

Anslut sock till en fjärrsockel på address.

Asynkron version av socket.connect().

sock måste vara ett icke-blockerande uttag.

Ändrad i version 3.5.2: address behöver inte längre lösas. sock_connect kommer att försöka kontrollera om adressen redan är löst genom att anropa socket.inet_pton(). Om inte, kommer loop.getaddrinfo() att användas för att lösa upp adressen.

Se även

loop.create_connection() och asyncio.open_connection().

async loop.sock_accept(sock)

Acceptera en anslutning. Modellerad efter den blockerande socket.accept()-metoden.

Uttaget måste vara bundet till en adress och lyssna efter anslutningar. Returvärdet är ett par (conn, address) där conn är ett nytt socketobjekt som kan användas för att skicka och ta emot data på anslutningen och address är den adress som är bunden till sockeln i andra änden av anslutningen.

sock måste vara ett icke-blockerande uttag.

Ändrad i version 3.7: Även om metoden alltid dokumenterats som en coroutine-metod, returnerade den före Python 3.7 en Future. Sedan Python 3.7 är detta en async def-metod.

Se även

loop.create_server() och start_server().

async loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True)

Skicka en fil med hjälp av högpresterande os.sendfile om möjligt. Returnerar det totala antalet bytes som skickats.

Asynkron version av socket.sendfile().

sock måste vara en icke-blockerande socket.SOCK_STREAM socket.

file måste vara ett vanligt filobjekt som öppnas i binärt läge.

offset anger varifrån filen ska börja läsas. Om det anges är count det totala antalet byte som ska överföras i motsats till att skicka filen tills EOF nås. Filens position uppdateras alltid, även om metoden ger upphov till ett fel, och file.tell() kan användas för att få fram det faktiska antalet byte som skickats.

fallback, när den är inställd på True, gör att asyncio manuellt läser och skickar filen när plattformen inte stöder sendfile syscall (t.ex. Windows eller SSL-socket på Unix).

Utlöser SendfileNotAvailableError om systemet inte stöder syscall sendfile och fallback är False.

sock måste vara ett icke-blockerande uttag.

Tillagd i version 3.7.

DNS

async loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

Asynkron version av socket.getaddrinfo().

async loop.getnameinfo(sockaddr, flags=0)

Asynkron version av socket.getnameinfo().

Anteckning

Både getaddrinfo och getnameinfo använder internt sina synkrona versioner via loopens standardtrådpoolsexekverare. När denna exekverare är mättad kan dessa metoder uppleva fördröjningar, vilket nätverksbibliotek på högre nivå kan rapportera som ökade tidsavbrott. För att mildra detta bör du överväga att använda en anpassad exekverare för andra användaruppgifter eller ställa in en standardexekverare med ett större antal arbetare.

Ändrad i version 3.7: Både metoderna getaddrinfo och getnameinfo har alltid dokumenterats att returnera en coroutine, men före Python 3.7 returnerade de i själva verket asyncio.Future-objekt. Från och med Python 3.7 är båda metoderna coroutines.

Arbeta med rör

async loop.connect_read_pipe(protocol_factory, pipe)

Registrera lässlutet av pipe i händelseslingan.

protocol_factory måste vara en anropsbar som returnerar en asyncio protocol-implementering.

pipe är en filliknande objekt.

Returnerar paret (transport, protocol), där transport stöder gränssnittet ReadTransport och protocol är ett objekt som instantierats av protocol_factory.

Med SelectorEventLoop händelseslinga är pipe inställd på icke-blockerande läge.

async loop.connect_write_pipe(protocol_factory, pipe)

Registrera den skrivande änden av pipe i händelseslingan.

protocol_factory måste vara en anropsbar som returnerar en asyncio protocol-implementering.

pipe är filliknande objekt.

Returnerar paret (transport, protocol), där transport stöder WriteTransport-gränssnittet och protocol är ett objekt som instantierats av protocol_factory.

Med SelectorEventLoop händelseslinga är pipe inställd på icke-blockerande läge.

Anteckning

SelectorEventLoop har inte stöd för ovanstående metoder i Windows. Använd ProactorEventLoop istället för Windows.

Se även

Metoderna loop.subprocess_exec() och loop.subprocess_shell().

Unix-signaler

loop.add_signal_handler(signum, callback, *args)

Ställ in callback som hanterare av signalen signum.

Återanropet kommer att anropas av loop, tillsammans med andra köade återanrop och körbara coroutines i den händelseslingan. Till skillnad från signalhanterare som registreras med signal.signal(), får en återuppringning som registreras med den här funktionen interagera med händelseslingan.

Ge upphov till ValueError om signalnumret är ogiltigt eller inte kan fångas upp. Raise RuntimeError om det finns ett problem med att konfigurera hanteraren.

Använd functools.partial() för att skicka nyckelordsargument till callback.

Precis som signal.signal() måste den här funktionen anropas i huvudtråden.

loop.remove_signal_handler(sig)

Ta bort hanteraren för signalen sig.

Returnerar True om signalhanteraren togs bort, eller False om ingen hanterare ställdes in för den givna signalen.

Tillgänglighet: Unix.

Se även

Modulen signal.

Exekvering av kod i tråd- eller processpooler

awaitable loop.run_in_executor(executor, func, *args)

Ordna så att func anropas i den angivna exekveraren.

Argumentet executor bör vara en instans av concurrent.futures.Executor. Standardutföraren används om executor är None. Standardutföraren kan ställas in med loop.set_default_executor(), annars kommer en concurrent.futures.ThreadPoolExecutor att initieras latent och användas av run_in_executor() vid behov.

Exempel:

import asyncio
import concurrent.futures

def blocking_io():
    # Filoperationer (t.ex. loggning) kan blockera
    # händelseslingan: kör dem i en trådpool.
    med open('/dev/urandom', 'rb') som f:
        return f.read(100)

def cpu_bound():
    # CPU-bundna operationer kommer att blockera händelseslingan:
    # i allmänhet är det att föredra att köra dem i en
    # processpool.
    return sum(i * i för i i intervallet(10 ** 7))

async def main():
    loop = asyncio.get_running_loop()

    ## Alternativ:

    # 1. Kör i standardslingans exekverare:
    result = await loop.run_in_executor(
        Ingen, blockering_io)
    print('standard trådpool', resultat)

    # 2. Kör i en anpassad trådpool:
    med concurrent.futures.ThreadPoolExecutor() som pool:
        result = await loop.run_in_executor(
            pool, blockering_io)
        print('anpassad trådpool', resultat)

    # 3. Kör i en anpassad processpool:
    med concurrent.futures.ProcessPoolExecutor() som pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('anpassad processpool', resultat)

    # 4. Kör i en anpassad tolkpool:
    med concurrent.futures.InterpreterPoolExecutor() som pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('anpassad tolkpool', resultat)

if __name__ == '__main__':
    asyncio.run(main())

Observera att startpunktsskyddet (if __name__ == '__main__') krävs för alternativ 3 på grund av de speciella egenskaperna hos multiprocessing, som används av ProcessPoolExecutor. Se Säker import av huvudmodulen.

Denna metod returnerar ett asyncio.Future-objekt.

Använd functools.partial() för att skicka nyckelordsargument till func.

Ändrad i version 3.5.3: loop.run_in_executor() konfigurerar inte längre max_workers för den trådpoolsexekutor som den skapar, utan överlåter det till trådpoolsexekutorn (ThreadPoolExecutor) att ange standardvärdet.

loop.set_default_executor(executor)

Ställ in executor som den standardexecutor som används av run_in_executor(). executor måste vara en instans av ThreadPoolExecutor, vilket inkluderar InterpreterPoolExecutor.

Ändrad i version 3.11: executor måste vara en instans av ThreadPoolExecutor.

API för felhantering

Gör det möjligt att anpassa hur undantag hanteras i händelseslingan.

loop.set_exception_handler(handler)

Ange handler som den nya undantagshanteraren för händelseslingan.

Om handler är None kommer standardhanteraren för undantag att användas. Annars måste handler vara en callable med en signatur som matchar (loop, context), där loop är en referens till den aktiva händelseslingan och context är ett dict-objekt som innehåller detaljer om undantaget (se call_exception_handler()-dokumentationen för detaljer om context).

Om hanteraren anropas på uppdrag av en Task eller Handle, körs den i contextvars.Context för den uppgiften eller callback-handtaget.

Ändrad i version 3.12: Hanteraren kan anropas i Context för den uppgift eller det handtag där undantaget uppstod.

loop.get_exception_handler()

Returnerar den aktuella undantagshanteraren, eller None om ingen egen undantagshanterare har angetts.

Tillagd i version 3.5.2.

loop.default_exception_handler(context)

Standardhantering av undantag.

Detta anropas när ett undantag inträffar och ingen undantagshanterare är inställd. Detta kan anropas av en anpassad undantagshanterare som vill använda standardhanterarens beteende.

context-parametern har samma betydelse som i call_exception_handler().

loop.call_exception_handler(context)

Anropa den aktuella undantagshanteraren för händelseslingan.

context är ett dict-objekt som innehåller följande nycklar (nya nycklar kan komma att införas i framtida Python-versioner):

  • ”meddelande”: Felmeddelande;

  • ”undantag” (valfritt): Objekt för undantag;

  • ”future” (valfritt): asyncio.Future instans;

  • ’task’ (valfritt): asyncio.Task instans;

  • ’handle’ (valfritt): asyncio.Handle instans;

  • ”protocol” (valfritt): Protocol instance;

  • ”transport” (valfritt): Transport instance;

  • ’socket’ (valfritt): socket.socket instans;

  • ”source_traceback” (valfritt): Traceback för källan;

  • ”handle_traceback” (valfritt): Traceback för handtaget;

  • ”asyncgen” (valfritt): Asynkron generator som orsakade

    undantaget.

Anteckning

Denna metod bör inte överbelastas i underklassade händelseslingor. För anpassad undantagshantering, använd metoden set_exception_handler().

Aktivering av felsökningsläge

loop.get_debug()

Hämta felsökningsläget (bool) för händelseslingan.

Standardvärdet är True om miljövariabeln PYTHONASYNCIODEBUG är inställd på en icke-tom sträng, annars False.

loop.set_debug(enabled: bool)

Ställ in felsökningsläget för händelseslingan.

Ändrad i version 3.7: Den nya Python Development Mode kan nu också användas för att aktivera felsökningsläget.

loop.slow_callback_duration

Detta attribut kan användas för att ange den minsta exekveringstid i sekunder som anses vara ”långsam”. När felsökningsläget är aktiverat loggas ”långsamma” callbacks.

Standardvärdet är 100 millisekunder.

Se även

debuggläge för asyncio.

Körning av underprocesser

Metoder som beskrivs i detta underavsnitt är på låg nivå. I vanlig async/await-kod bör du överväga att använda bekvämlighetsfunktionerna på hög nivå asyncio.create_subprocess_shell() och asyncio.create_subprocess_exec() istället.

Anteckning

I Windows har standardhändelseslingan ProactorEventLoop stöd för underprocesser, medan SelectorEventLoop inte har det. Se Subprocessstöd på Windows för mer information.

async loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Skapa en subprocess från ett eller flera strängargument som anges av args.

args måste vara en lista med strängar som representeras av:

Den första strängen anger det körbara programmet och de återstående strängarna anger argumenten. Tillsammans bildar strängargumenten programmets argv.

Detta liknar standardbibliotekets klass subprocess.Popen som anropas med shell=False och en lista med strängar som första argument; men där Popen tar ett enda argument som är en lista med strängar, tar subprocess_exec flera strängargument.

protocol_factory måste vara en callable som returnerar en subklass av klassen asyncio.SubprocessProtocol.

Övriga parametrar:

  • stdin kan vara vilket som helst av dessa:

    • ett filliknande objekt

    • en befintlig filbeskrivare (ett positivt heltal), t.ex. de som skapats med os.pipe()

    • konstanten subprocess.PIPE (standard) som skapar ett nytt rör och ansluter det,

    • värdet None som gör att subprocessen ärver filbeskrivaren från den här processen

    • konstanten subprocess.DEVNULL som anger att den speciella filen os.devnull ska användas

  • stdout kan vara vilken som helst av dessa:

    • ett filliknande objekt

    • konstanten subprocess.PIPE (standard) som skapar ett nytt rör och ansluter det,

    • värdet None som gör att subprocessen ärver filbeskrivaren från den här processen

    • konstanten subprocess.DEVNULL som anger att den speciella filen os.devnull ska användas

  • stderr kan vara vilken som helst av dessa:

    • ett filliknande objekt

    • konstanten subprocess.PIPE (standard) som skapar ett nytt rör och ansluter det,

    • värdet None som gör att subprocessen ärver filbeskrivaren från den här processen

    • konstanten subprocess.DEVNULL som anger att den speciella filen os.devnull ska användas

    • konstanten subprocess.STDOUT som kopplar standardfelströmmen till processens standardutgångsström

  • Alla andra nyckelordsargument skickas till subprocess.Popen utan tolkning, med undantag för bufsize, universal_newlines, shell, text, encoding och errors, som inte bör anges alls.

    API:et för underprocesser i asyncio stöder inte avkodning av strömmar som text. bytes.decode() kan användas för att konvertera byte som returneras från strömmen till text.

Om ett filliknande objekt som skickas som stdin, stdout eller stderr representerar en pipe, ska den andra sidan av denna pipe registreras med connect_write_pipe() eller connect_read_pipe() för användning med händelseslingan.

Se konstruktören för klassen subprocess.Popen för dokumentation om andra argument.

Returnerar ett par (transport, protocol), där transport överensstämmer med basklassen asyncio.SubprocessTransport och protocol är ett objekt som instantierats av protocol_factory.

async loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Skapa en underprocess från cmd, som kan vara en str eller en bytes-sträng kodad enligt filsystemets kodning, med hjälp av plattformens ”shell”-syntax.

Detta liknar standardbibliotekets subprocess.Popen-klass som anropas med shell=True.

protocol_factory måste vara en callable som returnerar en subklass av klassen SubprocessProtocol.

Se subprocess_exec() för mer information om de återstående argumenten.

Returnerar ett par (transport, protocol), där transport överensstämmer med basklassen SubprocessTransport och protocol är ett objekt som instantierats av protocol_factory.

Anteckning

Det är applikationens ansvar att se till att alla blanksteg och specialtecken citeras på rätt sätt för att undvika shell injection sårbarheter. Funktionen shlex.quote() kan användas för att på rätt sätt undkomma blanksteg och specialtecken i strängar som ska användas för att konstruera skalkommandon.

Handtag för återuppringning

class asyncio.Handle

Ett omslagsobjekt för återuppringning som returneras av loop.call_soon(), loop.call_soon_threadsafe().

get_context()

Returnerar contextvars.Context-objektet som är associerat med handtaget.

Tillagd i version 3.12.

cancel()

Avbryt återuppringningen. Om återkallelsen redan har avbrutits eller utförts har denna metod ingen effekt.

cancelled()

Returnerar True om återuppringningen avbröts.

Tillagd i version 3.7.

class asyncio.TimerHandle

Ett omslagsobjekt för återuppringning som returneras av loop.call_later() och loop.call_at().

Denna klass är en underklass till Handle.

when()

Returnerar en schemalagd callback-tid som float sekunder.

Tiden är en absolut tidsstämpel som använder samma tidsreferens som loop.time().

Tillagd i version 3.7.

Serverobjekt

Serverobjekt skapas av funktionerna loop.create_server(), loop.create_unix_server(), start_server() och start_unix_server().

Instansiera inte Server-klassen direkt.

class asyncio.Server

Server-objekt är asynkrona kontexthanterare. När de används i ett async with-uttryck, garanteras det att Server-objektet stängs och inte accepterar nya anslutningar när async with -uttrycket är slutfört:

srv = await loop.skapa_server(...)

asynkron med srv:
    # lite kod

# Vid denna tidpunkt är srv stängd och accepterar inte längre nya anslutningar.

Ändrad i version 3.7: Server-objektet är en asynkron kontexthanterare sedan Python 3.7.

Ändrad i version 3.11: Denna klass exponerades offentligt som asyncio.Server i Python 3.9.11, 3.10.3 och 3.11.

close()

Stoppa servering: stäng lyssnande uttag och sätt attributet sockets till None.

De uttag som representerar befintliga inkommande klientanslutningar lämnas öppna.

Servern stängs asynkront; använd wait_closed() coroutine för att vänta tills servern är stängd (och inga fler anslutningar är aktiva).

close_clients()

Stäng alla befintliga inkommande kundanslutningar.

Anropar close() på alla associerade transporter.

close() bör anropas före close_clients() när servern stängs för att undvika tävlingar med nya klienter som ansluter.

Tillagd i version 3.13.

abort_clients()

Stäng alla befintliga inkommande klientanslutningar omedelbart, utan att vänta på att väntande åtgärder ska slutföras.

Anropar abort() på alla associerade transporter.

close() bör anropas före abort_clients() när servern stängs för att undvika tävlingar med nya klienter som ansluter.

Tillagd i version 3.13.

get_loop()

Returnerar den händelseslinga som är kopplad till serverobjektet.

Tillagd i version 3.7.

async start_serving()

Börja acceptera kontakter.

Denna metod är idempotent, så den kan anropas när servern redan är i drift.

Nyckelordsparametern start_serving till loop.create_server() och asyncio.start_server() gör det möjligt att skapa ett serverobjekt som inte accepterar anslutningar initialt. I det här fallet kan Server.start_serving() eller Server.serve_forever() användas för att få servern att börja acceptera anslutningar.

Tillagd i version 3.7.

async serve_forever()

Börja acceptera anslutningar tills coroutinen avbryts. Om uppgiften serve_forever avbryts stängs servern.

Denna metod kan anropas om servern redan accepterar anslutningar. Endast en serve_forever uppgift kan finnas per ett Server-objekt.

Exempel:

async def client_connected(läsare, skribent):
    # Kommunicera med klienten med
    # strömmar av läsare/skrivare.  Till exempel
    await läsare.readline()

async def main(host, port):
    srv = await asyncio.start_server(
        client_connected, host, port)
    await srv.serve_forever()

asyncio.run(main('127.0.0.1', 0))

Tillagd i version 3.7.

is_serving()

Returnerar True om servern accepterar nya anslutningar.

Tillagd i version 3.7.

async wait_closed()

Vänta tills metoden close() har slutförts och alla aktiva anslutningar har avslutats.

sockets

Lista över socket-liknande objekt, asyncio.trsock.TransportSocket, som servern lyssnar på.

Ändrad i version 3.7: Före Python 3.7 brukade Server.sockets returnera en intern lista över serverns sockets direkt. I 3.7 returneras en kopia av den listan.

Implementering av händelseslingor

asyncio levereras med två olika implementationer av händelseslingor: SelectorEventLoop och ProactorEventLoop.

Som standard är asyncio konfigurerat att använda EventLoop.

class asyncio.SelectorEventLoop

En underklass till AbstractEventLoop baserad på modulen selectors.

Använder den effektivaste väljaren som finns tillgänglig för den givna plattformen. Det är också möjligt att manuellt konfigurera den exakta implementeringen av väljaren som ska användas:

import asyncio
import väljare

async def main():
   ...

loop_factory = lambda: asyncio.SelectorEventLoop(selectors.SelectSelector())
asyncio.run(main(), loop_factory=loop_factory)

Tillgänglighet: Unix, Windows.

class asyncio.ProactorEventLoop

En underklass till AbstractEventLoop för Windows som använder ”I/O Completion Ports” (IOCP).

Tillgänglighet: Windows.

Se även

MSDN-dokumentation om I/O Completion Ports.

class asyncio.EventLoop

Ett alias till den mest effektiva tillgängliga underklassen till AbstractEventLoop för den givna plattformen.

Det är ett alias till SelectorEventLoop på Unix och ProactorEventLoop på Windows.

Tillagd i version 3.13.

class asyncio.AbstractEventLoop

Abstrakt basklass för asynciokompatibla händelseslingor.

Avsnittet Metoder för händelseslingor listar alla metoder som en alternativ implementation av AbstractEventLoop borde ha definierat.

Exempel

Observera att alla exempel i detta avsnitt avsiktligt visar hur man använder lågnivå-API:er för händelseslingor, som loop.run_forever() och loop.call_soon(). Moderna asyncio-applikationer behöver sällan skrivas på det här sättet; överväg att använda högnivåfunktioner som asyncio.run().

Hello World med call_soon()

Ett exempel där metoden loop.call_soon() används för att schemalägga en återuppringning. Återkallelsen visar "Hello World" och stoppar sedan händelseslingan:

import asyncio

def hello_world(loop):
    """A callback to print 'Hello World' and stop the event loop"""
    print('Hello World')
    loop.stop()

loop = asyncio.new_event_loop()

# Schedule a call to hello_world()
loop.call_soon(hello_world, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

Se även

Ett liknande Hello World exempel skapat med en coroutine och funktionen run().

Visa aktuellt datum med call_later()

Ett exempel på en callback som visar aktuellt datum varje sekund. Återuppringningen använder metoden loop.call_later() för att schemalägga om sig själv efter 5 sekunder, och stoppar sedan händelseslingan:

import asyncio
import datetime

def display_date(slut_tid, loop):
    print(datetime.datetime.now())
    if (loop.time() + 1.0) < end_time:
        loop.call_later(1, display_date, end_time, loop)
    annat:
        loop.stop()

loop = asyncio.new_event_loop()

# Schemalägg det första anropet till display_date()
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# Blockerande anrop avbrutet av loop.stop()
försök:
    loop.run_forever()
finally: loop.run_forever()
    loop.close()

Se även

Ett liknande aktuellt datum exempel skapat med en coroutine och funktionen run().

Bevaka en filbeskrivare för läshändelser

Vänta tills en filbeskrivningsenhet har tagit emot data med hjälp av metoden loop.add_reader() och stäng sedan händelseslingan:

import asyncio
from socket import socketpair

# Create a pair of connected file descriptors
rsock, wsock = socketpair()

loop = asyncio.new_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())

    # We are done: unregister the file descriptor
    loop.remove_reader(rsock)

    # Stop the event loop
    loop.stop()

# Register the file descriptor for read event
loop.add_reader(rsock, reader)

# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())

try:
    # Run the event loop
    loop.run_forever()
finally:
    # We are done. Close sockets and the event loop.
    rsock.close()
    wsock.close()
    loop.close()

Se även

Ange signalhanterare för SIGINT och SIGTERM

(Detta signals-exempel fungerar bara på Unix.)

Registrera hanterare för signalerna SIGINT och SIGTERM med hjälp av metoden loop.add_signal_handler():

import asyncio
import functools
import os
import signal

def ask_exit(signame, loop):
    print("got signal %s: exit" % signame)
    loop.stop()

async def main():
    loop = asyncio.get_running_loop()

    for signame in {'SIGINT', 'SIGTERM'}:
        loop.add_signal_handler(
            getattr(signal, signame),
            functools.partial(ask_exit, signame, loop))

    await asyncio.sleep(3600)

print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
print(f"pid {os.getpid()}: send SIGINT or SIGTERM to exit.")

asyncio.run(main())