Added warning that FancyURLopener prompts the user on the terminal when

basic authentication is needed.

Added documentation for FancyURLopener.prompt_user_passwd(), explaining
that subclasses should provide more appropriate behavior for the hosting
environment.

1 files changed, 21 insertions, 0 deletions

diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
index 7b50924..788b91b 100644
--- a/Doc/lib/liburllib.tex
+++ b/Doc/lib/liburllib.tex
@@ -211,6 +211,13 @@ which defaults 10.
 
 The parameters to the constructor are the same as those for
 \class{URLopener}.
+
+\strong{Note:}  When performing basic authentication, a
+\class{FancyURLopener} instance calls its
+\method{prompt_user_passwd()} method.  The default implementation asks
+the users for the required information on the controlling terminal.  A
+subclass may override this method to support more appropriate behavior
+if needed.
 \end{classdesc}
 
 Restrictions:
@@ -315,6 +322,20 @@ set this in a subclass as a class variable or in the constructor
 before calling the base constructor.
 \end{memberdesc}
 
+The \class{FancyURLopener} class offers one additional method that
+should be overloaded to provide the appropriate behavior:
+
+\begin{methoddesc}[FancyURLopener]{prompt_user_passwd}{host, realm}
+Return information needed to authenticate the user at the given host
+in the specified security realm.  The return value should be a tuple,
+\code{(\var{user}, \var{password})}, which can be used for basic
+authentication.
+
+The implementation prompts for this information on the terminal; an
+application should override this method to use an appropriate
+interaction model in the local environment.
+\end{methoddesc}
+
 
 \subsection{Examples}
 \nodename{Urllib Examples}