Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/liburllib.tex @ 5817:48b94de85bf3 legacy-trunk
Extensive changes by AMK.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Thu, 17 Jul 1997 16:29:42 +0000 |
| parents | 2077a32d858e |
| children | 3468ea8645ca |
| rev | line source |
|---|---|
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
1 \section{Standard Module \sectcode{urllib}} |
| 2355 | 2 \stmodindex{urllib} |
| 3 \index{WWW} | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
4 \index{World-Wide Web} |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
5 \index{URL} |
| 2355 | 6 |
|
2453
cdd3a721b40e
a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents:
2446
diff
changeset
|
7 \renewcommand{\indexsubitem}{(in module urllib)} |
|
cdd3a721b40e
a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents:
2446
diff
changeset
|
8 |
| 2355 | 9 This module provides a high-level interface for fetching data across |
| 10 the World-Wide Web. In particular, the \code{urlopen} function is | |
| 11 similar to the built-in function \code{open}, but accepts URLs | |
| 12 (Universal Resource Locators) instead of filenames. Some restrictions | |
| 13 apply --- it can only open URLs for reading, and no seek operations | |
| 14 are available. | |
| 15 | |
| 16 it defines the following public functions: | |
| 17 | |
| 18 \begin{funcdesc}{urlopen}{url} | |
| 19 Open a network object denoted by a URL for reading. If the URL does | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
20 not have a scheme identifier, or if it has \samp{file:} as its scheme |
| 2355 | 21 identifier, this opens a local file; otherwise it opens a socket to a |
| 22 server somewhere on the network. If the connection cannot be made, or | |
| 23 if the server returns an error code, the \code{IOError} exception is | |
| 24 raised. If all went well, a file-like object is returned. This | |
| 25 supports the following methods: \code{read()}, \code{readline()}, | |
| 26 \code{readlines()}, \code{fileno()}, \code{close()} and \code{info()}. | |
| 27 Except for the last one, these methods have the same interface as for | |
| 28 file objects --- see the section on File Objects earlier in this | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
29 manual. (It's not a built-in file object, however, so it can't be |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
30 used at those few places where a true built-in file object is |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
31 required.) |
| 2355 | 32 |
| 33 The \code{info()} method returns an instance of the class | |
|
5686
2077a32d858e
It's now using mimetools instead of rfc822
Guido van Rossum <guido@python.org>
parents:
4716
diff
changeset
|
34 \code{mimetools.Message} containing the headers received from the server, |
| 2355 | 35 if the protocol uses such headers (currently the only supported |
| 36 protocol that uses this is HTTP). See the description of the | |
|
5686
2077a32d858e
It's now using mimetools instead of rfc822
Guido van Rossum <guido@python.org>
parents:
4716
diff
changeset
|
37 \code{mimetools} module. |
| 2355 | 38 \end{funcdesc} |
| 39 | |
| 40 \begin{funcdesc}{urlretrieve}{url} | |
| 41 Copy a network object denoted by a URL to a local file, if necessary. | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
42 If the URL points to a local file, or a valid cached copy of the |
| 2355 | 43 object exists, the object is not copied. Return a tuple (\var{filename}, |
| 44 \var{headers}) where \var{filename} is the local file name under which | |
| 45 the object can be found, and \var{headers} is either \code{None} (for | |
| 46 a local object) or whatever the \code{info()} method of the object | |
| 47 returned by \code{urlopen()} returned (for a remote object, possibly | |
| 48 cached). Exceptions are the same as for \code{urlopen()}. | |
| 49 \end{funcdesc} | |
| 50 | |
| 51 \begin{funcdesc}{urlcleanup}{} | |
| 52 Clear the cache that may have been built up by previous calls to | |
| 53 \code{urlretrieve()}. | |
| 54 \end{funcdesc} | |
| 55 | |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
56 \begin{funcdesc}{quote}{string\optional{\, addsafe}} |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
57 Replace special characters in \var{string} using the \code{\%xx} escape. |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
58 Letters, digits, and the characters ``\code{_,.-}'' are never quoted. |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
59 The optional \var{addsafe} parameter specifies additional characters |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
60 that should not be quoted --- its default value is \code{'/'}. |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
61 |
|
4716
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
62 Example: \code{quote('/\~connolly/')} yields \code{'/\%7econnolly/'}. |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
63 \end{funcdesc} |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
64 |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
65 \begin{funcdesc}{quote_plus}{string\optional{\, addsafe}} |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
66 Like \code{quote()}, but also replaces spaces by plus signs, as |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
67 required for quoting HTML form values. |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
68 \end{funcdesc} |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
69 |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
70 \begin{funcdesc}{unquote}{string} |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
71 Replace \samp{\%xx} escapes by their single-character equivalent. |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
72 |
|
2453
cdd3a721b40e
a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents:
2446
diff
changeset
|
73 Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~connolly/'}. |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
74 \end{funcdesc} |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
75 |
|
4716
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
76 \begin{funcdesc}{unquote_plus}{string} |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
77 Like \code{unquote()}, but also replaces plus signs by spaces, as |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
78 required for unquoting HTML form values. |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
79 \end{funcdesc} |
|
a8a547490a12
Added quote_plus() and unquote_plus(), to do space/plus substitutions
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
80 |
| 2355 | 81 Restrictions: |
| 82 | |
| 83 \begin{itemize} | |
| 84 | |
| 85 \item | |
| 86 Currently, only the following protocols are supported: HTTP, (versions | |
| 87 0.9 and 1.0), Gopher (but not Gopher-+), FTP, and local files. | |
| 88 \index{HTTP} | |
| 89 \index{Gopher} | |
| 90 \index{FTP} | |
| 91 | |
| 92 \item | |
| 93 The caching feature of \code{urlretrieve()} has been disabled until I | |
| 94 find the time to hack proper processing of Expiration time headers. | |
| 95 | |
| 96 \item | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
97 There should be a function to query whether a particular URL is in |
| 2355 | 98 the cache. |
| 99 | |
| 100 \item | |
| 101 For backward compatibility, if a URL appears to point to a local file | |
| 102 but the file can't be opened, the URL is re-interpreted using the FTP | |
| 103 protocol. This can sometimes cause confusing error messages. | |
| 104 | |
| 105 \item | |
| 106 The \code{urlopen()} and \code{urlretrieve()} functions can cause | |
| 107 arbitrarily long delays while waiting for a network connection to be | |
| 108 set up. This means that it is difficult to build an interactive | |
| 109 web client using these functions without using threads. | |
| 110 | |
| 111 \item | |
| 112 The data returned by \code{urlopen()} or \code{urlretrieve()} is the | |
| 113 raw data returned by the server. This may be binary data (e.g. an | |
| 114 image), plain text or (for example) HTML. The HTTP protocol provides | |
| 115 type information in the reply header, which can be inspected by | |
| 116 looking at the \code{Content-type} header. For the Gopher protocol, | |
| 117 type information is encoded in the URL; there is currently no easy way | |
| 118 to extract it. If the returned data is HTML, you can use the module | |
| 119 \code{htmllib} to parse it. | |
| 120 \index{HTML} | |
| 121 \index{HTTP} | |
| 122 \index{Gopher} | |
| 123 \stmodindex{htmllib} | |
| 124 | |
| 125 \item | |
| 126 Although the \code{urllib} module contains (undocumented) routines to | |
| 127 parse and unparse URL strings, the recommended interface for URL | |
| 128 manipulation is in module \code{urlparse}. | |
| 129 \stmodindex{urlparse} | |
| 130 | |
| 131 \end{itemize} |