Бібліотека Requests швидкий старт - Програмування Linux Windows

Чи готові почати? Бібліотека Requests: швидкий старт Ця сторінка дає достатньо уявлення про те, як розпочати роботу з Requests.

По-перше, переконайтеся, що:

Requests встановлено
Requests оновлено

Почнемо з кількох простих прикладів.

Створення запиту

Створення запиту за допомогою Requests – це дуже просто.

Почніть із імпорту модуля Requests:

Тепер спробуємо отримати веб-сторінку. Наприклад, отримаємо публічний тайм-лайн GitHub.

Тепер ми маємо об'єкт Response з ім'ям r. Ми можемо отримати всю необхідну інформацію з цього об'єкту.

Простий API Requests означає, що всі форми запитів HTTP є очевидними. Наприклад, ось як ви можете зробити HTTP POST запит:

Круто? А як щодо інших типів HTTP запиту: PUT, DELETE, HEAD та OPTIONS? Їх виконати так само просто:

Це вже добре. Навіть чудово. Але це далеко не все, що може робити Requests.

Надсилання параметрів в URL

Ви часто бажаєте надіслати якісь дані в рядку запиту URL. Якщо ви будуєте URL вручну, ці дані будуть представлені в ньому у вигляді пар ключ-значення після знака питання. Наприклад, httpbin.org/get?key=val. Requests дозволяє передати ці аргументи як словник, використовуючи аргумент params. Як приклад, якщо ви хочете передати key1=value1 та key2=value2 ресурсу httpbin.org/get, ви повинні використовувати наступний код:

Ви можете бачити, що URL було закодовано правильно:

Зауважимо, що будь-який ключ словника, значення якого None, не буде додано до рядка запиту URL-адреси.

Вміст відповіді

Requests автоматично декодуватиме вміст відповіді сервера. БільшістьUnicode кодування без проблем декодуються.

Коли ви запитуєте, Requests робить припущення про кодування, засноване на заголовках HTTP. Кодування тексту, вгадане Requests, використовується при зверненні до r.text. Ви можете дізнатися, яке кодування використовує Requests, і змінити його, скориставшись властивістю r.encoding:

Якщо ви зміните кодування, Requests буде використовувати нове значення r.encoding щоразу, коли ви будете використовувати r.text. Ви можете зробити це в будь-якій ситуації, де потрібна спеціалізована логіка роботи з кодуванням вмісту відповіді. Наприклад, HTML і XML мають можливість задавати кодування прямо в тілі документа. У таких ситуаціях ви повинні використовувати r.content, щоб знайти кодування, а потім встановити r.encoding. Це дозволить вам використовувати r.text з правильним кодуванням.

Requests може також використовувати кодування користувача у разі, якщо ви їх потребуєте. Якщо ви створили своє власне кодування і зареєстрували його в модулі codecs, ви можете просто використовувати назву кодека як значення r.encoding, і Requests буде працювати з цим кодуванням для вас.

Бінарний вміст відповіді

Ви також можете отримати доступ до тіла відповіді у вигляді байтів для нетекстових запитів:

Передача зі стисненням gzip та deflate автоматично декодується.

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

JSON вміст відповіді

З бібліотекою Requests також поставляється вбудований JSON декодер на випадок, якщо ви маєте справу з даними у форматі JSON:

Необроблений вміст відповіді

В окремих випадках, коли ви хочете отримати доступ до сирої відповіді сервера на рівнісокету, ви можете звернутися до r.raw. Якщо ви хочете зробити це, переконайтеся, що ви встановили stream=True у вашому першому запиті. Після цього ви вже можете зробити наступне:

Тепер ви можете використовувати подібний код як шаблон, щоб зберегти потік, що отримується у файл:

Користувальницькі HTTP заголовки

Якщо ви хочете додати HTTP-заголовки до запиту, просто передайте відповідний словник у параметрі headers.

Наприклад, ми не вказали заголовок content-type у попередньому прикладі:

Більш складні запити POST

Часто ви хочете послати деякі form-encoded дані також як це робиться у HTML формі. Щоб це зробити, просто передайте відповідний словник у аргументі data. Ваш словник даних у такому разі буде автоматично закодований як HTML форма, коли буде зроблено запит:

Але є багато випадків, коли ви можете захотіти надіслати дані, які не закодовані методом form-encoded. Якщо ви передаєте в запит рядок замість словника, дані будуть надіслані у незмінному вигляді.

Наприклад, API v3 GitHub приймає JSON-закодовані POST/PATCH дані:

Як надіслати Multipart-Encoded файл

Requests дозволяє легко надіслати на сервер Multipart-Encoded файли:

Ви можете встановити ім'я файлу, content-type та заголовки у явному вигляді:

Якщо ви хочете, ви можете надіслати рядки, які будуть прийняті у вигляді файлів:

Якщо ви надсилаєте дуже великий файл як multipart/form-data, ви можете захотіти надіслати запит потоком. За промовчанням requests не підтримує цього, але є окремий пакет, який це робить – requests-toolbelt. Ознайомтеся з документацією Toolbelt.

Щоб надіслати кілька файлів в одному запиті, зверніться до додаткової документації.

Коди стану відповіді

Ми можемо перевірити код стану відповіді:

Для зручності Requests також поставляється із вбудованим об'єктом підстановок кодів стану:

Якщо ми зробили поганий запит (помилка 4XX клієнта або помилка 5XX відповіді сервера), ми можемо порушити виняток за допомогою Response.raise_for_status() :

Але якщо status_code для г виявилося 200, то коли ми викликаємо raise_for_status() ми отримуємо:

Це означає, що все гаразд.

Заголовки відповідей

Ми можемо переглядати заголовки відповіді сервера за допомогою словника Python:

Однак це особливий словник: він зроблений спеціально для HTTP заголовків. Відповідно до RFC 7230, імена заголовків HTTP нечутливі до регістру.

Таким чином, ми можемо отримати доступ до заголовків з капіталізацією або без, якщо захочемо:

Якщо відповідь містить cookie, ви можете швидко отримати доступ до них:

Для надсилання власних cookie на сервер ви можете використовувати параметр cookies:

Редиректи та історія

За замовчуванням Requests буде виконувати редиректи для всіх дієслів HTTP, крім HEAD.

Ми можемо використовувати властивість історії об'єкта Response, щоб відстежувати редиректи.

Список Response.history містить об'єкти Response, створені під час виконання запиту. Список сортується від ранніх до пізніших відповідей.

Наприклад, GitHub перенаправляє всі HTTP запити на HTTPS:

Якщо ви використовуєте GET, OPTIONS, POST, PUT, PATCH або DELETE, ви можете вимкнути обробку редиректів за допомогою allow_redirects:

Якщо ви використовуєте HEAD, ви можете увімкнути обробку редиректів:

Ви можете сказати Requests припинити очікування відповіді після певної кількості секунд за допомогоюпараметра timeout:

Примітка: timeout це не обмеження часу повного завантаження відповіді. Виняток виникає, якщо сервер не дав відповідь за timeout секунд (точніше, якщо жодного байта не було отримано від основного сокету за timeout секунд).

Помилки та винятки

У разі несправностей в мережі (наприклад, відмови DNS, відмовився з'єднання і т.д.), Requests порушить виключення ConnectionError.

У рідкісному випадку неправильної HTTP відповіді, Requests порушить виняток HTTPError.

Якщо перевищено час очікування на відповідь, збуджується виключення Timeout.

Якщо запит перевищує задане значення максимальної кількості редиректів, збуджується виключення TooManyRedirects.

Усі винятки, які збуджує безпосередньо Requests, успадковані від requests.exceptions.RequestException.

Чи готові для більшого?

Ознайомтеся із додатковим розділом документації.