SF Patch 549151: urllib2 POSTs on redirect

(contributed by John J Lee)

2 files changed, 47 insertions, 11 deletions

diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
index c458616..a36df6b 100644
--- a/Doc/lib/liburllib.tex
+++ b/Doc/lib/liburllib.tex
@@ -254,12 +254,18 @@ actually retrieve a resource at an \file{https:} URL.
 
 \begin{classdesc}{FancyURLopener}{...}
 \class{FancyURLopener} subclasses \class{URLopener} providing default
-handling for the following HTTP response codes: 301, 302 or 401.  For
-301 and 302 response codes, the \mailheader{Location} header is used to
-fetch the actual URL.  For 401 response codes (authentication
-required), basic HTTP authentication is performed.  For 301 and 302 response
-codes, recursion is bounded by the value of the \var{maxtries} attribute,
-which defaults 10.
+handling for the following HTTP response codes: 301, 302, 303 and 401.
+For 301, 302 and 303 response codes, the \mailheader{Location} header
+is used to fetch the actual URL.  For 401 response codes
+(authentication required), basic HTTP authentication is performed.
+For 301, 302 and 303 response codes, recursion is bounded by the value
+of the \var{maxtries} attribute, which defaults 10.
+
+\note{According to the letter of \rfc{2616}, 301 and 302 responses to
+  POST requests must not be automatically redirected without
+  confirmation by the user.  In reality, browsers do allow automatic
+  redirection of these responses, changing the POST to a GET, and
+  \module{urllib} reproduces this behaviour.}
 
 The parameters to the constructor are the same as those for
 \class{URLopener}.
diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex
index 02a3cc3..9f279df 100644
--- a/Doc/lib/liburllib2.tex
+++ b/Doc/lib/liburllib2.tex
@@ -217,6 +217,12 @@ by all handlers except HTTP handlers --- and there it should be an
 request to be \code{POST} rather than \code{GET}. 
 \end{methoddesc}
 
+\begin{methoddesc}[Request]{get_method}{}
+Return a string indicating the HTTP request method.  This is only
+meaningful for HTTP requests, and currently always takes one of the
+values ("GET", "POST").
+\end{methoddesc}
+
 \begin{methoddesc}[Request]{has_data}{}
 Return whether the instance has a non-\code{None} data.
 \end{methoddesc}
@@ -394,25 +400,49 @@ Arguments, return values and exceptions raised should be the same as
 for \method{http_error_default()}.
 \end{methoddesc}
 
-
 \subsection{HTTPRedirectHandler Objects \label{http-redirect-handler}}
 
-\note{303 redirection is not supported by this version of 
-\module{urllib2}.}
+\note{Some HTTP redirections require action from this module's client
+  code.  If this is the case, \exception{HTTPError} is raised.  See
+  \rfc{2616} for details of the precise meanings of the various
+  redirection codes.}
+
+\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req,
+                                                  fp, code, msg, hdrs}
+Return a \class{Request} or \code{None} in response to a redirect.
+This is called by the default implementations of the
+\code{http_error_30x()} methods when a redirection is received from
+the server.  If a redirection should take place, return a new
+\class{Request} to allow \code{http_error_30x()} to perform the
+redirect.  Otherwise, raise \exception{HTTPError} if no other
+\class{Handler} should try to handle this URL, or return \code{None}
+if you can't but another \class{Handler} might.
+
+\note{The default implementation of this method does not strictly
+ follow \rfc{2616}: it allows automatic 302 redirection of POST
+ requests, because essentially all HTTP clients do this.}
+
+\end{methoddesc}
+
 
 \begin{methoddesc}[HTTPRedirectHandler]{http_error_301}{req,
                                                   fp, code, msg, hdrs}
 Redirect to the \code{Location:} URL.  This method is called by
 the parent \class{OpenerDirector} when getting an HTTP
-permanent-redirect response.
+`moved permanently' response.
 \end{methoddesc}
 
 \begin{methoddesc}[HTTPRedirectHandler]{http_error_302}{req,
                                                   fp, code, msg, hdrs}
 The same as \method{http_error_301()}, but called for the
-temporary-redirect response.
+`found' response.
 \end{methoddesc}
 
+\begin{methoddesc}[HTTPRedirectHandler]{http_error_303}{req,
+                                                  fp, code, msg, hdrs}
+The same as \method{http_error_301()}, but called for the
+`see other' redirect response.
+\end{methoddesc}
 
 \subsection{ProxyHandler Objects \label{proxy-handler}}