"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.


(Dé)compression de fichiers
===========================

bz2.open(filename, mode='rb', 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', *, 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'".

   Si *mode* est "'w'" ou "'a'", *compresslevel* peut être un entier
   entre "1" et "9" spécifiant le niveau de compression : "1" utilise
   la compression la moins forte, et "9" (par défaut) la compression
   la plus forte.

   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*.

   Modifié dans la version 3.9: Le paramètre *buffering* a été
   supprimé. Il était ignoré et obsolète depuis Python 3.0. Passez un
   objet fichier déjà ouvert si vous voulez contrôler la façon dont le
   fichier est ouvert.Le paramètre *compresslevel* est devenu un
   paramètre exclusivement nommé.


(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*, s'il est fourni, doit être un entier entre "1" et
   "9". Sa valeur par défaut est "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.


(Dé)compression en une fois
===========================

bz2.compress(data, compresslevel=9)

   Compresse *data*, un *bytes-like object*.

   *compresslevel*, s'il est fourni, doit être un entier entre "1" et
   "9". Sa valeur par défaut est "9".

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

bz2.decompress(data)

   Décompresse *data*, un *bytes-like object*.

   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*.


Exemples d'utilisation
======================

Ci-dessous, nous présentons quelques exemples typiques de
l'utilisation du module "bz2".

Utilise les fonctions "compress()" et "decompress()" pour démontrer
une compression aller-retour :

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

Utilise la classe "BZ2Compressor" pour une compression incrémentielle
:

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

L'exemple ci-dessus utilise un flux de données vraiment pas aléatoire
(un flux de blocs de *b"z"*). Les données aléatoires ont tendance à
mal se compresser, alors que les données répétitives ou ordonnées
donnent généralement un taux de compression élevé.

Écriture et lecture en mode binaire d'un fichier compressé avec
*bzip2* :

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
>>> content == data  # Check equality to original object after round-trip
True
