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
etset_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
estmultipart
, lève uneTypeError
; sinon recherche une fonction de gestion en se basant sur le type de obj (voir le paragraphe suivant), appelleclear_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 keyNone
. If there is no handler forNone
, raise aKeyError
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, voirset_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 objetsMessage
. 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éthodesadd_
, 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 objetEmailMessage
(pour les partiesmessage/rfc822
) ou d'un objetbytes
(pour tous les autres types à l'exception de multipart). Lève uneKeyError
si cette méthode est appelée sur unmultipart
. S'il s'agit d'une partietext
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 estreplace
.
- 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 lemaintype
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 uneTypeError
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 estpartial
, lève une erreur (les objetsbytes
doivent être utilisés pour construire les partiesmessage/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 estutf-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
etbinary
. Si l'entrée ne peut pas être encodée dans l'encodage spécifié (par exemple, en spécifiant un cte de7bit
pour une entrée qui contient des valeurs non-ASCII), lève uneValueError
.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 subtyperfc822`, lève une erreur pour un *cte* valant ``quoted-printable
oubase64
. Pour le subtypeexternal-body
, lève une erreur pour tout cte autre que7bit
. Pourmessage/rfc822
, la valeur par défaut de cte est8bit
. Pour toutes les autres valeurs de sous-type, la valeur par défaut de cte est7bit
.
Note
la valeur
binary
pour cte ne fonctionne pas encore correctement. L'objetEmailMessage
tel que modifié parset_content
est correct, maisBytesGenerator
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 sontattachment
etinline
.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'objetsheader
(distingués des chaînes par l'attributname
), ajoute ces en-têtes à msg.
Notes