[Python-checkins] r70817 - python/branches/py3k/Doc/library/urllib.request.rst
jeremy.hylton
python-checkins at python.org
Tue Mar 31 16:38:13 CEST 2009
Author: jeremy.hylton
Date: Tue Mar 31 16:38:13 2009
New Revision: 70817
Log:
Document public attributes of urllib.request.Request.
Modified:
python/branches/py3k/Doc/library/urllib.request.rst
Modified: python/branches/py3k/Doc/library/urllib.request.rst
==============================================================================
--- python/branches/py3k/Doc/library/urllib.request.rst (original)
+++ python/branches/py3k/Doc/library/urllib.request.rst Tue Mar 31 16:38:13 2009
@@ -3,7 +3,7 @@
.. module:: urllib.request
:synopsis: Next generation URL opening library.
-.. moduleauthor:: Jeremy Hylton <jhylton at users.sourceforge.net>
+.. moduleauthor:: Jeremy Hylton <jeremy at alum.mit.edu>
.. sectionauthor:: Moshe Zadka <moshez at users.sourceforge.net>
@@ -16,26 +16,28 @@
.. function:: urlopen(url[, data][, timeout])
- Open the URL *url*, which can be either a string or a :class:`Request` object.
+ Open the URL *url*, which can be either a string or a
+ :class:`Request` object.
- *data* may be a string specifying additional data to send to the server, or
- ``None`` if no such data is needed. Currently HTTP requests are the only ones
- that use *data*; the HTTP request will be a POST instead of a GET when the
- *data* parameter is provided. *data* should be a buffer in the standard
+ *data* may be a string specifying additional data to send to the
+ server, or ``None`` if no such data is needed. Currently HTTP
+ requests are the only ones that use *data*; the HTTP request will
+ be a POST instead of a GET when the *data* parameter is provided.
+ *data* should be a buffer in the standard
:mimetype:`application/x-www-form-urlencoded` format. The
:func:`urllib.parse.urlencode` function takes a mapping or sequence
of 2-tuples and returns a string in this format.
- The optional *timeout* parameter specifies a timeout in seconds for blocking
- operations like the connection attempt (if not specified, the global default
- timeout setting will be used). This actually only works for HTTP, HTTPS,
- FTP and FTPS connections.
+ The optional *timeout* parameter specifies a timeout in seconds for
+ blocking operations like the connection attempt (if not specified,
+ the global default timeout setting will be used). This actually
+ only works for HTTP, HTTPS, FTP and FTPS connections.
This function returns a file-like object with two additional methods from
the :mod:`urllib.response` module
- * :meth:`geturl` --- return the URL of the resource retrieved, commonly used to
- determine if a redirect was followed
+ * :meth:`geturl` --- return the URL of the resource retrieved,
+ commonly used to determine if a redirect was followed
* :meth:`info` --- return the meta-information of the page, such as headers,
in the form of an ``http.client.HTTPMessage`` instance (see `Quick
@@ -52,7 +54,6 @@
Proxy handling, which was done by passing a dictionary parameter to
``urllib.urlopen``, can be obtained by using :class:`ProxyHandler` objects.
-
.. function:: install_opener(opener)
Install an :class:`OpenerDirector` instance as the default global opener.
@@ -167,37 +168,42 @@
*url* should be a string containing a valid URL.
- *data* may be a string specifying additional data to send to the server, or
- ``None`` if no such data is needed. Currently HTTP requests are the only ones
- that use *data*; the HTTP request will be a POST instead of a GET when the
- *data* parameter is provided. *data* should be a buffer in the standard
+ *data* may be a string specifying additional data to send to the
+ server, or ``None`` if no such data is needed. Currently HTTP
+ requests are the only ones that use *data*; the HTTP request will
+ be a POST instead of a GET when the *data* parameter is provided.
+ *data* should be a buffer in the standard
:mimetype:`application/x-www-form-urlencoded` format. The
:func:`urllib.parse.urlencode` function takes a mapping or sequence
of 2-tuples and returns a string in this format.
- *headers* should be a dictionary, and will be treated as if :meth:`add_header`
- was called with each key and value as arguments. This is often used to "spoof"
- the ``User-Agent`` header, which is used by a browser to identify itself --
- some HTTP servers only allow requests coming from common browsers as opposed
- to scripts. For example, Mozilla Firefox may identify itself as ``"Mozilla/5.0
- (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"``, while :mod:`urllib`'s
- default user agent string is ``"Python-urllib/2.6"`` (on Python 2.6).
-
- The final two arguments are only of interest for correct handling of third-party
- HTTP cookies:
-
- *origin_req_host* should be the request-host of the origin transaction, as
- defined by :rfc:`2965`. It defaults to ``http.cookiejar.request_host(self)``.
- This is the host name or IP address of the original request that was
- initiated by the user. For example, if the request is for an image in an
- HTML document, this should be the request-host of the request for the page
+ *headers* should be a dictionary, and will be treated as if
+ :meth:`add_header` was called with each key and value as arguments.
+ This is often used to "spoof" the ``User-Agent`` header, which is
+ used by a browser to identify itself -- some HTTP servers only
+ allow requests coming from common browsers as opposed to scripts.
+ For example, Mozilla Firefox may identify itself as ``"Mozilla/5.0
+ (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"``, while
+ :mod:`urllib`'s default user agent string is
+ ``"Python-urllib/2.6"`` (on Python 2.6).
+
+ The final two arguments are only of interest for correct handling
+ of third-party HTTP cookies:
+
+ *origin_req_host* should be the request-host of the origin
+ transaction, as defined by :rfc:`2965`. It defaults to
+ ``http.cookiejar.request_host(self)``. This is the host name or IP
+ address of the original request that was initiated by the user.
+ For example, if the request is for an image in an HTML document,
+ this should be the request-host of the request for the page
containing the image.
- *unverifiable* should indicate whether the request is unverifiable, as defined
- by RFC 2965. It defaults to False. An unverifiable request is one whose URL
- the user did not have the option to approve. For example, if the request is for
- an image in an HTML document, and the user had no option to approve the
- automatic fetching of the image, this should be true.
+ *unverifiable* should indicate whether the request is unverifiable,
+ as defined by RFC 2965. It defaults to False. An unverifiable
+ request is one whose URL the user did not have the option to
+ approve. For example, if the request is for an image in an HTML
+ document, and the user had no option to approve the automatic
+ fetching of the image, this should be true.
.. class:: URLopener([proxies[, **x509]])
@@ -441,9 +447,41 @@
Request Objects
---------------
-The following methods describe all of :class:`Request`'s public interface, and
-so all must be overridden in subclasses.
+The following methods describe :class:`Request`'s public interface,
+and so all may be overridden in subclasses. It also defines several
+public attributes that can be used by clients to inspect the parsed
+request.
+
+.. attribute:: Request.full_url
+
+ The original URL passed to the constructor.
+
+.. attribute:: Request.type
+
+ The URI scheme.
+
+.. attribute:: Request.host
+
+ The URI authority, typically a host, but may also contain a port
+ separated by a colon.
+
+.. attribute:: Request.origin_req_host
+
+ The original host for the request, without port.
+
+.. attribute:: Request.selector
+
+ The URI path. If the :class:`Request` uses a proxy, then selector
+ will be the full url that is passed to the proxy.
+
+.. attribute:: Request.data
+
+ The entity body for the request, or None if not specified.
+
+.. attribute:: Request.unverifiable
+ boolean, indicates whether the request is unverifiable as defined
+ by RFC 2965.
.. method:: Request.add_data(data)
More information about the Python-checkins
mailing list