"email.contentmanager" : gestion du contenu MIME
************************************************

**Code source :** Lib/email/contentmanager.py

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

Nouveau dans la version 3.6: [1]

class email.contentmanager.ContentManager

   Classe mère pour les gestionnaires de contenu. Fournit les
   mécanismes de registre standard pour enregistrer les convertisseurs
   entre le contenu MIME et d'autres représentations, ainsi que les
   méthodes de répartition "get_content" et "set_content".

   get_content(msg, *args, **kw)

      Recherche une fonction de gestion en se basant sur le "mimetype"
      de *msg* (voir le paragraphe suivant), l'appelle en lui passant
      tous les arguments et renvoie le résultat de l'appel. Le
      gestionnaire doit extraire la charge utile de *msg* et renvoyer
      un objet qui encode les informations relatives aux données
      extraites.

      Pour trouver le gestionnaire, recherche les clés suivantes dans
      le registre, en s'arrêtant à la première trouvée :

      * une chaîne représentant le type MIME complet
        ("maintype/subtype") ;

      * une chaîne représentant le "maintype" ;

      * une chaîne vide.

      Si aucune de ces clés ne produit de gestionnaire, lève une
      "KeyError" pour le type MIME complet.

   set_content(msg, obj, *args, **kw)

      Si le "maintype" est "multipart", lève une "TypeError" ; sinon
      recherche une fonction de gestion en se basant sur le type de
      *obj* (voir le paragraphe suivant), appelle "clear_content()"
      sur le *msg* et appelle la fonction de gestion en lui passant
      tous les arguments. Le gestionnaire doit transformer et stocker
      *obj* en *msg*, apportant éventuellement d'autres modifications
      à *msg* également, comme l'ajout de divers en-têtes MIME pour
      coder les informations nécessaires à l'interprétation des
      données stockées.

      Pour trouver le gestionnaire, récupère le type de *obj* ("typ =
      type(obj)") et recherche les clés suivantes dans le registre, en
      s'arrêtant à la première trouvée :

      * le type lui-même ("typ") ;

      * le nom complet du type ("typ.__module__ + '.' +
        typ.__qualname__") ;

      * le nom qualifié du type ("typ.__qualname__") ;

      * le nom du type ("typ.__name__").

      Si aucune de ces clés ne correspond, répète toutes les
      vérifications ci-dessus pour chacun des types en suivant le
      *MRO* ("typ.__mro__"). Enfin, si aucune clé ne produit de
      gestionnaire, recherche un gestionnaire pour la clé "None". S'il
      n'y a pas de gestionnaire pour "None", lève une "KeyError" pour
      le nom complet du type.

      Ajoute également un en-tête *MIME-Version* s'il n'y en a pas
      (voir aussi "MIMEPart").

   add_get_handler(key, handler)

      Enregistre la fonction *handler* comme gestionnaire pour *key*.
      Pour les valeurs possibles de *key*, voir "get_content()".

   add_set_handler(typekey, handler)

      Enregistre *handler* comme fonction à appeler lorsqu'un objet
      d'un type correspondant à *typekey* est passé à "set_content()".
      Pour les valeurs possibles de *typekey*, voir "set_content()".


Instances de gestionnaires de contenus
======================================

Actuellement, le paquet *email* ne fournit qu'un seul gestionnaire de
contenu concret, "raw_data_manager", bien que d'autres puissent être
ajoutés à l'avenir. "raw_data_manager" est le "content_manager" fourni
par "EmailPolicy" et ses dérivés.

email.contentmanager.raw_data_manager

   Ce gestionnaire de contenu ne fournit qu'une interface minimale au-
   delà de celle fournie par "Message" lui-même : il  prend seulement
   en charge le texte, les chaînes d'octets brutes et les objets
   "Message". Néanmoins, il offre des avantages significatifs par
   rapport à l'API de base : "get_content" sur une partie de texte
   renvoie une chaîne Unicode sans que l'application ait besoin de la
   décoder manuellement, "set_content" fournit de nombreuses options
   pour contrôler les en-têtes ajoutés à une partie et l'encodage du
   transfert de contenu, et il permet l'utilisation des différentes
   méthodes "add_", ce qui simplifie la création de messages en
   plusieurs parties.

   email.contentmanager.get_content(msg, errors='replace')

      Renvoie la charge utile de la partie sous la forme d'une chaîne
      (pour les parties "text"), d'un objet "EmailMessage" (pour les
      parties "message/rfc822") ou d'un objet "bytes" (pour tous les
      autres types à l'exception de *multipart*). Lève une "KeyError"
      si cette méthode est appelée sur un "multipart". S'il s'agit
      d'une partie "text" et que *errors* est spécifié, ce paramètre
      est utilisé comme gestionnaire d'erreurs lors du décodage de la
      charge utile en Unicode. Le gestionnaire d'erreurs par défaut
      est "replace".

   email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
   email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
   email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

      Ajoute des en-têtes et une charge utile à *msg* :

      Ajoute un en-tête *Content-Type* avec une valeur
      "maintype/subtype".

      * Pour "str", définit le "maintype" MIME à "text" et définit le
        sous-type à *subtype* s'il est spécifié, ou à "plain" s'il ne
        l'est pas.

      * Pour "bytes", utilise les *maintype* et *subtype* spécifiés,
        ou lève une "TypeError" s'ils ne sont pas spécifiés.

      * Pour les objets "EmailMessage", définit le type principal
        (*maintype*) à "message" et définit le sous-type à *subtype*
        s'il est spécifié ou à "rfc822" s'il ne l'est pas. Si
        *subtype* est "partial", lève une erreur (les objets "bytes"
        doivent être utilisés pour construire les parties
        "message/partial").

      Si *charset* est fourni (qui n'est valide que pour "str"),
      encode la chaîne en octets en utilisant le jeu de caractères
      spécifié. La valeur par défaut est "utf-8". Si le *charset*
      spécifié est un alias connu pour un nom de jeu de caractères
      MIME standard, utilise plutôt le jeu de caractères standard.

      Si *cte* est défini, encode la charge utile à l'aide de
      l'encodage de transfert de contenu spécifié et définit l'en-tête
      *Content-Transfer-Encoding* à cette valeur. Les valeurs
      possibles pour *cte* sont "quoted-printable", "base64", "7bit",
      "8bit" et "binary". Si l'entrée ne peut pas être encodée dans
      l'encodage spécifié (par exemple, en spécifiant un *cte* de
      "7bit" pour une entrée qui contient des valeurs non-ASCII), lève
      une "ValueError".

      * Pour les objets "str", si *cte* n'est pas défini, utilise une
        heuristique pour déterminer l'encodage le plus compact.

      * Pour "EmailMessage", selon la **RFC 2046**, pour le *subtype*
        "rfc822`, lève une erreur pour un *cte* valant ``quoted-
        printable" ou "base64". Pour le *subtype* "external-body",
        lève une erreur pour tout *cte* autre que "7bit". Pour
        "message/rfc822", la valeur par défaut de *cte* est "8bit".
        Pour toutes les autres valeurs de *sous-type*, la valeur par
        défaut de *cte* est "7bit".

      Note:

        la valeur "binary" pour *cte* ne fonctionne pas encore
        correctement. L'objet "EmailMessage" tel que modifié par
        "set_content" est correct, mais "BytesGenerator" ne le
        sérialise pas correctement.

      Si *disposition* est spécifié, utilise cette valeur pour l'en-
      tête *Content-Disposition*. S'il n'est pas spécifié et que
      *filename* est spécifié, utilise la valeur "attachment" pour l
      'en-tête. Si ni *disposition* ni *filename* ne sont spécifiés,
      n'ajoute pas cet en-tête. Les seules valeurs valides pour
      *disposition* sont "attachment" et "inline".

      Si *filename* est spécifié, utilise cette valeur pour le
      paramètre "filename" de l'en-tête *Content-Disposition*.

      Si *cid* est spécifié, ajoute un en-tête *Content-ID* avec cette
      valeur.

      Si *params* est spécifié, itère sur sa méthode "items" et
      utilise les paires "(clé, valeur)" résultantes pour définir des
      paramètres supplémentaires dans l'en-tête *Content-Type*.

      Si *headers* est spécifié et est une liste de chaînes de la
      forme "headername: headervalue" ou une liste d'objets "header"
      (distingués des chaînes par l'attribut "name"), ajoute ces en-
      têtes à *msg*.

-[ Notes ]-

[1] Initialement ajouté dans 3.4 en tant que *paquet provisoire*.
