blob: 5863ed0846bb48d25a629b92c582e22618f7d4da [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
24of the file, creating a new instance will fail with a EOFError
25exception.
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:
67 raise EOFError
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()
Fred Drake553f6812001-05-11 19:14:51 +000073 except (AttributeError, IOError):
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:
88 self.skip()
Guido van Rossum8ca162f2002-04-07 06:36:23 +000089 self.closed = True
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000090
91 def isatty(self):
92 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +000093 raise ValueError("I/O operation on closed file")
Guido van Rossum8ca162f2002-04-07 06:36:23 +000094 return False
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000095
Guido van Rossum8ca162f2002-04-07 06:36:23 +000096 def seek(self, pos, whence=0):
Guido van Rossum8ea7bb81999-06-09 13:32:28 +000097 """Seek to specified position into the chunk.
98 Default position is 0 (start of chunk).
99 If the file is not seekable, this will result in an error.
Tim Peters88869f92001-01-14 23:36:06 +0000100 """
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000101
102 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000103 raise ValueError("I/O operation on closed file")
Guido van Rossum7bb11d61999-06-16 12:25:34 +0000104 if not self.seekable:
Collin Winterce36ad82007-08-30 01:19:48 +0000105 raise IOError("cannot seek")
Fred Drake624a1911999-06-25 14:58:44 +0000106 if whence == 1:
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000107 pos = pos + self.size_read
Fred Drake624a1911999-06-25 14:58:44 +0000108 elif whence == 2:
Guido van Rossum0d1b7ea2001-04-15 12:40:13 +0000109 pos = pos + self.chunksize
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000110 if pos < 0 or pos > self.chunksize:
111 raise RuntimeError
112 self.file.seek(self.offset + pos, 0)
113 self.size_read = pos
114
115 def tell(self):
116 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000117 raise ValueError("I/O operation on closed file")
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000118 return self.size_read
119
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000120 def read(self, size=-1):
Fred Drake624a1911999-06-25 14:58:44 +0000121 """Read at most size bytes from the chunk.
122 If size is omitted or negative, read until the end
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000123 of the chunk.
Tim Peters88869f92001-01-14 23:36:06 +0000124 """
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000125
126 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000127 raise ValueError("I/O operation on closed file")
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000128 if self.size_read >= self.chunksize:
129 return ''
Fred Drake624a1911999-06-25 14:58:44 +0000130 if size < 0:
131 size = self.chunksize - self.size_read
132 if size > self.chunksize - self.size_read:
Tim Peters88869f92001-01-14 23:36:06 +0000133 size = self.chunksize - self.size_read
Fred Drake624a1911999-06-25 14:58:44 +0000134 data = self.file.read(size)
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000135 self.size_read = self.size_read + len(data)
136 if self.size_read == self.chunksize and \
137 self.align and \
138 (self.chunksize & 1):
139 dummy = self.file.read(1)
140 self.size_read = self.size_read + len(dummy)
141 return data
142
143 def skip(self):
144 """Skip the rest of the chunk.
145 If you are not interested in the contents of the chunk,
146 this method should be called so that the file points to
147 the start of the next chunk.
Tim Peters88869f92001-01-14 23:36:06 +0000148 """
Guido van Rossum8ea7bb81999-06-09 13:32:28 +0000149
150 if self.closed:
Collin Winterce36ad82007-08-30 01:19:48 +0000151 raise ValueError("I/O operation on closed file")
Guido van Rossum7bb11d61999-06-16 12:25:34 +0000152 if self.seekable:
153 try:
154 n = self.chunksize - self.size_read
155 # maybe fix alignment
156 if self.align and (self.chunksize & 1):
157 n = n + 1
158 self.file.seek(n, 1)
159 self.size_read = self.size_read + n
160 return
Fred Drake553f6812001-05-11 19:14:51 +0000161 except IOError:
Guido van Rossum7bb11d61999-06-16 12:25:34 +0000162 pass
163 while self.size_read < self.chunksize:
164 n = min(8192, self.chunksize - self.size_read)
165 dummy = self.read(n)
166 if not dummy:
167 raise EOFError