 |
 |
 |
Python ライブラリリファレンス |  |
 |
 |
|
|
|
Python ライブラリリファレンス | |
|
|
このモジュールはワールドワイドウェブ (World Wide Web) を介してデータを 取り寄せるための高レベルのインタフェースを提供する。特に、関数 urlopen() は組み込み関数 open() と同様に動作し、 ファイル名の代わりにファイルユニバーサルリソースロケータ (URL) を 指定することができます。いくつかの制限はあります -- URL は読み出し 専用でしか開けませんし、seek 操作を行うことはできません。
このモジュールでは、以下の public な関数を定義します。
| url[, data[, proxies]]) |
info() および geturl() メソッドを除き、 これらのメソッドはファイルオブジェクトと同じインタフェースを持って います -- このマニュアルの 3.9 セクションを 参照してください。 (ですが、このオブジェクトは組み込みのファイル オブジェクトではないので、まれに真の組み込みファイルオブジェクトが 必要な場所では使うことができません)
info() メソッドは開いた URL に関連付けられたメタ情報 を含む mimetools.Message クラスのインスタンスを返します。 URL へのアクセスメソッドが HTTP である場合、メタ情報中の ヘッダ情報はサーバが HTML ページを返すときに先頭に付加するヘッダ 情報です (Content-Length および Content-Type を含みます) 。 アクセスメソッドが FTP の場合、ファイル取得リクエストに応答 してサーバがファイルの長さを返したときには (これは現在では普通に なりましたが) Content-Length ヘッダがメタ情報に含められます。 Content-type ヘッダは MIME タイプが推測可能なときにメタ情報に 含められます。アクセスメソッドがローカルファイルの場合、 返されるヘッダ情報にはファイルの最終更新日時を表す Date エントリ、 ファイルのサイズを示す Content-Length エントリ、そして推測される ファイル形式の Content-Type エントリが含まれます。 mimetools モジュールを 参照してください。
geturl() メソッドはページの実際の URL を返します。場合に よっては、HTTP サーバはクライアントの要求を他の URL に振り向け (redirect 、リダイレクト ) します。 関数 urlopen() はユーザに対してリダイレクトを透過的に 行いますが、呼び出し側にとってクライアントがどの URL にリダイレクト されたかを知りたいときがあります。geturl() メソッドを 使うと、このリダイレクトされた URL を取得できます。
url に http: スキーム識別子を使う場合、data 引数を
与えて POST 形式のリクエストを行うことができます (通常リクエストの
形式は GET です)。引数 data は標準の
application/x-www-form-urlencoded 形式でなければなりません;
以下の urlencode() 関数を参照してください。
urlopen() 関数は認証を必要としないプロキシ (proxy) に対して 透過的に動作します。Unix または Windows 環境では、 Python を起動 する前に、環境変数 http_proxy、 ftp_proxy 、および gopher_proxy にそれぞれのプロキシサーバを指定する URL を 設定してください。 例えば ("%" はコマンドプロンプトです):
% http_proxy="http://www.someproxy.com:3128" % export http_proxy % python ...
Windows 環境では、プロキシを指定する環境変数が設定されていない場合、 プロキシの設定値はレジストリの Internet Settings セクションから取得 されます。
Macintosh 環境では、urlopen() は 「インターネットの設定」 (Internet Config) からプロキシ情報を取得します。
別の方法として、オプション引数 proxies を使って明示的にプロキシを
設定することができます。この引数はスキーム名をプロキシの URL にマップする
辞書型のオブジェクトでなくてはなりません。空の辞書を指定するとプロキシを
使いません。None (デフォルトの値です) を指定すると、上で述べた
ように環境変数で指定されたプロキシ設定を使います。例えば:
# http://www.someproxy.com:3128 を http プロキシに使う
proxies = {'http': 'http://www.someproxy.com:3128'}
filehandle = urllib.urlopen(some_url, proxies=proxies)
# プロキシを使わない
filehandle = urllib.urlopen(some_url, proxies={})
# 環境変数からプロキシを使う - 両方の表記とも同じ意味です。
filehandle = urllib.urlopen(some_url, proxies=None)
filehandle = urllib.urlopen(some_url)
(訳注: 上記と矛盾する内容です。おそらく旧バージョンのドキュメントです) 関数 urlopen() は明示的なプロキシ指定をサポートしていません。 環境変数のプロキシ設定を上書きしたい場合には URLopener を使う か、FancyURLopener などのサブクラスを使ってください。
認証を必要とするプロキシは現在のところサポートされていません。 これは実装上の制限 (implementation limitation) と考えています。
バージョン 2.3 で 変更 された仕様: proxies のサポートを追加しました。
| url[, filename[, reporthook[, data]]]) |
(filename, headers) を
返し、filename はローカルで見つかったオブジェクトに対する
ファイル名で、headers は urlopen() が返した
(おそらくキャッシュされているリモートの) オブジェクトに
info() を適用して得られるものになります。
urlopen() と同じ例外を送出します。
2 つめの引数がある場合、オブジェクトのコピー先となるファイルの位置を
指定します (もしなければ、ファイルの場所は一時ファイル (tmpfile) の
置き場になり、名前は適当につけられます)。
3 つめの引数がある場合、ネットワークとの接続が確立された際に一度
呼び出され、以降データのブロックが読み出されるたびに呼び出されるフック
関数 (hook function) を指定します。フック関数には 3 つの引数が渡され
ます; これまで転送されたブロック数のカウント、バイト単位で表された
ブロックサイズ、ファイルの総サイズです。3 つ目のファイルの総サイズ
は、ファイル取得の際の応答時にファイルサイズを返さない古い FTP サーバ
では -1 になります。
url が http: スキーム識別子を使っていた場合、オプション
引数 data を与えることで POST リクエストを行うよう
指定することができます (通常リクエストの形式は GET です)。
data 引数は標準の application/x-www-form-urlencoded
形式でなくてはなりません; 以下の urlencode() 関数を参照して
ください。
バージョン 2.5 で 変更 された仕様:
'urlretrieve()' は、予想 (これは Content-Length ヘッダにより
通知されるサイズです) よりも取得できるデータ量が少ないことを検知した場合、
ContentTooShortError を発生します。これは、例えば、ダウンロードが
中断された場合などに発生します。
Content-Length は下限として扱われます: より多いデータがある場合、
urlretrieve はそのデータを読みますが、より少ないデータしか取得できない場合、
これは exception を発生します。
このような場合にもダウンロードされたデータを取得することは可能で、これは
exception インスタンスの content 属性に保存されています。
Content-Length ヘッダが無い場合、urlretrieve はダウンロードされた
データのサイズをチェックできず、単にそれを返します。この場合は、
ダウンロードは成功したと見なす必要があります。
urllib._urlopener に代入した
後、呼び出したい関数を呼ぶことができます。
例えば、アプリケーションが URLopener が定義しているのとは
異なった User-Agent: ヘッダを指定したい場合があるかも
しれません。この機能は以下のコードで実現できます:
import urllib
class AppURLopener(urllib.FancyURLopener):
version = "App/1.7"
urllib._urlopener = AppURLopener()
| ) |
| string[, safe]) |
'/' です。
例: quote('/~connolly/') は '/%7econnolly/' になります。
| string[, safe]) |
'/' です。
| string) |
例: unquote('/%7Econnolly/') は '/~connolly/' になります。
| string) |
| query[, doseq]) |
POST 型のリクエストに渡すときに便利です。
返される文字列は key=value のペアを "&"
で区切ったシーケンスで、key と value の双方は上の
quote_plus() で quote 処理されます。
オプションのパラメタ doseq が与えられていて、その評価結果が真
であった場合、シーケンス doseq の個々の要素について
key=value のペアが生成されます。
2 つの要素をもったタプルからなるシーケンスが引数 query として使われた
場合、各タプルの最初の値が key で、2 番目の値が value になります。
このときエンコードされた文字列中のパラメタの順番はシーケンス中のタプルの順番
と同じになります。
cgi モジュールでは、関数 parse_qs() および
parse_qsl() を提供しており、クエリ文字列を解析して
Python のデータ構造にするのに利用できます。
| path) |
| path) |
| [proxies[, **x509]]) |
デフォルトでは、 URLopener クラスは User-Agent: ヘッダとして "urllib/VVV" を送信します。ここで VVV は urllib のバージョン番号です。アプリケーションで独自の User-Agent: ヘッダを送信したい場合は、URLopener かまたは FancyURLopener のサブクラスを作成し、 サブクラス定義においてクラス属性 version を適切な 文字列値に設定することで行うことができます。
オプションのパラメタ proxies はスキーム名をプロキシの URL に
マップする辞書でなくてはなりません。空の辞書はプロキシ機能を完全に
オフにします。デフォルトの値は None で、この場合、
urlopen() の定義で述べたように、プロキシを設定する環境変数が
存在するならそれを使います。
追加のキーワードパラメタは x509 に集められますが、これは https: スキームを使った際のクライアント認証に使われることがあります。 キーワード引数 key_file および cert_file が SSL 鍵と証明書を 設定するためにサポートされています; クライアント認証をするには両方が必要です。
URLopener オブジェクトは、サーバがエラーコードを 返した時には IOError を発生します。
| ...) |
その他のレスポンスコードについては、http_error_default() が 呼ばれます。これはサブクラスでエラーを適切に処理するように オーバーライドすることができます。
注意: RFC 2616 によると、 POST 要求に対する 301 および 302 応答はユーザの承認無しに自動的にリダイレクトしてはなりません。 実際は、これらの応答に対して自動リダイレクトを許すブラウザでは POST を GET に変更しており、urllib でもこの動作を 再現します。
コンストラクタに与えるパラメタは URLopener と同じです。
注意: 基本的な HTTP 認証を行う際、 FancyURLopener インスタンスは prompt_user_passwd() メソッドを呼び出します。このメソッドは デフォルトでは実行を制御している端末上で認証に必要な情報を要求する ように実装されています。必要ならば、このクラスのサブクラスにおいて より適切な動作をサポートするために prompt_user_passwd() メソッドをオーバライドしてもかまいません。
| msg[, content]) |
制限:
Gopher プロトコルでは、データのタイプに 関する情報は URL にエンコードされます; これを展開することは簡単 ではありません。返されたデータが HTML であれば、 htmllib を使ってパースすることが できます。
FTP プロトコルを扱うコードでは、ファイルとディレクトリ
を区別できません。このことから、アクセスできないファイルを指している
URL からデータを読み出そうとすると、予期しない動作を引き起こす
場合があります。 URL が/ で終わっていれば、ディレクトリを
指しているものとみなして、それに適した処理を行います。
しかし、ファイルの読み出し操作が 550 エラー (URL が存在しないか、
主にパーミッションの理由でアクセスできない) になった場合、
URL がディレクトリを指していて、末尾の / を忘れたケース
を処理するため、パスをディレクトリとして扱います。
このために、パーミッションのためにアクセスできないファイルを
fetch しようとすると、FTP コードはそのファイルを開こうとして 550
エラーに陥り、次にディレクトリ一覧を表示しようとするため、
誤解を生むような結果を引き起こす可能性があるのです。
よく調整された制御が必要なら、ftplib モジュールを使うか、
FancyURLOpener をサブクラス化するか、
_urlopener を変更して目的に合わせるよう検討してください。
|
|
|
Python ライブラリリファレンス | |
|
|