324 lines
17 KiB
HTML
324 lines
17 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>chunk — Read IFF chunked data — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="colorsys — Conversions between color systems" href="colorsys.html" />
|
||
<link rel="prev" title="wave — Read and write WAV files" href="wave.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/chunk.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="colorsys.html" title="colorsys — Conversions between color systems"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="wave.html" title="wave — Read and write WAV files"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="mm.html" accesskey="U">Multimedia Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-chunk">
|
||
<span id="chunk-read-iff-chunked-data"></span><h1><a class="reference internal" href="#module-chunk" title="chunk: Module to read IFF chunks."><code class="xref py py-mod docutils literal notranslate"><span class="pre">chunk</span></code></a> — Read IFF chunked data<a class="headerlink" href="#module-chunk" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/chunk.py">Lib/chunk.py</a></p>
|
||
<hr class="docutils" id="index-0" />
|
||
<p>This module provides an interface for reading files that use EA IFF 85 chunks.
|
||
<a class="footnote-reference brackets" href="#id2" id="id1">1</a> This format is used in at least the Audio Interchange File Format
|
||
(AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format
|
||
is closely related and can also be read using this module.</p>
|
||
<p>A chunk has the following structure:</p>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 19%" />
|
||
<col style="width: 17%" />
|
||
<col style="width: 65%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Offset</p></th>
|
||
<th class="head"><p>Length</p></th>
|
||
<th class="head"><p>Contents</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>0</p></td>
|
||
<td><p>4</p></td>
|
||
<td><p>Chunk ID</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>4</p></td>
|
||
<td><p>4</p></td>
|
||
<td><p>Size of chunk in big-endian
|
||
byte order, not including the
|
||
header</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>8</p></td>
|
||
<td><p><em>n</em></p></td>
|
||
<td><p>Data bytes, where <em>n</em> is the
|
||
size given in the preceding
|
||
field</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>8 + <em>n</em></p></td>
|
||
<td><p>0 or 1</p></td>
|
||
<td><p>Pad byte needed if <em>n</em> is odd
|
||
and chunk alignment is used</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The ID is a 4-byte string which identifies the type of chunk.</p>
|
||
<p>The size field (a 32-bit value, encoded using big-endian byte order) gives the
|
||
size of the chunk data, not including the 8-byte header.</p>
|
||
<p>Usually an IFF-type file consists of one or more chunks. The proposed usage of
|
||
the <a class="reference internal" href="#chunk.Chunk" title="chunk.Chunk"><code class="xref py py-class docutils literal notranslate"><span class="pre">Chunk</span></code></a> class defined here is to instantiate an instance at the start
|
||
of each chunk and read from the instance until it reaches the end, after which a
|
||
new instance can be instantiated. At the end of the file, creating a new
|
||
instance will fail with an <a class="reference internal" href="exceptions.html#EOFError" title="EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a> exception.</p>
|
||
<dl class="class">
|
||
<dt id="chunk.Chunk">
|
||
<em class="property">class </em><code class="descclassname">chunk.</code><code class="descname">Chunk</code><span class="sig-paren">(</span><em>file</em>, <em>align=True</em>, <em>bigendian=True</em>, <em>inclheader=False</em><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Class which represents a chunk. The <em>file</em> argument is expected to be a
|
||
file-like object. An instance of this class is specifically allowed. The
|
||
only method that is needed is <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>. If the methods
|
||
<a class="reference internal" href="io.html#io.IOBase.seek" title="io.IOBase.seek"><code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code></a> and <a class="reference internal" href="io.html#io.IOBase.tell" title="io.IOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tell()</span></code></a> are present and don’t
|
||
raise an exception, they are also used.
|
||
If these methods are present and raise an exception, they are expected to not
|
||
have altered the object. If the optional argument <em>align</em> is true, chunks
|
||
are assumed to be aligned on 2-byte boundaries. If <em>align</em> is false, no
|
||
alignment is assumed. The default value is true. If the optional argument
|
||
<em>bigendian</em> is false, the chunk size is assumed to be in little-endian order.
|
||
This is needed for WAVE audio files. The default value is true. If the
|
||
optional argument <em>inclheader</em> is true, the size given in the chunk header
|
||
includes the size of the header. The default value is false.</p>
|
||
<p>A <a class="reference internal" href="#chunk.Chunk" title="chunk.Chunk"><code class="xref py py-class docutils literal notranslate"><span class="pre">Chunk</span></code></a> object supports the following methods:</p>
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.getname">
|
||
<code class="descname">getname</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.getname" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the name (ID) of the chunk. This is the first 4 bytes of the
|
||
chunk.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.getsize">
|
||
<code class="descname">getsize</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.getsize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the size of the chunk.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close and skip to the end of the chunk. This does not close the
|
||
underlying file.</p>
|
||
</dd></dl>
|
||
|
||
<p>The remaining methods will raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> if called after the
|
||
<a class="reference internal" href="#chunk.Chunk.close" title="chunk.Chunk.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method has been called. Before Python 3.3, they used to
|
||
raise <a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a>, now an alias of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.isatty">
|
||
<code class="descname">isatty</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.isatty" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.seek">
|
||
<code class="descname">seek</code><span class="sig-paren">(</span><em>pos</em>, <em>whence=0</em><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.seek" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the chunk’s current position. The <em>whence</em> argument is optional and
|
||
defaults to <code class="docutils literal notranslate"><span class="pre">0</span></code> (absolute file positioning); other values are <code class="docutils literal notranslate"><span class="pre">1</span></code>
|
||
(seek relative to the current position) and <code class="docutils literal notranslate"><span class="pre">2</span></code> (seek relative to the
|
||
file’s end). There is no return value. If the underlying file does not
|
||
allow seek, only forward seeks are allowed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.tell">
|
||
<code class="descname">tell</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.tell" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current position into the chunk.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.read">
|
||
<code class="descname">read</code><span class="sig-paren">(</span><em>size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read at most <em>size</em> bytes from the chunk (less if the read hits the end of
|
||
the chunk before obtaining <em>size</em> bytes). If the <em>size</em> argument is
|
||
negative or omitted, read all data until the end of the chunk. An empty
|
||
bytes object is returned when the end of the chunk is encountered
|
||
immediately.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="chunk.Chunk.skip">
|
||
<code class="descname">skip</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#chunk.Chunk.skip" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Skip to the end of the chunk. All further calls to <a class="reference internal" href="#chunk.Chunk.read" title="chunk.Chunk.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> for the
|
||
chunk will return <code class="docutils literal notranslate"><span class="pre">b''</span></code>. If you are not interested in the contents of
|
||
the chunk, this method should be called so that the file points to the
|
||
start of the next chunk.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p class="rubric">Footnotes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
|
||
<dd><p>“EA IFF 85” Standard for Interchange Format Files, Jerry Morrison, Electronic
|
||
Arts, January 1985.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="wave.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">wave</span></code> — Read and write WAV files</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="colorsys.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">colorsys</span></code> — Conversions between color systems</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/chunk.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="colorsys.html" title="colorsys — Conversions between color systems"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="wave.html" title="wave — Read and write WAV files"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="mm.html" >Multimedia Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |