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