Index de l'API de bas niveau
****************************

Cette page répertorie toutes les API asynchrones de bas niveau.


Obtenir une boucle d'évènements
===============================

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.get_running_loop()"                       | La fonction **préférée** pour obtenir la boucle    |
|                                                    | d'événements en cours d'exécution.                 |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.get_event_loop()"                         | Renvoie une instance de boucle d'événements (en    |
|                                                    | cours d'exécution ou actuelle via la politique     |
|                                                    | actuelle).                                         |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.set_event_loop()"                         | Définit la boucle d'événements comme actuelle via  |
|                                                    | la politique actuelle.                             |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.new_event_loop()"                         | Crée une nouvelle boucle d'événements.             |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Utilisation d'asyncio.get_running_loop().


Méthodes de la boucle d'évènements
==================================

Voir aussi la section principale de la documentation sur les Méthodes
de la boucle d'évènements.

-[ Cycle de vie ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.run_until_complete()"                        | Exécute un Future/Task/awaitable jusqu'à ce qu'il  |
|                                                    | soit terminé.                                      |
+----------------------------------------------------+----------------------------------------------------+
| "loop.run_forever()"                               | Exécute la boucle d'événements pour toujours.      |
+----------------------------------------------------+----------------------------------------------------+
| "loop.stop()"                                      | Arrête l'exécution de la boucle d'évènements.      |
+----------------------------------------------------+----------------------------------------------------+
| "loop.close()"                                     | Arrête la boucle d'évènements.                     |
+----------------------------------------------------+----------------------------------------------------+
| "loop.is_running()"                                | Renvoie "True" si la boucle d'événements est en    |
|                                                    | cours d'exécution.                                 |
+----------------------------------------------------+----------------------------------------------------+
| "loop.is_closed()"                                 | Renvoie "True" si la boucle d'évènements est       |
|                                                    | arrêtée.                                           |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.shutdown_asyncgens()"                | Ferme les générateurs asynchrones.                 |
+----------------------------------------------------+----------------------------------------------------+

-[ Débogage ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.set_debug()"                                 | Active ou désactive le mode débogage.              |
+----------------------------------------------------+----------------------------------------------------+
| "loop.get_debug()"                                 | Renvoie le mode de débogage actuel.                |
+----------------------------------------------------+----------------------------------------------------+

-[ Planification des rappels ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.call_soon()"                                 | Invoque un rappel bientôt.                         |
+----------------------------------------------------+----------------------------------------------------+
| "loop.call_soon_threadsafe()"                      | Une variante compatible avec les programmes à fils |
|                                                    | d'exécution multiples de "loop.call_soon()".       |
+----------------------------------------------------+----------------------------------------------------+
| "loop.call_later()"                                | Invoque un rappel *après* le temps imparti.        |
+----------------------------------------------------+----------------------------------------------------+
| "loop.call_at()"                                   | Invoque un rappel *à l'heure* indiquée.            |
+----------------------------------------------------+----------------------------------------------------+

-[ Pool de fils d'exécution ou processus ]-

+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.run_in_executor()"                   | Exécute une fonction utilisant beaucoup de CPU ou  |
|                                                    | une autre fonction bloquante dans un exécuteur     |
|                                                    | "concurrent.futures".                              |
+----------------------------------------------------+----------------------------------------------------+
| "loop.set_default_executor()"                      | Définit l'exécuteur par défaut pour                |
|                                                    | "loop.run_in_executor()".                          |
+----------------------------------------------------+----------------------------------------------------+

-[ Tâches et *Futures* ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.create_future()"                             | Crée un objet "Future".                            |
+----------------------------------------------------+----------------------------------------------------+
| "loop.create_task()"                               | Planifie la coroutine en tant que "Task".          |
+----------------------------------------------------+----------------------------------------------------+
| "loop.set_task_factory()"                          | Définit une fabrique utilisée par                  |
|                                                    | "loop.create_task()" pour créer des "Tasks".       |
+----------------------------------------------------+----------------------------------------------------+
| "loop.get_task_factory()"                          | Récupère la fabrique que "loop.create_task()"      |
|                                                    | utilise pour créer des "Tasks".                    |
+----------------------------------------------------+----------------------------------------------------+

-[ DNS ]-

+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.getaddrinfo()"                       | Version asynchrone de "socket.getaddrinfo()".      |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.getnameinfo()"                       | Version asynchrone de "socket.getnameinfo()".      |
+----------------------------------------------------+----------------------------------------------------+

-[ Réseau et communication inter-processus ]-

+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.create_connection()"                 | Ouvre une connexion TCP.                           |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.create_server()"                     | Crée un serveur TCP.                               |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.create_unix_connection()"            | Ouvre une connexion socket Unix.                   |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.create_unix_server()"                | Crée un serveur de socket Unix.                    |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.connect_accepted_socket()"           | Enveloppe une "socket" dans une paire "(transport, |
|                                                    | protocol)".                                        |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.create_datagram_endpoint()"          | Ouvre une connexion par datagramme (UDP).          |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sendfile()"                          | Envoie un fichier via un transport.                |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.start_tls()"                         | Bascule une connexion existante vers TLS.          |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.connect_read_pipe()"                 | Enveloppe une extrémité de lecture d'un tube dans  |
|                                                    | une paire "(transport, protocol)".                 |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.connect_write_pipe()"                | Enveloppe une extrémité d'écriture d'un tube dans  |
|                                                    | une paire "(transport, protocol)".                 |
+----------------------------------------------------+----------------------------------------------------+

-[ Interfaces de connexion (*sockets*) ]-

+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_recv()"                         | Reçoit les données de "socket".                    |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_recv_into()"                    | Reçoit les données de "socket" dans un tampon.     |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_recvfrom()"                     | Reçoit un datagramme de "socket".                  |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_recvfrom_into()"                | Reçoit un datagramme de "socket" dans un tampon.   |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_sendall()"                      | Envoie des données à "socket".                     |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_sendto()"                       | Envoie un datagramme via "socket" à l'adresse      |
|                                                    | indiquée.                                          |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_connect()"                      | Connecte la "socket".                              |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_accept()"                       | Accepte une connexion "socket".                    |
+----------------------------------------------------+----------------------------------------------------+
| "await" "loop.sock_sendfile()"                     | Envoie un fichier via "socket".                    |
+----------------------------------------------------+----------------------------------------------------+
| "loop.add_reader()"                                | Commence à observer un descripteur de fichier pour |
|                                                    | la disponibilité en lecture.                       |
+----------------------------------------------------+----------------------------------------------------+
| "loop.remove_reader()"                             | Arrête d'observer un descripteur de fichier pour   |
|                                                    | la disponibilité en lecture.                       |
+----------------------------------------------------+----------------------------------------------------+
| "loop.add_writer()"                                | Commence à observer un descripteur de fichier pour |
|                                                    | la disponibilité en écriture.                      |
+----------------------------------------------------+----------------------------------------------------+
| "loop.remove_writer()"                             | Arrête d'observer un descripteur de fichier pour   |
|                                                    | la disponibilité en écriture.                      |
+----------------------------------------------------+----------------------------------------------------+

-[ Signaux Unix ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.add_signal_handler()"                        | Ajoute un gestionnaire pour le "signal".           |
+----------------------------------------------------+----------------------------------------------------+
| "loop.remove_signal_handler()"                     | Supprime un gestionnaire pour le "signal".         |
+----------------------------------------------------+----------------------------------------------------+

-[ Sous-processus ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.subprocess_exec()"                           | Crée un sous-processus.                            |
+----------------------------------------------------+----------------------------------------------------+
| "loop.subprocess_shell()"                          | Crée un sous-processus à partir d'une commande     |
|                                                    | shell.                                             |
+----------------------------------------------------+----------------------------------------------------+

-[ Gestion des erreurs ]-

+----------------------------------------------------+----------------------------------------------------+
| "loop.call_exception_handler()"                    | Appelle le gestionnaire d'exceptions.              |
+----------------------------------------------------+----------------------------------------------------+
| "loop.set_exception_handler()"                     | Définit un nouveau gestionnaire d'exceptions.      |
+----------------------------------------------------+----------------------------------------------------+
| "loop.get_exception_handler()"                     | Renvoie le gestionnaire d'exceptions actuel.       |
+----------------------------------------------------+----------------------------------------------------+
| "loop.default_exception_handler()"                 | Implémentation du gestionnaire d'exceptions par    |
|                                                    | défaut.                                            |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Utilisation d'asyncio.new_event_loop() et de loop.run_forever().

* Utilisation de loop.call_later().

* Utilisation de "loop.create_connection()" pour implémenter un client
  écho.

* Utilisation de "loop.create_connection()" pour connecter un socket.

* Utilisation de add_reader() pour surveiller un descripteur de
  fichier pour les événements de lecture.

* Utilisation de loop.add_signal_handler().

* Utilisation de loop.subprocess_exec().


Transports
==========

Tous les transports mettent en œuvre les méthodes suivantes :

+----------------------------------------------------+----------------------------------------------------+
| "transport.close()"                                | Ferme le transport.                                |
+----------------------------------------------------+----------------------------------------------------+
| "transport.is_closing()"                           | Renvoie "True" si le transport se ferme ou est     |
|                                                    | fermé.                                             |
+----------------------------------------------------+----------------------------------------------------+
| "transport.get_extra_info()"                       | Demande d'informations sur le transport.           |
+----------------------------------------------------+----------------------------------------------------+
| "transport.set_protocol()"                         | Change le protocole.                               |
+----------------------------------------------------+----------------------------------------------------+
| "transport.get_protocol()"                         | Renvoie le protocole courant.                      |
+----------------------------------------------------+----------------------------------------------------+

Transports pouvant recevoir des données (connexions TCP et Unix,
pipes, etc.). Renvoyé par des méthodes telles que
"loop.create_connection()", "loop.create_unix_connection()",
"loop.connect_read_pipe()", etc :

-[ Transports en lecture ]-

+----------------------------------------------------+----------------------------------------------------+
| "transport.is_reading()"                           | Renvoie "True" si le transport est en cours de     |
|                                                    | réception.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "transport.pause_reading()"                        | Suspend la réception.                              |
+----------------------------------------------------+----------------------------------------------------+
| "transport.resume_reading()"                       | Reprend la réception.                              |
+----------------------------------------------------+----------------------------------------------------+

Transports pouvant envoyer des données (connexions TCP et Unix, pipes,
etc.). Renvoyé par des méthodes telles que "loop.create_connection()",
"loop.create_unix_connection()", "loop.connect_write_pipe()", etc :

-[ Transports en écriture ]-

+----------------------------------------------------+----------------------------------------------------+
| "transport.write()"                                | Écrit des données dans le transport.               |
+----------------------------------------------------+----------------------------------------------------+
| "transport.writelines()"                           | Écrit des tampons dans le transport.               |
+----------------------------------------------------+----------------------------------------------------+
| "transport.can_write_eof()"                        | Renvoie "True" si le transport prend en charge     |
|                                                    | l'envoi d'EOF.                                     |
+----------------------------------------------------+----------------------------------------------------+
| "transport.write_eof()"                            | Ferme et envoie EOF après avoir vidé les données   |
|                                                    | mises en mémoire tampon.                           |
+----------------------------------------------------+----------------------------------------------------+
| "transport.abort()"                                | Ferme immédiatement le transport.                  |
+----------------------------------------------------+----------------------------------------------------+
| "transport.get_write_buffer_size()"                | Return the current size of the output buffer.      |
+----------------------------------------------------+----------------------------------------------------+
| "transport.get_write_buffer_limits()"              | Renvoie les seuils haut et bas pour le contrôle du |
|                                                    | flux d'écriture.                                   |
+----------------------------------------------------+----------------------------------------------------+
| "transport.set_write_buffer_limits()"              | Définit de nouvelles bornes hautes et basses pour  |
|                                                    | le contrôle du flux d'écriture.                    |
+----------------------------------------------------+----------------------------------------------------+

Transports renvoyés par "loop.create_datagram_endpoint()" :

-[ Transports par datagrammes ]-

+----------------------------------------------------+----------------------------------------------------+
| "transport.sendto()"                               | Envoie des données au pair distant.                |
+----------------------------------------------------+----------------------------------------------------+
| "transport.abort()"                                | Ferme immédiatement le transport.                  |
+----------------------------------------------------+----------------------------------------------------+

Abstraction de transport de bas niveau sur les sous-processus. Renvoyé
par "loop.subprocess_exec()" et "loop.subprocess_shell()" :

-[ Transports vers des sous-processus ]-

+----------------------------------------------------+----------------------------------------------------+
| "transport.get_pid()"                              | Renvoie l'ID de processus du sous-processus.       |
+----------------------------------------------------+----------------------------------------------------+
| "transport.get_pipe_transport()"                   | Renvoie le transport pour le tube de communication |
|                                                    | demandé (*stdin*, *stdout* ou *stderr*).           |
+----------------------------------------------------+----------------------------------------------------+
| "transport.get_returncode()"                       | Renvoie le code de retour du sous-processus.       |
+----------------------------------------------------+----------------------------------------------------+
| "transport.kill()"                                 | Tue le sous-processus.                             |
+----------------------------------------------------+----------------------------------------------------+
| "transport.send_signal()"                          | Envoie un signal au sous-processus.                |
+----------------------------------------------------+----------------------------------------------------+
| "transport.terminate()"                            | Termine le sous-processus.                         |
+----------------------------------------------------+----------------------------------------------------+
| "transport.close()"                                | Tue le sous-processus et ferme tous les tubes.     |
+----------------------------------------------------+----------------------------------------------------+


Protocoles
==========

Les classes de protocole peuvent implémenter les **méthodes de
rappel** suivantes :

+----------------------------------------------------+----------------------------------------------------+
| "callback" "connection_made()"                     | Appelée lorsqu'une connexion est établie.          |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "connection_lost()"                     | Appelé lorsqu'une connexion est perdue ou fermée.  |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "pause_writing()"                       | Appelée lorsque la mémoire tampon du transport     |
|                                                    | dépasse le seuil haut.                             |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "resume_writing()"                      | Appelée lorsque la mémoire tampon du transport     |
|                                                    | passe sous le seuil bas.                           |
+----------------------------------------------------+----------------------------------------------------+

-[ Protocoles de flux (TCP, Unix Sockets, Pipes) ]-

+----------------------------------------------------+----------------------------------------------------+
| "callback" "data_received()"                       | Appelée lorsque certaines données sont reçues.     |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "eof_received()"                        | Appelée lorsqu'un EOF est reçu.                    |
+----------------------------------------------------+----------------------------------------------------+

-[ Protocoles de flux tamponnés ]-

+----------------------------------------------------+----------------------------------------------------+
| "callback" "get_buffer()"                          | Appelée pour allouer un nouveau tampon de          |
|                                                    | réception.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "buffer_updated()"                      | Appelée lorsque le tampon a été mis à jour avec    |
|                                                    | les données reçues.                                |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "eof_received()"                        | Appelée lorsqu'un EOF est reçu.                    |
+----------------------------------------------------+----------------------------------------------------+

-[ Protocoles par datagrammes (non-connectés) ]-

+----------------------------------------------------+----------------------------------------------------+
| "callback" "datagram_received()"                   | Appelée lorsqu'un datagramme est reçu.             |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "error_received()"                      | Appelée lorsqu'une opération d'envoi ou de         |
|                                                    | réception précédente lève une "OSError".           |
+----------------------------------------------------+----------------------------------------------------+

-[ Protocoles liés aux sous-processus ]-

+----------------------------------------------------+----------------------------------------------------+
| "callback" "pipe_data_received()"                  | Appelée lorsqu'un processus enfant écrit sur sa    |
|                                                    | sortie d'erreur ou sa sortie standard.             |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "pipe_connection_lost()"                | Appelée lorsqu'un tube de communication avec un    |
|                                                    | sous-processus est fermée.                         |
+----------------------------------------------------+----------------------------------------------------+
| "callback" "process_exited()"                      | Called when the child process has exited. It can   |
|                                                    | be called before "pipe_data_received()" and        |
|                                                    | "pipe_connection_lost()" methods.                  |
+----------------------------------------------------+----------------------------------------------------+


Politiques de boucle d'événements
=================================

Les politiques sont un mécanisme de bas niveau pour modifier le
comportement de fonctions telles que "asyncio.get_event_loop()". Voir
aussi la section principale Politiques pour plus de détails.

-[ Accès aux politiques ]-

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.get_event_loop_policy()"                  | Renvoie la politique actuelle à l'échelle du       |
|                                                    | processus.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.set_event_loop_policy()"                  | Définit une nouvelle politique à l'échelle du      |
|                                                    | processus.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "AbstractEventLoopPolicy"                          | Classe mère pour les objets de politique.          |
+----------------------------------------------------+----------------------------------------------------+
