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