http.client — HTTP protocol client

Вихідний код: 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.

Дивись також

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

Примітка

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

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

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 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 not longer supported.

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

class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=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.6: key_file and cert_file are deprecated in favor of context. Please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system’s trusted CA certificates for you.

The check_hostname parameter is also deprecated; the ssl.SSLContext.check_hostname attribute of context should be used instead.

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(), коли спроба прочитати відповідь не призводить до зчитування даних із з’єднання, що вказує на те, що віддалена сторона закрила з’єднання.

Нове в версії 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 selector url.

Якщо вказано 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.

Якщо 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, тіло буде закодовано фрагментами.

Примітка

До протоколу 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, які створюються.

Нове в версії 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.

Наприклад, щоб тунелювати через проксі-сервер 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")

Нове в версії 3.2.

HTTPConnection.connect()

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

HTTPConnection.close()

Закрийте підключення до сервера.

HTTPConnection.blocksize

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

Нове в версії 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: Chunked encoding support. The encode_chunked parameter was added.

HTTPConnection.send(data)

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

Об’єкти HTTPResponse

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

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

HTTPResponse.read([amt])

Читає та повертає тіло відповіді або до наступних байтів amt.

HTTPResponse.readinto(b)

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

Нове в версії 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.getstatus()

Застаріло починаючи з версії 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 shows how to POST requests:

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

Об’єкти HTTPMessage

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