# 13.3. `bz2` — Prise en charge de la compression bzip2

Code Source : Lib/bz2.py

Ce module fournit une interface complète pour compresser et décompresser les données en utilisant l’algorithme de compression bzip2.

Le module `bz2` contient :

- La fonction `open()` et la classe `BZ2File` pour lire et écrire des fichiers compressés.

- Les classes `BZ2Compressor` et `BZ2Decompressor` pour la (dé)compression incrémentielle.

- Les fonctions `compress()` et `decompress()` pour la (dé)compression en une seule fois.

Toutes les classes de ce module peuvent en toute sécurité être accédées depuis de multiples fils d’exécution.

## 13.3.1. (Dé)compression de fichiers

`bz2.``open`(filename, mode='r', compresslevel=9, encoding=None, errors=None, newline=None)

  Ouvre un fichier compressé par bzip2 en mode binaire ou texte, le renvoyant en file object.

  Tout comme avec le constructeur pour la classe `BZ2File`, l’argument filename peut être un nom de fichier réel (un objet `str` ou `bytes`), ou un objet fichier existant à lire ou à écrire.

  L’argument mode peut valoir `'r'`, `'rb'`, `'w'`, `'wb'`, `'x'`, `'xb'`, `'a'` ou `'ab'` pour le mode binaire, ou `'rt'`, `'wt'`, `'xt'` ou `'at'` pour le mode texte. Il vaut par défaut `'rb'`.

  L’argument compresslevel est un entier de 1 à 9, comme pour le constructeur `BZ2File`.

  Pour le mode binaire, cette fonction est équivalente au constructeur `BZ2File` : `BZ2File(filename, mode, compresslevel=compresslevel)`. Dans ce cas, les arguments encoding, errors et newline arguments ne doivent pas être fournis.

  Pour le mode texte, un objet `BZ2File` est créé et encapsulé dans une instance `io.TextIOWrapper` avec l’encodage spécifié, le comportement de gestion des erreurs et les fins de ligne.

  Nouveau dans la version 3.3.

  Modifié dans la version 3.4: Le mode `'x'` (création exclusive) est ajouté.

  Modifié dans la version 3.6: Accepte un path-like object.

class `bz2.``BZ2File`(filename, mode='r', buffering=None, compresslevel=9)

  Ouvre un fichier bzip2 en mode binaire.

  Si filename est un objet `str` ou `bytes`, ouvre le nom de fichier directement. Autrement, filename doit être un file object, qui est utilisé pour lire ou écrire les données compressées.

  L’argument mode peut être soit `'r'` pour lire (par défaut), `'w'` pour écraser, `'x'` pour créer exclusivement, ou `'a'` pour ajouter. Ils peuvent également être écrits respectivement comme `'rb'`, `'wb'`, `'xb'` et `'ab'`.

  Si filename est un objet fichier (plutôt que le nom de fichier réel), le mode `'w'` ne tronque pas le fichier, mais équivaut à `'a'`.

  The buffering argument is ignored. Its use is deprecated.

  If mode is `'w'` or `'a'`, compresslevel can be a number between `1` and `9` specifying the level of compression: `1` produces the least compression, and `9` (default) produces the most compression.

  Si mode est `'r'`, le fichier d’entrée peut être la concaténation de plusieurs flux compressés.

  `BZ2File` fournit tous les membres spécifiés par la classe `io.BufferedIOBase`, excepté les méthodes `detach()` et `truncate()`. L’itération et l’instruction `with` sont prises en charge.

  `BZ2File` fournit aussi la méthode suivante :

  `peek`([n])

    Renvoie des données en mémoire tampon sans avancer la position du fichier. Au moins un octet de donnée (sauf l’EOF) est renvoyé. Le nombre exact d’octets renvoyés n’est pas spécifié.

    Note

    Bien que l’appel à la méthode `peek()` ne change pas la position du fichier de la classe `BZ2File`, il peut changer la position de l’objet fichier sous-jacent (e.g. si la classe `BZ2File` a été construite en passant un objet fichier à filename).

    Nouveau dans la version 3.3.

  Modifié dans la version 3.1: La prise en charge de l’instruction `with` a été ajoutée.

  Modifié dans la version 3.3: Les méthodes `fileno()`, `readable()`, `seekable()`, `writable()`, `read1()` et `readinto()` ont été ajoutées.

  Modifié dans la version 3.3: La gestion de filename comme file object au lieu d’un nom de fichier réel a été ajoutée.

  Modifié dans la version 3.3: Le mode `'a'` (ajout) a été ajouté, avec la prise en charge de la lecture des fichiers multiflux.

  Modifié dans la version 3.4: Le mode `'x'` (création exclusive) est ajouté.

  Modifié dans la version 3.5: La méthode `read()` accepte maintenant un argument `None`.

  Modifié dans la version 3.6: Accepte un path-like object.

## 13.3.2. (Dé)compression incrémentielle

class `bz2.``BZ2Compressor`(compresslevel=9)

  Crée un nouvel objet compresseur. Cet objet peut être utilisé pour compresser les données de manière incrémentielle. Pour une compression en une seule fois, utilisez à la place la fonction `compress()`.

  compresslevel, if given, must be a number between `1` and `9`. The default is `9`.

  `compress`(data)

    Fournit la donnée à l’objet compresseur. Renvoie un bloc de données compressées si possible, ou autrement une chaîne d’octet vide.

    Quand vous avez fini de fournir des données au compresseur, appelez la méthode `flush()` pour finir le processus de compression.

  `flush`()

    Finit le processus de compression. Renvoie la donnée compressée restante dans les tampons internes.

    L’objet compresseur ne peut pas être utilisé après que cette méthode a été appelée.

class `bz2.``BZ2Decompressor`

  Crée un nouvel objet décompresseur. Cet objet peut être utilisé pour décompresser les données de manière incrémentielle. Pour une compression en une seule fois, utilisez à la place la fonction `decompress()`.

  Note

  Cette classe ne gère pas de manière transparente les entrées contenant plusieurs flux compressés, à la différence de `decompress()` et `BZ2File`. Si vous avez besoin de décompresser une entrée multiflux avec la classe `BZ2Decompressor`, vous devez utiliser un nouveau décompresseur pour chaque flux.

  `decompress`(data, max_length=-1)

    Décompresse data (un bytes-like object), renvoyant une donnée non compressée en tant que chaîne d’octets. Certaines de ces data peuvent être mises en interne en tampon, pour un usage lors d’appels ultérieurs par la méthode `decompress()`. La donnée renvoyée doit être concaténée avec la sortie des appels précédents à la méthode `decompress()`.

    Si max_length est positif, renvoie au plus max_length octets de données compressées. Si la limite est atteinte et que d’autres sorties peuvent être produites, l’attribut `needs_input` est positionné sur `False`. Dans ce cas, lors de l’appel suivant à la méthode `decompress()`, vous pouvez fournir `b''` dans data afin d’obtenir la suite de la sortie.

    Si toutes les données entrées ont été décompressées et renvoyées (soit parce qu’il y avait moins de max_length octets, ou parce que max_length était négatif), l’attribut `needs_input` sera configuré sur `True`.

    Essayer de décompresser des données après que la fin du flux soit atteinte lève une erreur EOFError. Toute donnée trouvée après la fin du flux est ignorée et sauvegardée dans l’attribut `unused_data`.

    Modifié dans la version 3.5: Ajout du paramètre max_length.

  `eof`

    `True` si le marqueur de fin de flux a été atteint.

    Nouveau dans la version 3.3.

  `unused_data`

    Donnée trouvée après la fin du flux compressé.

    Si l’attribut est accédé avant que la fin du flux ait été atteint, sa valeur sera `b''`.

  `needs_input`

    `False` si la méthode `decompress()` peut fournir plus de données décompressées avant l’acquisition d’une nouvelle entrée non compressée.

    Nouveau dans la version 3.5.

## 13.3.3. (Dé)compression en une fois

`bz2.``compress`(data, compresslevel=9)

  Compresse data.

  compresslevel, if given, must be a number between `1` and `9`. The default is `9`.

  Pour la compression incrémentielle, utilisez à la place la classe `BZ2Compressor`.

`bz2.``decompress`(data)

  Décompresse data.

  Si data est la concaténation de multiples flux compressés, décompresse tous les flux.

  Pour une décompression incrémentielle, utilisez à la place la classe `BZ2Decompressor`.

  Modifié dans la version 3.3: Prise en charge des entrées multiflux.