From dfca4dc503b884ddd544a670d1b23b56bb315cfd Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 25 Aug 2000 05:13:42 +0000 Subject: Revised documentation relevant to SourceForge patch #100837 (simplify making HTTP POST requests). Added documentation of URLopener.version and how it can be overridden. --- Doc/lib/liburllib.tex | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex index a41f728..06b4a7a 100644 --- a/Doc/lib/liburllib.tex +++ b/Doc/lib/liburllib.tex @@ -1,5 +1,5 @@ \section{\module{urllib} --- - Open an arbitrary resource by URL} + Open arbitrary resources by URL} \declaremodule{standard}{urllib} \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. \end{funcdesc} -The public functions \function{urlopen()} and \function{urlretrieve()} -create an instance of the \class{FancyURLopener} class and use it to perform -their requested actions. To override this functionality, programmers can -create a subclass of \class{URLopener} or \class{FancyURLopener}, then -assign that class to the \var{urllib._urlopener} variable before calling the -desired function. For example, applications may want to specify a different +The public functions \function{urlopen()} and +\function{urlretrieve()} create an instance of the +\class{FancyURLopener} class and use it to perform their requested +actions. To override this functionality, programmers can create a +subclass of \class{URLopener} or \class{FancyURLopener}, then assign +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 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 define their own \code{user-agent} header by subclassing \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. 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} \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 up cache and proxy information, then calls the appropriate open method with 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()}. \end{methoddesc} -\begin{methoddesc}{open_unknown}{fullurl\optional{, data}} +\begin{methoddesc}[URLopener]{open_unknown}{fullurl\optional{, data}} Overridable interface to open unknown URL types. \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 return value is a tuple consisting of a local filename and either a \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. \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} \nodename{Urllib Examples} -- cgit v0.12