Python requests 使い方 まとめ



Pythonの中でもぶっちぎりNo1レベルでヘビーユースな外部モジュールrequestsについての便利さをひたすらまとめていきます。

requests 概要

簡単に言うとPythonで行うHTTPリクエストを簡単に手軽にしてくれる神ライブラリです。

言語を跨いだHTTPインターフェイスのディファクトスタンダードといえばCURLコマンドが非常に有名ですが、ことPythonにおいてはCURLの出番はありません。

requestsが優秀すぎるためです。(CURLも一応あります。)

requests 使い方

パッケージ管理モジュールで一発でインストールできます。

pip以外でやってみた事はないんですが、多分condaとかeasy install とかでも普通に入ると思います。

スクリプト内で利用する際はimportする必要があります。

requestsの基本メソッド

requestsの基本メソッドはHTTPリクエストのメソッドと同じ名称なので非常に覚えやすいです。

以下で一挙に紹介します。

requests.get

HTTPで一番利用頻度の高いGETメソッドは、requests.get として要求します。

第一引数はアクセス先のURI、第二引数以降はキーワード引数で各種パラメータを受け付けます。

これらの挙動は各種メソッドに共通します。

params引数

getメソッドに限らず、クエリストリングをキーワード引数「params」として渡すことが出来ます。

pythonの辞書型で引きた渡すとrequestsが自動的にURLエンコードしてくれます。

requests.post

HTTPリクエストの中でgetの次に使用頻度が高いPOSTもそのまま、requests.postとして要求します。

data引数

基本的にpostメソッドが必要になる展開では、URL単体でリクエストすることは稀で、実用上はリクエストボディを送信するパターンが大半かと思われますが、リクエストボディはキーワード引数「data」として引き渡します。

requests.put

このあたりから利用頻度はぐっと減りますが、restfulなweb apiなどでは使う可能性のあるメソッドです。

POSTがリソースの作成を担当するというのが定義上ではされていますが、PUTはリソースの作成に加えて、「置き換え」を担当するメソッドです。

requests.delete

DELETEは見たまんまリソースの削除に使われるメソッドです。

このほかHTTPのHEAD、PATCHやOPTIONSに対応するメソッドもそのままの名前のメソッドして実装されています。

requests 各種メソッドに渡せるキーワード引数

上でも少し解説してますが、requestsではあらゆるHTTPリクエストを簡単に表現できるように各種メソッドにキーワード引数で必要な情報を渡すことが出来ます。

基本的に key / value の構造になっているデータはpythonの辞書型で引き渡すと、requestsが内部でよしなに変換してくれるというのが非常に便利な部分です。

引数:headers

この引数に辞書を渡すことによって、HTTPのリクエストヘッダを書き換えることが可能です。

大抵のリクエストヘッダ情報はrequestsが良しなに書き換えてくれるのですので、特別操作する必要がある項目自体は意外と少ないのですが、よくある書き換えポイントとしてはオーソライゼンーションヘッダや、ユーザーエージェントの書き換えですね。

ちなみに、ディフォルトの状態だとユーザーエージェントは「python-requests/2.○○.0」となっており、スクリプトアクセスであることがサーバー側にまるわかりですので、対策をしてるサイトにアクセスするとUA偽装なしの場合は簡単に弾かれます。

引数:params

上の項で少し解説しましたが、params引数に辞書を渡すと、URLのクエリストリングとして付加したURLにアクセスします。

引数:data

こちらも上の項で少し解説しましたが、リクエストボディとして投げる文字列をdata引数として引き渡すことが出来ます。

辞書として渡す

data引数に辞書型を引き渡した場合、モジュール内で自動的にURLエンドーディングされたクエリストリング型の文字列に変換されリクエストボディとして送信されます。

上記の例では実際に送信されるリクエストボディは以下の様な文字列です。

data引数に辞書を渡した場合は、リクエストヘッダにContent-Typeが application/x-www-form-urlencoded として自動的に付加されます。

文字列として渡す

data引数に辞書を渡さずに文字列型を渡すとその文字列がそのまま渡されます。

リクエストボディをjsonやxml、その他の文字列型で投げたい場合はそのまま標準のstr型テキストとしてdata引数に渡せばOKです。

ただし、辞書型で引き渡した情報と違い文字列型で引き渡した場合はContent-Typeが自動付与されませんので、必要な場合は自分で、リクエストヘッダを書き換える必要があります。

引数:json

リクエストボディをjsonで表現したい場合は、上で挙げたdata引数よりも、こちらのjson引数として取り扱う方が便利です。

引き渡し方は辞書型で、requestsが自動的にjson型の文字列に変換した文字列をリクエストボディとして送信してくれます。

この場合、data引数にjson文字列を引き渡した場合と異なり、自動的にContent-Typeがapplication/jsonとして書き換えらえ送信されます。

引数:files

バイナリータイプのデータを送信することが出来ます。

マルチパートエンコードというタイプの送信手段になります。

受け入れ先のURLがファイル名やmimetype等を受け付ける場合、またはそれらが必須の要素である場合がありますが、辞書のvalue側をタプルで括って、送信するファイルの複数の属性を受け渡すことが可能です。

引数:timeout

リクエストのタイムアウトを設定できます。

requests内のタイムアウトは内部的に二種類存在していて、これらtimeoutの引数で受け渡すことが出来る数値の範疇に、データのダウンロードなど実際の通信本体に要した時間は含まれません。

実際通信の本体部分が開始される前段階をそれぞれ段階ごとに分けてタイムアウト設定することが可能です。

connect timeout

通信相手のサーバーとの通信を確立するまでの時間のタイムアウトコントロールです。

相手方のサーバーがダウンしているなど、「そもそも通信を開始できない状況」であればこちらのconnect timeoutが発生します。

read timeout

通信が確立された後、相手方のサーバーが応答の最後のバイトを送出してからのタイムアウトです。

通信が終了しておらず、相手方サーバーからの応答がtimeout引数で設定した時間以上空白となった場合、こちらのread timeoutが発生します。

こちらはダウンしているとかではなく、過負荷など処理に時間がかかって応答できない状態である場合に発生するものです。

timeoutの引き渡し方

上記二種類のタイムアウトをそれぞれ整数型(int)、または浮動小数型(float)で引き渡すことが出来ます。

connect timeout、read timeoutをそれぞれ別々の数値で指定したい場合はタプルで引き渡すことが出来ます。

タプル内の第一要素がconnect timeout、第二要素がread timeoutとして取り扱われます。

requestsはディフォルトではタイムアウトしない設定になっているため、GUIを使った通信を行うアプリケーションなどを製作している場合、通信相手方からのレスポンスを待ち続けて、GUIがフリーズするなんてこともよく起きますので、可能な限りtimeoutを設定してエラーハンドリングしておくのがベターです。

引数:stream

レスポンス本体をイテレータの形式で取得することが可能になります。

これにより応答が完全に完了する前からデータの読み取りを開始することが可能になります。

指定方法はTrueのみ。(ディフォルトがFalseなので意味なし)

引数:allow_redirects

通常requestsのレスポンスは最終的な結果が返ってきますので、リダイレクトのあるURLにアクセスした場合は最終着地した200番台のレスポンスオブジェクトが本体として返されます。

レスポンスオブジェクトのhistory属性としてリダイレクトの履歴をたどることは可能ですが、そもそもリダイレクトを許容しない設定にすることも可能です。

指定方法はFalseのみ。(ディフォルトがTrueなので意味なし)

これにより300番台のレスポンスを直接取得することが出来ます。

requests Responseオブジェクトの操作

属性:url

実際にアクセスした先のurl(クエリストリングを含む)を返却するアトリビュートです。

属性:text

HTTPリクエストのレスポンス本文をテキストの形式で返します。

属性:content

HTTPリクエストのレスポンス本文をbytes(バイナリ)の形式で返します。

属性:headers

レスポンスヘッダを辞書型で返却するアトリビュート。

リクエスト時のヘッダではないので注意。

属性:encoding

requestsがレスポンスを解析したencoding形式を返却するアトリビュート。

属性:history

アクセスしたページにリダイレクトが設定されていた場合、その遷移の履歴がリストとしてhistory属性に格納されます。

属性:status_code

レスポンスのステータスコードがint型で返却されます。

属性:request

実際に送信したリクエストの各種パラメータがPreparedRequestオブジェクトとして返却されます。

PreparedRequestの__dict__アトリビュートにアクセスすると辞書型で実際に要求したリクエストを確認することが出来ます。
デバッグ時などに便利です。

属性:elapsed

要求を完了するまでにかかった時間をビルトインのdatetime型の派生datetime.timedelta型として返却します。

属性:reason

リクエストの最終的なレスポンスの状態を英文の文字列として返却します。

200系の返却なら'OK'、400系、500系ならなぜダメだったのかのエラーメッセージの様なものが返ってきます。

属性:cookies

そのURLにアクセスすることによって付与されたCookieをRequestsCookieJarオブジェクトとして返却します。

属性:raw

requestsの正体はurllib3のラッパーモジュールの様なものなのですが、rawアトリビュートのurallib3で受け取った生のレスポンスオブジェクトにアクセスすることが出来ます。

実はほぼ使ったことないですし、使い処もイマイチ思い浮かびません。

メソッド:json()

HTTPリクエストのレスポンスボディがJSON形式のテキストデータであった場合、pythonのビルトインの辞書型(dict)に変換して返却します。

requestsが内部的にjson.loads(res.text)をしてくれているイメージですね。

Web APIを利用する場合は、最近ではJSON形式での返却はディファクトスタンダードになりつつありますので、非常によく使うメソッドです。

レスポンスボディがJSON形式のテキストデータでない場合(例えばHTML形式など)、ビルトインのjson.loads()が失敗した時と同じJSONDecodeErrorが発生します。

メソッド:raise_for_status()

レスポンスのステータスコードが200系の場合は、特に何も起きず、200以外のエラーステータスコードだった場合は例外を発生させます。

メソッド:iter_content()

レスポンスボディにイテレータアクセスするためのメソッド。

上で解説しているstream引数にTrueを与えて要求したリエクエストのレスポンスオブジェクトに対して有効。