`http.client` — HTTP protocol client¶

Вихідний код: Lib/http/client.py

This module defines classes that 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.

Дивись також

The Requests package is recommended for a higher-level HTTP client interface.

Примітка

Підтримка HTTPS доступна, лише якщо Python було скомпільовано з підтримкою SSL (через модуль ssl).

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

Модуль надає такі класи:

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 by 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 form host: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.

Наприклад, усі наведені нижче виклики створюють екземпляри, які підключаються до сервера на одному хості та порту:

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

Змінено в версії 3.2: вихідна_адреса була додана.

Змінено в версії 3.4: The strict parameter was removed. HTTP 0.9-style «Simple Responses» are no longer supported.

Змінено в версії 3.7: Додано параметр blocksize.

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

Підклас HTTPConnection, який використовує SSL для зв’язку із захищеними серверами. Стандартний порт 443. Якщо вказано контекст, це має бути екземпляр ssl.SSLContext, який описує різні параметри SSL.

Будь ласка, прочитайте Міркування безпеки, щоб дізнатися більше про найкращі практики.

Змінено в версії 3.2: Додано source_address, context і check_hostname.

Змінено в версії 3.2: This class now supports HTTPS virtual hosts if possible (that is, if ssl.HAS_SNI is true).

Змінено в версії 3.4: Параметр strict видалено. «Прості відповіді» у стилі HTTP 0.9 більше не підтримуються.

Змінено в версії 3.4.3: This class now performs all the necessary certificate and hostname checks by default. To revert to the previous, unverified, behavior ssl._create_unverified_context() can be passed to the context parameter.

Змінено в версії 3.8: Цей клас тепер увімкне TLS 1.3 ssl.SSLContext.post_handshake_auth для контексту за замовчуванням або коли cert_file передається з настроюваним контекстом.

Змінено в версії 3.10: This class now sends an ALPN extension with protocol indicator http/1.1 when no context is given. Custom context should set ALPN protocols with set_alpn_protocols().

Змінено в версії 3.12: The deprecated key_file, cert_file and check_hostname parameters have been removed.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)¶: Клас, екземпляри якого повертаються після успішного підключення. Не створюється безпосередньо користувачем.

Змінено в версії 3.4: Параметр strict видалено. Стиль HTTP 0.9 «Прості відповіді» більше не підтримується.

Цей модуль забезпечує наступні функції:

http.client.parse_headers(fp)¶

Parse the headers from a file pointer fp representing a HTTP request/response. The file has to be a BufferedIOBase reader (i.e. not text) and must provide a valid RFC 2822 style header.

Ця функція повертає екземпляр http.client.HTTPMessage, який містить поля заголовка, але не містить корисного навантаження (те саме, що HTTPResponse.msg і http.server.BaseHTTPRequestHandler.headers ). Після повернення покажчик файлу fp готовий читати тіло HTTP.

Примітка

parse_headers() не аналізує початковий рядок HTTP-повідомлення; він аналізує лише рядки Назва: значення. Файл має бути готовий до читання цих рядків полів, тому перший рядок уже має бути використано перед викликом функції.

Наступні винятки підняті відповідно до:

exception http.client.HTTPException¶: Базовий клас інших винятків у цьому модулі. Це підклас Exception.

exception http.client.NotConnected¶: Підклас HTTPException.

exception http.client.InvalidURL¶: Підклас HTTPException, викликаний, якщо задано порт, який є нечисловим або порожнім.

exception http.client.UnknownProtocol¶: Підклас HTTPException.

exception http.client.UnknownTransferEncoding¶: Підклас HTTPException.

exception http.client.UnimplementedFileMode¶: Підклас HTTPException.

exception http.client.IncompleteRead¶: Підклас HTTPException.

exception http.client.ImproperConnectionState¶: Підклас HTTPException.

exception http.client.CannotSendRequest¶: Підклас ImproperConnectionState.

exception http.client.CannotSendHeader¶: Підклас ImproperConnectionState.

exception http.client.ResponseNotReady¶: Підклас ImproperConnectionState.

exception http.client.BadStatusLine¶: Підклас HTTPException. Викликається, якщо сервер відповідає кодом статусу HTTP, який ми не розуміємо.

exception http.client.LineTooLong¶: Підклас HTTPException. Викликається, якщо в протоколі HTTP від сервера отримано надто довгий рядок.

exception http.client.RemoteDisconnected¶: Підклас ConnectionResetError і BadStatusLine. Викликається HTTPConnection.getresponse(), коли спроба прочитати відповідь не призводить до зчитування даних із з’єднання, що вказує на те, що віддалена сторона закрила з’єднання.

Added in version 3.5: Раніше було піднято BadStatusLine('').

Константи, визначені в цьому модулі:

http.client.HTTP_PORT¶: Порт за замовчуванням для протоколу HTTP (завжди 80).

http.client.HTTPS_PORT¶: Порт за замовчуванням для протоколу HTTPS (завжди 443).

http.client.responses¶

Цей словник відображає коди статусу HTTP 1.1 на імена W3C.

Приклад: http.client.responses[http.client.NOT_FOUND] означає 'Не знайдено'.

Перегляньте Коди стану HTTP список кодів стану HTTP, які доступні в цьому модулі як константи.

Об’єкти HTTPConnection¶

Екземпляри HTTPConnection мають такі методи:

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

This will send a request to the server using the HTTP request method method and the request URI url. The provided url must be an absolute path to conform with RFC 2616 §5.1.2 (unless connecting to an HTTP proxy server or using the OPTIONS or CONNECT methods).

Якщо вказано body, зазначені дані надсилаються після завершення заголовків. Це може бути str, bytes-like object, відкритий file object або ітерація bytes. Якщо body є рядком, він кодується як ISO-8859-1, стандартний для HTTP. Якщо це байтоподібний об’єкт, байти надсилаються як є. Якщо це file object, вміст файлу надсилається; цей файловий об’єкт має підтримувати принаймні метод read(). Якщо об’єкт файлу є екземпляром io.TextIOBase, дані, повернуті методом read(), будуть закодовані як ISO-8859-1, інакше дані, повернуті read() надсилається як є. Якщо body є iterable, елементи iterable надсилаються як є, доки iterable не буде вичерпано.

The headers argument should be a mapping of extra HTTP headers to send with the request. A Host header must be provided to conform with RFC 2616 §5.1.2 (unless connecting to an HTTP proxy server or using the OPTIONS or CONNECT methods).

Якщо headers не містить ані Content-Length, ані Transfer-Encoding, але є тіло запиту, одне з цих полів заголовка буде додано автоматично. Якщо body має значення None, заголовок Content-Length встановлюється на 0 для методів, які очікують тіла (PUT, POST і PATCH). . Якщо body є рядком або байтоподібним об’єктом, який також не є файлом, заголовок Content-Length встановлюється на його довжину. Будь-який інший тип body (файли та ітерації загалом) буде закодовано фрагментами, а заголовок Transfer-Encoding буде автоматично встановлено замість Content-Length.

Аргумент encode_chunked доречний, лише якщо Transfer-Encoding указано в headers. Якщо encode_chunked має значення False, об’єкт HTTPConnection припускає, що все кодування обробляється кодом виклику. Якщо значення True, тіло буде закодовано фрагментами.

For example, to perform a GET request to https://docs.python.org/3/:

>>> import http.client
>>> host = "docs.python.org"
>>> conn = http.client.HTTPSConnection(host)
>>> conn.request("GET", "/3/", headers={"Host": host})
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200 OK

Примітка

До протоколу HTTP версії 1.1 додано кодування передачі фрагментами. Якщо не відомо, що HTTP-сервер обробляє HTTP 1.1, абонент повинен або вказати Content-Length, або повинен передати str або байт-подібний об’єкт, який також не є файлом, як представлення тіла.

Змінено в версії 3.2: body тепер може бути ітерованим.

Змінено в версії 3.6: Якщо ані Content-Length, ані Transfer-Encoding не встановлено в headers, файл і ітераційні body об’єкти тепер закодовані фрагментами. Додано аргумент encode_chunked. Не робиться жодних спроб визначити довжину вмісту для файлових об’єктів.

HTTPConnection.getresponse()¶: Має викликатися після надсилання запиту, щоб отримати відповідь від сервера. Повертає екземпляр HTTPResponse.

Примітка

Зверніть увагу, що ви повинні прочитати всю відповідь, перш ніж ви зможете надіслати новий запит на сервер.

Змінено в версії 3.5: Якщо виникає ConnectionError або підклас, об’єкт HTTPConnection буде готовий до повторного підключення, коли буде надіслано новий запит.

HTTPConnection.set_debuglevel(level)¶: Встановіть рівень налагодження. Рівень налагодження за замовчуванням 0, тобто вихідні дані налагодження не друкуються. Будь-яке значення, яке перевищує 0, призведе до того, що весь поточний визначений вихід налагодження буде надруковано в stdout. debuglevel передається будь-яким новим об’єктам HTTPResponse, які створюються.

Added in version 3.1.

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

Встановіть хост і порт для тунелювання підключення HTTP. Це дозволяє запускати підключення через проксі-сервер.

The host and port arguments specify the endpoint of the tunneled connection (i.e. the address included in the CONNECT request, not the address of the proxy server).

The headers argument should be a mapping of extra HTTP headers to send with the CONNECT request.

As HTTP/1.1 is used for HTTP CONNECT tunnelling request, as per the RFC, a HTTP Host: header must be provided, matching the authority-form of the request target provided as the destination for the CONNECT request. If a HTTP Host: header is not provided via the headers argument, one is generated and transmitted automatically.

Наприклад, щоб тунелювати через проксі-сервер HTTPS, який працює локально на порту 8080, ми повинні передати адресу проксі-сервера до конструктора HTTPSConnection, а адресу хоста, до якого ми хочемо отримати доступ, до set_tunnel() метод:

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

Added in version 3.2.

Змінено в версії 3.12: HTTP CONNECT tunnelling requests use protocol HTTP/1.1, upgraded from protocol HTTP/1.0. Host: HTTP headers are mandatory for HTTP/1.1, so one will be automatically generated and transmitted if not provided in the headers argument.

HTTPConnection.get_proxy_response_headers()¶

Returns a dictionary with the headers of the response received from the proxy server to the CONNECT request.

If the CONNECT request was not sent, the method returns None.

Added in version 3.12.

HTTPConnection.connect()¶

Підключіться до сервера, указаного під час створення об’єкта. За замовчуванням це викликається автоматично під час надсилання запиту, якщо клієнт ще не має підключення.

Викликає подію аудиту http.client.connect з аргументами self, host, port.

HTTPConnection.close()¶: Закрийте підключення до сервера.

HTTPConnection.blocksize¶: Розмір буфера в байтах для надсилання тіла повідомлення, схожого на файл.

Added in version 3.7.

As an alternative to using the request() method described above, you can also send your request step by step, by using the four functions below.

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)¶: Це має бути перший виклик після підключення до сервера. Він надсилає на сервер рядок, що складається з рядка method, рядка url і версії HTTP (HTTP/1.1). Щоб вимкнути автоматичне надсилання заголовків Host: або Accept-Encoding: (наприклад, щоб прийняти додаткове кодування вмісту), укажіть skip_host або skip_accept_encoding зі значеннями, відмінними від False.

HTTPConnection.putheader(header, argument[, ...])¶: Надішліть на сервер заголовок у стилі RFC 822. Він надсилає на сервер рядок, що складається із заголовка, двокрапки, пробілу та першого аргументу. Якщо задано більше аргументів, надсилаються рядки продовження, кожен з яких складається з табуляції та аргументу.

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

Надішліть порожній рядок на сервер, сигналізуючи про кінець заголовків. Додатковий аргумент message_body можна використовувати для передачі тіла повідомлення, пов’язаного із запитом.

Якщо encode_chunked має значення True, результат кожної ітерації message_body буде закодовано фрагментами, як зазначено в RFC 7230, розділ 3.3.1. Спосіб кодування даних залежить від типу message_body. Якщо message_body реалізує інтерфейс буфера, кодування призведе до єдиного блоку. Якщо message_body є collections.abc.Iterable, кожна ітерація message_body призведе до блоку. Якщо message_body є об’єктом file object, кожен виклик .read() призведе до блоку. Метод автоматично сигналізує про кінець даних, закодованих фрагментами, відразу після message_body.

Примітка

Через специфікацію фрагментованого кодування порожні фрагменти, отримані тілом ітератора, ігноруватимуться кодувальником фрагментів. Це робиться для того, щоб уникнути передчасного припинення читання запиту цільовим сервером через неправильне кодування.

Змінено в версії 3.6: Added chunked encoding support and the encode_chunked parameter.

HTTPConnection.send(data)¶

Надіслати дані на сервер. Це слід використовувати безпосередньо лише після виклику методу endheaders() і до виклику getresponse().

Викликає подію аудиту http.client.send з аргументами self, data.

Об’єкти HTTPResponse¶

Екземпляр HTTPResponse обгортає відповідь HTTP від сервера. Він забезпечує доступ до заголовків запиту та тіла сутності. Відповідь є повторюваним об’єктом і може використовуватися в операторі with.

Змінено в версії 3.5: Інтерфейс io.BufferedIOBase тепер реалізовано, і всі його операції читання підтримуються.

HTTPResponse.read([amt])¶: Читає та повертає тіло відповіді або до наступних байтів amt.

HTTPResponse.readinto(b)¶: Зчитує до наступного len(b) байт тіла відповіді в буфер b. Повертає кількість прочитаних байтів.

Added in 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()¶: Повертає список кортежів (заголовок, значення).

HTTPResponse.fileno()¶: Повертає fileno основного сокета.

HTTPResponse.msg¶: Екземпляр http.client.HTTPMessage, що містить заголовки відповідей. http.client.HTTPMessage є підкласом email.message.Message.

HTTPResponse.version¶: Версія протоколу HTTP, яку використовує сервер. 10 для HTTP/1.0, 11 для HTTP/1.1.

HTTPResponse.url¶: URL-адреса отриманого ресурсу, яка зазвичай використовується для визначення того, чи було переспрямовано.

HTTPResponse.headers¶: Заголовки відповіді у формі екземпляра email.message.EmailMessage.

HTTPResponse.status¶: Код статусу, повернутий сервером.

HTTPResponse.reason¶: Фраза причини, повернута сервером.

HTTPResponse.debuglevel¶: Гачок для налагодження. Якщо debuglevel більше нуля, повідомлення буде надруковано в стандартний вихід під час читання та аналізу відповіді.

HTTPResponse.closed¶: Значить True, якщо потік закрито.

HTTPResponse.geturl()¶: Застаріло починаючи з версії 3.9: Застаріло на користь url.

HTTPResponse.info()¶: Застаріло починаючи з версії 3.9: Застаріло на користь headers.

HTTPResponse.getcode()¶: Застаріло починаючи з версії 3.9: Застаріло на користь status.

Приклади¶

Ось приклад сеансу, який використовує метод 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()

Ось приклад сеансу, який використовує метод HEAD. Зауважте, що метод HEAD ніколи не повертає жодних даних.

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

Here is an example session that uses the POST method:

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

Client side HTTP PUT requests are very similar to POST requests. The difference lies only on the server side where HTTP servers will allow resources to be created via PUT requests. 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 uses the PUT method:

>>> # This creates an HTTP request
>>> # 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

Об’єкти HTTPMessage¶

class http.client.HTTPMessage(email.message.Message)¶

Екземпляр http.client.HTTPMessage містить заголовки відповіді HTTP. Це реалізовано за допомогою класу email.message.Message.

`http.client` — HTTP protocol client¶

Об’єкти HTTPConnection¶

Об’єкти HTTPResponse¶

Приклади¶

Об’єкти HTTPMessage¶

Table of Contents

Попередній розділ

Наступна тема

This page

http.client — HTTP protocol client¶

Об’єкти HTTPConnection¶

Об’єкти HTTPResponse¶

Приклади¶

Об’єкти HTTPMessage¶

`http.client` — HTTP protocol client¶