Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Revised documentation relevant to SourceForge patch #100837 

(simplify making HTTP POST requests).

Added documentation of URLopener.version and how it can be overridden.
This commit is contained in:
Fred Drake 2000-08-25 05:13:42 +00:00
parent 99a3701618
commit dfca4dc503
1 changed files with 23 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
Doc/lib/liburllib.tex
View File

@ -1,5 +1,5 @@
\section{\module{urllib} --- \section{\module{urllib} ---
Open an arbitrary resource by URL} Open arbitrary resources by URL}
\declaremodule{standard}{urllib} \declaremodule{standard}{urllib}
\modulesynopsis{Open an arbitrary network resource by URL (requires sockets).} \modulesynopsis{Open an arbitrary network resource by URL (requires sockets).}
@ -164,12 +164,14 @@ characters, where both \var{key} and \var{value} are quoted using
\function{quote_plus()} above. \function{quote_plus()} above.
\end{funcdesc} \end{funcdesc}
The public functions \function{urlopen()} and \function{urlretrieve()} The public functions \function{urlopen()} and
create an instance of the \class{FancyURLopener} class and use it to perform \function{urlretrieve()} create an instance of the
their requested actions. To override this functionality, programmers can \class{FancyURLopener} class and use it to perform their requested
create a subclass of \class{URLopener} or \class{FancyURLopener}, then actions. To override this functionality, programmers can create a
assign that class to the \var{urllib._urlopener} variable before calling the subclass of \class{URLopener} or \class{FancyURLopener}, then assign
desired function. For example, applications may want to specify a different that an instance of that class to the
\code{urllib._urlopener} variable before calling the desired function.
For example, applications may want to specify a different
\code{user-agent} header than \class{URLopener} defines. This can be \code{user-agent} header than \class{URLopener} defines. This can be
accomplished with the following code: accomplished with the following code:
@ -193,7 +195,7 @@ By default, the \class{URLopener} class sends a
\var{VVV} is the \module{urllib} version number. Applications can \var{VVV} is the \module{urllib} version number. Applications can
define their own \code{user-agent} header by subclassing define their own \code{user-agent} header by subclassing
\class{URLopener} or \class{FancyURLopener} and setting the instance \class{URLopener} or \class{FancyURLopener} and setting the instance
attribute \var{version} to an appropriate string value before the attribute \member{version} to an appropriate string value before the
\method{open()} method is called. \method{open()} method is called.
Additional keyword parameters, collected in \var{x509}, are used for Additional keyword parameters, collected in \var{x509}, are used for
@ -267,9 +269,9 @@ manipulation is in module \refmodule{urlparse}\refstmodindex{urlparse}.
\sectionauthor{Skip Montanaro}{skip@mojam.com} \sectionauthor{Skip Montanaro}{skip@mojam.com}
\class{URLopener} and \class{FancyURLopener} objects have the \class{URLopener} and \class{FancyURLopener} objects have the
following methods. following attributes.
\begin{methoddesc}{open}{fullurl\optional{, data}} \begin{methoddesc}[URLopener]{open}{fullurl\optional{, data}}
Open \var{fullurl} using the appropriate protocol. This method sets Open \var{fullurl} using the appropriate protocol. This method sets
up cache and proxy information, then calls the appropriate open method with up cache and proxy information, then calls the appropriate open method with
its input arguments. If the scheme is not recognized, its input arguments. If the scheme is not recognized,
@ -277,11 +279,13 @@ its input arguments. If the scheme is not recognized,
has the same meaning as the \var{data} argument of \function{urlopen()}. has the same meaning as the \var{data} argument of \function{urlopen()}.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{open_unknown}{fullurl\optional{, data}} \begin{methoddesc}[URLopener]{open_unknown}{fullurl\optional{, data}}
Overridable interface to open unknown URL types. Overridable interface to open unknown URL types.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{retrieve}{url\optional{, filename\optional{, reporthook}}} \begin{methoddesc}[URLopener]{retrieve}{url\optional{,
filename\optional{,
reporthook\optional{, data}}}}
Retrieves the contents of \var{url} and places it in \var{filename}. The Retrieves the contents of \var{url} and places it in \var{filename}. The
return value is a tuple consisting of a local filename and either a return value is a tuple consisting of a local filename and either a
\class{mimetools.Message} object containing the response headers (for remote \class{mimetools.Message} object containing the response headers (for remote
@ -302,6 +306,13 @@ must in standard \file{application/x-www-form-urlencoded} format;
see the \function{urlencode()} function below. see the \function{urlencode()} function below.
\end{methoddesc} \end{methoddesc}
\begin{memberdesc}[URLopener]{version}
Variable that specifies the user agent of the opener object. To get
\refmodule{urllib} to tell servers that it is a particular user agent,
set this in a subclass as a class variable or in the constructor
before calling the base constructor.
\end{memberdesc}
\subsection{Examples} \subsection{Examples}
\nodename{Urllib Examples} \nodename{Urllib Examples}