Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcodecs.tex @ 24042:63fbbed10714 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Simplify HTTPSConnection constructor. See discussion in SF bug 458463.
author Jeremy Hylton <jeremy@alum.mit.edu>
date Fri, 28 Jun 2002 23:38:14 +0000
parents 94aa4eb9bb7d
children 0337dad8403e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{codecs} ---
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
2 Codec registry and base classes}
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
4 \declaremodule{standard}{codecs}
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{Encode and decode data and streams.}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 \index{Unicode}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 \index{Codecs}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 \indexii{Codecs}{encode}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 \indexii{Codecs}{decode}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 \index{streams}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 \indexii{stackable}{streams}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 This module defines base classes for standard Python codecs (encoders
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 and decoders) and provides access to the internal Python codec
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 registry which manages the codec lookup process.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 It defines the following functions:
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 \begin{funcdesc}{register}{search_function}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 Register a codec search function. Search functions are expected to
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 take one argument, the encoding name in all lower case letters, and
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 return a tuple of functions \code{(\var{encoder}, \var{decoder}, \var{stream_reader},
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 \var{stream_writer})} taking the following arguments:
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 \var{encoder} and \var{decoder}: These must be functions or methods
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
31 which have the same interface as the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
32 \method{encode()}/\method{decode()} methods of Codec instances (see
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
33 Codec Interface). The functions/methods are expected to work in a
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
34 stateless mode.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 \var{stream_reader} and \var{stream_writer}: These have to be
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 factory functions providing the following interface:
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
39 \code{factory(\var{stream}, \var{errors}='strict')}
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 The factory functions must return objects providing the interfaces
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
42 defined by the base classes \class{StreamWriter} and
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
43 \class{StreamReader}, respectively. Stream codecs can maintain
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
44 state.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
46 Possible values for errors are \code{'strict'} (raise an exception
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
47 in case of an encoding error), \code{'replace'} (replace malformed
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
48 data with a suitable replacement marker, such as \character{?}) and
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
49 \code{'ignore'} (ignore malformed data and continue without further
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
50 notice).
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 In case a search function cannot find a given encoding, it should
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
53 return \code{None}.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 \end{funcdesc}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 \begin{funcdesc}{lookup}{encoding}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 Looks up a codec tuple in the Python codec registry and returns the
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 function tuple as defined above.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 Encodings are first looked up in the registry's cache. If not found,
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 the list of registered search functions is scanned. If no codecs tuple
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
62 is found, a \exception{LookupError} is raised. Otherwise, the codecs
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
63 tuple is stored in the cache and returned to the caller.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 \end{funcdesc}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65
23112
Skip Montanaro <skip@pobox.com>
parents: 23087
diff changeset
66 To simplify access to the various codecs, the module provides these
19982
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
67 additional functions which use \function{lookup()} for the codec
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
68 lookup:
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
69
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
70 \begin{funcdesc}{getencoder}{encoding}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
71 Lookup up the codec for the given encoding and return its encoder
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
72 function.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
73
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
74 Raises a \exception{LookupError} in case the encoding cannot be found.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
75 \end{funcdesc}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
76
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
77 \begin{funcdesc}{getdecoder}{encoding}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
78 Lookup up the codec for the given encoding and return its decoder
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
79 function.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
80
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
81 Raises a \exception{LookupError} in case the encoding cannot be found.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
82 \end{funcdesc}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
83
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
84 \begin{funcdesc}{getreader}{encoding}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
85 Lookup up the codec for the given encoding and return its StreamReader
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
86 class or factory function.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
87
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
88 Raises a \exception{LookupError} in case the encoding cannot be found.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
89 \end{funcdesc}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
90
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
91 \begin{funcdesc}{getwriter}{encoding}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
92 Lookup up the codec for the given encoding and return its StreamWriter
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
93 class or factory function.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
94
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
95 Raises a \exception{LookupError} in case the encoding cannot be found.
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
96 \end{funcdesc}
bf4b1b08a2c6 Docs and News item for the codecs.py additions.
Marc-André Lemburg <mal@egenix.com>
parents: 16127
diff changeset
97
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 To simplify working with encoded files or stream, the module
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 also defines these utility functions:
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
101 \begin{funcdesc}{open}{filename, mode\optional{, encoding\optional{,
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
102 errors\optional{, buffering}}}}
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 Open an encoded file using the given \var{mode} and return
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 a wrapped version providing transparent encoding/decoding.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19982
diff changeset
106 \note{The wrapped version will only accept the object format
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
107 defined by the codecs, i.e.\ Unicode objects for most built-in
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
108 codecs. Output is also codec-dependent and will usually be Unicode as
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19982
diff changeset
109 well.}
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \var{encoding} specifies the encoding which is to be used for the
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 the file.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 \var{errors} may be given to define the error handling. It defaults
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
115 to \code{'strict'} which causes a \exception{ValueError} to be raised
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
116 in case an encoding error occurs.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117
12274
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
118 \var{buffering} has the same meaning as for the built-in
559b25a79032 Make sure the \declaremodule uses the right name for the module!
Fred Drake <fdrake@acm.org>
parents: 12260
diff changeset
119 \function{open()} function. It defaults to line buffered.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \end{funcdesc}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
122 \begin{funcdesc}{EncodedFile}{file, input\optional{,
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
123 output\optional{, errors}}}
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 Return a wrapped version of file which provides transparent
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 encoding translation.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 Strings written to the wrapped file are interpreted according to the
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 given \var{input} encoding and then written to the original file as
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
129 strings using the \var{output} encoding. The intermediate encoding will
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 usually be Unicode but depends on the specified codecs.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
132 If \var{output} is not given, it defaults to \var{input}.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 \var{errors} may be given to define the error handling. It defaults to
13696
bb364d6f9f69 Fix small typos and markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12274
diff changeset
135 \code{'strict'}, which causes \exception{ValueError} to be raised in case
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136 an encoding error occurs.
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137 \end{funcdesc}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139 The module also provides the following constants which are useful
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140 for reading and writing to platform dependent files:
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142 \begin{datadesc}{BOM}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 \dataline{BOM_BE}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144 \dataline{BOM_LE}
23658
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
145 \dataline{BOM_UTF8}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
146 \dataline{BOM_UTF16}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
147 \dataline{BOM_UTF16_BE}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
148 \dataline{BOM_UTF16_LE}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
149 \dataline{BOM_UTF32}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
150 \dataline{BOM_UTF32_BE}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
151 \dataline{BOM_UTF32_LE}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
152 These constants define various encodings of the Unicode byte order mark
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
153 (BOM) used in UTF-16 and UTF-32 data streams to indicate the byte order
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
154 used in the stream or file and in UTF-8 as a Unicode signature.
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
155 \constant{BOM_UTF16} is either \constant{BOM_UTF16_BE} or
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
156 \constant{BOM_UTF16_LE} depending on the platform's native byte order,
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
157 \constant{BOM} is an alias for \constant{BOM_UTF16}, \constant{BOM_LE}
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
158 for \constant{BOM_UTF16_LE} and \constant{BOM_BE} for \constant{BOM_UTF16_BE}.
94aa4eb9bb7d Add constants BOM_UTF8, BOM_UTF16, BOM_UTF16_LE, BOM_UTF16_BE,
Walter Dörwald <walter@livinglogic.de>
parents: 23112
diff changeset
159 The others represent the BOM in UTF-8 and UTF-32 encodings.
12260
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 \end{datadesc}
8c0f863ba50c Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161
16127
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
162
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
163 \begin{seealso}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
164 \seeurl{http://sourceforge.net/projects/python-codecs/}{A
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
165 SourceForge project working on additional support for Asian
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
166 codecs for use with Python. They are in the early stages of
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
167 development at the time of this writing --- look in their
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
168 FTP area for downloadable files.}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
169 \end{seealso}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
170
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
171
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
172 \subsection{Codec Base Classes}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
173
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
174 The \module{codecs} defines a set of base classes which define the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
175 interface and can also be used to easily write you own codecs for use
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
176 in Python.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
177
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
178 Each codec has to define four interfaces to make it usable as codec in
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
179 Python: stateless encoder, stateless decoder, stream reader and stream
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
180 writer. The stream reader and writers typically reuse the stateless
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
181 encoder/decoder to implement the file protocols.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
182
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
183 The \class{Codec} class defines the interface for stateless
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
184 encoders/decoders.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
185
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
186 To simplify and standardize error handling, the \method{encode()} and
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
187 \method{decode()} methods may implement different error handling
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
188 schemes by providing the \var{errors} string argument. The following
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
189 string values are defined and implemented by all standard Python
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
190 codecs:
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
191
16127
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
192 \begin{tableii}{l|l}{code}{Value}{Meaning}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
193 \lineii{'strict'}{Raise \exception{ValueError} (or a subclass);
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
194 this is the default.}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
195 \lineii{'ignore'}{Ignore the character and continue with the next.}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
196 \lineii{'replace'}{Replace with a suitable replacement character;
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
197 Python will use the official U+FFFD REPLACEMENT
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
198 CHARACTER for the built-in Unicode codecs.}
6f1fd8500398 Added link to the "Python Codecs" project at SourceForge.
Fred Drake <fdrake@acm.org>
parents: 15186
diff changeset
199 \end{tableii}
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
200
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
201
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
202 \subsubsection{Codec Objects \label{codec-objects}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
203
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
204 The \class{Codec} class defines these methods which also define the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
205 function interfaces of the stateless encoder and decoder:
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
206
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
207 \begin{methoddesc}{encode}{input\optional{, errors}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
208 Encodes the object \var{input} and returns a tuple (output object,
23087
09db3f5d0bd0 added small clarification to the descriptions of encode() and decode()
Skip Montanaro <skip@pobox.com>
parents: 20580
diff changeset
209 length consumed). While codecs are not restricted to use with Unicode, in
09db3f5d0bd0 added small clarification to the descriptions of encode() and decode()
Skip Montanaro <skip@pobox.com>
parents: 20580
diff changeset
210 a Unicode context, encoding converts a Unicode object to a plain string
09db3f5d0bd0 added small clarification to the descriptions of encode() and decode()
Skip Montanaro <skip@pobox.com>
parents: 20580
diff changeset
211 using a particular character set encoding (e.g., \code{cp1252} or
09db3f5d0bd0 added small clarification to the descriptions of encode() and decode()
Skip Montanaro <skip@pobox.com>
parents: 20580
diff changeset
212 \code{iso-8859-1}).
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
213
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
214 \var{errors} defines the error handling to apply. It defaults to
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
215 \code{'strict'} handling.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
216
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
217 The method may not store state in the \class{Codec} instance. Use
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
218 \class{StreamCodec} for codecs which have to keep state in order to
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
219 make encoding/decoding efficient.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
220
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
221 The encoder must be able to handle zero length input and return an
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
222 empty object of the output object type in this situation.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
223 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
224
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
225 \begin{methoddesc}{decode}{input\optional{, errors}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
226 Decodes the object \var{input} and returns a tuple (output object,
23087
09db3f5d0bd0 added small clarification to the descriptions of encode() and decode()
Skip Montanaro <skip@pobox.com>
parents: 20580
diff changeset
227 length consumed). In a Unicode context, decoding converts a plain string
09db3f5d0bd0 added small clarification to the descriptions of encode() and decode()
Skip Montanaro <skip@pobox.com>
parents: 20580
diff changeset
228 encoded using a particular character set encoding to a Unicode object.
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
229
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
230 \var{input} must be an object which provides the \code{bf_getreadbuf}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
231 buffer slot. Python strings, buffer objects and memory mapped files
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
232 are examples of objects providing this slot.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
233
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
234 \var{errors} defines the error handling to apply. It defaults to
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
235 \code{'strict'} handling.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
236
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
237 The method may not store state in the \class{Codec} instance. Use
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
238 \class{StreamCodec} for codecs which have to keep state in order to
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
239 make encoding/decoding efficient.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
240
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
241 The decoder must be able to handle zero length input and return an
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
242 empty object of the output object type in this situation.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
243 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
244
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
245 The \class{StreamWriter} and \class{StreamReader} classes provide
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
246 generic working interfaces which can be used to implement new
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
247 encodings submodules very easily. See \module{encodings.utf_8} for an
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
248 example on how this is done.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
249
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
250
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
251 \subsubsection{StreamWriter Objects \label{stream-writer-objects}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
252
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
253 The \class{StreamWriter} class is a subclass of \class{Codec} and
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
254 defines the following methods which every stream writer must define in
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
255 order to be compatible to the Python codec registry.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
256
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
257 \begin{classdesc}{StreamWriter}{stream\optional{, errors}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
258 Constructor for a \class{StreamWriter} instance.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
259
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
260 All stream writers must provide this constructor interface. They are
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
261 free to add additional keyword arguments, but only the ones defined
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
262 here are used by the Python codec registry.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
263
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
264 \var{stream} must be a file-like object open for writing (binary)
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
265 data.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
266
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
267 The \class{StreamWriter} may implement different error handling
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
268 schemes by providing the \var{errors} keyword argument. These
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
269 parameters are defined:
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
270
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
271 \begin{itemize}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
272 \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
273 this is the default.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
274 \item \code{'ignore'} Ignore the character and continue with the next.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
275 \item \code{'replace'} Replace with a suitable replacement character
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
276 \end{itemize}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
277 \end{classdesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
278
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
279 \begin{methoddesc}{write}{object}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
280 Writes the object's contents encoded to the stream.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
281 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
282
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
283 \begin{methoddesc}{writelines}{list}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
284 Writes the concatenated list of strings to the stream (possibly by
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
285 reusing the \method{write()} method).
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
286 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
287
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
288 \begin{methoddesc}{reset}{}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
289 Flushes and resets the codec buffers used for keeping state.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
290
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
291 Calling this method should ensure that the data on the output is put
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
292 into a clean state, that allows appending of new fresh data without
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
293 having to rescan the whole stream to recover state.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
294 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
295
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
296 In addition to the above methods, the \class{StreamWriter} must also
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
297 inherit all other methods and attribute from the underlying stream.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
298
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
299
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
300 \subsubsection{StreamReader Objects \label{stream-reader-objects}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
301
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
302 The \class{StreamReader} class is a subclass of \class{Codec} and
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
303 defines the following methods which every stream reader must define in
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
304 order to be compatible to the Python codec registry.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
305
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
306 \begin{classdesc}{StreamReader}{stream\optional{, errors}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
307 Constructor for a \class{StreamReader} instance.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
308
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
309 All stream readers must provide this constructor interface. They are
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
310 free to add additional keyword arguments, but only the ones defined
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
311 here are used by the Python codec registry.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
312
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
313 \var{stream} must be a file-like object open for reading (binary)
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
314 data.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
315
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
316 The \class{StreamReader} may implement different error handling
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
317 schemes by providing the \var{errors} keyword argument. These
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
318 parameters are defined:
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
319
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
320 \begin{itemize}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
321 \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
322 this is the default.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
323 \item \code{'ignore'} Ignore the character and continue with the next.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
324 \item \code{'replace'} Replace with a suitable replacement character.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
325 \end{itemize}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
326 \end{classdesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
327
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
328 \begin{methoddesc}{read}{\optional{size}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
329 Decodes data from the stream and returns the resulting object.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
330
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
331 \var{size} indicates the approximate maximum number of bytes to read
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
332 from the stream for decoding purposes. The decoder can modify this
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
333 setting as appropriate. The default value -1 indicates to read and
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
334 decode as much as possible. \var{size} is intended to prevent having
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
335 to decode huge files in one step.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
336
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
337 The method should use a greedy read strategy meaning that it should
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
338 read as much data as is allowed within the definition of the encoding
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
339 and the given size, e.g. if optional encoding endings or state
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
340 markers are available on the stream, these should be read too.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
341 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
342
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
343 \begin{methoddesc}{readline}{[size]}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
344 Read one line from the input stream and return the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
345 decoded data.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
346
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19982
diff changeset
347 Unlike the \method{readlines()} method, this method inherits
15186
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
348 the line breaking knowledge from the underlying stream's
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
349 \method{readline()} method -- there is currently no support for line
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
350 breaking using the codec decoder due to lack of line buffering.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
351 Sublcasses should however, if possible, try to implement this method
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
352 using their own knowledge of line breaking.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
353
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
354 \var{size}, if given, is passed as size argument to the stream's
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
355 \method{readline()} method.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
356 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
357
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
358 \begin{methoddesc}{readlines}{[sizehint]}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
359 Read all lines available on the input stream and return them as list
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
360 of lines.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
361
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
362 Line breaks are implemented using the codec's decoder method and are
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
363 included in the list entries.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
364
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
365 \var{sizehint}, if given, is passed as \var{size} argument to the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
366 stream's \method{read()} method.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
367 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
368
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
369 \begin{methoddesc}{reset}{}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
370 Resets the codec buffers used for keeping state.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
371
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
372 Note that no stream repositioning should take place. This method is
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
373 primarily intended to be able to recover from decoding errors.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
374 \end{methoddesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
375
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
376 In addition to the above methods, the \class{StreamReader} must also
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
377 inherit all other methods and attribute from the underlying stream.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
378
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
379 The next two base classes are included for convenience. They are not
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
380 needed by the codec registry, but may provide useful in practice.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
381
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
382
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
383 \subsubsection{StreamReaderWriter Objects \label{stream-reader-writer}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
384
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
385 The \class{StreamReaderWriter} allows wrapping streams which work in
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
386 both read and write modes.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
387
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
388 The design is such that one can use the factory functions returned by
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
389 the \function{lookup()} function to construct the instance.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
390
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
391 \begin{classdesc}{StreamReaderWriter}{stream, Reader, Writer, errors}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
392 Creates a \class{StreamReaderWriter} instance.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
393 \var{stream} must be a file-like object.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
394 \var{Reader} and \var{Writer} must be factory functions or classes
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
395 providing the \class{StreamReader} and \class{StreamWriter} interface
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
396 resp.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
397 Error handling is done in the same way as defined for the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
398 stream readers and writers.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
399 \end{classdesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
400
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
401 \class{StreamReaderWriter} instances define the combined interfaces of
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
402 \class{StreamReader} and \class{StreamWriter} classes. They inherit
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
403 all other methods and attribute from the underlying stream.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
404
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
405
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
406 \subsubsection{StreamRecoder Objects \label{stream-recoder-objects}}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
407
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
408 The \class{StreamRecoder} provide a frontend - backend view of
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
409 encoding data which is sometimes useful when dealing with different
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
410 encoding environments.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
411
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
412 The design is such that one can use the factory functions returned by
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
413 the \function{lookup()} function to construct the instance.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
414
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
415 \begin{classdesc}{StreamRecoder}{stream, encode, decode,
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
416 Reader, Writer, errors}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
417 Creates a \class{StreamRecoder} instance which implements a two-way
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
418 conversion: \var{encode} and \var{decode} work on the frontend (the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
419 input to \method{read()} and output of \method{write()}) while
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
420 \var{Reader} and \var{Writer} work on the backend (reading and
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
421 writing to the stream).
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
422
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
423 You can use these objects to do transparent direct recodings from
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
424 e.g.\ Latin-1 to UTF-8 and back.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
425
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
426 \var{stream} must be a file-like object.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
427
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
428 \var{encode}, \var{decode} must adhere to the \class{Codec}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
429 interface, \var{Reader}, \var{Writer} must be factory functions or
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
430 classes providing objects of the the \class{StreamReader} and
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
431 \class{StreamWriter} interface respectively.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
432
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
433 \var{encode} and \var{decode} are needed for the frontend
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
434 translation, \var{Reader} and \var{Writer} for the backend
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
435 translation. The intermediate format used is determined by the two
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
436 sets of codecs, e.g. the Unicode codecs will use Unicode as
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
437 intermediate encoding.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
438
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
439 Error handling is done in the same way as defined for the
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
440 stream readers and writers.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
441 \end{classdesc}
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
442
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
443 \class{StreamRecoder} instances define the combined interfaces of
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
444 \class{StreamReader} and \class{StreamWriter} classes. They inherit
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
445 all other methods and attribute from the underlying stream.
b2892cbc63db Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13696
diff changeset
446