11.5. "filecmp" – Comparaisons de fichiers et de répertoires
************************************************************

**Code source :** Lib/filecmp.py

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

Le module "filecmp" définit les fonctions permettant de comparer les
fichiers et les répertoires, avec différents compromis optionnels
durée / exactitude. Pour comparer des fichiers, voir aussi le module
"difflib".

Le module "filecmp" définit les fonctions suivantes :

filecmp.cmp(f1, f2, shallow=True)

   Compare les fichiers nommés *f1* et *f2* , renvoie "True" s’ils
   semblent égaux, "False" sinon.

   Si *shallow* est vrai, les fichiers avec des signatures "os.stat()"
   identiques sont considérés comme égaux. Sinon, le contenu des
   fichiers est comparé.

   Notez qu'aucun programme externe n'est appelé à partir de cette
   fonction, ce qui lui confère des qualités de portabilité et
   d'efficacité.

   Cette fonction utilise un cache pour les comparaisons antérieures
   et les résultats, les entrées du cache étant invalidées si les
   informations "os.stat()" du fichier sont modifiées. La totalité du
   cache peut être effacée avec "clear_cache()".

filecmp.cmpfiles(dir1, dir2, common, shallow=True)

   Compare les fichiers des deux répertoires *dir1* et *dir2* dont les
   noms sont donnés par *common*.

   Renvoie trois listes de noms de fichiers : *match* , *mismatch*,
   *errors*. *match* contient la liste des fichiers qui correspondent,
   *mismatch* contient les noms de ceux qui ne correspondent pas et
   *errors* répertorie les noms des fichiers qui n'ont pas pu être
   comparés. Les fichiers sont répertoriés dans *errors* s'ils
   n'existent pas dans l'un des répertoires, si l'utilisateur ne
   dispose pas de l'autorisation nécessaire pour les lire ou si la
   comparaison n'a pas pu être effectuée pour une autre raison.

   Le paramètre *shallow* a la même signification et la même valeur
   par défaut que pour "filecmp.cmp()".

   Par exemple, "cmpfiles('a', 'b', ['c', 'd/e'])"  compare "a/c" et
   "b/c" et "a/d/e" avec "b/d/e".  "'c'" et "'d/e'" seront chacun dans
   l'une des trois listes renvoyées.

filecmp.clear_cache()

   Efface le cache *filecmp*. Cela peut être utile si un fichier est
   comparé juste après avoir été modifié (dans un délai inférieur à la
   résolution *mtime* du système de fichiers sous-jacent).

   Nouveau dans la version 3.4.


11.5.1. La classe "dircmp"
==========================

class filecmp.dircmp(a, b, ignore=None, hide=None)

   Construit un nouvel objet de comparaison de répertoires, pour
   comparer les répertoires *a* et *b*. *ignore* est une liste de noms
   à ignorer, par défaut à "filecmp.DEFAULT_IGNORES". *hide* est une
   liste de noms à cacher, par défaut  à "[os.curdir, os.pardir]".

   La classe "dircmp" compare les fichiers en faisant des comparaisons
   *superficielles* comme décrit pour "filecmp.cmp()".

   La classe "dircmp" fournit les méthodes suivantes :

   report()

      Affiche (sur "sys.stdout") une comparaison entre *a* et *b*.

   report_partial_closure()

      Affiche une comparaison entre *a* et *b* et les sous-répertoires
      immédiats communs.

   report_full_closure()

      Affiche une comparaison entre a et b et les sous-répertoires
      communs (récursivement).

   La classe "dircmp" offre un certain nombre d'attributs intéressants
   qui peuvent être utilisés pour obtenir diverses informations sur
   les arborescences de répertoires comparées.

   Notez que, via les points d'ancrage "__getattr__()", tous les
   attributs sont calculés de manière paresseuse. Il n'y a donc pas de
   pénalité en vitesse si seuls les attributs rapides à calculer sont
   utilisés.

   left

      Le répertoire *a*.

   right

      Le répertoire *b*.

   left_list

      Fichiers et sous-répertoires dans *a* , filtrés par *hide* et
      *ignore*.

   right_list

      Fichiers et sous-répertoires dans *b* , filtrés par *hide* et
      *ignore*.

   common

      Fichiers et sous-répertoires à la fois dans *a* et *b*.

   left_only

      Fichiers et sous-répertoires uniquement dans *a*.

   right_only

      Fichiers et sous-répertoires uniquement dans *b*.

   common_dirs

      Sous-répertoires à la fois dans *a* et *b*.

   common_files

      Fichiers à la fois dans *a* et *b*.

   common_funny

      Noms dans *a* et *b* , tels que le type diffère entre les
      répertoires, ou noms pour lesquels "os.stat()" signale une
      erreur.

   same_files

      Fichiers identiques dans *a* et *b*, en utilisant l'opérateur de
      comparaison de fichiers de la classe.

   diff_files

      Fichiers figurant à la fois dans *a* et dans *b* , dont le
      contenu diffère en fonction de l'opérateur de comparaison de
      fichiers de la classe.

   funny_files

      Fichiers à la fois dans *a* et dans *b* , mais ne pouvant pas
      être comparés.

   subdirs

      Un dictionnaire faisant correspondre les noms dans "common_dirs"
      vers des objets "dircmp".

filecmp.DEFAULT_IGNORES

   Nouveau dans la version 3.4.

   Liste des répertoires ignorés par défaut par "dircmp".

Voici un exemple simplifié d'utilisation de l'attribut "subdirs" pour
effectuer une recherche récursive dans deux répertoires afin
d'afficher des fichiers communs différents :

   >>> from filecmp import dircmp
   >>> def print_diff_files(dcmp):
   ...     for name in dcmp.diff_files:
   ...         print("diff_file %s found in %s and %s" % (name, dcmp.left,
   ...               dcmp.right))
   ...     for sub_dcmp in dcmp.subdirs.values():
   ...         print_diff_files(sub_dcmp)
   ...
   >>> dcmp = dircmp('dir1', 'dir2') 
   >>> print_diff_files(dcmp) 
