"email.contentmanager": Managing MIME Content
*********************************************

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

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

Ajouté 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__") ;

      * the type's "qualname" ("typ.__qualname__")

      * the type's "name" ("typ.__name__").

      If none of the above match, repeat all of the checks above for
      each of the types in the *MRO* ("typ.__mro__"). Finally, if no
      other key yields a handler, check for a handler for the key
      "None".  If there is no handler for "None", raise a "KeyError"
      for the fully qualified name of the 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

   This content manager provides only a minimum interface beyond that
   provided by "Message" itself:  it deals only with text, raw bytes,
   and "Message" objects.  Nevertheless, it provides significant
   advantages compared to the base API: "get_content" on a text part
   will return a string without the application needing to manually
   decode it, "set_content" provides a rich set of options for
   controlling the headers added to a part and controlling the content
   transfer encoding, and it enables the use of the various "add_"
   methods, thereby simplifying the creation of multipart messages.

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

      Return the payload of the part as either a string (for "text"
      parts), an "EmailMessage" object (for "message/rfc822" parts),
      or a "bytes" object (for all other non-multipart types).  Raise
      a "KeyError" if called on a "multipart".  If the part is a
      "text" part and *errors* is specified, use it as the error
      handler when decoding the payload to a string.  The default
      error handler is "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".

      * For "str" objects, if *cte* is not set use heuristics to
        determine the most compact encoding.  Prior to encoding,
        "str.splitlines()" is used to normalize all line boundaries,
        ensuring that each line of the payload is terminated by the
        current policy's "linesep" property (even if the original
        string did not end with one).

      * For "bytes" objects, *cte* is taken to be base64 if not set,
        and the aforementioned newline translation is not performed.

      * 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*.
