"zipfile" --- Work with ZIP archives
************************************

**Source code:** Lib/zipfile/

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

Le format de fichier ZIP est une archive et un standard de compression
couramment utilisés. Ce module fournit des outils pour créer, écrire,
ajouter des données à et lister un fichier ZIP. L'utilisation avancée
de ce module requiert une certaine compréhension du format, comme
défini dans PKZIP Application Note.

This module does not handle multipart ZIP files. It can handle ZIP
files that use the ZIP64 extensions (that is ZIP files that are more
than 4 GiB in size).  It supports decryption of encrypted files in ZIP
archives, but it cannot create an encrypted file.  Decryption is
extremely slow as it is implemented in native Python rather than C.

Handling compressed archives requires *optional modules* such as
"zlib", "bz2", "lzma", and "compression.zstd". If any of them are
missing from your copy of CPython, look for documentation from your
distributor (that is, whoever provided Python to you). If you are the
distributor, see Requirements for optional modules.

Le module définit les éléments suivants :

exception zipfile.BadZipFile

   Erreur levée en cas de fichier ZIP non valide.

   Ajouté dans la version 3.2.

exception zipfile.BadZipfile

   Alias de "BadZipFile", pour la compatibilité avec les versions de
   Python précédentes.

   Obsolète depuis la version 3.2.

exception zipfile.LargeZipFile

   Erreur levée quand un fichier ZIP nécessite la fonctionnalité ZIP64
   mais qu'elle n'a pas été activée.

class zipfile.ZipFile

   Classe pour lire et écrire des fichiers ZIP. Voir la section
   ZipFile objects pour les détails du constructeur.

class zipfile.Path

   Class that implements a subset of the interface provided by
   "pathlib.Path", including the full
   "importlib.resources.abc.Traversable" interface.

   Ajouté dans la version 3.8.

class zipfile.PyZipFile

   Classe pour créer des archives ZIP contenant des bibliothèques
   Python.

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

   Class used to represent information about a member of an archive.
   Instances of this class are returned by the "getinfo()" and
   "infolist()" methods of "ZipFile" objects.  Most users of the
   "zipfile" module will not need to create these, but only use those
   created by this module. *filename* should be the full name of the
   archive member, and *date_time* should be a tuple containing six
   fields which describe the time of the last modification to the
   file; the fields are described in section ZipInfo objects.

   Modifié dans la version 3.13: A public "compress_level" attribute
   has been added to expose the formerly protected "_compresslevel".
   The older protected name continues to work as a property for
   backwards compatibility.

   _for_archive(archive)

      Resolve the date_time, compression attributes, and external
      attributes to suitable defaults as used by "ZipFile.writestr()".

      Returns self for chaining.

      Ajouté dans la version 3.14.

zipfile.is_zipfile(filename)

   Retourne "True" si *filename* est un fichier ZIP valide basé sur
   son nombre magique, sinon retourne "False". *filename* peut aussi
   être un fichier ou un objet fichier-compatible.

   Modifié dans la version 3.1: Gestion des objets fichier et fichier-
   compatibles.

zipfile.ZIP_STORED

   Constante numérique pour un membre d'une archive décompressée.

zipfile.ZIP_DEFLATED

   Constante numérique pour la méthode habituelle de compression de
   ZIP. Nécessite le module "zlib".

zipfile.ZIP_BZIP2

   Constante numérique pour la méthode de compressions BZIP2.
   Nécessite le module "bz2".

   Ajouté dans la version 3.3.

zipfile.ZIP_LZMA

   Constante numérique pour la méthode de compressions LZMA. Nécessite
   le module "lzma".

   Ajouté dans la version 3.3.

zipfile.ZIP_ZSTANDARD

   The numeric constant for Zstandard compression. This requires the
   "compression.zstd" module.

   Note:

     In APPNOTE 6.3.7, the method ID "20" was assigned to Zstandard
     compression. This was changed in APPNOTE 6.3.8 to method ID "93"
     to avoid conflicts, with method ID "20" being deprecated. For
     compatibility, the "zipfile" module reads both method IDs but
     will only write data with method ID "93".

   Ajouté dans la version 3.14.

Note:

  The ZIP file format specification has included support for bzip2
  compression since 2001, for LZMA compression since 2006, and
  Zstandard compression since 2020. However, some tools (including
  older Python releases) do not support these compression methods, and
  may either refuse to process the ZIP file altogether, or fail to
  extract individual files.

Voir aussi:

  PKZIP Application Note
     Documentation sur le format de fichier ZIP par Phil Katz,
     créateur du format et des algorithmes utilisés.

  Info-ZIP Home Page
     Informations sur les programmes et les bibliothèques de
     développement d'archivage ZIP du projet Info-ZIP.


ZipFile objects
===============

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

   Ouvre un fichier ZIP, où *file* peut être un chemin vers un fichier
   (une chaîne de caractères), un objet fichier-compatible ou un objet
   chemin-compatible *path-like object*.

   Le paramètre *mode* doit être "r" pour lire un fichier existant,
   "w" pour tronquer et écrire un nouveau fichier, "a" pour ajouter
   des données à la fin d'un fichier existant ou "x" pour créer et
   écrire exclusivement un nouveau fichier. Si *mode* est à "x" et
   *file* fait référence à un fichier existant, une exception
   "FileExistsError" est levée. Si *mode* est à "a" et *file* fait
   référence à un fichier ZIP existant, alors des fichiers
   supplémentaires y seront ajoutés. Si *file* ne fait pas référence à
   un fichier ZIP, alors une nouvelle archive ZIP est ajoutée au
   fichier, afin de prévoir le cas d'ajouter une archive ZIP à un
   autre fichier (comme par exemple "python.exe"). Si *mode* est à "r"
   ou "a", le fichier doit être navigable.

   *compression* is the ZIP compression method to use when writing the
   archive, and should be "ZIP_STORED", "ZIP_DEFLATED", "ZIP_BZIP2",
   "ZIP_LZMA", or "ZIP_ZSTANDARD"; unrecognized values will cause
   "NotImplementedError" to be raised.  If "ZIP_DEFLATED",
   "ZIP_BZIP2", "ZIP_LZMA", or "ZIP_ZSTANDARD" is specified but the
   corresponding module ("zlib", "bz2", "lzma", or "compression.zstd")
   is not available, "RuntimeError" is raised. The default is
   "ZIP_STORED".

   If *allowZip64* is "True" (the default) zipfile will create ZIP
   files that use the ZIP64 extensions when the zipfile is larger than
   4 GiB. If it is "false" "zipfile" will raise an exception when the
   ZIP file would require ZIP64 extensions.

   The *compresslevel* parameter controls the compression level to use
   when writing files to the archive. When using "ZIP_STORED" or
   "ZIP_LZMA" it has no effect. When using "ZIP_DEFLATED" integers "0"
   through "9" are accepted (see "zlib" for more information). When
   using "ZIP_BZIP2" integers "1" through "9" are accepted (see "bz2"
   for more information). When using "ZIP_ZSTANDARD" integers
   "-131072" through "22" are commonly accepted (see
   "CompressionParameter.compression_level" for more on retrieving
   valid values and their meaning).

   Les fichiers ZIP plus anciens que le 1er janvier 1980 sont
   autorisés lorsque l'argument *strict_timestamps* vaut "False",
   moyennant de les voir datés du 1er janvier 1980. De même pour les
   fichiers datés d'après le 31 décembre 2107 qui voient leur
   horodatage fixé au 31 décembre 2107.

   When mode is "'r'", *metadata_encoding* may be set to the name of a
   codec, which will be used to decode metadata such as the names of
   members and ZIP comments.

   Si le fichier est créé avec le mode "'w'", "'x'" ou "'a'" et
   ensuite "fermé" sans ajouter de fichiers à l'archive, la structure
   appropriée pour un fichier archive ZIP vide sera écrite dans le
   fichier.

   *ZipFile* est aussi un gestionnaire de contexte et gère ainsi la
   déclaration "with". Dans l'exemple, *myzip* est fermé à la fin de
   la déclaration "with" --- même si une exception est levée :

      with ZipFile('spam.zip', 'w') as myzip:
          myzip.write('eggs.txt')

   Note:

     *metadata_encoding* is an instance-wide setting for the ZipFile.
     It is not possible to set this on a per-member basis.This
     attribute is a workaround for legacy implementations which
     produce archives with names in the current locale encoding or
     code page (mostly on Windows).  According to the .ZIP standard,
     the encoding of metadata may be specified to be either IBM code
     page (default) or UTF-8 by a flag in the archive header. That
     flag takes precedence over *metadata_encoding*, which is a
     Python-specific extension.

   Modifié dans la version 3.2: Ajout de la possibilité d'utiliser
   "ZipFile" comme un gestionnaire de contexte.

   Modifié dans la version 3.3: Ajout de la gestion de la compression
   "bzip2" et "lzma".

   Modifié dans la version 3.4: Les extensions ZIP64 sont activées par
   défaut.

   Modifié dans la version 3.5: Ajout de la gestion de l'écriture dans
   des flux non navigables. Ajout de la gestion du mode "x".

   Modifié dans la version 3.6: Auparavant, une simple exception
   "RuntimeError" était levée pour des valeurs de compression non
   reconnues.

   Modifié dans la version 3.6.2: Le paramètre *file* accepte un objet
   fichier-compatible *path-like object*.

   Modifié dans la version 3.7: Ajout du paramètre *compresslevel*.

   Modifié dans la version 3.8: The *strict_timestamps* keyword-only
   parameter.

   Modifié dans la version 3.11: Added support for specifying member
   name encoding for reading metadata in the zipfile's directory and
   file headers.

ZipFile.close()

   Ferme l'archive. Vous devez appeler "close()" avant de terminer
   votre programme ou des informations essentielles n'y seront pas
   enregistrées.

ZipFile.getinfo(name)

   Retourne un objet "ZipInfo" avec les informations du membre *name*
   de l'archive. Appeler "getinfo()" pour un nom non contenu dans
   l'archive lève une exception "KeyError".

ZipFile.infolist()

   Retourne une liste contenant un objet "ZipInfo" pour chaque membre
   de l'archive. Les objets ont le même ordre que leurs entrées dans
   le fichier ZIP présent sur disque s'il s'agissait d'une archive
   préexistante.

ZipFile.namelist()

   Retourne une liste des membres de l'archive indexés par leur nom.

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

   Access a member of the archive as a binary file-like object.
   *name* can be either the name of a file within the archive or a
   "ZipInfo" object.  The *mode* parameter, if included, must be "'r'"
   (the default) or "'w'".  *pwd* is the password used to decrypt
   encrypted ZIP files as a "bytes" object.

   "open()" est aussi un gestionnaire de contexte et gère ainsi la
   déclaration "with" :

      with ZipFile('spam.zip') as myzip:
          with myzip.open('eggs.txt') as myfile:
              print(myfile.read())

   With *mode* "'r'" the file-like object ("ZipExtFile") is read-only
   and provides the following methods: "read()", "readline()",
   "readlines()", "seek()", "tell()", "__iter__()", "__next__()".
   These objects can operate independently of the ZipFile.

   Avec "mode='w'" un descripteur de fichier en écriture est retourné,
   gérant la méthode "write()". Quand le descripteur d'un fichier
   inscriptible est ouvert, tenter de lire ou écrire d'autres fichiers
   dans le fichier ZIP lève une exception "ValueError".

   In both cases the file-like object has also attributes "name",
   which is equivalent to the name of a file within the archive, and
   "mode", which is "'rb'" or "'wb'" depending on the input mode.

   Lors de l'écriture d'un fichier, si la taille du fichier n'est pas
   connue mais peut être supérieure à 2 GiO, spécifiez
   "force_zip64=True" afin de vous assurer que le format d'en-tête est
   capable de supporter des fichiers volumineux. Si la taille du
   fichier est connue à l'avance, instanciez un objet "ZipInfo" avec
   l'attribut "file_size" défini et utilisez-le en tant que paramètre
   *name*.

   Note:

     Les méthodes "open()", "read()" et "extract()" peuvent prendre un
     nom de fichier ou un objet "ZipInfo". Cela est appréciable
     lorsqu'on essaie de lire un fichier ZIP qui contient des membres
     avec des noms en double.

   Modifié dans la version 3.6: Suppression de la gestion de
   "mode='U'".  Utilisez "io.TextIOWrapper" pour lire des fichiers
   texte compressés en mode *universal newlines*.

   Modifié dans la version 3.6: "ZipFile.open()" can now be used to
   write files into the archive with the "mode='w'" option.

   Modifié dans la version 3.6: Appeler "open()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

   Modifié dans la version 3.13: Added attributes "name" and "mode"
   for the writeable file-like object. The value of the "mode"
   attribute for the readable file-like object was changed from "'r'"
   to "'rb'".

ZipFile.extract(member, path=None, pwd=None)

   Extract a member from the archive to the current working directory;
   *member* must be its full name or a "ZipInfo" object.  Its file
   information is extracted as accurately as possible.  *path*
   specifies a different directory to extract to.  *member* can be a
   filename or a "ZipInfo" object. *pwd* is the password used for
   encrypted files as a "bytes" object.

   Retourne le chemin normalisé créé (un dossier ou un nouveau
   fichier).

   Note:

     Si le nom de fichier d'un membre est un chemin absolu, le
     disque/partage UNC et les (anti)slashes de départ seront
     supprimés, par exemple "///foo/bar" devient "foo/bar" sous Unix
     et "C:\foo\bar" devient "foo\bar" sous Windows. Et tous les
     composants "".."" dans le nom de fichier d'un membre seront
     supprimés, par exemple "../../foo../../ba..r" devient
     "foo../ba..r". Sous Windows les caractères illégaux (":", "<",
     ">", "|", """, "?" et "*") sont remplacés par un *underscore*
     ("_").

   Modifié dans la version 3.6: Appeler "extract()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

   Modifié dans la version 3.6.2: Le paramètre *path* accepte un objet
   chemin-compatible *path-like object*.

ZipFile.extractall(path=None, members=None, pwd=None)

   Extract all members from the archive to the current working
   directory.  *path* specifies a different directory to extract to.
   *members* is optional and must be a subset of the list returned by
   "namelist()".  *pwd* is the password used for encrypted files as a
   "bytes" object.

   Avertissement:

     N'extrayez jamais d'archives depuis des sources non fiables sans
     inspection préalable. Il est possible que des fichiers soient
     créés en dehors de *path*, par exemple des membres qui ont des
     chemins de fichier absolus commençant par ""/"" ou des noms de
     fichier avec deux points "".."".  Ce module essaie de prévenir
     ceci. Voir la note de "extract()".

   Modifié dans la version 3.6: Appeler "extractall()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

   Modifié dans la version 3.6.2: Le paramètre *path* accepte un objet
   chemin-compatible *path-like object*.

ZipFile.printdir()

   Affiche la liste des contenus de l'archive sur "sys.stdout".

ZipFile.setpassword(pwd)

   Set *pwd* (a "bytes" object) as default password to extract
   encrypted files.

ZipFile.read(name, pwd=None)

   Return the bytes of the file *name* in the archive.  *name* is the
   name of the file in the archive, or a "ZipInfo" object.  The
   archive must be open for read or append. *pwd* is the password used
   for encrypted files as a "bytes" object and, if specified,
   overrides the default password set with "setpassword()". Calling
   "read()" on a ZipFile that uses a compression method other than
   "ZIP_STORED", "ZIP_DEFLATED", "ZIP_BZIP2", "ZIP_LZMA", or
   "ZIP_ZSTANDARD" will raise a "NotImplementedError". An error will
   also be raised if the corresponding compression module is not
   available.

   Modifié dans la version 3.6: Appeler "read()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

ZipFile.testzip()

   Lit tous les fichiers de l'archive et vérifie leurs sommes CRC et
   leurs en-têtes. Retourne le nom du premier fichier mauvais ou
   retourne "None" sinon.

   Modifié dans la version 3.6: Appeler "testzip()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)

   Écrit le fichier nommé *filename* dans l'archive, lui donnant
   *arcname* comme nom dans l'archive (par défaut, *arcname* prend la
   même valeur que *filename* mais sans lettre de disque et séparateur
   de chemin en première position). Si donné, *compress_type* écrase
   la valeur donnée pour le paramètre *compression* au constructeur
   pour la nouvelle entrée. De la même manière, *compression* écrase
   le constructeur si donné. L'archive doit être ouverte avec le mode
   "'w'", "'x'" ou "'a'".

   Note:

     The ZIP file standard historically did not specify a metadata
     encoding, but strongly recommended CP437 (the original IBM PC
     encoding) for interoperability.  Recent versions allow use of
     UTF-8 (only).  In this module, UTF-8 will automatically be used
     to write the member names if they contain any non-ASCII
     characters.  It is not possible to write member names in any
     encoding other than ASCII or UTF-8.

   Note:

     Les noms d'archive doivent être relatifs à la racine de
     l'archive, c'est-à-dire qu'ils ne doivent pas commencer par un
     séparateur de chemin.

   Note:

     Si "arcname" (ou "filename" si "arcname" n'est pas donné)
     contient un octet nul, le nom du fichier dans l'archive sera
     tronqué à l'octet nul.

   Note:

     A leading slash in the filename may lead to the archive being
     impossible to open in some zip programs on Windows systems.

   Modifié dans la version 3.6: Appeler "write()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

   Écrit un fichier dans l'archive. Le contenu est *data*, qui peut
   être soit une instance de "str" ou une instance de "bytes" ; s'il
   s'agit d'une "str", il est encodé en UTF-8 au préalable.
   *zinfo_or_arcname* est soit le nom de fichier qu'il sera donné dans
   l'archive, soit une instance de "ZipInfo". Si c'est une instance,
   au moins le nom de fichier, la date et l'heure doivent être donnés.
   S'il s'agit d'un nom, la date et l'heure sont définies sur la date
   et l'heure actuelles. L'archive doit être ouverte avec le mode
   "'w'", "'x'" ou "'a'".

   Si donné, *compress_type* écrase la valeur donnée pour le paramètre
   *compression* au constructeur de la nouvelle entrée ou dans le
   paramètre *zinfo_or_arcname* (si c'est une instance de "ZipInfo").
   De la même manière, *compresslevel* le constructeur si donné.

   Note:

     Lorsque l'on passe une instance de "ZipInfo" dans le paramètre
     *zinfo_or_arcname*, la méthode de compression utilisée sera celle
     spécifiée dans le membre *compress_type* de l'instance "ZipInfo"
     donnée. Par défaut, le constructeur de la classe "ZipInfo"
     définit ce membre à "ZIP_STORED".

   Modifié dans la version 3.2: L'argument *compress_type*.

   Modifié dans la version 3.6: Appeler "writestr()" sur un fichier
   ZipFile fermé lève une erreur "ValueError". Précédemment, une
   erreur "RuntimeError" était levée.

ZipFile.mkdir(zinfo_or_directory, mode=511)

   Create a directory inside the archive.  If *zinfo_or_directory* is
   a string, a directory is created inside the archive with the mode
   that is specified in the *mode* argument. If, however,
   *zinfo_or_directory* is a "ZipInfo" instance then the *mode*
   argument is ignored.

   The archive must be opened with mode "'w'", "'x'" or "'a'".

   Ajouté dans la version 3.11.

Les attributs suivants sont aussi disponibles :

ZipFile.filename

   Nom du fichier ZIP.

ZipFile.debug

   Le niveau d'affichage de *debug* à utiliser. Peut être défini de
   "0" (par défaut, pas d'affichage) à "3" (affichage le plus bavard).
   Les informations de débogage sont affichées sur "sys.stdout".

ZipFile.comment

   Le commentaire associé au fichier ZIP en tant qu'objet "bytes". Si
   vous affectez un commentaire à une instance de "ZipFile" créée avec
   le mode "'w'", "'x'" ou "'a'", il ne doit pas dépasser 65535
   octets. Les commentaires plus longs que cette taille seront
   tronqués.


Path objects
============

class zipfile.Path(root, at='')

   Construit un objet *Path* depuis le fichier ZIP *root* (qui peut
   être une instance de "ZipFile" ou tout ce qui sera accepté par le
   paramètre *file* du constructeur de "ZipFile").

   "at" indique la position de ce *Path* dans l'archive ZIP, par
   exemple ""dir/file.txt"", ""dir/"", ou """". Par défaut c'est une
   chaine vide, indiquant la racine de l'archive.

   Note:

     The "Path" class does not sanitize filenames within the ZIP
     archive. Unlike the "ZipFile.extract()" and
     "ZipFile.extractall()" methods, it is the caller's responsibility
     to validate or sanitize filenames to prevent path traversal
     vulnerabilities (e.g., filenames containing ".." or absolute
     paths). When handling untrusted archives, consider resolving
     filenames using "os.path.abspath()" and checking against the
     target directory with "os.path.commonpath()".

Les objets "Path" de "zipfile" exposent les fonctionnalités suivantes
des objets de "pathlib.Path" :

Path objects are traversable using the "/" operator or "joinpath".

Path.name

   Le dernier segment du chemin.

Path.open(mode='r', *, pwd, **)

   Appelle "ZipFile.open()" sur ce chemin. Il est possible d'ouvrir en
   lecture ou en écriture, au format texte ou binaire, via les modes
   "'r'", "'w'", "'rb'" et "'wb'". Les arguments positionnels et
   nommés sont passés à la classe "io.TextIOWrapper" lors d'une
   ouverture au format texte, ils sont ignorés autrement. "pwd" est le
   paramètre "pwd" de "ZipFile.open()".

   Modifié dans la version 3.9: prise en charge des modes texte et
   binaire pour "open". Le mode texte est maintenant le mode par
   défaut.

   Modifié dans la version 3.11.2: The "encoding" parameter can be
   supplied as a positional argument without causing a "TypeError". As
   it could in 3.9. Code needing to be compatible with unpatched 3.10
   and 3.11 versions must pass all "io.TextIOWrapper" arguments,
   "encoding" included, as keywords.

Path.iterdir()

   Énumère le contenu du dossier actuel.

Path.is_dir()

   Renvoie "True" si ce chemin pointe sur un dossier.

Path.is_file()

   Renvoie "True" si ce chemin pointe sur un fichier.

Path.is_symlink()

   Return "True" if the current context references a symbolic link.

   Ajouté dans la version 3.12.

   Modifié dans la version 3.13: Previously, "is_symlink" would
   unconditionally return "False".

Path.exists()

   Renvoie "True" si le chemin pointe sur un fichier ou un dossier de
   l'archive ZIP

Path.suffix

   The last dot-separated portion of the final component, if any. This
   is commonly called the file extension.

   Ajouté dans la version 3.11: Added "Path.suffix" property.

Path.stem

   The final path component, without its suffix.

   Ajouté dans la version 3.11: Added "Path.stem" property.

Path.suffixes

   A list of the path’s suffixes, commonly called file extensions.

   Ajouté dans la version 3.11: Added "Path.suffixes" property.

Path.read_text(*, **)

   Lit le fichier au format texte. Les arguments positionnels et
   nommés sont passés à "io.TextIOWrapper" (sauf "buffer", qui est
   imposé par le contexte)

   Modifié dans la version 3.11.2: The "encoding" parameter can be
   supplied as a positional argument without causing a "TypeError". As
   it could in 3.9. Code needing to be compatible with unpatched 3.10
   and 3.11 versions must pass all "io.TextIOWrapper" arguments,
   "encoding" included, as keywords.

Path.read_bytes()

   Lit le fichier en mode binaire, renvoyant un objet *bytes*.

Path.joinpath(*other)

   Return a new Path object with each of the *other* arguments joined.
   The following are equivalent:

      >>> Path(...).joinpath('child').joinpath('grandchild')
      >>> Path(...).joinpath('child', 'grandchild')
      >>> Path(...) / 'child' / 'grandchild'

   Modifié dans la version 3.10: Prior to 3.10, "joinpath" was
   undocumented and accepted exactly one parameter.

The zipp project provides backports of the latest path object
functionality to older Pythons. Use "zipp.Path" in place of
"zipfile.Path" for early access to changes.


PyZipFile objects
=================

Le constructeur de "PyZipFile" prend les mêmes paramètres que le
constructeur de "ZipFile" avec un paramètre additionnel *optimize*.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)

   Modifié dans la version 3.2: Added the *optimize* parameter.

   Modifié dans la version 3.4: Les extensions ZIP64 sont activées par
   défaut.

   Les instances ont une méthode supplémentaire par rapport aux objets
   "ZipFile" :

   writepy(pathname, basename='', filterfunc=None)

      Cherche les fichiers "*.py" et ajoute le fichier correspondant à
      l'archive.

      Si le paramètre *optimize* du constructeur de "PyZipFile" n'a
      pas été donné ou est à "-1", le fichier correspondant est un
      fichier "*.pyc", à compiler si nécessaire.

      Si le paramètre *optimize* du constructeur de "PyZipFile" est à
      "0", "1" ou "2", ne sont ajoutés dans l'archive que les fichiers
      avec ce niveau d'optimisation (voir "compile()"), à compiler si
      nécessaire.

      Si *pathname* est un fichier, le chemin de fichier doit terminer
      par  ".py" et uniquement le fichier ("*.pyc" correspondant) est
      ajouté au niveau le plus haut (sans information de chemin). Si
      *pathname* est un fichier ne terminant pas par ".py", une
      exception "RuntimeError" est levée. Si c'est un répertoire et
      que le répertoire n'est pas un répertoire de paquet, alors tous
      les fichiers  "*.pyc" sont ajoutés à la racine. Si le répertoire
      est un répertoire de paquet, alors tous les "*.pyc" sont ajoutés
      sous le nom du paquet en tant que chemin, et s'il y a des sous-
      répertoires qui sont des répertoires de paquet, ils sont tous
      ajoutés récursivement dans un ordre trié.

      *basename* n'est sensé être utilisé qu'en interne.

      *filterfunc*, si donné, doit être une fonction prenant une seule
      chaîne de caractères en argument. Il lui sera passé chaque
      chemin (incluant chaque chemin de fichier complet individuel)
      avant d'être ajouté à l'archive. Si *filterfunc* retourne une
      valeur fausse, le chemin n'est pas ajouté et si c'est un
      répertoire son contenu est ignoré. Par exemple, si nos fichiers
      de test sont tous soit dans des répertoires "test" ou commencent
      par "test_", nous pouvons utiliser une fonction *filterfunc*
      pour les exclure :

         >>> zf = PyZipFile('myprog.zip')
         >>> def notests(s):
         ...     fn = os.path.basename(s)
         ...     return (not (fn == 'test' or fn.startswith('test_')))
         ...
         >>> zf.writepy('myprog', filterfunc=notests)

      La méthode "writepy()" crée des archives avec des noms de
      fichier comme suit :

         string.pyc                   # Top level name
         test/__init__.pyc            # Package directory
         test/testall.pyc             # Module test.testall
         test/bogus/__init__.pyc      # Subpackage directory
         test/bogus/myfile.pyc        # Submodule test.bogus.myfile

      Modifié dans la version 3.4: Added the *filterfunc* parameter.

      Modifié dans la version 3.6.2: Le paramètre *pathname* accepte
      un objet chemin-compatible *path-like object*.

      Modifié dans la version 3.7: La récursion trie les entrées de
      dossier.


ZipInfo objects
===============

Des instances de la classe "ZipInfo" sont retournées par les méthodes
"getinfo()" et "infolist()" des objets "ZipFile". Chaque objet stocke
des informations sur un seul membre de l'archive ZIP.

Il y a une méthode de classe pour créer une instance de "ZipInfo" pour
un fichier du système de fichiers :

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

   Construit une instance de "ZipInfo" pour le fichier du système de
   fichiers, en préparation de l'ajouter à un fichier ZIP.

   *filename* doit être un chemin vers un fichier ou un répertoire
   dans le système de fichiers.

   Si *arcname* est spécifié, il est utilisé en tant que nom dans
   l'archive. Si *arcname* n'est pas spécifié, le nom sera le même que
   *filename* mais sans lettre de disque et sans séparateur de chemin
   en première position.

   Les fichiers ZIP plus anciens que le 1er janvier 1980 sont
   autorisés lorsque l'argument *strict_timestamps* vaut "False",
   moyennant de les voir datés du 1er janvier 1980. De même pour les
   fichiers datés d'après le 31 décembre 2107 qui voient leur
   horodatage fixé au 31 décembre 2107.

   Ajouté dans la version 3.6.

   Modifié dans la version 3.6.2: Le paramètre  *filename* accepte un
   objet chemin-compatible *path-like object*.

   Modifié dans la version 3.8: Added the *strict_timestamps* keyword-
   only parameter.

Les instances ont les méthodes et attributs suivants :

ZipInfo.is_dir()

   Retourne "True" si le membre d'archive est un répertoire.

   Utilise le nom de l'entrée : les répertoires doivent toujours se
   terminer par "/".

   Ajouté dans la version 3.6.

ZipInfo.filename

   Nom du fichier dans l'archive.

ZipInfo.date_time

   The time and date of the last modification to the archive member.
   This is a tuple of six values representing the "last [modified]
   file time" and "last [modified] file date" fields from the ZIP
   file's central directory.

   The tuple contains:

   +---------+----------------------------+
   | Index   | Valeur                     |
   |=========|============================|
   | "0"     | Année (>= 1980)            |
   +---------+----------------------------+
   | "1"     | Mois (indexé à partir de   |
   |         | 1)                         |
   +---------+----------------------------+
   | "2"     | Jour du mois (indexé à     |
   |         | partir de 1)               |
   +---------+----------------------------+
   | "3"     | Heures (indexées à partir  |
   |         | de 0)                      |
   +---------+----------------------------+
   | "4"     | Minutes (indexées à partir |
   |         | de 0)                      |
   +---------+----------------------------+
   | "5"     | Secondes (indexées à       |
   |         | partir de 0)               |
   +---------+----------------------------+

   Note:

     The ZIP format supports multiple timestamp fields in different
     locations (central directory, extra fields for NTFS/UNIX systems,
     etc.). This attribute specifically returns the timestamp from the
     central directory. The central directory timestamp format in ZIP
     files does not support timestamps before 1980. While some extra
     field formats (such as UNIX timestamps) can represent earlier
     dates, this attribute only returns the central directory
     timestamp.The central directory timestamp is interpreted as
     representing local time, rather than UTC time, to match the
     behavior of other zip tools.

ZipInfo.compress_type

   Type de compression du membre d'archive.

ZipInfo.comment

   Commentaire pour le membre d'archive individuel en tant qu'objet
   "bytes".

ZipInfo.extra

   Données du champ d'extension. La documentation PKZIP Application
   Note contient quelques commentaires sur la structure interne des
   données contenues dans cet objet "bytes".

ZipInfo.create_system

   Système ayant créé l'archive ZIP.

ZipInfo.create_version

   Version de PKZIP ayant créé l'archive ZIP.

ZipInfo.extract_version

   Version de PKZIP nécessaire à l'extraction de l'archive ZIP.

ZipInfo.reserved

   Doit être à zéro.

ZipInfo.flag_bits

   Bits d'options ZIP.

ZipInfo.volume

   Numéro de volume de l'entête du fichier.

ZipInfo.internal_attr

   Attributs internes.

ZipInfo.external_attr

   Attributs de fichier externes.

ZipInfo.header_offset

   Longueur de l'entête du fichier en octets.

ZipInfo.CRC

   CRC-32 du fichier décompressé.

ZipInfo.compress_size

   Taille des données décompressées.

ZipInfo.file_size

   Taille du fichier décompressé.


Command-line interface
======================

The "zipfile" module provides a simple command-line interface to
interact with ZIP archives.

Si vous voulez créer une nouvelle archive ZIP, spécifiez son nom après
l'option "-c" et listez ensuite le(s) nom(s) de fichier à inclure :

   $ python -m zipfile -c monty.zip spam.txt eggs.txt

Passer un répertoire est aussi possible :

   $ python -m zipfile -c monty.zip life-of-brian_1979/

Si vous voulez extraire une archive ZIP dans un répertoire donné,
utilisez l'option "-e" :

   $ python -m zipfile -e monty.zip target-dir/

Pour une liste des fichiers dans une archive ZIP, utilisez l'option
"-l" :

   $ python -m zipfile -l monty.zip


Options de la ligne de commande
-------------------------------

-l <zipfile>
--list <zipfile>

   Liste les fichiers dans un fichier ZIP *zipfile*.

-c <zipfile> <source1> ... <sourceN>
--create <zipfile> <source1> ... <sourceN>

   Crée un fichier ZIP *zipfile* à partir des fichiers *source*.

-e <zipfile> <output_dir>
--extract <zipfile> <output_dir>

   Extrait le fichier ZIP *zipfile* vers le répertoire cible
   *output_dir*.

-t <zipfile>
--test <zipfile>

   Teste si le fichier zip est valide.

--metadata-encoding <encoding>

   Specify encoding of member names for "-l", "-e" and "-t".

   Ajouté dans la version 3.11.


Problèmes de décompression
==========================

L'extraction d'une archive ZIP par le module *zipfile* peut échouer
pour les raisons listées ci-dessous.


À cause du fichier lui-même
---------------------------

La décompression peut échouer à cause d'un mot de passe ou d'une somme
de contrôle CRC incorrectes. Elle peut aussi échouer si le format, la
méthode de compression, ou de chiffrement n'est pas implémenté.


File system limitations
-----------------------

Dépasser les limites du système de fichiers peut faire échouer la
décompression. Ces limites peuvent concerner les caractères licites
pour un nom de fichier, la longueur du nom du fichier ou du chemin, la
taille d'un fichier, le nombre de fichiers, etc.


Ressources limitées
-------------------

Le manque de mémoire ou d'espace disque peut mener à un échec de
décompression. Par exemple, une bombe de décompression (ZIP bomb),
décompressés avec *zifile* peut remplir l'espace disque.


Interruption
------------

Une interruption durant la décompression, en utilisant *control-C* ou
en tuant le processus, peut mener à une décompression partielle de
l'archive.


Comportements par défaut de l'extraction
----------------------------------------

Ne pas connaître le comportement d'extraction par défaut peut causer
des résultats inattendus. Par exemple, lors de l'extraction d'une même
archive deux fois, les fichiers sont écrasés sans prévenir.
