email.contentmanager: Hantering av MIME-innehåll

Källkod: Lib/email/contentmanager.py

Tillagd i version 3.6: [1]

class email.contentmanager.ContentManager

Basklass för innehållshanterare. Tillhandahåller standardregistermekanismer för att registrera omvandlare mellan MIME-innehåll och andra representationer, samt leveransmetoderna get_content och set_content.

get_content(msg, *args, **kw)

Leta upp en hanterarfunktion baserad på mimetype för msg (se nästa stycke), anropa den, skicka igenom alla argument och returnera resultatet av anropet. Förväntningen är att hanteraren kommer att extrahera nyttolasten från msg och returnera ett objekt som kodar information om de extraherade data.

För att hitta hanteraren, leta efter följande nycklar i registret och sluta med den första som hittas:

  • den sträng som representerar den fullständiga MIME-typen (maintype/subtype)

  • den sträng som representerar maintypen

  • den tomma strängen

Om ingen av dessa nycklar producerar en hanterare, skapa ett KeyError för den fullständiga MIME-typen.

set_content(msg, obj, *args, **kw)

Om maintypen är multipart, skapa en TypeError; annars leta upp en hanterarfunktion baserad på typen av obj (se nästa stycke), anropa clear_content() på msg, och anropa hanterarfunktionen, genom att skicka igenom alla argument. Förväntningen är att hanteraren ska omvandla och lagra obj till msg och eventuellt göra andra ändringar i msg, t.ex. lägga till olika MIME-rubriker för att koda information som behövs för att tolka de lagrade uppgifterna.

För att hitta hanteraren får du fram typen av obj (typ = type(obj)) och letar efter följande nycklar i registret, med början med den första som hittas:

  • själva typen (typ)

  • typens fullständigt kvalificerade namn (typ.__module__ + '.' + typ.__qualname__).

  • typens qualname (typ.__qualname__)

  • typens name (typ.__name__).

Om inget av ovanstående stämmer upprepar du alla kontroller ovan för var och en av typerna i MRO (typ.__mro__). Slutligen, om ingen annan nyckel ger en hanterare, kontrollera om det finns en hanterare för nyckeln None. Om det inte finns någon hanterare för None, skapa ett KeyError för det fullständigt kvalificerade namnet på typen.

Lägg också till en MIME-Version header om en sådan saknas (se även MIMEPart).

add_get_handler(key, handler)

Registrera funktionen handler som hanterare för key. För de möjliga värdena för key, se get_content().

add_set_handler(typekey, handler)

Registrera handler som den funktion som ska anropas när ett objekt av en typ som matchar typekey skickas till set_content(). För de möjliga värdena för typekey, se set_content().

Instanser för innehållshanterare

För närvarande tillhandahåller e-postpaketet endast en konkret innehållshanterare, raw_data_manager, men fler kan läggas till i framtiden. raw_data_manager är den content_manager som tillhandahålls av EmailPolicy och dess derivat.

email.contentmanager.raw_data_manager

Denna innehållshanterare tillhandahåller endast ett minimalt gränssnitt utöver det som tillhandahålls av Message själv: den hanterar endast text, råa byte-strängar och Message-objekt. Trots detta ger det betydande fördelar jämfört med bas-API:et: get_content på en textdel returnerar en unicode-sträng utan att programmet behöver avkoda den manuellt, set_content ger en rik uppsättning alternativ för att kontrollera de rubriker som läggs till en del och kontrollera innehållets överföringskodning, och det gör det möjligt att använda de olika add_-metoderna, vilket förenklar skapandet av flerpartsmeddelanden.

email.contentmanager.get_content(msg, errors='replace')

Returnera delens nyttolast som antingen en sträng (för text-delar), ett EmailMessage-objekt (för message/rfc822-delar) eller ett bytes-objekt (för alla andra icke-multipart-typer). Generera ett KeyError om det anropas på en multipart. Om delen är en text-del och errors är angivet, använd det som felhanterare när nyttolasten avkodas till unicode. Standardfelhanteraren är 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)

Lägg till rubriker och nyttolast i msg:

Lägg till ett Content-Type-huvud med värdet maintype/subtype.

  • För str, sätt MIME maintype till text, och sätt subtypen till subtype om den är specificerad, eller plain om den inte är det.

  • För bytes, använd den angivna maintype och subtype, eller skapa ett TypeError om de inte är angivna.

  • För EmailMessage-objekt, sätt huvudtypen till message, och sätt undertypen till subtype om den är specificerad eller rfc822 om den inte är det. Om subtype är partial, uppstår ett fel (bytes-objekt måste användas för att konstruera message/partial-delar).

Om charset anges (vilket endast är giltigt för str), kodas strängen till bytes med den angivna teckenuppsättningen. Standardvärdet är utf-8. Om den angivna charset är ett känt alias för ett MIME-standardcharsetnamn, används standardcharsetet istället.

Om cte anges, kodas nyttolasten med den angivna innehållsöverföringskodningen och rubriken Content-Transfer-Encoding anges till det värdet. Möjliga värden för cte är quoted-printable, base64, 7bit, 8bit och binary. Om indata inte kan kodas i den angivna kodningen (t.ex. om du anger en cte på 7bit för indata som innehåller icke-ASCII-värden), uppstår ett ValueError.

  • För str-objekt, om cte inte är angivet, används heuristik för att bestämma den mest kompakta kodningen. Före kodningen används str.splitlines() för att normalisera alla radgränser, vilket säkerställer att varje rad i nyttolasten avslutas med den aktuella policyns linesep-egenskap (även om den ursprungliga strängen inte slutade med en sådan).

  • För bytes-objekt antas cte vara base64 om den inte är inställd, och den tidigare nämnda översättningen av nya rader utförs inte.

  • För EmailMessage, per RFC 2046, skapa ett fel om en cte av quoted-printable eller base64 begärs för subtype rfc822, och för någon cte annan än 7bit för subtype external-body. För message/rfc822, använd 8bit om cte inte är specificerat. För alla andra värden av subtype, använd 7bit.

Anteckning

En cte av binary fungerar faktiskt inte korrekt ännu. Objektet EmailMessage som modifieras av set_content är korrekt, men BytesGenerator serialiserar det inte korrekt.

Om disposition anges används det som värde för rubriken Content-Disposition. Om disposition inte har angetts och filnamn har angetts, läggs rubriken med värdet attachment till. Om disposition inte anges och filnamn inte heller anges, läggs inte rubriken till. De enda giltiga värdena för disposition är attachment och inline.

Om filename anges används det som värde för parametern filename i rubriken Content-Disposition.

Om cid anges, lägg till ett Content-ID-huvud med cid som värde.

Om params anges, itererar du dess items-metod och använder de resulterande (nyckel, värde)-paren för att ange ytterligare parametrar för Content-Type-huvudet.

Om headers anges och är en lista med strängar av formen headername: headervalue eller en lista med header-objekt (som skiljer sig från strängar genom att ha ett name-attribut), lägg till headers i msg.

Fotnoter