# `email.parser`: Parsing email messages

Code source : Lib/email/parser.py

Les instances de messages peuvent être créées de deux façons : elles peuvent être créées de toutes pièces en créant un objet `EmailMessage`, en ajoutant des en-têtes en utilisant l'interface de dictionnaire, et en ajoutant un ou plusieurs corps de message en utilisant `set_content()` et les méthodes associées, ou elles peuvent être créées en analysant une représentation sérialisée de l'e-mail.

Le paquet `email` fournit un analyseur standard qui comprend la plupart des structures de documents de courrier électronique, y compris les documents MIME. Vous pouvez passer à l'analyseur un objet bytes, chaîne ou fichier, et l'analyseur vous renverra l'instance racine `EmailMessage` de la structure de l'objet. Pour les messages simples non MIME, la charge utile de cet objet racine sera probablement une chaîne contenant le texte du message. Pour les messages MIME, la méthode `is_multipart()` de l'objet racine renvoie `True`, et les sous-parties sont accessibles via les méthodes de manipulation de la charge utile, telles que `get_body()`, `iter_parts()` et `walk()`.

Il existe en fait deux interfaces d'analyseur disponibles, l'API `Parser` et l'API incrémentale `FeedParser`. L'API `Parser` est plus utile si vous avez le texte entier du message en mémoire ou si le message entier réside dans un fichier sur le système de fichiers. `FeedParser` est plus appropriée lorsque vous lisez le message à partir d'un flux qui peut bloquer en attente d'une entrée supplémentaire (comme la lecture d'un message électronique à partir d'un connecteur réseau). `FeedParser` peut consommer et analyser le message de manière incrémentielle et ne renvoie l'objet racine que lorsque vous fermez l'analyseur.

Note that the parser can be extended in limited ways, and of course you can implement your own parser completely from scratch. All of the logic that connects the `email` package's bundled parser and the `EmailMessage` class is embodied in the `Policy` class, so a custom parser can create message object trees any way it finds necessary by implementing custom versions of the appropriate `Policy` methods.

## API FeedParser

`BytesFeedParser`, importée du module `email.feedparser`, fournit une API propice à l'analyse incrémentielle des messages électroniques, adaptée à la lecture du texte d'un message électronique à partir d'une source qui peut bloquer (comme un connecteur). `BytesFeedParser` peut bien sûr être utilisée pour analyser un message électronique entièrement contenu dans un objet octets-compatible, une chaîne ou un fichier, mais l'API `BytesParser` peut être plus pratique dans ces utilisations. La sémantique et les résultats des deux API d'analyseurs sont identiques.

L'API de `BytesFeedParser` est simple ; vous créez une instance, l'alimentez d'une suite d'octets jusqu'à ce qu'il n'y en ait plus pour l'alimenter, puis fermez l'analyseur pour récupérer l'objet message racine. `BytesFeedParser` est extrêmement précise lors de l'analyse des messages conformes aux normes, et elle fait un très bon travail d'analyse des messages non conformes, fournissant des informations sur ce qu'elle considère comme non approprié dans un message. Elle remplit l'attribut `defects` d'un objet message avec une liste de tous les problèmes trouvés dans un message. Voir le module `email.errors` pour la liste des défauts qu'elle peut trouver.

Voici l’API de `BytesFeedParser` :

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

  Crée une instance `BytesFeedParser`. _factory est un appelable facultatif sans argument ; s'il n'est pas spécifié, elle utilise la `message_factory` de la policy. Elle appelle _factory chaque fois qu'un nouvel objet de message est nécessaire.

  Si policy est spécifiée, elle utilise les règles spécifiées pour mettre à jour la représentation du message. Si policy n'est pas définie, elle utilise la stratégie `compat32`, qui maintient la rétrocompatibilité avec la version Python 3.2 du paquet de messagerie et fournit `Message` comme usine par défaut. Toutes les autres stratégies fournissent `EmailMessage` comme _factory par défaut. Pour plus d'informations sur ce que policy régit, consultez la documentation `policy`.

  Remarque : Le paramètre nommé « policy » doit toujours être spécifié ; La valeur par défaut deviendra `email.policy.default` dans une future version de Python.

  Ajouté dans la version 3.2.

  Modifié dans la version 3.3: ajout du paramètre nommé policy.

  Modifié dans la version 3.6: _factory utilise par défaut la politique `message_factory`.

  feed(data)

    Alimente l'analyseur avec plus de données. data doit être un objet octets-compatible contenant une ou plusieurs lignes. Les lignes peuvent être partielles et l'analyseur assemble correctement ces lignes partielles. Les lignes peuvent avoir l'une des trois fins de ligne courantes : retour chariot, nouvelle ligne ou retour chariot et nouvelle ligne (elles peuvent même être mélangées).

  close()

    Termine l'analyse de toutes les données précédemment alimentées et renvoie l'objet message racine. Ce qui se passe si `feed()` est appelée après l'appel de cette méthode n'est pas défini.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

  Fonctionne comme `BytesFeedParser` sauf que l'entrée de la méthode `feed()` doit être une chaîne. Ceci est d'une utilité limitée, car la seule façon pour qu'un tel message soit valide est qu'il ne contienne que du texte ASCII ou, si `utf8` vaut `True`, aucun binaire en pièce jointe.

  Modifié dans la version 3.3: ajout du paramètre nommé policy.

## API de Parser

La classe `BytesParser`, importée du module `email.parser`, fournit une API qui peut être utilisée pour analyser un message lorsque le contenu complet du message est disponible dans un objet octets-compatible ou un fichier. Le module `email.parser` fournit également `Parser` pour l'analyse des chaînes et des analyseurs d'en-tête uniquement, `BytesHeaderParser` et `HeaderParser`, qui peuvent être utilisés si vous ne vous intéressez qu'aux en-têtes du message. `BytesHeaderParser` et `HeaderParser` peuvent être beaucoup plus rapides dans ces situations, car ils n'essaient pas d'analyser le corps du message.

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

  Crée une instance `BytesParser`. Les arguments _class et policy ont la même signification et la même sémantique que les arguments _factory et policy de `BytesFeedParser`.

  Remarque : Le paramètre nommé « policy » doit toujours être spécifié ; La valeur par défaut deviendra `email.policy.default` dans une future version de Python.

  Modifié dans la version 3.3: suppression de l'argument strict qui était obsolète dans 2.4. Ajout du paramètre nommé policy.

  Modifié dans la version 3.6: _class utilise par défaut la politique `message_factory`.

  parse(fp, headersonly=False)

    Lit toutes les données de l'objet de type fichier binaire fp, analyse les octets résultants et renvoie l'objet message. fp doit prendre en charge les méthodes `readline()` et `read()`.

    Les octets contenus dans fp doivent être formatés comme un bloc d'en-têtes de style conforme à la RFC 5322 (ou, si `utf8` est `True`, à la RFC 6532), éventuellement précédés d'un en-tête d'enveloppe. Le bloc d'en-têtes se termine soit par la fin des données, soit par une ligne blanche. Après le bloc d'en-têtes se trouve le corps du message (qui peut contenir des sous-parties codées MIME, y compris des sous-parties avec un Content-Transfer-Encoding de `8bit`).

    headersonly est un indicateur facultatif spécifiant s'il faut arrêter l'analyse après avoir lu les en-têtes ou non. La valeur par défaut est `False`, ce qui signifie qu'il analyse tout le contenu du fichier.

  parsebytes(bytes, headersonly=False)

    Semblable à la méthode `parse()`, sauf qu'elle prend un objet octets-compatible au lieu d'un objet de type fichier. Appeler cette méthode sur un objet octets-compatible équivaut à envelopper bytes dans une instance `BytesIO` d'abord et à appeler `parse()`.

    L'utilisation de l'option headersonly est identique à son utilisation dans la méthode `parse()`.

  Ajouté dans la version 3.2.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

  Exactement comme `BytesParser`, sauf que headersonly par défaut est `True`.

  Ajouté dans la version 3.3.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

  Cette classe est semblable à `BytesParser`, mais elle accepte une chaîne en entrée.

  Modifié dans la version 3.3: suppression de l'argument strict. Ajout de l'argument nommé policy.

  Modifié dans la version 3.6: _class utilise par défaut la politique `message_factory`.

  parse(fp, headersonly=False)

    Lit toutes les données de l'objet de type fichier en mode texte fp, analyse le texte résultant et renvoie l'objet message racine. fp doit prendre en charge les méthodes `readline()` et `read()` sur les objets de type fichier.

    Outre l'exigence du mode texte, cette méthode fonctionne comme `BytesParser.parse()`.

  parsestr(text, headersonly=False)

    Similaire à la méthode `parse()`, sauf qu'elle prend un objet chaîne au lieu d'un objet de type fichier. Appeler cette méthode sur une chaîne équivaut à envelopper text dans une instance `StringIO` d'abord et à appeler `parse()`.

    L'utilisation de l'option headersonly est identique à son utilisation dans la méthode `parse()`.

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

  Exactement comme `Parser`, sauf que headersonly par défaut est `True`.

Étant donné que la création d'une structure d'objet message à partir d'une chaîne ou d'un objet fichier est une tâche très courante, quatre fonctions sont fournies par commodité. Elles sont disponibles dans l'espace de noms de paquet de niveau supérieur `email`.

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

  Renvoie une structure d'objet message à partir d'un objet octets-compatible. C'est équivalent à `BytesParser().parsebytes(s)`. _class et policy (facultatifs) sont interprétés comme pour le constructeur de classe `BytesParser`.

  Ajouté dans la version 3.2.

  Modifié dans la version 3.3: suppression de l'argument strict. Ajout de l'argument nommé policy.

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

  Renvoie une arborescence d'objets message à partir d'un objet fichier binaire ouvert. C'est équivalent à `BytesParser().parse(fp)`. _class et policy sont interprétés comme pour le constructeur de classe `BytesParser`.

  Ajouté dans la version 3.2.

  Modifié dans la version 3.3: suppression de l'argument strict. Ajout de l'argument nommé policy.

email.message_from_string(s, _class=None, *, policy=policy.compat32)

  Renvoie une structure d'objet message à partir d'une chaîne. C'est équivalent à `Parser().parsestr(s)`. _class et policy sont interprétés comme avec le constructeur de classe `Parser`.

  Modifié dans la version 3.3: suppression de l'argument strict. Ajout de l'argument nommé policy.

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

  Renvoie une arborescence de structures d'objets messages à partir d'un objet fichier ouvert. C'est équivalent à `Parser().parse(fp)`. _class et policy sont interprétés comme avec le constructeur de classe `Parser`.

  Modifié dans la version 3.3: suppression de l'argument strict. Ajout de l'argument nommé policy.

  Modifié dans la version 3.6: _class utilise par défaut la politique `message_factory`.

Voici un exemple d'utilisation `message_from_bytes()` dans une invite Python interactive :

    >>> import email
    >>> msg = email.message_from_bytes(myBytes)

## Notes complémentaires

Voici des remarques sur la sémantique d'analyse :

- La plupart des messages de type non-multipart sont analysés comme un seul objet de message avec une charge utile de type chaîne. Ces objets renvoient `False` pour `is_multipart()` et `iter_parts()` donne une liste vide.

- Tous les messages de type multipart sont analysés comme un objet de message conteneur avec une liste d'objets de sous-messages pour leur charge utile. Le message du conteneur externe renvoie `True` pour `is_multipart()` et `iter_parts()` donne une liste de sous-parties.

- La plupart des messages avec un type de contenu de message/* (tels que message/delivery-status et message/rfc822) sont également analysés en tant qu'objet conteneur contenant une charge utile de type « liste de longueur 1 ». Leur méthode `is_multipart()` renvoie `True`. L'élément unique généré par `iter_parts()` est un objet sous-message.

- Certains messages non conformes aux normes peuvent ne pas être cohérents en interne quant à multipart. De tels messages peuvent avoir un en-tête Content-Type de type multipart, mais leur méthode `is_multipart()` peut renvoyer `False`. Si de tels messages ont été analysés avec la `FeedParser`, ils auront une instance de la classe `MultipartInvariantViolationDefect` dans leur liste d'attributs defects. Voir `email.errors` pour plus de détails.