| the :class:`Chunk` 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 a :exc:`EOFError` exception. |
| |
| |
| .. class:: Chunk(file[, align, bigendian, inclheader]) |
| |
n | Class which represents a chunk. The *file* argument is expected to be a file- |
n | Class which represents a chunk. The *file* argument is expected to be a |
| like object. An instance of this class is specifically allowed. The only |
| file-like object. An instance of this class is specifically allowed. The |
| method that is needed is :meth:`read`. If the methods :meth:`seek` and |
| only method that is needed is :meth:`read`. If the methods :meth:`seek` and |
| :meth:`tell` are present and don't raise an exception, they are also used. If |
| :meth:`tell` are present and don't raise an exception, they are also used. |
| these methods are present and raise an exception, they are expected to not have |
| If these methods are present and raise an exception, they are expected to not |
| altered the object. If the optional argument *align* is true, chunks are |
| have altered the object. If the optional argument *align* is true, chunks |
| assumed to be aligned on 2-byte boundaries. If *align* is false, no alignment |
| are assumed to be aligned on 2-byte boundaries. If *align* is false, no |
| is assumed. The default value is true. If the optional argument *bigendian* is |
| alignment is assumed. The default value is true. If the optional argument |
| false, the chunk size is assumed to be in little-endian order. This is needed |
| *bigendian* is false, the chunk size is assumed to be in little-endian order. |
| for WAVE audio files. The default value is true. If the optional argument |
| This is needed for WAVE audio files. The default value is true. If the |
| *inclheader* is true, the size given in the chunk header includes the size of |
| optional argument *inclheader* is true, the size given in the chunk header |
| the header. The default value is false. |
| includes the size of the header. The default value is false. |
| |
n | A :class:`Chunk` object supports the following methods: |
n | A :class:`Chunk` object supports the following methods: |
| |
| |
n | .. method:: Chunk.getname() |
n | .. method:: getname() |
| |
n | Returns the name (ID) of the chunk. This is the first 4 bytes of the chunk. |
n | Returns the name (ID) of the chunk. This is the first 4 bytes of the |
| chunk. |
| |
| |
n | .. method:: Chunk.getsize() |
n | .. method:: getsize() |
| |
n | Returns the size of the chunk. |
n | Returns the size of the chunk. |
| |
| |
n | .. method:: Chunk.close() |
n | .. method:: close() |
| |
n | Close and skip to the end of the chunk. This does not close the underlying |
n | Close and skip to the end of the chunk. This does not close the |
| file. |
| underlying file. |
| |
n | The remaining methods will raise :exc:`IOError` if called after the |
n | The remaining methods will raise :exc:`IOError` if called after the |
| :meth:`close` method has been called. |
| :meth:`close` method has been called. |
| |
| |
n | .. method:: Chunk.isatty() |
n | .. method:: isatty() |
| |
n | Returns ``False``. |
n | Returns ``False``. |
| |
| |
n | .. method:: Chunk.seek(pos[, whence]) |
n | .. method:: seek(pos[, whence]) |
| |
n | Set the chunk's current position. The *whence* argument is optional and |
n | Set the chunk's current position. The *whence* argument is optional and |
| defaults to ``0`` (absolute file positioning); other values are ``1`` (seek |
| defaults to ``0`` (absolute file positioning); other values are ``1`` |
| relative to the current position) and ``2`` (seek relative to the file's end). |
| (seek relative to the current position) and ``2`` (seek relative to the |
| There is no return value. If the underlying file does not allow seek, only |
| file's end). There is no return value. If the underlying file does not |
| forward seeks are allowed. |
| allow seek, only forward seeks are allowed. |
| |
| |
n | .. method:: Chunk.tell() |
n | .. method:: tell() |
| |
n | Return the current position into the chunk. |
n | Return the current position into the chunk. |
| |
| |
n | .. method:: Chunk.read([size]) |
n | .. method:: read([size]) |
| |
n | Read at most *size* bytes from the chunk (less if the read hits the end of the |
n | Read at most *size* bytes from the chunk (less if the read hits the end of |
| chunk before obtaining *size* bytes). If the *size* argument is negative or |
| the chunk before obtaining *size* bytes). If the *size* argument is |
| omitted, read all data until the end of the chunk. The bytes are returned as a |
| negative or omitted, read all data until the end of the chunk. The bytes |
| string object. An empty string is returned when the end of the chunk is |
| are returned as a string object. An empty string is returned when the end |
| encountered immediately. |
| of the chunk is encountered immediately. |
| |
| |
n | .. method:: Chunk.skip() |
n | .. method:: skip() |
| |
t | Skip to the end of the chunk. All further calls to :meth:`read` for the chunk |
t | Skip to the end of the chunk. All further calls to :meth:`read` for the |
| will return ``''``. If you are not interested in the contents of the chunk, |
| chunk will return ``''``. If you are not interested in the contents of |
| this method should be called so that the file points to the start of the next |
| the chunk, this method should be called so that the file points to the |
| chunk. |
| start of the next chunk. |
| |
| |
| .. rubric:: Footnotes |
| |
| .. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic |
| Arts, January 1985. |
| |