http.client
— Client pour le protocole HTTP¶
Code source : Lib/http/client.py
This module defines classes which implement the client side of the HTTP and
HTTPS protocols. It is normally not used directly --- the module
urllib.request
uses it to handle URLs that use HTTP and HTTPS.
Voir aussi
Le paquet Requests est recommandé pour une interface client HTTP de plus haut niveau.
Note
L'implémentation d'HTTPS n'est disponible que si Python a été compilé avec la prise en charge de SSL (au moyen du module ssl
).
Le module fournit les classes suivantes :
-
class
http.client.
HTTPConnection
(host, port=None, [timeout, ]source_address=None, blocksize=8192)¶ An
HTTPConnection
instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the formhost:port
, else the default HTTP port (80) is used. If the optional timeout parameter is given, blocking operations (like connection attempts) will timeout after that many seconds (if it is not given, the global default timeout setting is used). The optional source_address parameter may be a tuple of a (host, port) to use as the source address the HTTP connection is made from. The optional blocksize parameter sets the buffer size in bytes for sending a file-like message body.Par exemple, tous les appels suivants créent des instances qui se connectent à un serveur sur le même hôte et le même port :
>>> h1 = http.client.HTTPConnection('www.python.org') >>> h2 = http.client.HTTPConnection('www.python.org:80') >>> h3 = http.client.HTTPConnection('www.python.org', 80) >>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)
Modifié dans la version 3.2: Le paramètre source_address a été ajouté.
Modifié dans la version 3.4: The strict parameter was removed. HTTP 0.9-style "Simple Responses" are not longer supported.
Modifié dans la version 3.7: Le paramètre blocksize a été ajouté.
-
class
http.client.
HTTPSConnection
(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)¶ Cette sous-classe de
HTTPConnection
utilise SSL pour communiquer avec des serveurs sécurisés. Le port par défaut est443
. Si le paramètre context est fourni, ce doit être une instance dessl.SSLContext
décrivant les diverses options SSL.Il est conseillé de lire Security considerations pour plus d'informations sur les bonnes pratiques.
Modifié dans la version 3.2: Les paramètres source_address, context et check_hostname ont été ajoutés.
Modifié dans la version 3.2: Cette classe implémente désormais les hôtes virtuels HTTPS dans la mesure du possible (c'est-à-dire si
ssl.HAS_SNI
est vrai).Modifié dans la version 3.4: Le paramètre strict a été supprimé. Les « réponses simples » de HTTP 0.9 ne sont plus prises en charge.
Modifié dans la version 3.4.3: Cette classe réalise maintenant par défaut toutes les vérifications de certificat et de nom d'hôte. Pour revenir au comportement antérieur, sans vérification,
ssl._create_unverified_context()
peut être passé au paramètre context.Modifié dans la version 3.8: Cette classe sélectionne désormais TLS 1.3 pour
ssl.SSLContext.post_handshake_auth
dans le context par défaut ou quand cert_file est fourni avec une valeur de context personnalisée.Obsolète depuis la version 3.6: Les paramètres key_file et cert_file sont rendus obsolètes par context. Veuillez plutôt utiliser
ssl.SSLContext.load_cert_chain()
, ou laissezssl.create_default_context()
sélectionner les certificats racines de confiance du système pour vous.Le paramètre check_hostname est de même obsolète : utilisez l'attribut
ssl.SSLContext.check_hostname
de context à la place.
-
class
http.client.
HTTPResponse
(sock, debuglevel=0, method=None, url=None)¶ Classe dont les instances sont renvoyées dès qu'une connexion est établie. Cette classe n'est jamais instanciée directement par l'utilisateur.
Modifié dans la version 3.4: Le paramètre strict a été supprimé. Les « réponses simples » de HTTP 0.9 ne sont plus prises en charge.
Ce module fournit les fonctions suivantes :
-
http.client.
parse_headers
(fp)¶ Analyse les en-têtes à partir d'un pointeur de fichier fp représentant une requête/réponse HTTP. Le fichier doit être un lecteur de classe
BufferedIOBase
(c'est-à-dire non textuel) et doit impérativement renvoyer un en-tête valide selon la RFC 2822.Cette fonction renvoie une instance de
http.client.HTTPMessage
qui contient les champs d'en-tête, mais pas la charge utile (de même queHTTPResponse.msg
ethttp.server.BaseHTTPRequestHandler.headers
). Après le retour, le pointeur de fichier fp est prêt à lire le corps HTTP.Note
La méthode
parse_headers()
n'analyse pas la ligne initiale d'un message HTTP ; elle n'analyse que les lignesName: value
. Le fichier doit être prêt à lire ces lignes de champs, aussi la première ligne doit déjà avoir été consommée avant l'appel de la fonction.
Les exceptions suivantes sont levées selon les cas :
-
exception
http.client.
HTTPException
¶ La classe de base des autres exceptions de ce module. C'est une sous-classe de
Exception
.
-
exception
http.client.
NotConnected
¶ Sous-classe de
HTTPException
.
-
exception
http.client.
InvalidURL
¶ Sous-classe de
HTTPException
, levée si le port donné n'est pas numérique ou est vide.
-
exception
http.client.
UnknownProtocol
¶ Sous-classe de
HTTPException
.
-
exception
http.client.
UnknownTransferEncoding
¶ Sous-classe de
HTTPException
.
-
exception
http.client.
UnimplementedFileMode
¶ Sous-classe de
HTTPException
.
-
exception
http.client.
IncompleteRead
¶ Sous-classe de
HTTPException
.
-
exception
http.client.
ImproperConnectionState
¶ Sous-classe de
HTTPException
.
-
exception
http.client.
CannotSendRequest
¶ Sous-classe de
ImproperConnectionState
.
-
exception
http.client.
CannotSendHeader
¶ Sous-classe de
ImproperConnectionState
.
-
exception
http.client.
ResponseNotReady
¶ Sous-classe de
ImproperConnectionState
.
-
exception
http.client.
BadStatusLine
¶ Sous-classe de
HTTPException
. Levée si un serveur répond avec un code d'état HTTP qui n'est pas compris.
-
exception
http.client.
LineTooLong
¶ Sous-classe de
HTTPException
. Levée si une ligne du protocole HTTP est excessivement longue dans ce qui provient du serveur.
-
exception
http.client.
RemoteDisconnected
¶ Sous-classe de
ConnectionResetError
etBadStatusLine
. Levée par la méthodeHTTPConnection.getresponse()
quand la tentative de lire la réponse n'aboutit à aucune donnée provenant de la connexion, indiquant ainsi que la partie distante a fermé celle-ci.Nouveau dans la version 3.5: Antérieurement,
BadStatusLine
('')
était levée.
Les constantes définies dans ce module sont :
-
http.client.
HTTP_PORT
¶ Le port par défaut du protocole HTTP (toujours
80
).
-
http.client.
HTTPS_PORT
¶ Le port par défaut du protocole HTTPS (toujours
443
).
-
http.client.
responses
¶ Ce dictionnaire associe les codes d'états HTTP 1.1 à leurs noms tels que définis par le W3C.
Par exemple :
http.client.responses[http.client.NOT_FOUND]
est'Not Found'
.
Voir Codes d'état HTTP pour une liste des codes d'état HTTP qui sont disponibles comme constantes dans ce module.
Les objets HTTPConnection¶
Les instances de la classe HTTPConnection
possèdent les méthodes suivantes :
-
HTTPConnection.
request
(method, url, body=None, headers={}, *, encode_chunked=False)¶ Envoie une requête à un serveur en utilisant la méthode method de requête HTTP et le sélecteur url.
Si body est passé en paramètre, les données transmises sont envoyées à la suite des en-têtes. Ce paramètre peut-être une
str
, un objet octet-comptatible, un objet fichier préalablement ouvert, ou un itérable de classebytes
. Si body est une chaîne, elle est encodée en ISO-8859-1, valeur par défaut pour HTTP. Si c'est un objet octet-compatible, les octets sont envoyés tels quels. Si c'est un objet fichier, le contenu du fichier est envoyé ; cet objet fichier doit implémenter au moins la méthoderead()
. Si l'objet fichier est une instance deio.TextIOBase
, les données renvoyées par la méthoderead()
sont encodées en ISO-8859-1, sinon les données renvoyées parread()
sont envoyées telles quelles. Si body est un itérable, les éléments de cet itérable sont envoyés jusqu'à ce que l'itérable soit vide.L'argument headers doit contenir les en-têtes HTTP supplémentaires sous forme de dictionnaire. Ces en-têtes sont transmis dans la requête.
Si headers ne contient ni
Content-Length:
niTransfer-Encoding:
, mais qu'un corps de requête est fourni, un de ces en-têtes est ajouté automatiquement. Si body estNone
, l'en-têteContent-Length:
est paramétré à0
pour les méthodes qui attendent un corps (PUT
,POST
, etPATCH
). Si body est une chaîne ou un objet de type octets qui n'est pas un (objet fichier), l'en-têteContent-Length
est paramétré à sa longueur. Un body de tout autre type (fichiers ou itérables en général) est encodé par morceaux et l'en-têteTransfer-Encoding
est automatiquement paramétré à la place deContent-Length
.L'argument encode_chunked n'est pertinent que si l'en-tête
Transfer-Encoding:
est présent. Si encode_chunked estFalse
, l'objet HTTPConnection suppose que l'encodage est géré par le code d'appel. S'il vautTrue
, le corps est encodé par morceaux.Note
L'encodage pour les transferts par morceaux a été ajouté à la version 1.1 du protocole HTTP. À moins que le serveur HTTP sache gérer HTTP 1.1, l'appelant doit soit spécifier l'en-tête
Content-Length:
, soit passer la représentation du corps de message dans un objet de classestr
ou un objet octet-compatible qui ne soit pas un fichier.Nouveau dans la version 3.2: body peut désormais être un itérable.
Modifié dans la version 3.6: Si parmi les en-têtes ne figure ni
Content-Length:
, niTransfer-Encoding:
, les objets fichiers et itérables body sont désormais encodés par morceaux. L'argument encode_chunked a été ajouté. Aucune tentative n'est faite pour essayer de déterminer la valeur de l'en-têteContent-Length
pour un objet fichier.
-
HTTPConnection.
getresponse
()¶ Doit être appelé après qu'une requête a été envoyée pour récupérer la réponse du serveur. Renvoie une instance de
HTTPResponse
.Note
Notez que la totalité de la réponse doit être lue avant de pouvoir envoyer une nouvelle requête au serveur.
Modifié dans la version 3.5: Si une exception
ConnectionError
ou une de ses sous-classes est levée, l'objet de classeHTTPConnection
sera prêt à se reconnecter quand une nouvelle requête sera envoyée.
-
HTTPConnection.
set_debuglevel
(level)¶ Règle le niveau de débogage. Le niveau de débogage par défaut est
0
(aucune sortie de débogage n'est affichée). Toute valeur plus grande que0
provoque l'affichage sursys.stdout
de toutes les sorties de débogage actuellement définies. Le paramètredebuglevel
est passé à tout nouvel objet de classeHTTPResponse
qui est créé.Nouveau dans la version 3.1.
-
HTTPConnection.
set_tunnel
(host, port=None, headers=None)¶ Paramètre l'hôte et le port pour le tunnel de connexion HTTP. Il permet de réaliser la connexion au travers d'un serveur mandataire.
Les arguments d'hôte et de port indiquent le point de terminaison de la connexion par tunnel (c'est-à-dire l'adresse incluse dans la requête CONNECT, et non l'adresse du serveur mandataire).
L'argument headers doit contenir les en-têtes HTTP supplémentaires sous forme d'un dictionnaire. Ceux-ci seront envoyés avec la requête CONNECT.
Par exemple, pour un tunnel traversant un serveur mandataire HTTPS accessible localement sur le port 8080, nous devons passer l'adresse du serveur mandataire au constructeur de la classe
HTTPSConnection
, en plus de l'éventuelle adresse de l'hôte que nous voulons atteindre, qui elle doit être passée à la méthodeset_tunnel()
:>>> import http.client >>> conn = http.client.HTTPSConnection("localhost", 8080) >>> conn.set_tunnel("www.python.org") >>> conn.request("HEAD","/index.html")
Nouveau dans la version 3.2.
-
HTTPConnection.
connect
()¶ Se connecte au serveur spécifié quand l'objet est créé. Par défaut, est appelée automatiquement lorsqu'une requête est faite alors que le client ne s'est pas connecté au préalable.
-
HTTPConnection.
close
()¶ Ferme la connexion au serveur.
-
HTTPConnection.
blocksize
¶ Taille en octets du tampon utilisé pour transmettre un corps de message de type fichier.
Nouveau dans la version 3.7.
Plutôt que d'utiliser la méthode request()
décrite plus haut, il est également possible d'envoyer une requête étape par étape en utilisant les quatre fonctions ci-dessous.
-
HTTPConnection.
putrequest
(method, url, skip_host=False, skip_accept_encoding=False)¶ Ce doit être le premier appel une fois que la connexion au serveur a été réalisée. Est envoyée au serveur une ligne consistant en la chaîne method, la chaîne d'url, et la version du protocole HTTP (
HTTP/1.1
). Pour désactiver l'envoi automatique des en-têtesHost:
ouAccept-Encoding:
(par exemple pour accepter des encodages supplémentaires de contenus), il est nécessaire de passer les paramètres skip_host ou skip_accept_encoding avec des valeurs différentes deFalse
.
-
HTTPConnection.
putheader
(header, argument[, ...])¶ Envoie un en-tête de style RFC 822 au serveur. Elle envoie au serveur une ligne regroupant un en-tête, une espace, un
:
, une espace et le premier argument. Si plusieurs arguments sont donnés, des lignes de continuation sont envoyées, chacune d'elle étant constituée d'une espace suivie d'un argument.
-
HTTPConnection.
endheaders
(message_body=None, *, encode_chunked=False)¶ Envoie une ligne blanche au serveur, signalant la fin des en-têtes. L'argument optionnel message_body peut-être utilisé pour passer le corps du message associé à la requête.
Si encode_chunked est
True
, le résultat de chaque itération sur message_body est un morceau encodé selon la RFC 7230, section 3.3.1. La façon dont les données sont encodées dépend du type de message_body. Si message_body implémente l'interface tampon l'encodage donne un unique morceau. Si message_body est un itérable de classecollections.abc.Iterable
, chaque itération sur message_body donne un morceau. Si message_body est un fichier objet, chaque appel à.read()
renvoie un morceau. La méthode signale automatiquement la fin des données encodées par morceaux immédiatement après message_body.Note
Selon la spécification de l'encodage des morceaux, les morceaux vides renvoyés par un itérateur associé au corps du message sont ignorés par l'encodeur de morceaux. Ce comportement est choisi pour éviter que la lecture de la requête par le serveur cible ne se termine prématurément pour cause d'encodage mal formé.
Nouveau dans la version 3.6: Implémentation de l'encodage (pour les transferts) par morceaux. Le paramètre encode_chunked a été ajouté.
-
HTTPConnection.
send
(data)¶ Envoie les données au serveur. Elle ne peut être utilisée directement qu'une fois la méthode
endheaders()
a été appelée et avant que la méthodegetresponse()
ait été appelée.
Les objets HTTPResponse¶
Une instance de HTTPResponse
encapsule la réponse HTTP du serveur. Elle fournit un accès aux en-têtes et au corps de la réponse. La réponse est un objet itérable pouvant être utilisé avec l'instruction with
.
Modifié dans la version 3.5: L'interface de la classe io.BufferedIOBase
est désormais implémentée et toutes ses opérations de lecture sont gérées.
-
HTTPResponse.
read
([amt])¶ Lit et renvoie soit tout le corps de la réponse soit une partie de celui-ci se limitant aux amt octets suivants.
-
HTTPResponse.
readinto
(b)¶ Lit les prochains
len(b)
octets du corps de la réponse et les place dans le tampon b. Renvoie le nombre d'octets lus.Nouveau dans la version 3.3.
-
HTTPResponse.
getheader
(name, default=None)¶ Return the value of the header name, or default if there is no header matching name. If there is more than one header with the name name, return all of the values joined by ', '. If 'default' is any iterable other than a single string, its elements are similarly returned joined by commas.
-
HTTPResponse.
getheaders
()¶ Renvoie une liste d'n-uplets
(en-tête, valeur)
.
-
HTTPResponse.
fileno
()¶ Renvoie le
fileno
du connecteur réseau sous-jacent.
-
HTTPResponse.
msg
¶ Une instance de
http.client.HTTPMessage
contenant les en-têtes de la réponse. La classehttp.client.HTTPMessage
est une sous-classe de la classeemail.message.Message
.
-
HTTPResponse.
version
¶ La version du protocole HTTP utilisée par le serveur : 10 pour HTTP/1.0, 11 pour HTTP/1.1.
-
HTTPResponse.
status
¶ Code d'état renvoyé par le serveur.
-
HTTPResponse.
reason
¶ Phrase renvoyée par le serveur et indiquant la cause.
-
HTTPResponse.
debuglevel
¶ Un point d'entrée pour débogage. Si
debuglevel
est plus grand que zéro, les messages sont envoyés àsys.stdout
pendant la lecture et l'analyse de la réponse.
-
HTTPResponse.
closed
¶ Vaut
True
si le flux est terminé.
Exemples¶
Voici un exemple de session utilisant la méthode GET
:
>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read() # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
... print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()
Voici un exemple de session utilisant la méthode HEAD
. Notez que la méthode HEAD
ne renvoie jamais de données.
>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b''
True
Voici un exemple de session montrant l'utilisation de la méthode POST
:
>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
... "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()
Client side HTTP PUT
requests are very similar to POST
requests. The
difference lies only the server side where HTTP server will allow resources to
be created via PUT
request. It should be noted that custom HTTP methods
are also handled in urllib.request.Request
by setting the appropriate
method attribute. Here is an example session that shows how to send a PUT
request using http.client:
>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK
Les objets HTTPMessage¶
Une instance de classe http.client.HTTPMessage
contient les en-têtes d'une réponse HTTP. Elle est implémentée en utilisant la classe email.message.Message
.