Pkg.EML — API for parsing EML email messages

Overview

The Pkg.EML module contains the API for parsing RFC 2822 email messages stored in the EML file format.

The message is exposed through two classes: EMLObject represents the whole file and drives parsing, and EMLPart represents a single part (root message or sub-part) with accessors for its headers, content type, and payload.

Parsing an EML File

The following code example shows how to parse an EML file and inspect its main headers:

from Pro.Core import *
from Pkg.EML import *

def parseEML(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = EMLObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    root = obj.GetRootPart()
    for key in ("From", "To", "Subject", "Date"):
        print("{}: {}".format(key, EMLPart.DecodeHeader(root.GetHeader(key))))

Iterating Attachments

Each attachment is exposed together with its offset and size in the source stream. This makes it possible to extract attachment data directly from the container:

from Pro.Core import *
from Pkg.EML import *

def dumpAttachments(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = EMLObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    stream = obj.GetStream()
    for part, offset, size, cte in obj.IterAttachments():
        name = part.GetAttachmentName()
        data = stream.read(offset, size)
        flt = obj.GetAttachmentFilterXml(cte)
        if flt:
            nc = NTContainer()
            nc.setData(data)
            data = applyFilters(nc, flt, False).read(0, size)
        print("attachment:", name, "size:", len(data))

Generating a Preview

Text-producing methods take an NTTextStream out parameter so that callers can direct the output without a redundant string allocation:

from Pro.Core import *
from Pkg.EML import *

def emlPreview(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = EMLObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    out = proTextStream()
    obj.FormatPreview(out)
    print(out.buffer)

Module API

Pkg.EML module API.

Classes:

EMLObject()

This class represents an EML email message.

EMLPart()

This class represents a single part of an EML message: either the root message or a sub-part in a multipart message.
class EMLObject

Bases: Pro.Core.CFFObject

This class represents an EML email message.

Methods:

DumpDefects(out)

Writes a human-readable list of parser defects to the given text stream.

DumpMetadata(out)

Writes a summary of the root part’s content type, charset, parameters, and flags to the given text stream.

DumpSource(out)

Writes the raw source bytes of the message, decoded for display, to the given text stream.

FormatPreview(out)

Writes a human-readable preview of the message (main headers followed by the plain-text or HTML body) to the given text stream.

GetAttachmentFilterXml(cte)

Returns the Pro filter XML needed to decode an attachment encoded with the given Content-Transfer-Encoding.

GetRootPart()

Returns the root message part if CFFObject.Initialize() succeeded; otherwise returns None.

HasDefects()

Returns True if the parser recorded one or more defects; otherwise returns False.

IterAttachments(*[, wo])

Iterates over the attachments in the message and their location in the source stream.

IterParts()

Iterates over every part of the message (root first, then nested parts in document order).
DumpDefects(out: Pro.Core.NTTextStream) → None

Writes a human-readable list of parser defects to the given text stream.

Parameters

out (NTTextStream) – The output text stream.

DumpMetadata(out: Pro.Core.NTTextStream) → None

Writes a summary of the root part’s content type, charset, parameters, and flags to the given text stream.

Parameters

out (NTTextStream) – The output text stream.

DumpSource(out: Pro.Core.NTTextStream) → None

Writes the raw source bytes of the message, decoded for display, to the given text stream.

Parameters

out (NTTextStream) – The output text stream.

FormatPreview(out: Pro.Core.NTTextStream) → None

Writes a human-readable preview of the message (main headers followed by the plain-text or HTML body) to the given text stream.

Parameters

out (NTTextStream) – The output text stream.

GetAttachmentFilterXml(cte: str) → Optional[str]

Returns the Pro filter XML needed to decode an attachment encoded with the given Content-Transfer-Encoding.

Supported encodings are base64 and quoted-printable. For any other value the method returns None, meaning no filter is needed.

Parameters

cte (str) – The Content-Transfer-Encoding value.

Returns

Returns the filter XML string if a decoder is needed; otherwise returns None.

Return type

Optional[str]

GetRootPart() → Optional[Pkg.EML.EMLPart]
Returns

Returns the root message part if CFFObject.Initialize() succeeded; otherwise returns None.

Return type

Optional[EMLPart]

See also IterParts().

HasDefects() → bool
Returns

Returns True if the parser recorded one or more defects; otherwise returns False.

Return type

bool

See also DumpDefects().

IterAttachments(*, wo: Optional[Pro.Core.NTIWait] = None) → Iterator[Tuple[Pkg.EML.EMLPart, int, int, str]]

Iterates over the attachments in the message and their location in the source stream.

Parameters

wo (Optional[NTIWait]) – Optional wait object for long-running iteration.

Returns

Yields (part, offset, size, content_transfer_encoding) tuples.

Return type

Iterator[Tuple[EMLPart, int, int, str]]

See also GetAttachmentFilterXml().

IterParts() → Iterator[Pkg.EML.EMLPart]

Iterates over every part of the message (root first, then nested parts in document order).

Returns

Yields each EMLPart.

Return type

Iterator[EMLPart]

class EMLPart

This class represents a single part of an EML message: either the root message or a sub-part in a multipart message.

Methods:

DecodeHeader(s)

Decodes a raw header value: MIME encoded-words are resolved, and RFC 2231 parameters are collapsed to a printable form.

DumpContent(out)

Writes the reconstructed textual representation of this part (headers and body) to the given text stream.

GetAttachmentName([strict])

Returns a decoded attachment name for the part.

GetBoundary()

Returns the multipart boundary for the part, or None if the part is not multipart.

GetCharset()

Returns the declared charset (from the part’s charset or the charset parameter), or None.

GetContentParams()

Returns the parameters of the Content-Type header (charset, boundary, etc.), excluding the type itself.

GetContentTransferEncoding()

Returns the lowercased value of the Content-Transfer-Encoding header, or an empty string.

GetContentType()

Returns the part’s content type (e.g. text/plain).

GetDecodedPayload()

Returns the decoded payload of a non-multipart part (Content-Transfer-Encoding is resolved, and charset decoding is applied where possible).

GetEpilogue()

Returns the multipart epilogue (text after the closing boundary), or an empty string.

GetHeader(name[, default])

Retrieves the raw value of a named header.

GetHeaders()

Returns the list of all headers in their declared order, preserving duplicates.

GetPreamble()

Returns the multipart preamble (text before the first boundary), or an empty string.

GetSubParts()

Returns the immediate sub-parts of this part, or an empty list if it is not multipart.

IsAttachment()

Returns True if the part is an attachment (explicit disposition, application/* content, embedded message, or declared filename); otherwise returns False.

IsMultipart()

Returns True if the part is a multipart container; otherwise returns False.
static DecodeHeader(s: str) → str

Decodes a raw header value: MIME encoded-words are resolved, and RFC 2231 parameters are collapsed to a printable form.

Parameters

s (str) – The raw header value.

Returns

Returns the decoded header value.

Return type

str

DumpContent(out: Pro.Core.NTTextStream) → None

Writes the reconstructed textual representation of this part (headers and body) to the given text stream.

Parameters

out (NTTextStream) – The output text stream.

GetAttachmentName(strict: bool = False) → str

Returns a decoded attachment name for the part.

When strict is False, a fallback name is synthesized from the content type if no explicit filename is declared.

Parameters

strict (bool) – If True, only return a name when the part declares one explicitly.

Returns

Returns the decoded attachment name, or an empty string.

Return type

str

GetBoundary() → Optional[str]
Returns

Returns the multipart boundary for the part, or None if the part is not multipart.

Return type

Optional[str]

GetCharset() → Optional[str]
Returns

Returns the declared charset (from the part’s charset or the charset parameter), or None.

Return type

Optional[str]

GetContentParams() → List[Tuple[str, str]]

Returns the parameters of the Content-Type header (charset, boundary, etc.), excluding the type itself.

Returns

Returns a list of (name, value) tuples.

Return type

List[Tuple[str, str]]

GetContentTransferEncoding() → str
Returns

Returns the lowercased value of the Content-Transfer-Encoding header, or an empty string.

Return type

str

GetContentType() → str
Returns

Returns the part’s content type (e.g. text/plain).

Return type

str

GetDecodedPayload() → Union[bytes, str]

Returns the decoded payload of a non-multipart part (Content-Transfer-Encoding is resolved, and charset decoding is applied where possible).

Returns

Returns str when a charset is known, otherwise bytes.

Return type

Union[bytes, str]

GetEpilogue() → str
Returns

Returns the multipart epilogue (text after the closing boundary), or an empty string.

Return type

str

GetHeader(name: str, default: str = '') → str

Retrieves the raw value of a named header.

Parameters

  • name (str) – The header name (case-insensitive).

  • default (str) – The value to return when the header is absent.

Returns

Returns the raw header value, or the default.

Return type

str

See also GetHeaders(), decodeHeader().

GetHeaders() → List[Tuple[str, str]]

Returns the list of all headers in their declared order, preserving duplicates.

Returns

Returns a list of (name, raw_value) tuples.

Return type

List[Tuple[str, str]]

See also decodeHeader().

GetPreamble() → str
Returns

Returns the multipart preamble (text before the first boundary), or an empty string.

Return type

str

GetSubParts() → List[Pkg.EML.EMLPart]
Returns

Returns the immediate sub-parts of this part, or an empty list if it is not multipart.

Return type

List[EMLPart]

IsAttachment() → bool
Returns

Returns True if the part is an attachment (explicit disposition, application/* content, embedded message, or declared filename); otherwise returns False.

Return type

bool

IsMultipart() → bool
Returns

Returns True if the part is a multipart container; otherwise returns False.

Return type

bool