Mercurial > cpython-lru_cache-weakref
annotate Doc/liburllib.tex @ 4566:6403c94de50d legacy-trunk
Added safeguard against failure in __del__.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Wed, 27 Nov 1996 19:39:58 +0000 |
| parents | f47bc5554418 |
| children | a8a547490a12 |
| 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 | |
| 34 \code{rfc822.Message} containing the headers received from the server, | |
| 35 if the protocol uses such headers (currently the only supported | |
| 36 protocol that uses this is HTTP). See the description of the | |
| 37 \code{rfc822} module. | |
| 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 |
|
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
|
62 Example: \code{quote('/\~conolly/')} yields \code{'/\%7econnolly/'}. |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
63 \end{funcdesc} |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
64 |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
65 \begin{funcdesc}{unquote}{string} |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
66 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
|
67 |
|
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
|
68 Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~connolly/'}. |
|
2446
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
69 \end{funcdesc} |
|
6f1211b2e077
added quote and unquote
Guido van Rossum <guido@python.org>
parents:
2355
diff
changeset
|
70 |
| 2355 | 71 Restrictions: |
| 72 | |
| 73 \begin{itemize} | |
| 74 | |
| 75 \item | |
| 76 Currently, only the following protocols are supported: HTTP, (versions | |
| 77 0.9 and 1.0), Gopher (but not Gopher-+), FTP, and local files. | |
| 78 \index{HTTP} | |
| 79 \index{Gopher} | |
| 80 \index{FTP} | |
| 81 | |
| 82 \item | |
| 83 The caching feature of \code{urlretrieve()} has been disabled until I | |
| 84 find the time to hack proper processing of Expiration time headers. | |
| 85 | |
| 86 \item | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
87 There should be a function to query whether a particular URL is in |
| 2355 | 88 the cache. |
| 89 | |
| 90 \item | |
| 91 For backward compatibility, if a URL appears to point to a local file | |
| 92 but the file can't be opened, the URL is re-interpreted using the FTP | |
| 93 protocol. This can sometimes cause confusing error messages. | |
| 94 | |
| 95 \item | |
| 96 The \code{urlopen()} and \code{urlretrieve()} functions can cause | |
| 97 arbitrarily long delays while waiting for a network connection to be | |
| 98 set up. This means that it is difficult to build an interactive | |
| 99 web client using these functions without using threads. | |
| 100 | |
| 101 \item | |
| 102 The data returned by \code{urlopen()} or \code{urlretrieve()} is the | |
| 103 raw data returned by the server. This may be binary data (e.g. an | |
| 104 image), plain text or (for example) HTML. The HTTP protocol provides | |
| 105 type information in the reply header, which can be inspected by | |
| 106 looking at the \code{Content-type} header. For the Gopher protocol, | |
| 107 type information is encoded in the URL; there is currently no easy way | |
| 108 to extract it. If the returned data is HTML, you can use the module | |
| 109 \code{htmllib} to parse it. | |
| 110 \index{HTML} | |
| 111 \index{HTTP} | |
| 112 \index{Gopher} | |
| 113 \stmodindex{htmllib} | |
| 114 | |
| 115 \item | |
| 116 Although the \code{urllib} module contains (undocumented) routines to | |
| 117 parse and unparse URL strings, the recommended interface for URL | |
| 118 manipulation is in module \code{urlparse}. | |
| 119 \stmodindex{urlparse} | |
| 120 | |
| 121 \end{itemize} |