[Python-checkins] CVS: python/dist/src/Doc/lib liburllib2.tex,1.5,1.6
Fred L. Drake
fdrake@users.sourceforge.net
Thu, 08 Nov 2001 19:49:31 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv9093/lib
Modified Files:
liburllib2.tex
Log Message:
Fix a variety of typographical, grammatical, and clarity problems reported
by Detlef Lannert.
Index: liburllib2.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liburllib2.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** liburllib2.tex 2001/10/20 04:24:09 1.5
--- liburllib2.tex 2001/11/09 03:49:29 1.6
***************
*** 16,20 ****
\begin{funcdesc}{urlopen}{url\optional{, data}}
! Open the url \var{url}, which can either a string or a \class{Request}
object (currently the code checks that it really is a \class{Request}
instance, or an instance of a subclass of \class{Request}).
--- 16,20 ----
\begin{funcdesc}{urlopen}{url\optional{, data}}
! Open the URL \var{url}, which can be either a string or a \class{Request}
object (currently the code checks that it really is a \class{Request}
instance, or an instance of a subclass of \class{Request}).
***************
*** 38,42 ****
\begin{funcdesc}{install_opener}{opener}
! Install a \class{OpenerDirector} instance as the default opener.
The code does not check for a real \class{OpenerDirector}, and any
class with the appropriate interface will work.
--- 38,42 ----
\begin{funcdesc}{install_opener}{opener}
! Install an \class{OpenerDirector} instance as the default opener.
The code does not check for a real \class{OpenerDirector}, and any
class with the appropriate interface will work.
***************
*** 48,53 ****
of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in
which case it must be possible to call the constructor without
! any parameters. Instances of the following classes will be in
! the front of the \var{handler}s, unless the \var{handler}s contain
them, instances of them or subclasses of them:
--- 48,53 ----
of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in
which case it must be possible to call the constructor without
! any parameters). Instances of the following classes will be in
! front of the \var{handler}s, unless the \var{handler}s contain
them, instances of them or subclasses of them:
***************
*** 63,68 ****
\begin{excdesc}{URLError}
! The error handlers raise when they run into a problem. It is a
! subclass of \exception{IOError}.
\end{excdesc}
--- 63,68 ----
\begin{excdesc}{URLError}
! The handlers raise this exception (or derived exceptions) when they
! run into a problem. It is a subclass of \exception{IOError}.
\end{excdesc}
***************
*** 85,89 ****
This class is an abstraction of a URL request.
! \var{url} should be a string which is a valid URL. For descrtion
of \var{data} see the \method{add_data()} description.
\var{headers} should be a dictionary, and will be treated as if
--- 85,89 ----
This class is an abstraction of a URL request.
! \var{url} should be a string which is a valid URL. For a description
of \var{data} see the \method{add_data()} description.
\var{headers} should be a dictionary, and will be treated as if
***************
*** 135,173 ****
This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
!
! \var{password_mgr} should be something that is compatible with
! \class{HTTPPasswordMgr} --- supplies the documented interface above.
\end{classdesc}
\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}}
Handle authentication with the remote host.
! Valid \var{password_mgr}, if given, are the same as for
! \class{AbstractBasicAuthHandler}.
\end{classdesc}
\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}}
Handle authentication with the proxy.
! Valid \var{password_mgr}, if given, are the same as for
! \class{AbstractBasicAuthHandler}.
\end{classdesc}
\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}}
! This is a mixin class, that helps with HTTP authentication, both
to the remote host and to a proxy.
!
! \var{password_mgr} should be something that is compatible with
! \class{HTTPPasswordMgr} --- supplies the documented interface above.
\end{classdesc}
\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}}
Handle authentication with the remote host.
! Valid \var{password_mgr}, if given, are the same as for
! \class{AbstractBasicAuthHandler}.
\end{classdesc}
\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}}
Handle authentication with the proxy.
! \var{password_mgr}, if given, shoudl be the same as for
! the constructor of \class{AbstractDigestAuthHandler}.
\end{classdesc}
--- 135,177 ----
This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
! \var{password_mgr}, if given, should be something that is compatible
! with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
! for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}}
Handle authentication with the remote host.
! \var{password_mgr}, if given, should be something that is compatible
! with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
! for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}}
Handle authentication with the proxy.
! \var{password_mgr}, if given, should be something that is compatible
! with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
! for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}}
! This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
! \var{password_mgr}, if given, should be something that is compatible
! with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
! for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}}
Handle authentication with the remote host.
! \var{password_mgr}, if given, should be something that is compatible
! with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
! for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}}
Handle authentication with the proxy.
! \var{password_mgr}, if given, should be something that is compatible
! with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
! for information on the interface that must be supported.
\end{classdesc}
***************
*** 208,222 ****
\begin{methoddesc}[Request]{add_data}{data}
! Set the \class{Request} data to \var{data} is ignored
by all handlers except HTTP handlers --- and there it should be an
\mimetype{application/x-www-form-encoded} buffer, and will change the
! request to be \code{POST} rather then \code{GET}.
\end{methoddesc}
! \begin{methoddesc}[Request]{has_data}{data}
Return whether the instance has a non-\code{None} data.
\end{methoddesc}
! \begin{methoddesc}[Request]{get_data}{data}
Return the instance's data.
\end{methoddesc}
--- 212,226 ----
\begin{methoddesc}[Request]{add_data}{data}
! Set the \class{Request} data to \var{data}. This is ignored
by all handlers except HTTP handlers --- and there it should be an
\mimetype{application/x-www-form-encoded} buffer, and will change the
! request to be \code{POST} rather than \code{GET}.
\end{methoddesc}
! \begin{methoddesc}[Request]{has_data}{}
Return whether the instance has a non-\code{None} data.
\end{methoddesc}
! \begin{methoddesc}[Request]{get_data}{}
Return the instance's data.
\end{methoddesc}
***************
*** 225,233 ****
Add another header to the request. Headers are currently ignored by
all handlers except HTTP handlers, where they are added to the list
! of headers sent to the server. Note that there cannot be more then
one header with the same name, and later calls will overwrite
previous calls in case the \var{key} collides. Currently, this is
no loss of HTTP functionality, since all headers which have meaning
! when used more then once have a (header-specific) way of gaining the
same functionality using only one header.
\end{methoddesc}
--- 229,237 ----
Add another header to the request. Headers are currently ignored by
all handlers except HTTP handlers, where they are added to the list
! of headers sent to the server. Note that there cannot be more than
one header with the same name, and later calls will overwrite
previous calls in case the \var{key} collides. Currently, this is
no loss of HTTP functionality, since all headers which have meaning
! when used more than once have a (header-specific) way of gaining the
same functionality using only one header.
\end{methoddesc}
***************
*** 242,246 ****
\begin{methoddesc}[Request]{get_host}{}
! Return the host to which connection will be made.
\end{methoddesc}
--- 246,250 ----
\begin{methoddesc}[Request]{get_host}{}
! Return the host to which a connection will be made.
\end{methoddesc}
***************
*** 251,256 ****
\begin{methoddesc}[Request]{set_proxy}{host, type}
! Make the request by connecting to a proxy server. The \var{host} and
! \var{type} will replace those of the instance, and the instance's
selector will be the original URL given in the constructor.
\end{methoddesc}
--- 255,260 ----
\begin{methoddesc}[Request]{set_proxy}{host, type}
! Prepare the request by connecting to a proxy server. The \var{host}
! and \var{type} will replace those of the instance, and the instance's
selector will be the original URL given in the constructor.
\end{methoddesc}
***************
*** 278,282 ****
Because the \class{OpenerDirector} needs to know the registered handlers,
and a handler needs to know who the \class{OpenerDirector} who called
! it is, there is a reference cycles. Even though recent versions of Python
have cycle-collection, it is sometimes preferable to explicitly break
the cycles.
--- 282,286 ----
Because the \class{OpenerDirector} needs to know the registered handlers,
and a handler needs to know who the \class{OpenerDirector} who called
! it is, there is a reference cycle. Even though recent versions of Python
have cycle-collection, it is sometimes preferable to explicitly break
the cycles.
***************
*** 284,288 ****
\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}}
! Open the given \var{url}. (which can be a request object or a string),
optionally passing the given \var{data}.
Arguments, return values and exceptions raised are the same as those
--- 288,292 ----
\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}}
! Open the given \var{url} (which can be a request object or a string),
optionally passing the given \var{data}.
Arguments, return values and exceptions raised are the same as those
***************
*** 293,299 ****
\begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
arg\optional{, \moreargs}}}
! Handle an error in a given protocol. The HTTP protocol is special cased to
! use the code as the error. This will call the registered error handlers
! for the given protocol with the given arguments (which are protocol specific).
Return values and exceptions raised are the same as those
--- 297,305 ----
\begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
arg\optional{, \moreargs}}}
! Handle an error in a given protocol. This will call the registered
! error handlers for the given protocol with the given arguments (which
! are protocol specific). The HTTP protocol is a special case which
! uses the HTTP response code to determine the specific error handler;
! refer to the \method{http_error_*()} methods of the handler classes.
Return values and exceptions raised are the same as those
***************
*** 316,320 ****
\end{methoddesc}
! The following members and methods should be used only be classes
derived from \class{BaseHandler}:
--- 322,326 ----
\end{methoddesc}
! The following members and methods should only be used by classes
derived from \class{BaseHandler}:
***************
*** 328,338 ****
subclasses should define it if they want to catch all URLs.
! This method, if exists, will be called by the \member{parent}
\class{OpenerDirector}. It should return a file-like object as
described in the return value of the \method{open()} of
! \class{OpenerDirector} or \code{None}. It should raise
\exception{URLError}, unless a truly exceptional thing happens (for
example, \exception{MemoryError} should not be mapped to
! \exception{URLError}.
This method will be called before any protocol-specific open method.
--- 334,344 ----
subclasses should define it if they want to catch all URLs.
! This method, if implemented, will be called by the parent
\class{OpenerDirector}. It should return a file-like object as
described in the return value of the \method{open()} of
! \class{OpenerDirector}, or \code{None}. It should raise
\exception{URLError}, unless a truly exceptional thing happens (for
example, \exception{MemoryError} should not be mapped to
! \exception{URLError}).
This method will be called before any protocol-specific open method.
***************
*** 344,348 ****
protocol.
! This method, if defined, will be called by the \member{parent}
\class{OpenerDirector}. Return values should be the same as for
\method{default_open()}.
--- 350,354 ----
protocol.
! This method, if defined, will be called by the parent
\class{OpenerDirector}. Return values should be the same as for
\method{default_open()}.
***************
*** 352,358 ****
This method is \var{not} defined in \class{BaseHandler}, but
subclasses should define it if they want to catch all URLs with no
! specific registerd handler to open it.
! This method, if exists, will be called by the \member{parent}
\class{OpenerDirector}. Return values should be the same as for
\method{default_open()}.
--- 358,364 ----
This method is \var{not} defined in \class{BaseHandler}, but
subclasses should define it if they want to catch all URLs with no
! specific registered handler to open it.
! This method, if implemented, will be called by the \member{parent}
\class{OpenerDirector}. Return values should be the same as for
\method{default_open()}.
***************
*** 449,456 ****
\begin{methoddesc}[AbstractBasicAuthHandler]{handle_authentication_request}
{authreq, host, req, headers}
! Handle an authentication request by getting user/password pair, and retrying.
! \var{authreq} should be the name of the header where the information about
! the realm, \var{host} is the host to authenticate too, \var{req} should be the
! (failed) \class{Request} object, and \var{headers} should be the error headers.
\end{methoddesc}
--- 455,464 ----
\begin{methoddesc}[AbstractBasicAuthHandler]{handle_authentication_request}
{authreq, host, req, headers}
! Handle an authentication request by getting a user/password pair, and
! re-trying the request. \var{authreq} should be the name of the header
! where the information about the realm is included in the request,
! \var{host} is the host to authenticate to, \var{req} should be the
! (failed) \class{Request} object, and \var{headers} should be the error
! headers.
\end{methoddesc}
***************
*** 461,465 ****
\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code,
msg, hdrs}
! Retry the request with authentication info, if available.
\end{methoddesc}
--- 469,473 ----
\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code,
msg, hdrs}
! Retry the request with authentication information, if available.
\end{methoddesc}
***************
*** 470,474 ****
\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code,
msg, hdrs}
! Retry the request with authentication info, if available.
\end{methoddesc}
--- 478,482 ----
\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code,
msg, hdrs}
! Retry the request with authentication information, if available.
\end{methoddesc}
***************
*** 480,486 ****
{authreq, host, req, headers}
\var{authreq} should be the name of the header where the information about
! the realm, \var{host} should be the host to authenticate too, \var{req}
! should be the (failed) \class{Request} object, and \var{headers} should be the
! error headers.
\end{methoddesc}
--- 488,494 ----
{authreq, host, req, headers}
\var{authreq} should be the name of the header where the information about
! the realm is included in the request, \var{host} should be the host to
! authenticate to, \var{req} should be the (failed) \class{Request}
! object, and \var{headers} should be the error headers.
\end{methoddesc}
***************
*** 491,495 ****
\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code,
msg, hdrs}
! Retry the request with authentication info, if available.
\end{methoddesc}
--- 499,503 ----
\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code,
msg, hdrs}
! Retry the request with authentication information, if available.
\end{methoddesc}
***************
*** 507,511 ****
\begin{methoddesc}[HTTPHandler]{http_open}{req}
! Send an HTTP request, whcih can be either GET or POST, depending on
\code{\var{req}.has_data()}.
\end{methoddesc}
--- 515,519 ----
\begin{methoddesc}[HTTPHandler]{http_open}{req}
! Send an HTTP request, which can be either GET or POST, depending on
\code{\var{req}.has_data()}.
\end{methoddesc}