diff options
Diffstat (limited to 'Doc/liburllib.tex')
| -rw-r--r-- | Doc/liburllib.tex | 103 |
1 files changed, 51 insertions, 52 deletions
diff --git a/Doc/liburllib.tex b/Doc/liburllib.tex index 8e7decf..01fc875 100644 --- a/Doc/liburllib.tex +++ b/Doc/liburllib.tex @@ -5,59 +5,59 @@ \index{World-Wide Web} \index{URL} -\setindexsubitem{(in module urllib)} This module provides a high-level interface for fetching data across -the World-Wide Web. In particular, the \code{urlopen()} function is -similar to the built-in function \code{open()}, but accepts URLs -(Universal Resource Locators) instead of filenames. Some restrictions -apply --- it can only open URLs for reading, and no seek operations -are available. +the World-Wide Web. In particular, the \function{urlopen()} function +is similar to the built-in function \function{open()}, but accepts +Universal Resource Locators (URLs) instead of filenames. Some +restrictions apply --- it can only open URLs for reading, and no seek +operations are available. It defines the following public functions: \begin{funcdesc}{urlopen}{url} Open a network object denoted by a URL for reading. If the URL does -not have a scheme identifier, or if it has \samp{file:} as its scheme +not have a scheme identifier, or if it has \file{file:} as its scheme identifier, this opens a local file; otherwise it opens a socket to a server somewhere on the network. If the connection cannot be made, or -if the server returns an error code, the \code{IOError} exception is -raised. If all went well, a file-like object is returned. This -supports the following methods: \code{read()}, \code{readline()}, -\code{readlines()}, \code{fileno()}, \code{close()} and \code{info()}. +if the server returns an error code, the \exception{IOError} exception +is raised. If all went well, a file-like object is returned. This +supports the following methods: \method{read()}, \method{readline()}, +\method{readlines()}, \method{fileno()}, \method{close()} and +\method{info()}. Except for the last one, these methods have the same interface as for -file objects --- see the section on File Objects earlier in this -manual. (It's not a built-in file object, however, so it can't be +file objects --- see section \ref{bltin-file-objects} in this +manual. (It is not a built-in file object, however, so it can't be used at those few places where a true built-in file object is required.) -The \code{info()} method returns an instance of the class -\code{mimetools.Message} containing the headers received from the server, -if the protocol uses such headers (currently the only supported -protocol that uses this is HTTP). See the description of the -\code{mimetools} module. -\refstmodindex{mimetools} +The \method{info()} method returns an instance of the class +\class{mimetools.Message} containing the headers received from the +server, if the protocol uses such headers (currently the only +supported protocol that uses this is HTTP). See the description of +the \module{mimetools}\refstmodindex{mimetools} module. \end{funcdesc} \begin{funcdesc}{urlretrieve}{url} Copy a network object denoted by a URL to a local file, if necessary. If the URL points to a local file, or a valid cached copy of the -object exists, the object is not copied. Return a tuple (\var{filename}, -\var{headers}) where \var{filename} is the local file name under which -the object can be found, and \var{headers} is either \code{None} (for -a local object) or whatever the \code{info()} method of the object -returned by \code{urlopen()} returned (for a remote object, possibly -cached). Exceptions are the same as for \code{urlopen()}. +object exists, the object is not copied. Return a tuple +\code{(\var{filename}, \var{headers})} where \var{filename} is the +local file name under which the object can be found, and \var{headers} +is either \code{None} (for a local object) or whatever the +\method{info()} method of the object returned by \function{urlopen()} +returned (for a remote object, possibly cached). Exceptions are the +same as for \function{urlopen()}. \end{funcdesc} \begin{funcdesc}{urlcleanup}{} Clear the cache that may have been built up by previous calls to -\code{urlretrieve()}. +\function{urlretrieve()}. \end{funcdesc} \begin{funcdesc}{quote}{string\optional{\, addsafe}} -Replace special characters in \var{string} using the \code{\%xx} escape. -Letters, digits, and the characters ``\code{_,.-}'' are never quoted. +Replace special characters in \var{string} using the \samp{\%xx} escape. +Letters, digits, and the characters \character{_,.-} are never quoted. The optional \var{addsafe} parameter specifies additional characters that should not be quoted --- its default value is \code{'/'}. @@ -65,7 +65,7 @@ Example: \code{quote('/\~connolly/')} yields \code{'/\%7econnolly/'}. \end{funcdesc} \begin{funcdesc}{quote_plus}{string\optional{\, addsafe}} -Like \code{quote()}, but also replaces spaces by plus signs, as +Like \function{quote()}, but also replaces spaces by plus signs, as required for quoting HTML form values. \end{funcdesc} @@ -76,7 +76,7 @@ Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~connolly/'}. \end{funcdesc} \begin{funcdesc}{unquote_plus}{string} -Like \code{unquote()}, but also replaces plus signs by spaces, as +Like \function{unquote()}, but also replaces plus signs by spaces, as required for unquoting HTML form values. \end{funcdesc} @@ -87,13 +87,14 @@ Restrictions: \item Currently, only the following protocols are supported: HTTP, (versions 0.9 and 1.0), Gopher (but not Gopher-+), FTP, and local files. -\index{HTTP} -\index{Gopher} -\index{FTP} +\indexii{HTTP}{protocol} +\indexii{Gopher}{protocol} +\indexii{FTP}{protocol} \item -The caching feature of \code{urlretrieve()} has been disabled until I -find the time to hack proper processing of Expiration time headers. +The caching feature of \function{urlretrieve()} has been disabled +until I find the time to hack proper processing of Expiration time +headers. \item There should be a function to query whether a particular URL is in @@ -105,29 +106,27 @@ but the file can't be opened, the URL is re-interpreted using the FTP protocol. This can sometimes cause confusing error messages. \item -The \code{urlopen()} and \code{urlretrieve()} functions can cause -arbitrarily long delays while waiting for a network connection to be -set up. This means that it is difficult to build an interactive +The \function{urlopen()} and \function{urlretrieve()} functions can +cause arbitrarily long delays while waiting for a network connection +to be set up. This means that it is difficult to build an interactive web client using these functions without using threads. \item -The data returned by \code{urlopen()} or \code{urlretrieve()} is the -raw data returned by the server. This may be binary data (e.g. an -image), plain text or (for example) HTML. The HTTP protocol provides -type information in the reply header, which can be inspected by -looking at the \code{Content-type} header. For the Gopher protocol, +The data returned by \function{urlopen()} or \function{urlretrieve()} +is the raw data returned by the server. This may be binary data +(e.g. an image), plain text or (for example) HTML. The HTTP protocol +provides type information in the reply header, which can be inspected +by looking at the \code{content-type} header. For the Gopher protocol, type information is encoded in the URL; there is currently no easy way to extract it. If the returned data is HTML, you can use the module -\code{htmllib} to parse it. -\index{HTML}% -\index{HTTP}% -\index{Gopher}% -\refstmodindex{htmllib} +\module{htmllib}\refstmodindex{htmllib} to parse it. +\index{HTML} +\indexii{HTTP}{protocol} +\indexii{Gopher}{protocol} \item -Although the \code{urllib} module contains (undocumented) routines to -parse and unparse URL strings, the recommended interface for URL -manipulation is in module \code{urlparse}. -\refstmodindex{urlparse} +Although the \module{urllib} module contains (undocumented) routines +to parse and unparse URL strings, the recommended interface for URL +manipulation is in module \module{urlparse}\refstmodindex{urlparse}. \end{itemize} |