← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.2-docs-html/_sources/library/chunk.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

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