projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / stream-reader-objects.html
CommitLineData
86530b38
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="stream-reader-writer.html" />
13<link rel="prev" href="stream-writer-objects.html" />
14<link rel="parent" href="node130.html" />
15<link rel="next" href="stream-reader-writer.html" />
16<meta name='aesop' content='information' />
17<title>4.9.1.3 StreamReader Objects </title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="4.9.1.2 StreamWriter Objects"
25 href="stream-writer-objects.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="4.9.1 Codec Base Classes"
28 href="node130.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="4.9.1.4 StreamReaderWriter Objects"
31 href="stream-reader-writer.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="stream-writer-objects.html">4.9.1.2 StreamWriter Objects</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="node130.html">4.9.1 Codec Base Classes</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="stream-reader-writer.html">4.9.1.4 StreamReaderWriter Objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H3><A NAME="SECTION006913000000000000000"></A><A NAME="stream-reader-objects"></A>
56<BR>
574.9.1.3 StreamReader Objects
58</H3>
59
60<P>
61The <tt class="class">StreamReader</tt> class is a subclass of <tt class="class">Codec</tt> and
62defines the following methods which every stream reader must define in
63order to be compatible to the Python codec registry.
64
65<P>
66<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
67 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1011' xml:id='l2h-1011' class="class">StreamReader</tt></b>(</nobr></td>
68 <td><var>stream</var><big>[</big><var>, errors</var><big>]</big><var></var>)</td></tr></table></dt>
69<dd>
70 Constructor for a <tt class="class">StreamReader</tt> instance.
71
72<P>
73All stream readers must provide this constructor interface. They are
74 free to add additional keyword arguments, but only the ones defined
75 here are used by the Python codec registry.
76
77<P>
78<var>stream</var> must be a file-like object open for reading (binary)
79 data.
80
81<P>
82The <tt class="class">StreamReader</tt> may implement different error handling
83 schemes by providing the <var>errors</var> keyword argument. These
84 parameters are defined:
85
86<P>
87
88<UL>
89<LI><code>'strict'</code> Raise <tt class="exception">ValueError</tt> (or a subclass);
90 this is the default.
91</LI>
92<LI><code>'ignore'</code> Ignore the character and continue with the next.
93</LI>
94<LI><code>'replace'</code> Replace with a suitable replacement character.
95
96</LI>
97</UL>
98
99<P>
100The <var>errors</var> argument will be assigned to an attribute of the
101 same name. Assigning to this attribute makes it possible to switch
102 between different error handling strategies during the lifetime
103 of the <tt class="class">StreamReader</tt> object.
104
105<P>
106The set of allowed values for the <var>errors</var> argument can
107 be extended with <tt class="function">register_error()</tt>.
108</dl>
109
110<P>
111<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
112 <td><nobr><b><tt id='l2h-1012' xml:id='l2h-1012' class="method">read</tt></b>(</nobr></td>
113 <td><var></var><big>[</big><var>size</var><big>[</big><var>, chars, </var><big>[</big><var>firstline</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
114<dd>
115 Decodes data from the stream and returns the resulting object.
116
117<P>
118<var>chars</var> indicates the number of characters to read from the
119 stream. <tt class="function">read()</tt> will never return more than <var>chars</var>
120 characters, but it might return less, if there are not enough
121 characters available.
122
123<P>
124<var>size</var> indicates the approximate maximum number of bytes to read
125 from the stream for decoding purposes. The decoder can modify this
126 setting as appropriate. The default value -1 indicates to read and
127 decode as much as possible. <var>size</var> is intended to prevent having
128 to decode huge files in one step.
129
130<P>
131<var>firstline</var> indicates that it would be sufficient to only return
132 the first line, if there are decoding errors on later lines.
133
134<P>
135The method should use a greedy read strategy meaning that it should
136 read as much data as is allowed within the definition of the encoding
137 and the given size, e.g. if optional encoding endings or state
138 markers are available on the stream, these should be read too.
139
140<P>
141
142<span class="versionnote">Changed in version 2.4:
143<var>chars</var> argument added.</span>
144
145<span class="versionnote">Changed in version 2.4.2:
146<var>firstline</var> argument added.</span>
147
148</dl>
149
150<P>
151<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
152 <td><nobr><b><tt id='l2h-1013' xml:id='l2h-1013' class="method">readline</tt></b>(</nobr></td>
153 <td><var></var><big>[</big><var>size</var><big>[</big><var>, keepends</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
154<dd>
155 Read one line from the input stream and return the
156 decoded data.
157
158<P>
159<var>size</var>, if given, is passed as size argument to the stream's
160 <tt class="method">readline()</tt> method.
161
162<P>
163If <var>keepends</var> is false lineends will be stripped from the
164 lines returned.
165
166<P>
167
168<span class="versionnote">Changed in version 2.4:
169<var>keepends</var> argument added.</span>
170
171</dl>
172
173<P>
174<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
175 <td><nobr><b><tt id='l2h-1014' xml:id='l2h-1014' class="method">readlines</tt></b>(</nobr></td>
176 <td><var></var><big>[</big><var>sizehint</var><big>[</big><var>, keepends</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
177<dd>
178 Read all lines available on the input stream and return them as list
179 of lines.
180
181<P>
182Line breaks are implemented using the codec's decoder method and are
183 included in the list entries if <var>keepends</var> is true.
184
185<P>
186<var>sizehint</var>, if given, is passed as <var>size</var> argument to the
187 stream's <tt class="method">read()</tt> method.
188</dl>
189
190<P>
191<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
192 <td><nobr><b><tt id='l2h-1015' xml:id='l2h-1015' class="method">reset</tt></b>(</nobr></td>
193 <td><var></var>)</td></tr></table></dt>
194<dd>
195 Resets the codec buffers used for keeping state.
196
197<P>
198Note that no stream repositioning should take place. This method is
199 primarily intended to be able to recover from decoding errors.
200</dl>
201
202<P>
203In addition to the above methods, the <tt class="class">StreamReader</tt> must also
204inherit all other methods and attribute from the underlying stream.
205
206<P>
207The next two base classes are included for convenience. They are not
208needed by the codec registry, but may provide useful in practice.
209
210<P>
211
212<DIV CLASS="navigation">
213<div class='online-navigation'>
214<p></p><hr />
215<table align="center" width="100%" cellpadding="0" cellspacing="2">
216<tr>
217<td class='online-navigation'><a rel="prev" title="4.9.1.2 StreamWriter Objects"
218 href="stream-writer-objects.html"><img src='../icons/previous.png'
219 border='0' height='32' alt='Previous Page' width='32' /></A></td>
220<td class='online-navigation'><a rel="parent" title="4.9.1 Codec Base Classes"
221 href="node130.html"><img src='../icons/up.png'
222 border='0' height='32' alt='Up One Level' width='32' /></A></td>
223<td class='online-navigation'><a rel="next" title="4.9.1.4 StreamReaderWriter Objects"
224 href="stream-reader-writer.html"><img src='../icons/next.png'
225 border='0' height='32' alt='Next Page' width='32' /></A></td>
226<td align="center" width="100%">Python Library Reference</td>
227<td class='online-navigation'><a rel="contents" title="Table of Contents"
228 href="contents.html"><img src='../icons/contents.png'
229 border='0' height='32' alt='Contents' width='32' /></A></td>
230<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
231 border='0' height='32' alt='Module Index' width='32' /></a></td>
232<td class='online-navigation'><a rel="index" title="Index"
233 href="genindex.html"><img src='../icons/index.png'
234 border='0' height='32' alt='Index' width='32' /></A></td>
235</tr></table>
236<div class='online-navigation'>
237<b class="navlabel">Previous:</b>
238<a class="sectref" rel="prev" href="stream-writer-objects.html">4.9.1.2 StreamWriter Objects</A>
239<b class="navlabel">Up:</b>
240<a class="sectref" rel="parent" href="node130.html">4.9.1 Codec Base Classes</A>
241<b class="navlabel">Next:</b>
242<a class="sectref" rel="next" href="stream-reader-writer.html">4.9.1.4 StreamReaderWriter Objects</A>
243</div>
244</div>
245<hr />
246<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
247</DIV>
248<!--End of Navigation Panel-->
249<ADDRESS>
250See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
251</ADDRESS>
252</BODY>
253</HTML>
Full OpenSPARC design & verification tarball including full HDL.