"mailcap" — Manipulation de fichiers Mailcap
********************************************

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

Obsolète depuis la version 3.11, sera supprimé dans la version 3.13:
The "mailcap" module is deprecated (see **PEP 594** for details). The
"mimetypes" module provides an alternative.

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

Mailcap files are used to configure how MIME-aware applications such
as mail readers and web browsers react to files with different MIME
types. (The name "mailcap" is derived from the phrase "mail
capability".)  For example, a mailcap file might contain a line like
"video/mpeg; xmpeg %s".  Then, if the user encounters an email message
or web document with the MIME type *video/mpeg*, "%s" will be replaced
by a filename (usually one belonging to a temporary file) and the
**xmpeg** program can be automatically started to view the file.

The mailcap format is documented in **RFC 1524**, "A User Agent
Configuration Mechanism For Multimedia Mail Format Information", but
is not an internet standard.  However, mailcap files are supported on
most Unix systems.

mailcap.findmatch(caps, MIMEtype, key='view', filename='/dev/null', plist=[])

   Renvoie une paire ; le premier élément est une chaîne de caractères
   (string) contenant la ligne de commande à exécuter (qui peut être
   passée à "os.system()"), et le second élément est l’entrée
   *mailcap* pour un type de MIME donné. Si le type MIME n’est pas
   identifié, "(None, None)" est renvoyé.

   *key* est le nom de champ souhaité, qui représente le type d’action
   à exécuter ; la valeur par défaut est "'view'", puisque dans la
   majorité des cas le besoin consiste juste à lire le corps (body) de
   la donnée de type MIME. Les autres valeurs possibles peuvent être
   "'compose'" et "'edit'", si le besoin consiste à créer un nouveau
   corps de données (body) ou modifier celui existant. Voir la **RFC
   1524** pour une liste complète des champs.

   *filename* est le nom de fichier à remplacer pour "%s" en ligne de
   commande ; la valeur par défaut est "’/dev/null’" qui n’est
   certainement pas celle que vous attendez. Donc la plupart du temps,
   le nom de fichier doit être indiqué.

   *plist* peut être une liste contenant des noms de paramètres ; la
   valeur par défaut est une simple liste vide. Chaque entrée dans la
   liste doit être une chaîne de caractères contenant le nom du
   paramètre, un signe égal ("’=‘"), ainsi que la valeur du paramètre.
   Les entrées *mailcap* peuvent contenir des noms de paramètres tels
   que "%{foo}", remplacé par la valeur du paramètre nommé *foo*. Par
   exemple, si la ligne de commande "showpartial %{id} %{number}
   %{total}" est un fichier *mailcap*, et *plist*  configuré à
   "[‘id=1’, ‘number=2’, ‘total=3’]", la ligne de commande qui en
   résulte est "’showpartial 1 2 3’".

   Dans un fichier *mailcap*, le champ « test » peut être renseigné de
   façon optionnelle afin de tester certaines conditions externes
   (comme l’architecture machine, ou le gestionnaire de fenêtre
   utilisé) afin de déterminer si la ligne *mailcap* est pertinente ou
   non. "findmatch()" vérifie automatiquement ces conditions et ignore
   l’entrée si la vérification échoue.

   Modifié dans la version 3.11: To prevent security issues with shell
   metacharacters (symbols that have special effects in a shell
   command line), "findmatch" will refuse to inject ASCII characters
   other than alphanumerics and "@+=:,./-_" into the returned command
   line.If a disallowed character appears in *filename*, "findmatch"
   will always return "(None, None)" as if no entry was found. If such
   a character appears elsewhere (a value in *plist* or in
   *MIMEtype*), "findmatch" will ignore all mailcap entries which use
   that value. A "warning" will be raised in either case.

mailcap.getcaps()

   Renvoie un dictionnaire qui associe les types MIME à une liste
   d’entrées de fichier *mailcap*. Ce dictionnaire doit être transmis
   à la fonction "findmatch()". Une entrée est enregistrée en tant
   qu’une liste de dictionnaires, mais il n’est pas nécessaire de
   connaitre les détails de cette représentation.

   L’information provient de tous les fichiers *mailcap* trouvés dans
   le système. Les configurations réalisées dans le fichier *mailcap*
   du répertoire utilisateur "$HOME/.mailcap" outrepasse les
   configurations systèmes des fichiers *mailcap* "/etc/mailcap",
   "/usr/etc/mailcap", et "/usr/local/etc/mailcap".

Un exemple d’utilisation :

   >>> import mailcap
   >>> d = mailcap.getcaps()
   >>> mailcap.findmatch(d, 'video/mpeg', filename='tmp1223')
   ('xmpeg tmp1223', {'view': 'xmpeg %s'})
