blob: 870c39fe7f5037152dd5b430e6b6f3f7e5d7a8de [file] [log] [blame]
Guido van Rossum8ea7bb81999-06-09 13:32:28 +00001"""Simple class to read IFF chunks.
2
3An IFF chunk (used in formats such as AIFF, TIFF, RMFF (RealMedia File
4Format)) has the following structure:
5
6+----------------+
7| ID (4 bytes) |
8+----------------+
9| size (4 bytes) |
10+----------------+
11| data |
12| ... |
13+----------------+
14
15The ID is a 4-byte string which identifies the type of chunk.
16
17The size field (a 32-bit value, encoded using big-endian byte order)
18gives the size of the whole chunk, including the 8-byte header.
19
Fred Drake624a1911999-06-25 14:58:44 +000020Usually an IFF-type file consists of one or more chunks. The proposed
Tim Peters88869f92001-01-14 23:36:06 +000021usage of the Chunk class defined here is to instantiate an instance at
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000022the start of each chunk and read from the instance until it reaches
23the end, after which a new instance can be instantiated. At the end
Martin Panter7462b6492015-11-02 03:37:02 +000024of the file, creating a new instance will fail with an EOFError
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000025exception.
26
27Usage:
Guido van Rossum8ca162f2002-04-07 06:36:23 +000028while True:
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000029 try:
30 chunk = Chunk(file)
31 except EOFError:
32 break
33 chunktype = chunk.getname()
Guido van Rossum8ca162f2002-04-07 06:36:23 +000034 while True:
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000035 data = chunk.read(nbytes)
36 if not data:
37 pass
38 # do something with data
39
40The interface is file-like. The implemented methods are:
41read, close, seek, tell, isatty.
42Extra methods are: skip() (called by close, skips to the end of the chunk),
43getname() (returns the name (ID) of the chunk)
44
45The __init__ method has one required argument, a file-like object
46(including a chunk instance), and one optional argument, a flag which
Tim Peters88869f92001-01-14 23:36:06 +000047specifies whether or not chunks are aligned on 2-byte boundaries. The
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000048default is 1, i.e. aligned.
49"""
50
51class Chunk:
Guido van Rossum8ca162f2002-04-07 06:36:23 +000052 def __init__(self, file, align=True, bigendian=True, inclheader=False):
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000053 import struct
Guido van Rossum8ca162f2002-04-07 06:36:23 +000054 self.closed = False
Tim Peters88869f92001-01-14 23:36:06 +000055 self.align = align # whether to align to word (2-byte) boundaries
Guido van Rossum3601e881999-08-26 15:50:43 +000056 if bigendian:
57 strflag = '>'
58 else:
59 strflag = '<'
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000060 self.file = file
61 self.chunkname = file.read(4)
62 if len(self.chunkname) < 4:
63 raise EOFError
64 try:
Guido van Rossumdc0b1a12007-04-12 22:55:07 +000065 self.chunksize = struct.unpack_from(strflag+'L', file.read(4))[0]
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000066 except struct.error:
Serhiy Storchaka5affd232017-04-05 09:37:24 +030067 raise EOFError from None
Guido van Rossum3601e881999-08-26 15:50:43 +000068 if inclheader:
69 self.chunksize = self.chunksize - 8 # subtract header
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000070 self.size_read = 0
Guido van Rossum7bb11d61999-06-16 12:25:34 +000071 try:
72 self.offset = self.file.tell()
Andrew Svetlovf7a17b42012-12-25 16:47:37 +020073 except (AttributeError, OSError):
Guido van Rossum8ca162f2002-04-07 06:36:23 +000074 self.seekable = False
Guido van Rossum7bb11d61999-06-16 12:25:34 +000075 else:
Guido van Rossum8ca162f2002-04-07 06:36:23 +000076 self.seekable = True
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000077
78 def getname(self):
79 """Return the name (ID) of the current chunk."""
80 return self.chunkname
81
Guido van Rossum3601e881999-08-26 15:50:43 +000082 def getsize(self):
83 """Return the size of the current chunk."""
84 return self.chunksize
85
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000086 def close(self):
87 if not self.closed:
Serhiy Storchaka7e7a3db2015-04-10 13:24:41 +030088 try:
89 self.skip()
90 finally:
91 self.closed = True
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000092
93 def isatty(self):
94 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +000095 raise ValueError("I/O operation on closed file")
Guido van Rossum8ca162f2002-04-07 06:36:23 +000096 return False
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000097
Guido van Rossum8ca162f2002-04-07 06:36:23 +000098 def seek(self, pos, whence=0):
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000099 """Seek to specified position into the chunk.
100 Default position is 0 (start of chunk).
101 If the file is not seekable, this will result in an error.
Tim Peters88869f92001-01-14 23:36:06 +0000102 """
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000103
104 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000105 raise ValueError("I/O operation on closed file")
Guido van Rossum7bb11d61999-06-16 12:25:34 +0000106 if not self.seekable:
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200107 raise OSError("cannot seek")
Fred Drake624a1911999-06-25 14:58:44 +0000108 if whence == 1:
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000109 pos = pos + self.size_read
Fred Drake624a1911999-06-25 14:58:44 +0000110 elif whence == 2:
Guido van Rossum0d1b7ea2001-04-15 12:40:13 +0000111 pos = pos + self.chunksize
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000112 if pos < 0 or pos > self.chunksize:
113 raise RuntimeError
114 self.file.seek(self.offset + pos, 0)
115 self.size_read = pos
116
117 def tell(self):
118 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000119 raise ValueError("I/O operation on closed file")
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000120 return self.size_read
121
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000122 def read(self, size=-1):
Fred Drake624a1911999-06-25 14:58:44 +0000123 """Read at most size bytes from the chunk.
124 If size is omitted or negative, read until the end
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000125 of the chunk.
Tim Peters88869f92001-01-14 23:36:06 +0000126 """
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000127
128 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000129 raise ValueError("I/O operation on closed file")
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000130 if self.size_read >= self.chunksize:
Serhiy Storchakad44768f2015-07-10 22:24:47 +0300131 return b''
Fred Drake624a1911999-06-25 14:58:44 +0000132 if size < 0:
133 size = self.chunksize - self.size_read
134 if size > self.chunksize - self.size_read:
Tim Peters88869f92001-01-14 23:36:06 +0000135 size = self.chunksize - self.size_read
Fred Drake624a1911999-06-25 14:58:44 +0000136 data = self.file.read(size)
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000137 self.size_read = self.size_read + len(data)
138 if self.size_read == self.chunksize and \
139 self.align and \
140 (self.chunksize & 1):
141 dummy = self.file.read(1)
142 self.size_read = self.size_read + len(dummy)
143 return data
144
145 def skip(self):
146 """Skip the rest of the chunk.
147 If you are not interested in the contents of the chunk,
148 this method should be called so that the file points to
149 the start of the next chunk.
Tim Peters88869f92001-01-14 23:36:06 +0000150 """
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000151
152 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000153 raise ValueError("I/O operation on closed file")
Guido van Rossum7bb11d61999-06-16 12:25:34 +0000154 if self.seekable:
155 try:
156 n = self.chunksize - self.size_read
157 # maybe fix alignment
158 if self.align and (self.chunksize & 1):
159 n = n + 1
160 self.file.seek(n, 1)
161 self.size_read = self.size_read + n
162 return
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200163 except OSError:
Guido van Rossum7bb11d61999-06-16 12:25:34 +0000164 pass
165 while self.size_read < self.chunksize:
166 n = min(8192, self.chunksize - self.size_read)
167 dummy = self.read(n)
168 if not dummy:
169 raise EOFError