Содержание
- HOWTO Fetch Internet Resources Using The urllib Package¶
- Introduction¶
- Fetching URLs¶
- Data¶
- Headers¶
- Handling Exceptions¶
- URLError¶
- HTTPError¶
- Error Codes¶
- Wrapping it Up¶
- Number 1В¶
- Number 2В¶
- info and geturl¶
- Openers and Handlers¶
- Basic Authentication¶
- Proxies¶
- Sockets and Layers¶
- Footnotes¶
HOWTO Fetch Internet Resources Using The urllib Package¶
There is a French translation of an earlier revision of this HOWTO, available at urllib2 — Le Manuel manquant.
Introduction¶
You may also find useful the following article on fetching web resources with Python:
A tutorial on Basic Authentication, with examples in Python.
urllib.request is a Python module for fetching URLs (Uniform Resource Locators). It offers a very simple interface, in the form of the urlopen function. This is capable of fetching URLs using a variety of different protocols. It also offers a slightly more complex interface for handling common situations — like basic authentication, cookies, proxies and so on. These are provided by objects called handlers and openers.
urllib.request supports fetching URLs for many “URL schemes” (identified by the string before the «:» in URL — for example «ftp» is the URL scheme of «ftp://python.org/» ) using their associated network protocols (e.g. FTP, HTTP). This tutorial focuses on the most common case, HTTP.
For straightforward situations urlopen is very easy to use. But as soon as you encounter errors or non-trivial cases when opening HTTP URLs, you will need some understanding of the HyperText Transfer Protocol. The most comprehensive and authoritative reference to HTTP is RFC 2616. This is a technical document and not intended to be easy to read. This HOWTO aims to illustrate using urllib, with enough detail about HTTP to help you through. It is not intended to replace the urllib.request docs, but is supplementary to them.
Fetching URLs¶
The simplest way to use urllib.request is as follows:
If you wish to retrieve a resource via URL and store it in a temporary location, you can do so via the shutil.copyfileobj() and tempfile.NamedTemporaryFile() functions:
Many uses of urllib will be that simple (note that instead of an вЂhttp:’ URL we could have used a URL starting with вЂftp:’, вЂfile:’, etc.). However, it’s the purpose of this tutorial to explain the more complicated cases, concentrating on HTTP.
HTTP is based on requests and responses — the client makes requests and servers send responses. urllib.request mirrors this with a Request object which represents the HTTP request you are making. In its simplest form you create a Request object that specifies the URL you want to fetch. Calling urlopen with this Request object returns a response object for the URL requested. This response is a file-like object, which means you can for example call .read() on the response:
Note that urllib.request makes use of the same Request interface to handle all URL schemes. For example, you can make an FTP request like so:
In the case of HTTP, there are two extra things that Request objects allow you to do: First, you can pass data to be sent to the server. Second, you can pass extra information (“metadata”) about the data or about the request itself, to the server — this information is sent as HTTP “headers”. Let’s look at each of these in turn.
Data¶
Sometimes you want to send data to a URL (often the URL will refer to a CGI (Common Gateway Interface) script or other web application). With HTTP, this is often done using what’s known as a POST request. This is often what your browser does when you submit a HTML form that you filled in on the web. Not all POSTs have to come from forms: you can use a POST to transmit arbitrary data to your own application. In the common case of HTML forms, the data needs to be encoded in a standard way, and then passed to the Request object as the data argument. The encoding is done using a function from the urllib.parse library.
Note that other encodings are sometimes required (e.g. for file upload from HTML forms — see HTML Specification, Form Submission for more details).
If you do not pass the data argument, urllib uses a GET request. One way in which GET and POST requests differ is that POST requests often have “side-effects”: they change the state of the system in some way (for example by placing an order with the website for a hundredweight of tinned spam to be delivered to your door). Though the HTTP standard makes it clear that POSTs are intended to always cause side-effects, and GET requests never to cause side-effects, nothing prevents a GET request from having side-effects, nor a POST requests from having no side-effects. Data can also be passed in an HTTP GET request by encoding it in the URL itself.
This is done as follows:
Notice that the full URL is created by adding a ? to the URL, followed by the encoded values.
We’ll discuss here one particular HTTP header, to illustrate how to add headers to your HTTP request.
Some websites 1 dislike being browsed by programs, or send different versions to different browsers 2. By default urllib identifies itself as Python-urllib/x.y (where x and y are the major and minor version numbers of the Python release, e.g. Python-urllib/2.5 ), which may confuse the site, or just plain not work. The way a browser identifies itself is through the User-Agent header 3. When you create a Request object you can pass a dictionary of headers in. The following example makes the same request as above, but identifies itself as a version of Internet Explorer 4.
The response also has two useful methods. See the section on info and geturl which comes after we have a look at what happens when things go wrong.
Handling Exceptions¶
urlopen raises URLError when it cannot handle a response (though as usual with Python APIs, built-in exceptions such as ValueError , TypeError etc. may also be raised).
HTTPError is the subclass of URLError raised in the specific case of HTTP URLs.
The exception classes are exported from the urllib.error module.
URLError¶
Often, URLError is raised because there is no network connection (no route to the specified server), or the specified server doesn’t exist. In this case, the exception raised will have a вЂreason’ attribute, which is a tuple containing an error code and a text error message.
HTTPError¶
Every HTTP response from the server contains a numeric “status code”. Sometimes the status code indicates that the server is unable to fulfil the request. The default handlers will handle some of these responses for you (for example, if the response is a “redirection” that requests the client fetch the document from a different URL, urllib will handle that for you). For those it can’t handle, urlopen will raise an HTTPError . Typical errors include вЂ404’ (page not found), вЂ403’ (request forbidden), and вЂ401’ (authentication required).
See section 10 of RFC 2616 for a reference on all the HTTP error codes.
The HTTPError instance raised will have an integer вЂcode’ attribute, which corresponds to the error sent by the server.
Error Codes¶
Because the default handlers handle redirects (codes in the 300 range), and codes in the 100–299 range indicate success, you will usually only see error codes in the 400–599 range.
http.server.BaseHTTPRequestHandler.responses is a useful dictionary of response codes in that shows all the response codes used by RFC 2616. The dictionary is reproduced here for convenience
When an error is raised the server responds by returning an HTTP error code and an error page. You can use the HTTPError instance as a response on the page returned. This means that as well as the code attribute, it also has read, geturl, and info, methods as returned by the urllib.response module:
Wrapping it Up¶
So if you want to be prepared for HTTPError or URLError there are two basic approaches. I prefer the second approach.
Number 1В¶
The except HTTPError must come first, otherwise except URLError will also catch an HTTPError .
Number 2В¶
info and geturl¶
The response returned by urlopen (or the HTTPError instance) has two useful methods info() and geturl() and is defined in the module urllib.response ..
geturl — this returns the real URL of the page fetched. This is useful because urlopen (or the opener object used) may have followed a redirect. The URL of the page fetched may not be the same as the URL requested.
info — this returns a dictionary-like object that describes the page fetched, particularly the headers sent by the server. It is currently an http.client.HTTPMessage instance.
Typical headers include вЂContent-length’, вЂContent-type’, and so on. See the Quick Reference to HTTP Headers for a useful listing of HTTP headers with brief explanations of their meaning and use.
Openers and Handlers¶
When you fetch a URL you use an opener (an instance of the perhaps confusingly named urllib.request.OpenerDirector ). Normally we have been using the default opener — via urlopen — but you can create custom openers. Openers use handlers. All the “heavy lifting” is done by the handlers. Each handler knows how to open URLs for a particular URL scheme (http, ftp, etc.), or how to handle an aspect of URL opening, for example HTTP redirections or HTTP cookies.
You will want to create openers if you want to fetch URLs with specific handlers installed, for example to get an opener that handles cookies, or to get an opener that does not handle redirections.
To create an opener, instantiate an OpenerDirector , and then call .add_handler(some_handler_instance) repeatedly.
Alternatively, you can use build_opener , which is a convenience function for creating opener objects with a single function call. build_opener adds several handlers by default, but provides a quick way to add more and/or override the default handlers.
Other sorts of handlers you might want to can handle proxies, authentication, and other common but slightly specialised situations.
install_opener can be used to make an opener object the (global) default opener. This means that calls to urlopen will use the opener you have installed.
Opener objects have an open method, which can be called directly to fetch urls in the same way as the urlopen function: there’s no need to call install_opener , except as a convenience.
Basic Authentication¶
To illustrate creating and installing a handler we will use the HTTPBasicAuthHandler . For a more detailed discussion of this subject – including an explanation of how Basic Authentication works — see the Basic Authentication Tutorial.
When authentication is required, the server sends a header (as well as the 401 error code) requesting authentication. This specifies the authentication scheme and a вЂrealm’. The header looks like: WWW-Authenticate: SCHEME realm=»REALM» .
The client should then retry the request with the appropriate name and password for the realm included as a header in the request. This is вЂbasic authentication’. In order to simplify this process we can create an instance of HTTPBasicAuthHandler and an opener to use this handler.
The HTTPBasicAuthHandler uses an object called a password manager to handle the mapping of URLs and realms to passwords and usernames. If you know what the realm is (from the authentication header sent by the server), then you can use a HTTPPasswordMgr . Frequently one doesn’t care what the realm is. In that case, it is convenient to use HTTPPasswordMgrWithDefaultRealm . This allows you to specify a default username and password for a URL. This will be supplied in the absence of you providing an alternative combination for a specific realm. We indicate this by providing None as the realm argument to the add_password method.
The top-level URL is the first URL that requires authentication. URLs “deeper” than the URL you pass to .add_password() will also match.
In the above example we only supplied our HTTPBasicAuthHandler to build_opener . By default openers have the handlers for normal situations – ProxyHandler (if a proxy setting such as an http_proxy environment variable is set), UnknownHandler , HTTPHandler , HTTPDefaultErrorHandler , HTTPRedirectHandler , FTPHandler , FileHandler , DataHandler , HTTPErrorProcessor .
top_level_url is in fact either a full URL (including the вЂhttp:’ scheme component and the hostname and optionally the port number) e.g. «http://example.com/» or an “authority” (i.e. the hostname, optionally including the port number) e.g. «example.com» or «example.com:8080» (the latter example includes a port number). The authority, if present, must NOT contain the “userinfo” component — for example «joe:password@example.com» is not correct.
Proxies¶
urllib will auto-detect your proxy settings and use those. This is through the ProxyHandler , which is part of the normal handler chain when a proxy setting is detected. Normally that’s a good thing, but there are occasions when it may not be helpful 5. One way to do this is to setup our own ProxyHandler , with no proxies defined. This is done using similar steps to setting up a Basic Authentication handler:
Currently urllib.request does not support fetching of https locations through a proxy. However, this can be enabled by extending urllib.request as shown in the recipe 6.
HTTP_PROXY will be ignored if a variable REQUEST_METHOD is set; see the documentation on getproxies() .
Sockets and Layers¶
The Python support for fetching resources from the web is layered. urllib uses the http.client library, which in turn uses the socket library.
As of Python 2.3 you can specify how long a socket should wait for a response before timing out. This can be useful in applications which have to fetch web pages. By default the socket module has no timeout and can hang. Currently, the socket timeout is not exposed at the http.client or urllib.request levels. However, you can set the default timeout globally for all sockets using
This document was reviewed and revised by John Lee.
Google for example.
Browser sniffing is a very bad practice for website design — building sites using web standards is much more sensible. Unfortunately a lot of sites still send different versions to different browsers.
The user agent for MSIE 6 is вЂMozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)’
For details of more HTTP request headers, see Quick Reference to HTTP Headers.
In my case I have to use a proxy to access the internet at work. If you attempt to fetch localhost URLs through this proxy it blocks them. IE is set to use the proxy, which urllib picks up on. In order to test scripts with a localhost server, I have to prevent urllib from using the proxy.
urllib opener for SSL proxy (CONNECT method): ASPN Cookbook Recipe.
Источник
Python 3.7
HOWTO Fetch Internet Resources Using The urllib Package
| Author: | Michael Foord |
|---|
Introduction
urllib.request is a Python module for fetching URLs
(Uniform Resource Locators). It offers a very simple interface, in the form of
the urlopen function. This is capable of fetching URLs using a variety of
different protocols. It also offers a slightly more complex interface for
handling common situations — like basic authentication, cookies, proxies and so
on. These are provided by objects called handlers and openers.
urllib.request supports fetching URLs for many “URL schemes” (identified by the string
before the ":" in URL — for example "ftp" is the URL scheme of
"ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP).
This tutorial focuses on the most common case, HTTP.
For straightforward situations urlopen is very easy to use. But as soon as you
encounter errors or non-trivial cases when opening HTTP URLs, you will need some
understanding of the HyperText Transfer Protocol. The most comprehensive and
authoritative reference to HTTP is RFC 2616. This is a technical document and
not intended to be easy to read. This HOWTO aims to illustrate using urllib,
with enough detail about HTTP to help you through. It is not intended to replace
the urllib.request docs, but is supplementary to them.
Fetching URLs
The simplest way to use urllib.request is as follows:
import urllib.request with urllib.request.urlopen('http://python.org/') as response: html = response.read()
If you wish to retrieve a resource via URL and store it in a temporary location,
you can do so via the urlretrieve() function:
import urllib.request local_filename, headers = urllib.request.urlretrieve('http://python.org/') html = open(local_filename)
Many uses of urllib will be that simple (note that instead of an ‘http:’ URL we
could have used a URL starting with ‘ftp:’, ‘file:’, etc.). However, it’s the
purpose of this tutorial to explain the more complicated cases, concentrating on
HTTP.
HTTP is based on requests and responses — the client makes requests and servers
send responses. urllib.request mirrors this with a Request object which represents
the HTTP request you are making. In its simplest form you create a Request
object that specifies the URL you want to fetch. Calling urlopen with this
Request object returns a response object for the URL requested. This response is
a file-like object, which means you can for example call .read() on the
response:
import urllib.request req = urllib.request.Request('http://www.voidspace.org.uk') with urllib.request.urlopen(req) as response: the_page = response.read()
Note that urllib.request makes use of the same Request interface to handle all URL
schemes. For example, you can make an FTP request like so:
req = urllib.request.Request('ftp://example.com/')
In the case of HTTP, there are two extra things that Request objects allow you
to do: First, you can pass data to be sent to the server. Second, you can pass
extra information (“metadata”) about the data or the about request itself, to
the server — this information is sent as HTTP “headers”. Let’s look at each of
these in turn.
Data
Sometimes you want to send data to a URL (often the URL will refer to a CGI
(Common Gateway Interface) script or other web application). With HTTP,
this is often done using what’s known as a POST request. This is often what
your browser does when you submit a HTML form that you filled in on the web. Not
all POSTs have to come from forms: you can use a POST to transmit arbitrary data
to your own application. In the common case of HTML forms, the data needs to be
encoded in a standard way, and then passed to the Request object as the data
argument. The encoding is done using a function from the urllib.parse
library.
import urllib.parse import urllib.request url = 'http://www.someserver.com/cgi-bin/register.cgi' values = {'name' : 'Michael Foord', 'location' : 'Northampton', 'language' : 'Python' } data = urllib.parse.urlencode(values) data = data.encode('ascii') # data should be bytes req = urllib.request.Request(url, data) with urllib.request.urlopen(req) as response: the_page = response.read()
Note that other encodings are sometimes required (e.g. for file upload from HTML
forms — see HTML Specification, Form Submission for more
details).
If you do not pass the data argument, urllib uses a GET request. One
way in which GET and POST requests differ is that POST requests often have
“side-effects”: they change the state of the system in some way (for example by
placing an order with the website for a hundredweight of tinned spam to be
delivered to your door). Though the HTTP standard makes it clear that POSTs are
intended to always cause side-effects, and GET requests never to cause
side-effects, nothing prevents a GET request from having side-effects, nor a
POST requests from having no side-effects. Data can also be passed in an HTTP
GET request by encoding it in the URL itself.
This is done as follows:
>>> import urllib.request >>> import urllib.parse >>> data = {} >>> data['name'] = 'Somebody Here' >>> data['location'] = 'Northampton' >>> data['language'] = 'Python' >>> url_values = urllib.parse.urlencode(data) >>> print(url_values) # The order may differ from below. name=Somebody+Here&language=Python&location=Northampton >>> url = 'http://www.example.com/example.cgi' >>> full_url = url + '?' + url_values >>> data = urllib.request.urlopen(full_url)
Notice that the full URL is created by adding a ? to the URL, followed by
the encoded values.
Handling Exceptions
urlopen raises URLError when it cannot handle a response (though as
usual with Python APIs, built-in exceptions such as ValueError,
TypeError etc. may also be raised).
HTTPError is the subclass of URLError raised in the specific case of
HTTP URLs.
The exception classes are exported from the urllib.error module.
URLError
Often, URLError is raised because there is no network connection (no route to
the specified server), or the specified server doesn’t exist. In this case, the
exception raised will have a ‘reason’ attribute, which is a tuple containing an
error code and a text error message.
e.g.
>>> req = urllib.request.Request('http://www.pretend_server.org') >>> try: urllib.request.urlopen(req) ... except urllib.error.URLError as e: ... print(e.reason) ... (4, 'getaddrinfo failed')
HTTPError
Every HTTP response from the server contains a numeric “status code”. Sometimes
the status code indicates that the server is unable to fulfil the request. The
default handlers will handle some of these responses for you (for example, if
the response is a “redirection” that requests the client fetch the document from
a different URL, urllib will handle that for you). For those it can’t handle,
urlopen will raise an HTTPError. Typical errors include ‘404’ (page not
found), ‘403’ (request forbidden), and ‘401’ (authentication required).
See section 10 of RFC 2616 for a reference on all the HTTP error codes.
The HTTPError instance raised will have an integer ‘code’ attribute, which
corresponds to the error sent by the server.
Error Codes
Because the default handlers handle redirects (codes in the 300 range), and
codes in the 100–299 range indicate success, you will usually only see error
codes in the 400–599 range.
http.server.BaseHTTPRequestHandler.responses is a useful dictionary of
response codes in that shows all the response codes used by RFC 2616. The
dictionary is reproduced here for convenience
# Table mapping response codes to messages; entries have the # form {code: (shortmessage, longmessage)}. responses = { 100: ('Continue', 'Request received, please continue'), 101: ('Switching Protocols', 'Switching to new protocol; obey Upgrade header'), 200: ('OK', 'Request fulfilled, document follows'), 201: ('Created', 'Document created, URL follows'), 202: ('Accepted', 'Request accepted, processing continues off-line'), 203: ('Non-Authoritative Information', 'Request fulfilled from cache'), 204: ('No Content', 'Request fulfilled, nothing follows'), 205: ('Reset Content', 'Clear input form for further input.'), 206: ('Partial Content', 'Partial content follows.'), 300: ('Multiple Choices', 'Object has several resources -- see URI list'), 301: ('Moved Permanently', 'Object moved permanently -- see URI list'), 302: ('Found', 'Object moved temporarily -- see URI list'), 303: ('See Other', 'Object moved -- see Method and URL list'), 304: ('Not Modified', 'Document has not changed since given time'), 305: ('Use Proxy', 'You must use proxy specified in Location to access this ' 'resource.'), 307: ('Temporary Redirect', 'Object moved temporarily -- see URI list'), 400: ('Bad Request', 'Bad request syntax or unsupported method'), 401: ('Unauthorized', 'No permission -- see authorization schemes'), 402: ('Payment Required', 'No payment -- see charging schemes'), 403: ('Forbidden', 'Request forbidden -- authorization will not help'), 404: ('Not Found', 'Nothing matches the given URI'), 405: ('Method Not Allowed', 'Specified method is invalid for this server.'), 406: ('Not Acceptable', 'URI not available in preferred format.'), 407: ('Proxy Authentication Required', 'You must authenticate with ' 'this proxy before proceeding.'), 408: ('Request Timeout', 'Request timed out; try again later.'), 409: ('Conflict', 'Request conflict.'), 410: ('Gone', 'URI no longer exists and has been permanently removed.'), 411: ('Length Required', 'Client must specify Content-Length.'), 412: ('Precondition Failed', 'Precondition in headers is false.'), 413: ('Request Entity Too Large', 'Entity is too large.'), 414: ('Request-URI Too Long', 'URI is too long.'), 415: ('Unsupported Media Type', 'Entity body in unsupported format.'), 416: ('Requested Range Not Satisfiable', 'Cannot satisfy request range.'), 417: ('Expectation Failed', 'Expect condition could not be satisfied.'), 500: ('Internal Server Error', 'Server got itself in trouble'), 501: ('Not Implemented', 'Server does not support this operation'), 502: ('Bad Gateway', 'Invalid responses from another server/proxy.'), 503: ('Service Unavailable', 'The server cannot process the request due to a high load'), 504: ('Gateway Timeout', 'The gateway server did not receive a timely response'), 505: ('HTTP Version Not Supported', 'Cannot fulfill request.'), }
When an error is raised the server responds by returning an HTTP error code
and an error page. You can use the HTTPError instance as a response on the
page returned. This means that as well as the code attribute, it also has read,
geturl, and info, methods as returned by the urllib.response module:
>>> req = urllib.request.Request('http://www.python.org/fish.html') >>> try: ... urllib.request.urlopen(req) ... except urllib.error.HTTPError as e: ... print(e.code) ... print(e.read()) ... 404 b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">nnn<html ... <title>Page Not Found</title>n ...
Wrapping it Up
So if you want to be prepared for HTTPError or URLError there are two
basic approaches. I prefer the second approach.
Number 1
from urllib.request import Request, urlopen from urllib.error import URLError, HTTPError req = Request(someurl) try: response = urlopen(req) except HTTPError as e: print('The server couldn't fulfill the request.') print('Error code: ', e.code) except URLError as e: print('We failed to reach a server.') print('Reason: ', e.reason) else: # everything is fine
Note
The except HTTPError must come first, otherwise except URLError
will also catch an HTTPError.
Number 2
from urllib.request import Request, urlopen from urllib.error import URLError req = Request(someurl) try: response = urlopen(req) except URLError as e: if hasattr(e, 'reason'): print('We failed to reach a server.') print('Reason: ', e.reason) elif hasattr(e, 'code'): print('The server couldn't fulfill the request.') print('Error code: ', e.code) else: # everything is fine
info and geturl
The response returned by urlopen (or the HTTPError instance) has two
useful methods info() and geturl() and is defined in the module
urllib.response..
geturl — this returns the real URL of the page fetched. This is useful
because urlopen (or the opener object used) may have followed a
redirect. The URL of the page fetched may not be the same as the URL requested.
info — this returns a dictionary-like object that describes the page
fetched, particularly the headers sent by the server. It is currently an
http.client.HTTPMessage instance.
Typical headers include ‘Content-length’, ‘Content-type’, and so on. See the
Quick Reference to HTTP Headers
for a useful listing of HTTP headers with brief explanations of their meaning
and use.
Openers and Handlers
When you fetch a URL you use an opener (an instance of the perhaps
confusingly-named urllib.request.OpenerDirector). Normally we have been using
the default opener — via urlopen — but you can create custom
openers. Openers use handlers. All the “heavy lifting” is done by the
handlers. Each handler knows how to open URLs for a particular URL scheme (http,
ftp, etc.), or how to handle an aspect of URL opening, for example HTTP
redirections or HTTP cookies.
You will want to create openers if you want to fetch URLs with specific handlers
installed, for example to get an opener that handles cookies, or to get an
opener that does not handle redirections.
To create an opener, instantiate an OpenerDirector, and then call
.add_handler(some_handler_instance) repeatedly.
Alternatively, you can use build_opener, which is a convenience function for
creating opener objects with a single function call. build_opener adds
several handlers by default, but provides a quick way to add more and/or
override the default handlers.
Other sorts of handlers you might want to can handle proxies, authentication,
and other common but slightly specialised situations.
install_opener can be used to make an opener object the (global) default
opener. This means that calls to urlopen will use the opener you have
installed.
Opener objects have an open method, which can be called directly to fetch
urls in the same way as the urlopen function: there’s no need to call
install_opener, except as a convenience.
Basic Authentication
To illustrate creating and installing a handler we will use the
HTTPBasicAuthHandler. For a more detailed discussion of this subject –
including an explanation of how Basic Authentication works — see the Basic
Authentication Tutorial.
When authentication is required, the server sends a header (as well as the 401
error code) requesting authentication. This specifies the authentication scheme
and a ‘realm’. The header looks like: WWW-Authenticate: SCHEME.
realm="REALM"
e.g.
WWW-Authenticate: Basic realm="cPanel Users"
The client should then retry the request with the appropriate name and password
for the realm included as a header in the request. This is ‘basic
authentication’. In order to simplify this process we can create an instance of
HTTPBasicAuthHandler and an opener to use this handler.
The HTTPBasicAuthHandler uses an object called a password manager to handle
the mapping of URLs and realms to passwords and usernames. If you know what the
realm is (from the authentication header sent by the server), then you can use a
HTTPPasswordMgr. Frequently one doesn’t care what the realm is. In that
case, it is convenient to use HTTPPasswordMgrWithDefaultRealm. This allows
you to specify a default username and password for a URL. This will be supplied
in the absence of you providing an alternative combination for a specific
realm. We indicate this by providing None as the realm argument to the
add_password method.
The top-level URL is the first URL that requires authentication. URLs “deeper”
than the URL you pass to .add_password() will also match.
# create a password manager password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm() # Add the username and password. # If we knew the realm, we could use it instead of None. top_level_url = "http://example.com/foo/" password_mgr.add_password(None, top_level_url, username, password) handler = urllib.request.HTTPBasicAuthHandler(password_mgr) # create "opener" (OpenerDirector instance) opener = urllib.request.build_opener(handler) # use the opener to fetch a URL opener.open(a_url) # Install the opener. # Now all calls to urllib.request.urlopen use our opener. urllib.request.install_opener(opener)
Note
In the above example we only supplied our HTTPBasicAuthHandler to
build_opener. By default openers have the handlers for normal situations
– ProxyHandler (if a proxy setting such as an http_proxy
environment variable is set), UnknownHandler, HTTPHandler,
HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler,
FileHandler, DataHandler, HTTPErrorProcessor.
top_level_url is in fact either a full URL (including the ‘http:’ scheme
component and the hostname and optionally the port number)
e.g. "http://example.com/" or an “authority” (i.e. the hostname,
optionally including the port number) e.g. "example.com" or "example.com:8080"
(the latter example includes a port number). The authority, if present, must
NOT contain the “userinfo” component — for example "joe:[email protected]" is
not correct.
Proxies
urllib will auto-detect your proxy settings and use those. This is through
the ProxyHandler, which is part of the normal handler chain when a proxy
setting is detected. Normally that’s a good thing, but there are occasions
when it may not be helpful [5]. One way to do this is to setup our own
ProxyHandler, with no proxies defined. This is done using similar steps to
setting up a Basic Authentication handler:
>>> proxy_support = urllib.request.ProxyHandler({}) >>> opener = urllib.request.build_opener(proxy_support) >>> urllib.request.install_opener(opener)
Note
Currently urllib.request does not support fetching of https locations
through a proxy. However, this can be enabled by extending urllib.request as
shown in the recipe [6].
Note
HTTP_PROXY will be ignored if a variable REQUEST_METHOD is set; see
the documentation on getproxies().
Sockets and Layers
The Python support for fetching resources from the web is layered. urllib uses
the http.client library, which in turn uses the socket library.
As of Python 2.3 you can specify how long a socket should wait for a response
before timing out. This can be useful in applications which have to fetch web
pages. By default the socket module has no timeout and can hang. Currently,
the socket timeout is not exposed at the http.client or urllib.request levels.
However, you can set the default timeout globally for all sockets using
import socket import urllib.request # timeout in seconds timeout = 10 socket.setdefaulttimeout(timeout) # this call to urllib.request.urlopen now uses the default timeout # we have set in the socket module req = urllib.request.Request('http://www.voidspace.org.uk') response = urllib.request.urlopen(req)
- Автор
-
Michael Foord
Введение¶
urllib.request — это модуль Python для получения URL (Uniform Resource Locators). Он предлагает очень простой интерфейс в виде функции urlopen. Он способен получать URL, используя множество различных протоколов. Она также предлагает немного более сложный интерфейс для обработки общих ситуаций, таких как базовая аутентификация, cookies, прокси и так далее. Эти функции предоставляются объектами, называемыми обработчиками и открывателями.
urllib.request поддерживает получение URL для многих «схем URL» (определяемых строкой перед ":" в URL — например, "ftp" является схемой URL "ftp://python.org/"), используя связанные с ними сетевые протоколы (например, FTP, HTTP). В этом учебнике рассматривается наиболее распространенный случай — HTTP.
Для простых ситуаций urlopen очень прост в использовании. Но как только вы столкнетесь с ошибками или нетривиальными случаями при открытии HTTP URL, вам понадобится некоторое понимание протокола HyperText Transfer Protocol. Наиболее полным и авторитетным справочником по HTTP является RFC 2616. Это технический документ, который не предназначен для легкого чтения. Цель этого HOWTO — проиллюстрировать использование urllib, с достаточным количеством подробностей о HTTP, чтобы помочь вам. Он не предназначен для замены документации urllib.request, а является дополнением к ней.
Получение URL-адресов¶
Самый простой способ использования urllib.request следующий:
import urllib.request with urllib.request.urlopen('http://python.org/') as response: html = response.read()
Если вы хотите получить ресурс по URL и сохранить его во временном месте, вы можете сделать это с помощью функций shutil.copyfileobj() и tempfile.NamedTemporaryFile():
import shutil import tempfile import urllib.request with urllib.request.urlopen('http://python.org/') as response: with tempfile.NamedTemporaryFile(delete=False) as tmp_file: shutil.copyfileobj(response, tmp_file) with open(tmp_file.name) as html: pass
Многие случаи использования urllib будут настолько простыми (обратите внимание, что вместо URL „http:“ мы могли бы использовать URL, начинающийся с „ftp:“, „file:“ и т.д.). Однако цель этого руководства — объяснить более сложные случаи, сосредоточившись на HTTP.
HTTP основан на запросах и ответах — клиент делает запросы, а серверы отправляют ответы. urllib.request отражает это с помощью объекта Request, который представляет HTTP-запрос, который вы делаете. В своей простейшей форме вы создаете объект Request, который определяет URL, который вы хотите получить. Вызов urlopen с этим объектом Request возвращает объект response для запрошенного URL. Этот ответ является файлоподобным объектом, что означает, что вы можете, например, вызвать .read() на ответе:
import urllib.request req = urllib.request.Request('http://www.voidspace.org.uk') with urllib.request.urlopen(req) as response: the_page = response.read()
Обратите внимание, что urllib.request использует один и тот же интерфейс Request для работы со всеми схемами URL. Например, вы можете сделать FTP-запрос следующим образом:
req = urllib.request.Request('ftp://example.com/')
В случае с HTTP есть две дополнительные вещи, которые позволяют делать объекты Request: Во-первых, вы можете передавать данные для отправки на сервер. Во-вторых, вы можете передать серверу дополнительную информацию («метаданные») о данных или о самом запросе — эта информация передается в виде «заголовков» HTTP. Давайте рассмотрим каждый из них по очереди.
Данные¶
Иногда вы хотите отправить данные на URL (часто URL ссылается на CGI (Common Gateway Interface) скрипт или другое веб-приложение). В HTTP это часто делается с помощью так называемого POST запроса. Именно так часто поступает ваш браузер, когда вы отправляете HTML-форму, заполненную в Интернете. Не все POST-запросы должны исходить от форм: вы можете использовать POST для передачи произвольных данных в ваше собственное приложение. В обычном случае HTML-формы данные должны быть закодированы стандартным образом, а затем переданы объекту Request в качестве аргумента data. Кодирование выполняется с помощью функции из библиотеки urllib.parse.
import urllib.parse import urllib.request url = 'http://www.someserver.com/cgi-bin/register.cgi' values = {'name' : 'Michael Foord', 'location' : 'Northampton', 'language' : 'Python' } data = urllib.parse.urlencode(values) data = data.encode('ascii') # data should be bytes req = urllib.request.Request(url, data) with urllib.request.urlopen(req) as response: the_page = response.read()
Обратите внимание, что иногда требуются другие кодировки (например, для загрузки файлов из HTML-форм — подробнее см. в HTML Specification, Form Submission).
Если вы не передаете аргумент data, urllib использует GET запрос. Различия между GET и POST запросами заключаются в том, что POST запросы часто имеют «побочные эффекты»: они каким-то образом изменяют состояние системы (например, размещая на сайте заказ на доставку сотни килограммов консервированного спама к вашей двери). Хотя стандарт HTTP четко указывает, что POST-запросы должны всегда вызывать побочные эффекты, а GET-запросы никогда не вызывать побочных эффектов, ничто не мешает GET-запросу иметь побочные эффекты, а POST-запросу — не иметь побочных эффектов. Данные также могут быть переданы в запросе HTTP GET путем кодирования их в самом URL.
Это делается следующим образом:
>>> import urllib.request >>> import urllib.parse >>> data = {} >>> data['name'] = 'Somebody Here' >>> data['location'] = 'Northampton' >>> data['language'] = 'Python' >>> url_values = urllib.parse.urlencode(data) >>> print(url_values) # The order may differ from below. name=Somebody+Here&language=Python&location=Northampton >>> url = 'http://www.example.com/example.cgi' >>> full_url = url + '?' + url_values >>> data = urllib.request.urlopen(full_url)
Обратите внимание, что полный URL создается путем добавления ? к URL, за которым следуют закодированные значения.
Обработка исключений¶
urlopen поднимает URLError, когда не может обработать ответ (хотя, как обычно в Python API, могут быть подняты и встроенные исключения, такие как ValueError, TypeError и т.д.).
HTTPError является подклассом URLError, возникающим в конкретном случае HTTP URL.
Классы исключений экспортируются из модуля urllib.error.
URLError¶
Часто URLError возникает из-за отсутствия сетевого соединения (нет маршрута к указанному серверу), или указанный сервер не существует. В этом случае вызванное исключение будет иметь атрибут „reason“, который представляет собой кортеж, содержащий код ошибки и текстовое сообщение об ошибке.
например
>>> req = urllib.request.Request('http://www.pretend_server.org') >>> try: urllib.request.urlopen(req) ... except urllib.error.URLError as e: ... print(e.reason) ... (4, 'getaddrinfo failed')
HTTPError¶
Каждый ответ HTTP от сервера содержит числовой «код состояния». Иногда код состояния указывает на то, что сервер не может выполнить запрос. Обработчики по умолчанию будут обрабатывать некоторые из этих ответов за вас (например, если ответ является «перенаправлением», которое просит клиента получить документ с другого URL, urllib обработает это за вас). Если urlopen не может обработать эти ответы, он выдаст ошибку HTTPError. Типичные ошибки включают „404“ (страница не найдена), „403“ (запрос запрещен) и „401“ (требуется аутентификация).
См. раздел 10 книги RFC 2616 для справки по всем кодам ошибок HTTP.
Поднятый экземпляр HTTPError будет иметь целочисленный атрибут „code“, который соответствует ошибке, отправленной сервером.
Коды ошибок¶
Поскольку обработчики по умолчанию обрабатывают перенаправления (коды в диапазоне 300), а коды в диапазоне 100-299 означают успех, вы обычно будете видеть только коды ошибок в диапазоне 400-599.
http.server.BaseHTTPRequestHandler.responses представляет собой полезный словарь кодов ответов, в котором показаны все коды ответов, используемые RFC 2616. Словарь воспроизводится здесь для удобства
# Table mapping response codes to messages; entries have the # form {code: (shortmessage, longmessage)}. responses = { 100: ('Continue', 'Request received, please continue'), 101: ('Switching Protocols', 'Switching to new protocol; obey Upgrade header'), 200: ('OK', 'Request fulfilled, document follows'), 201: ('Created', 'Document created, URL follows'), 202: ('Accepted', 'Request accepted, processing continues off-line'), 203: ('Non-Authoritative Information', 'Request fulfilled from cache'), 204: ('No Content', 'Request fulfilled, nothing follows'), 205: ('Reset Content', 'Clear input form for further input.'), 206: ('Partial Content', 'Partial content follows.'), 300: ('Multiple Choices', 'Object has several resources -- see URI list'), 301: ('Moved Permanently', 'Object moved permanently -- see URI list'), 302: ('Found', 'Object moved temporarily -- see URI list'), 303: ('See Other', 'Object moved -- see Method and URL list'), 304: ('Not Modified', 'Document has not changed since given time'), 305: ('Use Proxy', 'You must use proxy specified in Location to access this ' 'resource.'), 307: ('Temporary Redirect', 'Object moved temporarily -- see URI list'), 400: ('Bad Request', 'Bad request syntax or unsupported method'), 401: ('Unauthorized', 'No permission -- see authorization schemes'), 402: ('Payment Required', 'No payment -- see charging schemes'), 403: ('Forbidden', 'Request forbidden -- authorization will not help'), 404: ('Not Found', 'Nothing matches the given URI'), 405: ('Method Not Allowed', 'Specified method is invalid for this server.'), 406: ('Not Acceptable', 'URI not available in preferred format.'), 407: ('Proxy Authentication Required', 'You must authenticate with ' 'this proxy before proceeding.'), 408: ('Request Timeout', 'Request timed out; try again later.'), 409: ('Conflict', 'Request conflict.'), 410: ('Gone', 'URI no longer exists and has been permanently removed.'), 411: ('Length Required', 'Client must specify Content-Length.'), 412: ('Precondition Failed', 'Precondition in headers is false.'), 413: ('Request Entity Too Large', 'Entity is too large.'), 414: ('Request-URI Too Long', 'URI is too long.'), 415: ('Unsupported Media Type', 'Entity body in unsupported format.'), 416: ('Requested Range Not Satisfiable', 'Cannot satisfy request range.'), 417: ('Expectation Failed', 'Expect condition could not be satisfied.'), 500: ('Internal Server Error', 'Server got itself in trouble'), 501: ('Not Implemented', 'Server does not support this operation'), 502: ('Bad Gateway', 'Invalid responses from another server/proxy.'), 503: ('Service Unavailable', 'The server cannot process the request due to a high load'), 504: ('Gateway Timeout', 'The gateway server did not receive a timely response'), 505: ('HTTP Version Not Supported', 'Cannot fulfill request.'), }
При возникновении ошибки сервер возвращает код ошибки HTTP и страницу ошибки. Вы можете использовать экземпляр HTTPError в качестве ответа на возвращаемой странице. Это означает, что помимо атрибута code, он также имеет методы read, geturl и info, возвращаемые модулем urllib.response:
>>> req = urllib.request.Request('http://www.python.org/fish.html') >>> try: ... urllib.request.urlopen(req) ... except urllib.error.HTTPError as e: ... print(e.code) ... print(e.read()) ... 404 b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">nnn<html ... <title>Page Not Found</title>n ...
Подведение итогов¶
Итак, если вы хотите быть готовым к HTTPError или URLError, есть два основных подхода. Я предпочитаю второй подход.
Номер 1¶
from urllib.request import Request, urlopen from urllib.error import URLError, HTTPError req = Request(someurl) try: response = urlopen(req) except HTTPError as e: print('The server couldn't fulfill the request.') print('Error code: ', e.code) except URLError as e: print('We failed to reach a server.') print('Reason: ', e.reason) else: # everything is fine
Примечание
except HTTPError должен быть первым, иначе except URLError будет также ловить HTTPError.
Номер 2¶
from urllib.request import Request, urlopen from urllib.error import URLError req = Request(someurl) try: response = urlopen(req) except URLError as e: if hasattr(e, 'reason'): print('We failed to reach a server.') print('Reason: ', e.reason) elif hasattr(e, 'code'): print('The server couldn't fulfill the request.') print('Error code: ', e.code) else: # everything is fine
info и geturl¶
Ответ, возвращаемый urlopen (или экземпляр HTTPError), имеет два полезных метода info() и geturl() и определен в модуле urllib.response.
geturl — возвращает реальный URL полученной страницы. Это полезно, поскольку urlopen (или используемый объект opener) может следовать за перенаправлением. URL полученной страницы может не совпадать с запрошенным URL.
info — возвращает словареподобный объект, описывающий полученную страницу, в частности, заголовки, отправленные сервером. В настоящее время это экземпляр http.client.HTTPMessage.
Типичные заголовки включают „Content-length“, „Content-type“ и так далее. Смотрите Quick Reference to HTTP Headers для полезного списка заголовков HTTP с краткими объяснениями их значения и использования.
Открыватели и манипуляторы¶
Когда вы получаете URL, вы используете открыватель (экземпляр, возможно, сбивающего с толку названия urllib.request.OpenerDirector). Обычно мы используем открывалку по умолчанию — через urlopen, но вы можете создавать собственные открывалки. Открыватели используют обработчики. Всю «тяжелую работу» выполняют обработчики. Каждый обработчик знает, как открывать URL для определенной схемы URL (http, ftp и т.д.), или как обрабатывать тот или иной аспект открытия URL, например, HTTP-перенаправления или HTTP-куки.
Вы захотите создать открыватели, если вам нужно получить URL с установленными определенными обработчиками, например, чтобы получить открыватель, который обрабатывает cookies, или чтобы получить открыватель, который не обрабатывает перенаправления.
Чтобы создать открывалку, инстанцируйте OpenerDirector, а затем многократно вызывайте .add_handler(some_handler_instance).
В качестве альтернативы можно использовать build_opener, которая является удобной функцией для создания объектов-открывателей с помощью одного вызова функции. build_opener добавляет несколько обработчиков по умолчанию, но предоставляет быстрый способ добавить больше и/или переопределить обработчики по умолчанию.
Другие виды обработчиков, которые вам могут понадобиться, могут обрабатывать прокси, аутентификацию и другие распространенные, но немного специализированные ситуации.
install_opener можно использовать для того, чтобы сделать объект opener открывателем (глобальным) по умолчанию. Это означает, что вызовы urlopen будут использовать установленный вами открыватель.
Объекты Opener имеют метод open, который можно вызвать непосредственно для получения урлов таким же образом, как и функцию urlopen: нет необходимости вызывать install_opener, кроме как для удобства.
Базовая аутентификация¶
Для иллюстрации создания и установки обработчика мы будем использовать HTTPBasicAuthHandler. Для более подробного обсуждения этой темы — включая объяснение того, как работает базовая аутентификация — смотрите Basic Authentication Tutorial.
Когда требуется аутентификация, сервер отправляет заголовок (а также код ошибки 401) с запросом на аутентификацию. В нем указывается схема аутентификации и «область». Заголовок выглядит следующим образом: WWW-Authenticate: SCHEME realm="REALM".
например.
WWW-Authenticate: Basic realm="cPanel Users"
Затем клиент должен повторить запрос с соответствующими именем и паролем для сферы, включенными в качестве заголовка в запрос. Это и есть «базовая аутентификация». Чтобы упростить этот процесс, мы можем создать экземпляр HTTPBasicAuthHandler и открывающее устройство для использования этого обработчика.
HTTPBasicAuthHandler использует объект, называемый менеджером паролей, для обработки сопоставления URL и царств с паролями и именами пользователей. Если вы знаете, что такое царство (из заголовка аутентификации, отправленного сервером), то вы можете использовать HTTPPasswordMgr. Часто бывает так, что человеку не важно, что такое царство. В этом случае удобно использовать HTTPPasswordMgrWithDefaultRealm. Это позволяет указать имя пользователя и пароль по умолчанию для URL. Они будут заданы в том случае, если вы не укажете альтернативную комбинацию для конкретного царства. Мы указываем это, предоставляя None в качестве аргумента realm для метода add_password.
URL верхнего уровня — это первый URL, который требует аутентификации. URL «глубже», чем URL, который вы передаете в .add_password(), также будут соответствовать.
# create a password manager password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm() # Add the username and password. # If we knew the realm, we could use it instead of None. top_level_url = "http://example.com/foo/" password_mgr.add_password(None, top_level_url, username, password) handler = urllib.request.HTTPBasicAuthHandler(password_mgr) # create "opener" (OpenerDirector instance) opener = urllib.request.build_opener(handler) # use the opener to fetch a URL opener.open(a_url) # Install the opener. # Now all calls to urllib.request.urlopen use our opener. urllib.request.install_opener(opener)
Примечание
В приведенном выше примере мы только передали наш HTTPBasicAuthHandler в build_opener. По умолчанию открыватели имеют обработчики для обычных ситуаций – ProxyHandler (если установлена прокси-настройка, такая как переменная окружения http_proxy), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, DataHandler, HTTPErrorProcessor.
top_level_url фактически является либо полным URL (включая компонент схемы „http:“, имя хоста и, опционально, номер порта), например "http://example.com/" или «авторитетом» (т.е. именем хоста, опционально включая номер порта), например "example.com" или "example.com:8080" (последний пример включает номер порта). Авторитет, если он присутствует, НЕ должен содержать компонент «userinfo» — например, "joe:password@example.com" не является корректным.
Прокси¶
urllib будет автоматически определять ваши настройки прокси и использовать их. Это происходит через ProxyHandler, который является частью обычной цепочки обработчиков при обнаружении настроек прокси. Обычно это хорошо, но бывают случаи, когда это может быть бесполезно 5. Один из способов сделать это — установить собственный ProxyHandler, без определенных прокси. Это делается с помощью шагов, аналогичных настройке обработчика Basic Authentication:
>>> proxy_support = urllib.request.ProxyHandler({}) >>> opener = urllib.request.build_opener(proxy_support) >>> urllib.request.install_opener(opener)
Примечание
В настоящее время urllib.request не поддерживает получение расположений https через прокси. Однако это можно сделать, расширив urllib.request, как показано в рецепте 6.
Примечание
HTTP_PROXY будет игнорироваться, если установлена переменная REQUEST_METHOD; см. документацию по getproxies().
Сокеты и слои¶
Поддержка Python для получения ресурсов из Интернета многоуровневая. urllib использует библиотеку http.client, которая, в свою очередь, использует библиотеку сокетов.
Начиная с версии Python 2.3 вы можете указать, как долго сокет должен ждать ответа, прежде чем завершится тайминг. Это может быть полезно в приложениях, которые должны получать веб-страницы. По умолчанию модуль сокета имеет без таймаута и может зависнуть. В настоящее время таймаут сокета не раскрывается на уровнях http.client или urllib.request. Однако вы можете установить таймаут по умолчанию глобально для всех сокетов, используя
import socket import urllib.request # timeout in seconds timeout = 10 socket.setdefaulttimeout(timeout) # this call to urllib.request.urlopen now uses the default timeout # we have set in the socket module req = urllib.request.Request('http://www.voidspace.org.uk') response = urllib.request.urlopen(req)
Сноски¶
Этот документ был проверен и отредактирован Джоном Ли.
- 1
-
Например, Google.
- 2
-
Браузерный сниффинг — это очень плохая практика для дизайна сайтов — создание сайтов с использованием веб-стандартов гораздо более разумно. К сожалению, многие сайты все еще отправляют разные версии в разные браузеры.
- 3
-
Агент пользователя для MSIE 6 — „Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)“.
- 4
-
Для получения подробной информации о других заголовках HTTP-запросов смотрите Quick Reference to HTTP Headers.
- 5
-
В моем случае я вынужден использовать прокси-сервер для доступа в Интернет на работе. Если вы пытаетесь получить URL localhost через этот прокси, он блокирует их. IE настроен на использование прокси, и urllib это замечает. Чтобы протестировать скрипты с сервером localhost, я должен запретить urllib использовать прокси.
- 6
-
urllib-открывалка для SSL-прокси (метод CONNECT): ASPN Cookbook Recipe.