"chunk" --- Wczytaj pokawałkowane dane IFF
******************************************

**Kod źródłowy:** Lib/chunk.py

Zdezaprobowane w wersji 3.11, zostanie usunięte w wersji 3.13: The
"chunk" module is deprecated (see **PEP 594** for details).

======================================================================

Ten moduł dostarcza sprzęg dla wczytania pliku który używa kawałków EA
IFF 85. [1] Ten format jest używany co najmniej w AIFF - Formacie
Pliku Wymiany Dźwięku (AIFF/AIFF-C) i Formacie Pliku Real Media
(RMFF). Format pliku dźwiękowego WAVE jest blisko związany i może
także być wczytany używając tego modułu.

Kawałek ma następującą strukturę:

+-----------+----------+---------------------------------+
| Offset    | Długość  | Zawartość                       |
|===========|==========|=================================|
| 0         | 4        | ID kawałka                      |
+-----------+----------+---------------------------------+
| 4         | 4        | Rozmiar kawałka w porządku      |
|           |          | bajtów dużego-endian-u , nie    |
|           |          | zawierając nagłówka.            |
+-----------+----------+---------------------------------+
| 8         | *n*      | Bajty danych, gdzie *n* jest    |
|           |          | rozmiarem danym w poprzednim    |
|           |          | polu                            |
+-----------+----------+---------------------------------+
| 8 + *n*   | 0 lub 1  | Bajt wyrównania potrzebny jeśli |
|           |          | *n* jest nieparzysty i          |
|           |          | wyrównanie kawałka jest         |
|           |          | używane.                        |
+-----------+----------+---------------------------------+

Identyfikator ID jest 4-bajtowym ciągiem znaków który identyfikuje typ
kawałka.

Pole rozmiaru (32-bitowa wartość, zakodowana używając porządku bajtów
dużego-endian-a) daje rozmiar danych kawałka, nie zawierając
8-bajtowego nagłówka.

Zwykle plik typu IFF składa się z jednego lub więcej fragmentów.
Proponowane użycie zdefiniowanej tutaj klasy "Chunk" polega na
tworzeniu instancji na początku każdej porcji i odczytywaniu jej aż do
końca, po czym można utworzyć nową instancję. Na końcu pliku,
tworzenie nowej instancji zakończy się niepowodzeniem z wyjątkiem
"EOFError".

class chunk.Chunk(file, align=True, bigendian=True, inclheader=False)

   Class which represents a chunk.  The *file* argument is expected to
   be a file-like object.  An instance of this class is specifically
   allowed.  The only method that is needed is "read()".  If the
   methods "seek()" and "tell()" are present and don't raise an
   exception, they are also used. If these methods are present and
   raise an exception, they are expected to not have altered the
   object.  If the optional argument *align* is true, chunks are
   assumed to be aligned on 2-byte boundaries.  If *align* is false,
   no alignment is assumed.  The default value is true.  If the
   optional argument *bigendian* is false, the chunk size is assumed
   to be in little-endian order. This is needed for WAVE audio files.
   The default value is true.  If the optional argument *inclheader*
   is true, the size given in the chunk header includes the size of
   the header.  The default value is false.

   przedmiot uogólnienia "Chunk" wspiera następujące sposoby
   postępowania:

   getname()

      Zwraca nazwę (IDentyfikator) kawałka. To jest pierwsze 4 bajty
      kawałka.

   getsize()

      Zwraca rozmiar kawałka.

   close()

      Zamknij i przeskocz na koniec kawałka. To nie zamyka leżącego u
      podstaw pliku.

   The remaining methods will raise "OSError" if called after the
   "close()" method has been called.  Before Python 3.3, they used to
   raise "IOError", now an alias of "OSError".

   isatty()

      Zwraca "fałsz".

   seek(pos, whence=0)

      Ustaw obecną pozycję kawałka. Parametr *whence* jest opcjonalny
      i domyślnie równy "0" (bezwzględna pozycja w pliku); inne
      wartości są "1" (wyszukaj w odniesieniu do obecnej pozycji w
      pliku) i "2" (wyszukaj w odniesieniu do końca pliku). Nie ma
      wartości zwracanej. Jeśli leżący u podstaw plik nie pozwala na
      wyszukiwanie, tylko wyszukiwanie w przód jest dozwolone.

   tell()

      Zwróć obecną pozycję w kawałku.

   read(size=-1)

      Read at most *size* bytes from the chunk (less if the read hits
      the end of the chunk before obtaining *size* bytes).  If the
      *size* argument is negative or omitted, read all data until the
      end of the chunk.  An empty bytes object is returned when the
      end of the chunk is encountered immediately.

   skip()

      Skip to the end of the chunk.  All further calls to "read()" for
      the chunk will return "b''".  If you are not interested in the
      contents of the chunk, this method should be called so that the
      file points to the start of the next chunk.

-[ Przypisy ]-

[1] "EA IFF 85" Standard dla formatu plików wzajemnej wymiany, Jerry
    Morrison, Electronic Arts, styczeń 1985.
