Ejemplo de http.client de Python

Código fuente:Lib / http / client.py

Este módulo define clases que implementan el lado del cliente de los protocolos HTTP y HTTPS. Normalmente no se utiliza directamente: el módulo urllib.request lo usa para manejar URL que usan HTTP y HTTPS.

Ver también

los Paquete de solicitudes se recomienda para una interfaz de cliente HTTP de nivel superior.

Nota

El soporte HTTPS solo está disponible si Python se compiló con soporte SSL (a través del ssl módulo).

El módulo proporciona las siguientes clases:

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)

Un HTTPConnection instancia representa una transacción con un servidor HTTP. Se debe crear una instancia pasándole un host y un número de puerto opcional. Si no se pasa ningún número de puerto, el puerto se extrae de la cadena de host si tiene la forma host:port, de lo contrario, se utiliza el puerto HTTP predeterminado (80). Si el opcional se acabó el tiempo se proporciona el parámetro, las operaciones de bloqueo (como los intentos de conexión) expirarán después de esa cantidad de segundos (si no se proporciona, se utiliza la configuración de tiempo de espera global predeterminada). El opcional Dirección de la fuente El parámetro puede ser una tupla de (host, puerto) para usar como dirección de origen desde la que se realiza la conexión HTTP. El opcional tamaño de bloque El parámetro establece el tamaño del búfer en bytes para enviar un cuerpo de mensaje similar a un archivo.

Por ejemplo, todas las siguientes llamadas crean instancias que se conectan al servidor en el mismo host y puerto:

>>> 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)

Modificado en la versión 3.2: Dirección de la fuente fue añadido.

Modificado en la versión 3.4: los estricto se eliminó el parámetro. Las “Respuestas simples” de estilo HTTP 0.9 ya no son compatibles.

Modificado en la versión 3.7: tamaño de bloque se agregó el parámetro.

class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)

Una subclase de HTTPConnection que utiliza SSL para la comunicación con servidores seguros. El puerto predeterminado es 443. Si contexto se especifica, debe ser un ssl.SSLContext instancia que describe las diversas opciones de SSL.

Por favor lee Consideraciones de Seguridad para obtener más información sobre las mejores prácticas.

Modificado en la versión 3.2: Dirección de la fuente, contexto y check_hostname fueron agregados.

Modificado en la versión 3.2: Esta clase ahora admite hosts virtuales HTTPS si es posible (es decir, si ssl.HAS_SNI es verdad).

Modificado en la versión 3.4: los estricto se eliminó el parámetro. Las “Respuestas simples” de estilo HTTP 0.9 ya no son compatibles.

Modificado en la versión 3.4.3: Esta clase ahora realiza todas las comprobaciones necesarias de certificados y nombres de host de forma predeterminada. Para volver al comportamiento anterior, no verificado ssl._create_unverified_context() se puede pasar al contexto parámetro.

Modificado en la versión 3.8: Esta clase ahora habilita TLS 1.3 ssl.SSLContext.post_handshake_auth por defecto contexto o cuando cert_file se pasa con una costumbre contexto.

En desuso desde la versión 3.6: archivo de clave y cert_file están en desuso a favor de contexto. Por favor use ssl.SSLContext.load_cert_chain() en su lugar, o dejar ssl.create_default_context() seleccione los certificados CA de confianza del sistema para usted.

los check_hostname el parámetro también está en desuso; los ssl.SSLContext.check_hostname atributo de contexto debe usarse en su lugar.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)

Clase cuyas instancias se devuelven tras una conexión correcta. No instanciado directamente por el usuario.

Modificado en la versión 3.4: los estricto se eliminó el parámetro. Las “Respuestas simples” de estilo HTTP 0.9 ya no son compatibles.

Este módulo proporciona la siguiente función:

http.client.parse_headers(fp)

Analizar los encabezados de un puntero de archivo fp que representa una solicitud / respuesta HTTP. El archivo debe ser un BufferedIOBase lector (es decir, no texto) y debe proporcionar un RFC 2822 encabezado de estilo.

Esta función devuelve una instancia de http.client.HTTPMessage que contiene los campos de encabezado, pero sin carga útil (lo mismo que HTTPResponse.msg y http.server.BaseHTTPRequestHandler.headers). Después de regresar, el puntero del archivo fp está listo para leer el cuerpo HTTP.

Nota

parse_headers() no analiza la línea de inicio de un mensaje HTTP; solo analiza el Name: value líneas. El archivo debe estar listo para leer estas líneas de campo, por lo que la primera línea ya debería estar consumida antes de llamar a la función.

Las siguientes excepciones se plantean según corresponda:

exception http.client.HTTPException

La clase base de las otras excepciones de este módulo. Es una subclase de Exception.

exception http.client.NotConnected

Una subclase de HTTPException.

exception http.client.InvalidURL

Una subclase de HTTPException, se genera si se proporciona un puerto y no es numérico o está vacío.

exception http.client.UnknownProtocol

Una subclase de HTTPException.

exception http.client.UnknownTransferEncoding

Una subclase de HTTPException.

exception http.client.UnimplementedFileMode

Una subclase de HTTPException.

exception http.client.IncompleteRead

Una subclase de HTTPException.

exception http.client.ImproperConnectionState

Una subclase de HTTPException.

exception http.client.CannotSendRequest

Una subclase de ImproperConnectionState.

exception http.client.CannotSendHeader

Una subclase de ImproperConnectionState.

exception http.client.ResponseNotReady

Una subclase de ImproperConnectionState.

exception http.client.BadStatusLine

Una subclase de HTTPException. Se genera si un servidor responde con un código de estado HTTP que no entendemos.

exception http.client.LineTooLong

Una subclase de HTTPException. Se genera si se recibe una línea excesivamente larga en el protocolo HTTP desde el servidor.

exception http.client.RemoteDisconnected

Una subclase de ConnectionResetError y BadStatusLine. Criado por HTTPConnection.getresponse() cuando el intento de leer la respuesta da como resultado que no se lean datos de la conexión, lo que indica que el extremo remoto ha cerrado la conexión.

Nuevo en la versión 3.5: Previamente, BadStatusLine('') se elevó.

Las constantes definidas en este módulo son:

http.client.HTTP_PORT

El puerto predeterminado para el protocolo HTTP (siempre 80).

http.client.HTTPS_PORT

El puerto predeterminado para el protocolo HTTPS (siempre 443).

http.client.responses

Este diccionario asigna los códigos de estado HTTP 1.1 a los nombres del W3C.

Ejemplo: http.client.responses[http.client.NOT_FOUND] es 'Not Found'.

Ver Códigos de estado HTTP para obtener una lista de los códigos de estado HTTP que están disponibles en este módulo como constantes.

Objetos HTTPConnection

HTTPConnection instancias tienen los siguientes métodos:

HTTPConnection.request(method, url, body=None, headers=, *, encode_chunked=False)

Esto enviará una solicitud al servidor utilizando el método de solicitud HTTP método y el selector url.

Si cuerpo se especifica, los datos especificados se envían una vez finalizados los encabezados. Puede ser un str, a objeto similar a bytes, un abierto objeto de archivo, o un iterable de bytes. Si cuerpo es una cadena, está codificada como ISO-8859-1, el valor predeterminado para HTTP. Si es un objeto de tipo bytes, los bytes se envían tal cual. Si es un objeto de archivo, se envía el contenido del archivo; este objeto de archivo debe admitir al menos el read() método. Si el objeto de archivo es una instancia de io.TextIOBase, los datos devueltos por el read() El método se codificará como ISO-8859-1; de lo contrario, los datos devueltos por read() se envía tal cual. Si cuerpo es un iterable, los elementos del iterable se envían tal cual hasta que se agota el iterable.

los encabezados El argumento debe ser un mapeo de encabezados HTTP adicionales para enviar con la solicitud.

Si encabezados no contiene Content-Length ni Transfer-Encoding, pero hay un cuerpo de solicitud, uno de esos campos de encabezado se agregará automáticamente. Si cuerpo es None, el encabezado Content-Length se establece en 0 para métodos que esperan un cuerpo (PUT, POST, y PATCH). Si cuerpo es una cadena o un objeto de tipo bytes que no es también un expediente, el encabezado Content-Length se establece en su longitud. Cualquier otro tipo de cuerpo (archivos e iterables en general) se codificarán por fragmentos y el encabezado Transfer-Encoding se establecerá automáticamente en lugar de Content-Length.

los encode_chunked El argumento solo es relevante si Transfer-Encoding se especifica en encabezados. Si encode_chunked es False, el objeto HTTPConnection asume que toda la codificación es manejada por el código de llamada. Si esto es True, el cuerpo se codificará por fragmentos.

Nota

La codificación de transferencia fragmentada se ha agregado a la versión 1.1 del protocolo HTTP. A menos que se sepa que el servidor HTTP maneja HTTP 1.1, la persona que llama debe especificar la longitud del contenido o debe pasar un str o un objeto similar a bytes que no es también un archivo como representación del cuerpo.

Nuevo en la versión 3.2: cuerpo ahora puede ser iterable.

Modificado en la versión 3.6: Si ni Content-Length ni Transfer-Encoding están configurados en encabezados, archivo e iterable cuerpo los objetos ahora están codificados por bloques. los encode_chunked se añadió el argumento. No se intenta determinar la longitud del contenido de los objetos de archivo.

HTTPConnection.getresponse()

Se debe llamar después de enviar una solicitud para obtener la respuesta del servidor. Devuelve un HTTPResponse ejemplo.

Nota

Tenga en cuenta que debe haber leído la respuesta completa antes de poder enviar una nueva solicitud al servidor.

Modificado en la versión 3.5: Si un ConnectionError o subclase se eleva, el HTTPConnection El objeto estará listo para volver a conectarse cuando se envíe una nueva solicitud.

HTTPConnection.set_debuglevel(level)

Establezca el nivel de depuración. El nivel de depuración predeterminado es 0, lo que significa que no se imprime ninguna salida de depuración. Cualquier valor mayor que 0 hará que toda la salida de depuración definida actualmente se imprima en stdout. los debuglevel se pasa a cualquier nuevo HTTPResponse objetos que se crean.

Nuevo en la versión 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)

Configure el host y el puerto para HTTP Connect Tunneling. Esto permite ejecutar la conexión a través de un servidor proxy.

Los argumentos de host y puerto especifican el punto final de la conexión tunelizada (es decir, la dirección incluida en la solicitud CONNECT, no la dirección del servidor proxy).

El argumento de los encabezados debe ser un mapeo de extra Encabezados HTTP para enviar con la solicitud CONNECT.

Por ejemplo, para hacer un túnel a través de un servidor proxy HTTPS que se ejecuta localmente en el puerto 8080, pasaríamos la dirección del proxy al HTTPSConnection constructor, y la dirección del host al que eventualmente queremos llegar al set_tunnel() método:

>>>import http.client
>>> conn = http.client.HTTPSConnection("localhost",8080)>>> conn.set_tunnel("www.python.org")>>> conn.request("HEAD","/index.html")

Nuevo en la versión 3.2.

HTTPConnection.connect()

Conéctese al servidor especificado cuando se creó el objeto. De forma predeterminada, esto se llama automáticamente al realizar una solicitud si el cliente aún no tiene una conexión.

HTTPConnection.close()

Cierre la conexión al servidor.

HTTPConnection.blocksize

Tamaño del búfer en bytes para enviar un cuerpo de mensaje similar a un archivo.

Nuevo en la versión 3.7.

Como alternativa al uso de request() método descrito anteriormente, también puede enviar su solicitud paso a paso, utilizando las cuatro funciones a continuación.

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)

Esta debería ser la primera llamada después de que se haya realizado la conexión con el servidor. Envía una línea al servidor que consta de método cuerda, la url cadena y la versión HTTP (HTTP/1.1). Para deshabilitar el envío automático de Host: o Accept-Encoding: encabezados (por ejemplo, para aceptar codificaciones de contenido adicionales), especifique skip_host o skip_accept_encoding con valores que no sean falsos.

HTTPConnection.putheader(header, argument[, ...])

Mandar un RFC 822-encabezado de estilo al servidor. Envía una línea al servidor que consta del encabezado, dos puntos y un espacio, y el primer argumento. Si se dan más argumentos, se envían líneas de continuación, cada una de las cuales consta de una pestaña y un argumento.

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

Envíe una línea en blanco al servidor, señalando el final de los encabezados. El opcional Cuerpo del mensaje El argumento se puede utilizar para pasar un cuerpo de mensaje asociado con la solicitud.

Si encode_chunked es True, el resultado de cada iteración de Cuerpo del mensaje se codificará por fragmentos como se especifica en RFC 7230, Sección 3.3.1. La forma en que se codifican los datos depende del tipo de Cuerpo del mensaje. Si Cuerpo del mensaje implementa el interfaz de búfer la codificación dará como resultado un solo fragmento. Si Cuerpo del mensaje es un collections.abc.Iterable, cada iteración de Cuerpo del mensaje resultará en un trozo. Si Cuerpo del mensaje es un objeto de archivo, cada llamada a .read() resultará en un trozo. El método señala automáticamente el final de los datos codificados por fragmentos inmediatamente después Cuerpo del mensaje.

Nota

Debido a la especificación de codificación fragmentada, el codificador de fragmentos ignorará los fragmentos vacíos generados por un cuerpo de iterador. Esto es para evitar la terminación prematura de la lectura de la solicitud por parte del servidor de destino debido a una codificación mal formada.

Nuevo en la versión 3.6: Soporte de codificación fragmentada. los encode_chunked se agregó el parámetro.

HTTPConnection.send(data)

Envía datos al servidor. Esto debe usarse directamente solo después de la endheaders() se ha llamado al método y antes getresponse() se llama.

Objetos HTTPResponse

Un HTTPResponse instancia envuelve la respuesta HTTP del servidor. Proporciona acceso a los encabezados de la solicitud y al cuerpo de la entidad. La respuesta es un objeto iterable y se puede usar en una declaración with.

Modificado en la versión 3.5: los io.BufferedIOBase La interfaz ahora está implementada y todas sus operaciones de lectura son compatibles.

HTTPResponse.read([amt])

Lee y devuelve el cuerpo de la respuesta, o sube al siguiente amt bytes.

HTTPResponse.readinto(b)

Lee hasta los siguientes len (b) bytes del cuerpo de la respuesta en el búfer B. Devuelve el número de bytes leídos.

Nuevo en la versión 3.3.

HTTPResponse.getheader(name, default=None)

Devuelve el valor del encabezado nombre, o defecto si no hay coincidencia de encabezado nombre. Si hay más de un encabezado con el nombre nombre, devuelve todos los valores unidos por ‘,’. Si ‘predeterminado’ es cualquier iterable que no sea una sola cadena, sus elementos se devuelven de manera similar unidos por comas.

HTTPResponse.getheaders()

Devuelve una lista de tuplas (encabezado, valor).

HTTPResponse.fileno()

Devuelve el fileno del encaje subyacente.

HTTPResponse.msg

A http.client.HTTPMessage instancia que contiene los encabezados de respuesta. http.client.HTTPMessage es una subclase de email.message.Message.

HTTPResponse.version

Versión del protocolo HTTP utilizada por el servidor. 10 para HTTP / 1.0, 11 para HTTP / 1.1.

HTTPResponse.url

URL del recurso recuperado, comúnmente utilizado para determinar si se siguió una redirección.

HTTPResponse.headers

Encabezados de la respuesta en forma de email.message.EmailMessage ejemplo.

HTTPResponse.status

Código de estado devuelto por el servidor.

HTTPResponse.reason

Frase de motivo devuelta por el servidor.

HTTPResponse.debuglevel

Un gancho de depuración. Si debuglevel es mayor que cero, los mensajes se imprimirán en stdout a medida que se lea y analice la respuesta.

HTTPResponse.closed

Es True si el arroyo está cerrado.

HTTPResponse.geturl()

En desuso desde la versión 3.9: Desaprobado en favor de url.

HTTPResponse.info()

En desuso desde la versión 3.9: Desaprobado a favor de headers.

HTTPResponse.getstatus()

En desuso desde la versión 3.9: Desaprobado en favor de status.

Ejemplos de

Aquí hay una sesión de ejemplo que usa el GET método:

>>>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()

Aquí hay una sesión de ejemplo que usa el HEAD método. Tenga en cuenta que el HEAD El método nunca devuelve ningún dato.

>>>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

Aquí hay una sesión de ejemplo que muestra cómo POST peticiones:

>>>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 http://bugs.python.org/issue12524'>>> conn.close()

Lado del cliente HTTP PUT las solicitudes son muy similares a POST peticiones. La diferencia radica solo en el lado del servidor donde el servidor HTTP permitirá que los recursos se creen a través de PUT solicitud. Cabe señalar que los métodos HTTP personalizados también se manejan en urllib.request.Request estableciendo el atributo de método apropiado. Aquí hay una sesión de ejemplo que muestra cómo enviar un PUT solicitud usando 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

Objetos HTTPMessage

Un http.client.HTTPMessage La instancia contiene los encabezados de una respuesta HTTP. Se implementa utilizando el email.message.Message clase.