1:mod:`chunk` --- Read IFF chunked data
2======================================
3
4.. module:: chunk
5   :synopsis: Module to read IFF chunks.
6   :deprecated:
7
8.. moduleauthor:: Sjoerd Mullender <[email protected]>
9.. sectionauthor:: Sjoerd Mullender <[email protected]>
10
11**Source code:** :source:`Lib/chunk.py`
12
13.. index::
14   single: Audio Interchange File Format
15   single: AIFF
16   single: AIFF-C
17   single: Real Media File Format
18   single: RMFF
19
20.. deprecated-removed:: 3.11 3.13
21   The :mod:`chunk` module is deprecated
22   (see :pep:`PEP 594 <594#chunk>` for details).
23
24--------------
25
26This module provides an interface for reading files that use EA IFF 85 chunks.
27[#]_  This format is used in at least the Audio Interchange File Format
28(AIFF/AIFF-C) and the Real Media File Format (RMFF).  The WAVE audio file format
29is closely related and can also be read using this module.
30
31A chunk has the following structure:
32
33+---------+--------+-------------------------------+
34| Offset  | Length | Contents                      |
35+=========+========+===============================+
36| 0       | 4      | Chunk ID                      |
37+---------+--------+-------------------------------+
38| 4       | 4      | Size of chunk in big-endian   |
39|         |        | byte order, not including the |
40|         |        | header                        |
41+---------+--------+-------------------------------+
42| 8       | *n*    | Data bytes, where *n* is the  |
43|         |        | size given in the preceding   |
44|         |        | field                         |
45+---------+--------+-------------------------------+
46| 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd |
47|         |        | and chunk alignment is used   |
48+---------+--------+-------------------------------+
49
50The ID is a 4-byte string which identifies the type of chunk.
51
52The size field (a 32-bit value, encoded using big-endian byte order) gives the
53size of the chunk data, not including the 8-byte header.
54
55Usually an IFF-type file consists of one or more chunks.  The proposed usage of
56the :class:`Chunk` class defined here is to instantiate an instance at the start
57of each chunk and read from the instance until it reaches the end, after which a
58new instance can be instantiated. At the end of the file, creating a new
59instance will fail with an :exc:`EOFError` exception.
60
61
62.. class:: Chunk(file, align=True, bigendian=True, inclheader=False)
63
64   Class which represents a chunk.  The *file* argument is expected to be a
65   file-like object.  An instance of this class is specifically allowed.  The
66   only method that is needed is :meth:`~io.IOBase.read`.  If the methods
67   :meth:`~io.IOBase.seek` and :meth:`~io.IOBase.tell` are present and don't
68   raise an exception, they are also used.
69   If these methods are present and raise an exception, they are expected to not
70   have altered the object.  If the optional argument *align* is true, chunks
71   are assumed to be aligned on 2-byte boundaries.  If *align* is false, no
72   alignment is assumed.  The default value is true.  If the optional argument
73   *bigendian* is false, the chunk size is assumed to be in little-endian order.
74   This is needed for WAVE audio files. The default value is true.  If the
75   optional argument *inclheader* is true, the size given in the chunk header
76   includes the size of the header.  The default value is false.
77
78   A :class:`Chunk` object supports the following methods:
79
80
81   .. method:: getname()
82
83      Returns the name (ID) of the chunk.  This is the first 4 bytes of the
84      chunk.
85
86
87   .. method:: getsize()
88
89      Returns the size of the chunk.
90
91
92   .. method:: close()
93
94      Close and skip to the end of the chunk.  This does not close the
95      underlying file.
96
97   The remaining methods will raise :exc:`OSError` if called after the
98   :meth:`close` method has been called.  Before Python 3.3, they used to
99   raise :exc:`IOError`, now an alias of :exc:`OSError`.
100
101
102   .. method:: isatty()
103
104      Returns ``False``.
105
106
107   .. method:: seek(pos, whence=0)
108
109      Set the chunk's current position.  The *whence* argument is optional and
110      defaults to ``0`` (absolute file positioning); other values are ``1``
111      (seek relative to the current position) and ``2`` (seek relative to the
112      file's end).  There is no return value. If the underlying file does not
113      allow seek, only forward seeks are allowed.
114
115
116   .. method:: tell()
117
118      Return the current position into the chunk.
119
120
121   .. method:: read(size=-1)
122
123      Read at most *size* bytes from the chunk (less if the read hits the end of
124      the chunk before obtaining *size* bytes).  If the *size* argument is
125      negative or omitted, read all data until the end of the chunk.  An empty
126      bytes object is returned when the end of the chunk is encountered
127      immediately.
128
129
130   .. method:: skip()
131
132      Skip to the end of the chunk.  All further calls to :meth:`read` for the
133      chunk will return ``b''``.  If you are not interested in the contents of
134      the chunk, this method should be called so that the file points to the
135      start of the next chunk.
136
137
138.. rubric:: Footnotes
139
140.. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
141   Arts, January 1985.
142
143