31.1. "zipimport" — Importer des modules à partir d'archives Zip
****************************************************************

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

Ce module ajoute la possibilité d'importer des modules Python ("*.py",
"*.pyc") et des paquets depuis des archives au format ZIP. Il n'est
généralement pas nécessaire d'utiliser explicitement le module
"zipimport" ; il est automatiquement utilisé par le mécanisme intégré
de "import" pour les éléments "sys.path" qui sont des chemins vers les
archives ZIP.

Typiquement, "sys.path" est une liste de noms de répertoires sous
forme de chaînes.  Ce module permet également à un élément de
"sys.path" d'être une chaîne nommant une archive de fichier ZIP.
L'archive ZIP peut contenir une structure de sous-répertoire pour
prendre en charge les importations de paquets, et un chemin dans
l'archive peut être spécifié pour importer uniquement à partir d'un
sous-répertoire.  Par exemple, le chemin d'accès "example.zip/lib/"
importerait uniquement depuis le sous-répertoire "lib/" dans
l'archive.

Tous les fichiers peuvent être présents dans l'archive ZIP, mais seuls
les fichiers ".py" et ".pyc" sont disponibles pour importation.
L'importation ZIP des modules dynamiques (".pyd", ".so") est
interdite. Notez que si une archive ne contient que des fichiers ".py"
, Python n'essaiera pas de modifier l'archive en ajoutant le fichier
correspondant ".pyc", ce qui signifie que si une archive ZIP ne
contient pas de fichier: ".pyc", l'importation peut être assez lente.

Les archives ZIP avec un commentaire ne sont actuellement pas prises
en charge.

Voir aussi:

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

  **PEP 273** - Import Modules from Zip Archives
     Écrit par James C. Ahlstrom, qui a également fourni une mise en
     œuvre. Python 2.3 suit les spécifications de PEP 273, mais
     utilise une implémentation écrite par Just van Rossum qui utilise
     les crochets d'importation décrits dans PEP 302.

  **PEP 302** — Nouveaux crochets d'importation
     Le PEP pour ajouter les crochets d'importation qui aident ce
     module à fonctionner.

Ce module définit une exception :

exception zipimport.ZipImportError

   Exception levée par les objets *zipimporter*. C'est une sous-classe
   de "ImportError", donc il peut être pris comme "ImportError",
   aussi.


31.1.1. Objets *zimporter*
==========================

"zipimporter" est la classe pour importer des fichiers ZIP.

class zipimport.zipimporter(archivepath)

   Créez une nouvelle instance de *zipimporter*. *archivepath* doit
   être un chemin vers un fichier ZIP, ou vers un chemin spécifique
   dans un fichier ZIP.  Par exemple, un *archivepath* de
   "foo/bar.zip/lib" cherchera les modules dans le répertoire "lib" du
   fichier ZIP "foo/bar.zip" (si celui-ci existe).

   "ZipImportError" est levée si *archivepath* ne pointe pas vers une
   archive ZIP valide.

   find_module(fullname[, path])

      Rechercher un module spécifié par *fullname*. *fullname* doit
      être le nom du module entièrement qualifié (*dotted*). Elle
      retourne l'instance *zipimporter* elle-même si le module a été
      trouvé, ou "None" si ce n'est pas le cas. L'argument optionnel
      *path* est ignoré --- il est là pour la compatibilité avec le
      protocole de l'importateur.

   get_code(fullname)

      Retourne l'objet de code pour le module spécifié. Lève
      "ZipImportError" si le module n'a pas pu être trouvé.

   get_data(pathname)

      Renvoie les données associées à *pathname*. Lève "OSError" si le
      fichier n'a pas été trouvé.

      Modifié dans la version 3.3: Précédemment, c'était l'exception
      "IOError" qui était levée, au lieu de "OSError".

   get_filename(fullname)

      Renvoie la valeur "__file____" qui serait définie si le module
      spécifié était importé. Lève "ZipImportError" si le module n'a
      pas pu être trouvé.

      Nouveau dans la version 3.1.

   get_source(fullname)

      Renvoie le code source du module spécifié. Lève "ZipImportError"
      si le module n'a pas pu être trouvé, renvoie "None" si l'archive
      contient le module, mais n'en a pas la source.

   is_package(fullname)

      Renvoie "True" si le module spécifié par *fullname* est un
      paquet. Lève "ZipImportError" si le module n'a pas pu être
      trouvé.

   load_module(fullname)

      Charge le module spécifié par *fullname*. *fullname* doit être
      le nom du module entièrement qualifié (*dotted*). Il renvoie le
      module importé, ou augmente "ZipImportError" s'il n'a pas été
      trouvé.

   archive

      Le nom de fichier de l'archive ZIP associé à l'importateur, sans
      sous-chemin possible.

   prefix

      Le sous-chemin du fichier ZIP où les modules sont recherchés.
      C'est la chaîne vide pour les objets *zipimporter* qui pointent
      vers la racine du fichier ZIP.

   Les attributs "archive" et "prefix", lorsqu'ils sont combinés avec
   une barre oblique, égalent l'argument original *archivepath* donné
   au constructeur "zipimporter".


31.1.2. Exemples
================

Voici un exemple qui importe un module d'une archive ZIP — notez que
le module "zipimport" n'est pas explicitement utilisé.

   $ unzip -l example.zip
   Archive:  example.zip
     Length     Date   Time    Name
    --------    ----   ----    ----
        8467  11-26-02 22:30   jwzthreading.py
    --------                   -------
        8467                   1 file
   $ ./python
   Python 2.3 (#1, Aug 1 2003, 19:54:32)
   >>> import sys
   >>> sys.path.insert(0, 'example.zip')  # Add .zip file to front of path
   >>> import jwzthreading
   >>> jwzthreading.__file__
   'example.zip/jwzthreading.py'
