# `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.