From 399bc8c2816caa330c14b705b067b2dd669d912d Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 9 Nov 2001 03:49:29 +0000 Subject: [PATCH] Fix a variety of typographical, grammatical, and clarity problems reported by Detlef Lannert. --- Doc/lib/liburllib2.tex | 116 ++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 54 deletions(-) diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex index 46d4f66ca5b..02a3cc3795a 100644 --- a/Doc/lib/liburllib2.tex +++ b/Doc/lib/liburllib2.tex @@ -15,7 +15,7 @@ authentication, redirections and more. The \module{urllib2} module defines the following functions: \begin{funcdesc}{urlopen}{url\optional{, data}} -Open the url \var{url}, which can either a string or a \class{Request} +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}). @@ -37,7 +37,7 @@ Raises \exception{URLError} on errors. \end{funcdesc} \begin{funcdesc}{install_opener}{opener} -Install a \class{OpenerDirector} instance as the default 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. \end{funcdesc} @@ -47,8 +47,8 @@ Return an \class{OpenerDirector} instance, which chains the handlers in the order given. \var{handler}s can be either instances 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 +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: \code{ProxyHandler, UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, @@ -62,8 +62,8 @@ exists), \class{HTTPSHandler} will also be added. The following exceptions are raised as appropriate: \begin{excdesc}{URLError} -The error handlers raise when they run into a problem. It is a -subclass of \exception{IOError}. +The handlers raise this exception (or derived exceptions) when they +run into a problem. It is a subclass of \exception{IOError}. \end{excdesc} \begin{excdesc}{HTTPError} @@ -84,7 +84,7 @@ The following classes are provided: \begin{classdesc}{Request}{url\optional{, data\optional{, headers}}} This class is an abstraction of a URL request. -\var{url} should be a string which is a valid URL. For descrtion +\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 \method{add_header()} was called with each key and value as arguments. @@ -134,41 +134,45 @@ if no other realm fits. \begin{classdesc}{AbstractBasicAuthHandler}{\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. +\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. -Valid \var{password_mgr}, if given, are the same as for -\class{AbstractBasicAuthHandler}. +\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. -Valid \var{password_mgr}, if given, are the same as for -\class{AbstractBasicAuthHandler}. +\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 +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. +\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. -Valid \var{password_mgr}, if given, are the same as for -\class{AbstractBasicAuthHandler}. +\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, shoudl be the same as for -the constructor of \class{AbstractDigestAuthHandler}. +\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}{HTTPHandler}{} @@ -207,28 +211,28 @@ The following methods describe all of \class{Request}'s public interface, and so all must be overridden in subclasses. \begin{methoddesc}[Request]{add_data}{data} -Set the \class{Request} data to \var{data} is ignored +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 then \code{GET}. +request to be \code{POST} rather than \code{GET}. \end{methoddesc} -\begin{methoddesc}[Request]{has_data}{data} +\begin{methoddesc}[Request]{has_data}{} Return whether the instance has a non-\code{None} data. \end{methoddesc} -\begin{methoddesc}[Request]{get_data}{data} +\begin{methoddesc}[Request]{get_data}{} Return the instance's data. \end{methoddesc} \begin{methoddesc}[Request]{add_header}{key, val} 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 +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 then once have a (header-specific) way of gaining the +when used more than once have a (header-specific) way of gaining the same functionality using only one header. \end{methoddesc} @@ -241,7 +245,7 @@ Return the type of the URL --- also known as the scheme. \end{methoddesc} \begin{methoddesc}[Request]{get_host}{} -Return the host to which connection will be made. +Return the host to which a connection will be made. \end{methoddesc} \begin{methoddesc}[Request]{get_selector}{} @@ -250,8 +254,8 @@ the server. \end{methoddesc} \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 +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} @@ -277,13 +281,13 @@ following methods are searched, and added to the possible chains. Explicitly break cycles, and delete all the handlers. 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 +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. \end{methoddesc} \begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}} -Open the given \var{url}. (which can be a request object or a string), +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 of \function{urlopen()} (which simply calls the \method{open()} method @@ -292,9 +296,11 @@ on the default installed \class{OpenerDirector}. \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). +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 of \function{urlopen()}. @@ -315,7 +321,7 @@ Add a director as parent. Remove any parents. \end{methoddesc} -The following members and methods should be used only be classes +The following members and methods should only be used by classes derived from \class{BaseHandler}: \begin{memberdesc}[BaseHandler]{parent} @@ -327,13 +333,13 @@ different protocol, or handle errors. This method is \emph{not} defined in \class{BaseHandler}, but subclasses should define it if they want to catch all URLs. -This method, if exists, will be called by the \member{parent} +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 +\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}. +\exception{URLError}). This method will be called before any protocol-specific open method. \end{methoddesc} @@ -343,7 +349,7 @@ This method is \emph{not} defined in \class{BaseHandler}, but subclasses should define it if they want to handle URLs with the given protocol. -This method, if defined, will be called by the \member{parent} +This method, if defined, will be called by the parent \class{OpenerDirector}. Return values should be the same as for \method{default_open()}. \end{methoddescni} @@ -351,9 +357,9 @@ This method, if defined, will be called by the \member{parent} \begin{methoddesc}[BaseHandler]{unknown_open}{req} 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. +specific registered handler to open it. -This method, if exists, will be called by the \member{parent} +This method, if implemented, will be called by the \member{parent} \class{OpenerDirector}. Return values should be the same as for \method{default_open()}. \end{methoddesc} @@ -448,10 +454,12 @@ user/password. \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. +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} @@ -460,7 +468,7 @@ the realm, \var{host} is the host to authenticate too, \var{req} should be the \begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code, msg, hdrs} -Retry the request with authentication info, if available. +Retry the request with authentication information, if available. \end{methoddesc} @@ -469,7 +477,7 @@ Retry the request with authentication info, if available. \begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code, msg, hdrs} -Retry the request with authentication info, if available. +Retry the request with authentication information, if available. \end{methoddesc} @@ -479,9 +487,9 @@ Retry the request with authentication info, if available. \begin{methoddesc}[AbstractDigestAuthHandler]{handle_authentication_request} {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. +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} @@ -490,7 +498,7 @@ error headers. \begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code, msg, hdrs} -Retry the request with authentication info, if available. +Retry the request with authentication information, if available. \end{methoddesc} @@ -506,7 +514,7 @@ Retry the request with authentication information, if available. \subsection{HTTPHandler Objects \label{http-handler-objects}} \begin{methoddesc}[HTTPHandler]{http_open}{req} -Send an HTTP request, whcih can be either GET or POST, depending on +Send an HTTP request, which can be either GET or POST, depending on \code{\var{req}.has_data()}. \end{methoddesc}