sam-t2/devtools/v8plus/html/python/lib/stream-reader-objects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="stream-reader-writer.html" />
<link rel="prev" href="stream-writer-objects.html" />
<link rel="parent" href="node130.html" />
<link rel="next" href="stream-reader-writer.html" />
<meta name='aesop' content='information' />
<title>4.9.1.3 StreamReader Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.9.1.2 StreamWriter Objects"
  href="stream-writer-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.9.1 Codec Base Classes"
  href="node130.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.9.1.4 StreamReaderWriter Objects"
  href="stream-reader-writer.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="stream-writer-objects.html">4.9.1.2 StreamWriter Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="node130.html">4.9.1 Codec Base Classes</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="stream-reader-writer.html">4.9.1.4 StreamReaderWriter Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H3><A NAME="SECTION006913000000000000000"></A><A NAME="stream-reader-objects"></A>
<BR>
4.9.1.3 StreamReader Objects
</H3>

<P>
The <tt class="class">StreamReader</tt> class is a subclass of <tt class="class">Codec</tt> and
defines the following methods which every stream reader must define in
order to be compatible to the Python codec registry.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1011' xml:id='l2h-1011' class="class">StreamReader</tt></b>(</nobr></td>
  <td><var>stream</var><big>[</big><var>, errors</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Constructor for a <tt class="class">StreamReader</tt> instance.

<P>
All stream readers must provide this constructor interface. They are
  free to add additional keyword arguments, but only the ones defined
  here are used by the Python codec registry.

<P>
<var>stream</var> must be a file-like object open for reading (binary)
  data.

<P>
The <tt class="class">StreamReader</tt> may implement different error handling
  schemes by providing the <var>errors</var> keyword argument. These
  parameters are defined:

<P>

<UL>
<LI><code>'strict'</code> Raise <tt class="exception">ValueError</tt> (or a subclass);
                          this is the default.
</LI>
<LI><code>'ignore'</code> Ignore the character and continue with the next.
</LI>
<LI><code>'replace'</code> Replace with a suitable replacement character.

</LI>
</UL>

<P>
The <var>errors</var> argument will be assigned to an attribute of the
  same name. Assigning to this attribute makes it possible to switch
  between different error handling strategies during the lifetime
  of the <tt class="class">StreamReader</tt> object.

<P>
The set of allowed values for the <var>errors</var> argument can
  be extended with <tt class="function">register_error()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1012' xml:id='l2h-1012' class="method">read</tt></b>(</nobr></td>
  <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>
<dd>
  Decodes data from the stream and returns the resulting object.

<P>
<var>chars</var> indicates the number of characters to read from the
  stream. <tt class="function">read()</tt> will never return more than <var>chars</var>
  characters, but it might return less, if there are not enough
  characters available.

<P>
<var>size</var> indicates the approximate maximum number of bytes to read
  from the stream for decoding purposes. The decoder can modify this
  setting as appropriate. The default value -1 indicates to read and
  decode as much as possible.  <var>size</var> is intended to prevent having
  to decode huge files in one step.

<P>
<var>firstline</var> indicates that it would be sufficient to only return
  the first line, if there are decoding errors on later lines.

<P>
The method should use a greedy read strategy meaning that it should
  read as much data as is allowed within the definition of the encoding
  and the given size, e.g.  if optional encoding endings or state
  markers are available on the stream, these should be read too.

<P>

<span class="versionnote">Changed in version 2.4:
<var>chars</var> argument added.</span>

<span class="versionnote">Changed in version 2.4.2:
<var>firstline</var> argument added.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1013' xml:id='l2h-1013' class="method">readline</tt></b>(</nobr></td>
  <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>
<dd>
  Read one line from the input stream and return the
  decoded data.

<P>
<var>size</var>, if given, is passed as size argument to the stream's
  <tt class="method">readline()</tt> method.

<P>
If <var>keepends</var> is false lineends will be stripped from the
  lines returned.

<P>

<span class="versionnote">Changed in version 2.4:
<var>keepends</var> argument added.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1014' xml:id='l2h-1014' class="method">readlines</tt></b>(</nobr></td>
  <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>
<dd>
  Read all lines available on the input stream and return them as list
  of lines.

<P>
Line breaks are implemented using the codec's decoder method and are
  included in the list entries if <var>keepends</var> is true.

<P>
<var>sizehint</var>, if given, is passed as <var>size</var> argument to the
  stream's <tt class="method">read()</tt> method.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1015' xml:id='l2h-1015' class="method">reset</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Resets the codec buffers used for keeping state.

<P>
Note that no stream repositioning should take place.  This method is
  primarily intended to be able to recover from decoding errors.
</dl>

<P>
In addition to the above methods, the <tt class="class">StreamReader</tt> must also
inherit all other methods and attribute from the underlying stream.

<P>
The next two base classes are included for convenience. They are not
needed by the codec registry, but may provide useful in practice.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.9.1.2 StreamWriter Objects"
  href="stream-writer-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.9.1 Codec Base Classes"
  href="node130.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.9.1.4 StreamReaderWriter Objects"
  href="stream-reader-writer.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="stream-writer-objects.html">4.9.1.2 StreamWriter Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="node130.html">4.9.1 Codec Base Classes</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="stream-reader-writer.html">4.9.1.4 StreamReaderWriter Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>