# `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, max_response_headers=None)

  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. The optional max_response_headers parameter sets the maximum number of allowed response headers to help prevent denial-of-service attacks, otherwise the default value (100) is used.

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

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

  Змінено в версії 3.15: max_response_headers parameter was added.

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

  Підклас `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.

  Змінено в версії 3.15: max_response_headers parameter was added.

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 5322 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` або байт-подібний об’єкт, який також не є файлом, як представлення тіла.

  Примітка

  Note that you must have read the whole response or call `close()` if `getresponse()` raised an non-`ConnectionError` exception before you can send a new request to the server.

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

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

HTTPConnection.getresponse()

  Має викликатися після надсилання запиту, щоб отримати відповідь від сервера. Повертає екземпляр `HTTPResponse`.

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

  Note that this does not apply to `OSError`s raised by the underlying socket. Instead the caller is responsible to call `close()` on the existing connection.

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.

HTTPConnection.max_response_headers

  The maximum number of allowed response headers to help prevent denial-of-service attacks. By default, the maximum number of allowed headers is set to 100.

  Added in version 3.15.

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