extract-msg 0.48.2__py3-none-any.whl

extract_msg/__init__.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+# -*- coding: latin-1 -*-
+# Date Format: YYYY-MM-DD
+
+"""
+extract_msg:
+    Extracts emails and attachments saved in Microsoft Outlook's .msg files.
+
+https://github.com/TeamMsgExtractor/msg-extractor
+"""
+
+# --- LICENSE.txt --------------------------------------------------------------
+#
+#    Copyright 2013-2023 Matthew Walker and Destiny Peterson
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+__author__ = 'Destiny Peterson & Matthew Walker'
+__date__ = '2024-03-09'
+__version__ = '0.48.2'
+
+__all__ = [
+    # Modules:
+    'attachments',
+    'constants',
+    'enums',
+    'exceptions',
+    'msg_classes',
+    'null_date',
+    'properties',
+    'structures',
+
+    # Classes:
+    'Attachment',
+    'AttachmentBase',
+    'Message',
+    'MSGFile',
+    'Named',
+    'NamedProperties',
+    'OleWriter',
+    'PropertiesStore',
+    'Recipient',
+    'SignedAttachment',
+
+    # Functions:
+    'openMsg',
+    'openMsgBulk',
+]
+
+
+# Ensure these are imported before anything else.
+from . import constants, enums, exceptions
+
+from . import attachments, msg_classes, null_date, properties, structures
+from .attachments import Attachment, AttachmentBase, SignedAttachment
+from .msg_classes import Message, MSGFile
+from .ole_writer import OleWriter
+from .open_msg import openMsg, openMsgBulk
+from .properties import Named, NamedProperties, PropertiesStore
+from .recipient import Recipient

extract_msg/__main__.py

@@ -0,0 +1,115 @@
+__all__ = [
+    'main',
+]
+
+
+import os
+import sys
+import traceback
+import zipfile
+
+from extract_msg import __doc__, openMsg, utils
+from extract_msg.enums import ErrorBehavior
+from typing import List
+
+
+def main(argv : List[str]) -> None:
+    # Setup logging to stdout, indicate running from cli
+    CLI_LOGGING = 'extract_msg_cli'
+    args = utils.getCommandArgs(argv[1:])
+
+    # Determine where to save the files to.
+    currentDir = os.getcwd() # Store this in case the path changes.
+    if not args.zip:
+        if args.outPath:
+            if not os.path.exists(args.outPath):
+                os.makedirs(args.outPath)
+            out = args.outPath
+        else:
+            out = currentDir
+    else:
+        out = args.outPath if args.outPath else ''
+
+    if not args.dumpStdout:
+        utils.setupLogging(args.configPath, args.logLevel, args.log, args.fileLogging)
+
+    if args.zip:
+        createdZip = True
+        _zip = zipfile.ZipFile(args.zip, 'a', zipfile.ZIP_DEFLATED)
+    else:
+        createdZip = False
+        _zip = None
+
+    # Quickly make a dictionary for the keyword arguments.
+    kwargs = {
+        'allowFallback': args.allowFallback,
+        'attachmentsOnly': args.attachmentsOnly,
+        'charset': args.charset,
+        'contentId': args.cid,
+        'customFilename': args.outName,
+        'customPath': out,
+        'extractEmbedded': args.extractEmbedded,
+        'html': args.html,
+        'json': args.json,
+        'overwriteExisting': args.overwriteExisting,
+        'pdf': args.pdf,
+        'preparedHtml': args.preparedHtml,
+        'rtf': args.rtf,
+        'saveHeader': args.saveHeader,
+        'skipBodyNotFound': args.skipBodyNotFound,
+        'skipEmbedded': args.skipEmbedded,
+        'skipHidden': args.skipHidden,
+        'skipNotImplemented': args.skipNotImplemented,
+        'useMsgFilename': args.useFilename,
+        'wkOptions': args.wkOptions,
+        'wkPath': args.wkPath,
+        'zip': _zip,
+    }
+
+    openKwargs = {
+        'errorBehavior': ErrorBehavior.RTFDE if args.ignoreRtfDeErrors else ErrorBehavior.THROW,
+    }
+
+    # If we are skipping the NotImplementedError attachments, we need to
+    # suppress the error.
+    if args.skipNotImplemented:
+        openKwargs['errorBehavior'] |= ErrorBehavior.ATTACH_NOT_IMPLEMENTED
+
+    def strSanitize(inp):
+        """
+        Small function to santize parts of a string when failing to print
+        them.
+        """
+        return ''.join((x if x.isascii() else
+                f'\\x{ord(x):02X}' if ord(x) <= 0xFF else
+                f'\\u{ord(x):04X}' if ord(x) <= 0xFFFF else
+                f'\\U{ord(x):08X}') for x in repr(inp))
+
+    for x in args.msgs:
+        if args.progress:
+            # This may throw an error sometimes and not othertimes.
+            # Unclear why, so let's just silence it.
+            try:
+                print(f'Saving file "{x}"...')
+            except UnicodeEncodeError:
+                print(f'Saving file "{strSanitize(x)}" (failed to print without repr)...')
+        try:
+            with openMsg(x, **openKwargs) as msg:
+                if args.dumpStdout:
+                    print(msg.body)
+                elif args.noFolders:
+                    msg.saveAttachments(**kwargs)
+                else:
+                    msg.save(**kwargs)
+        except Exception as e:
+            try:
+                print(f'Error with file "{x}": {traceback.format_exc()}')
+            except UnicodeEncodeError:
+                print(f'Error with file "{strSanitize(x)}": {traceback.format_exc()}')
+
+    # Close the zip file if we opened it.
+    if createdZip:
+        _zip.close()
+
+if __name__ == '__main__':
+    main(sys.argv)

extract_msg/_rtf/__init__.py

@@ -0,0 +1,21 @@
+"""
+Module that provides access to functions to help manage RTF data.
+"""
+
+__all__ = [
+    # Classes:
+    'Token',
+    'TokenType',
+
+    # Functions:
+    'createDocument',
+    'injectStartRTF',
+    'injectStartRTFTokenized',
+    'tokenizeRTF',
+]
+
+
+from .create_doc import createDocument
+from .inject_rtf import injectStartRTF, injectStartRTFTokenized
+from .token import Token, TokenType
+from .tokenize_rtf import tokenizeRTF

extract_msg/_rtf/create_doc.py

@@ -0,0 +1,29 @@
+__all__ = [
+    'createDocument',
+]
+
+
+from typing import Iterable
+
+from .token import Token, TokenType
+
+
+
+def createDocument(tokens: Iterable[Token]) -> bytes:
+    """
+    Combines the tokenized data into bytes and returns the document.
+    """
+    document = b''
+
+    # Recombining follows a few very basic rules that are based solely on the
+    # token type. Since every token has the raw bytes, this is pretty easy. In
+    # fact, control words are the only place where we put a space, as a space
+    # anywhere else would be literal, and omitting a space could cause issues on
+    # some control words.
+    for token in tokens:
+        if token.type in (TokenType.CONTROL, TokenType.DESTINATION, TokenType.IGNORABLE_DESTINATION):
+            document += token.raw + b' '
+        else:
+            document += token.raw
+
+    return document

extract_msg/_rtf/inject_rtf.py

@@ -0,0 +1,174 @@
+__all__ = [
+    'injectStartRTF',
+    'injectStartRTFTokenized',
+]
+
+
+from .token import Token, TokenType
+from .tokenize_rtf import tokenizeRTF
+
+from typing import List, Iterable, TypeVar, Union
+
+
+_T = TypeVar('_T')
+
+# A tuple of destinations used in the header. All ignorable ones are skipped
+# anyways, so we don't need to list those here.
+_HEADER_DESTINATIONS = (
+    b'fonttbl',
+    b'colortbl',
+    b'stylesheet',
+)
+
+# A tuple of control words that are part of the header and that we simply skip.
+_HEADER_SKIPPABLE = (
+    # Tag used to specify something.
+    b'fbidis',
+    # Character set tags.
+    b'ansi',
+    b'mac',
+    b'pc',
+    b'pca',
+    b'ansicpg',
+    # From.
+    b'fromtext',
+    b'fromhtml',
+    # Def font.
+    b'deff',
+    b'adeff',
+    b'stshfdbch',
+    b'stshfloch',
+    b'stshfhich',
+    b'stshfbi',
+    # Def lang.
+    b'deflang',
+    b'deflangfe',
+    b'adeflang',
+)
+
+
+def _listInsertMult(dest: List[_T], source: Iterable[_T], index: int = -1):
+    """
+    Inserts into :param dest: all the items in :param source: at the index
+    specified.
+
+    :param dest: Any mutable sequence with methods ``insert``, ``__len__``, and
+        ``extend``.
+
+    If :param index: is not specified, the default position is the end of the
+    list. This is also where things will be inserted if index is greater than or
+    equal to the size of the list.
+    """
+    if index == -1 or index >= len(dest):
+        dest.extend(source)
+    else:
+        for offset, item in enumerate(source):
+            dest.insert(index + offset, item)
+
+
+def injectStartRTF(document: bytes, injectTokens: Union[bytes, List[Token]]) -> List[Token]:
+    """
+    Injects the specified tokens into the document, returning a new copy of the
+    document as a list of Tokens.
+
+    Injects the data just before the first rendered character.
+
+    :param document: The bytes representing the RTF document.
+    :param injectTokens: The tokens to inject into the document. Can either be
+        a list of ``Token``\\s or ``bytes`` to be tokenized.
+
+    :raises TypeError: The data is not recognized as RTF.
+    :raises ValueError: An issue with basic parsing occured.
+    """
+    return injectStartRTFTokenized(tokenizeRTF(document), injectTokens)
+
+
+def injectStartRTFTokenized(document: List[Token], injectTokens: Union[bytes, Iterable[Token]]) -> List[Token]:
+    """
+    Like :function injectStartRTF:, injects the specified tokens into the
+    document, returning a reference to the document, except that it accepts a
+    document in the form of a list of tokens.
+
+    Injects the data just before the first rendered character.
+
+    :param document: The list of tokens representing the RTF document. Will only
+        be modified if the function is successful.
+    :param injectTokens: The tokens to inject into the document. Can either be
+        a list of ``Token``\\s or ``bytes`` to be tokenized.
+
+    :raises TypeError: The data is not recognized as RTF.
+    :raises ValueError: An issue with basic parsing occured.
+    """
+    # Get to a list of tokens to inject instead of
+    if isinstance(injectTokens, bytes):
+        injectTokens = tokenizeRTF(injectTokens, False)
+
+    # Find the location to insert into. This is annoyingly complicated, and we
+    # do this by looking for the parts of the header (if they exist) as we go
+    # token by token. The moment we confirm we are no longer in the header (and
+    # we are not in a custom destination that we can simply ignore), we use the
+    # last recorded spot as the insert point. We don't move that recorded spot
+    # until we know that what we checked was part of the header.
+
+    # First confirm the first two tokens are what we expect.
+    if len(document) < 3:
+        raise ValueError('RTF documents cannot be less than 3 tokens.')
+    if document[0].type is not TokenType.GROUP_START or document[1].raw != b'\\rtf1':
+        raise TypeError('RTF document *must* start with "{\\rtf1".')
+
+    # Confirm that all start groups have an end group somewhere.
+    if sum(x.type == TokenType.GROUP_START for x in document) != sum(x.type == TokenType.GROUP_END for x in document):
+        raise ValueError('Number of group opens did not match number of group closes.')
+
+    # If the length is exactly 3, insert right before the end and return.
+    if len(document) == 3:
+        _listInsertMult(document, injectTokens, 2)
+        return document
+
+    # We have verified the minimal amount. Now, iterate through the rest to find
+    # the injection point.
+    currentInsertPos = 2
+    # Current number of open groups.
+    groupCount = 1
+    # Set to True when looking for if the group is a destination.
+    checkingDest = False
+
+    for item in document[2:]:
+        if groupCount == 1:
+            if item.type is TokenType.GROUP_END:
+                break
+            elif item.type is TokenType.GROUP_START:
+                groupCount += 1
+                checkingDest = True
+            elif item.type is TokenType.CONTROL and item.name in _HEADER_SKIPPABLE:
+                # If the control is one we know about in the header, skip it.
+                currentInsertPos += 1
+            else:
+                # Anything else means we are out of the header.
+                break
+        elif checkingDest:
+            if item.type is TokenType.DESTINATION:
+                # If it is *not* a header destination, just break, otherwise add
+                # 2 to the insert location and skip the destination.
+                if item.name in _HEADER_DESTINATIONS:
+                    currentInsertPos += 2
+                else:
+                    break
+            elif item.type is TokenType.IGNORABLE_DESTINATION:
+                # Add 2 to insert location and skip.
+                currentInsertPos += 2
+            else:
+                # If it is not an ignorible destination, we are now out of the
+                # header, so break.
+                break
+            checkingDest = False
+        else:
+            # Skip the current token, keeping track of groups.
+            if item.type is TokenType.GROUP_START:
+                groupCount += 1
+            if item.type is TokenType.GROUP_END:
+                groupCount -= 1
+            currentInsertPos += 1
+
+    _listInsertMult(document, injectTokens, currentInsertPos)
+    return document

extract_msg/_rtf/token.py

@@ -0,0 +1,35 @@
+__all__ = [
+    'Token',
+    'TokenType',
+]
+
+
+import enum
+
+from typing import NamedTuple, Optional
+
+
+class TokenType(enum.Enum):
+    GROUP_START = 0
+    GROUP_END = 1
+    CONTROL = 2
+    SYMBOL = 3
+    TEXT = 4
+    DESTINATION = 5
+    IGNORABLE_DESTINATION = 6
+    # This one is special, used for handling the binary data.
+    BINARY = 7
+
+
+
+class Token(NamedTuple):
+    # The raw bytes for the token, used to recreate the document.
+    raw: bytes
+    # The type of the token.
+    type: TokenType
+    ## The following are optional as they only apply for certain types of tokens.
+    # The name of the token, if it is a control or destination.
+    name: Optional[bytes] = None
+    # The parameter of the token, if it has one. If the token is a `\'hh` token,
+    # this will be the decimal equivelent of the hex value.
+    parameter: Optional[int] = None

extract_msg/_rtf/tokenize_rtf.py

@@ -0,0 +1,253 @@
+__all__ = [
+    'tokenizeRTF',
+]
+
+
+import io
+
+from typing import List, Optional, Tuple
+
+from .token import Token, TokenType
+
+
+_KNOWN_DESTINATIONS = (
+    b'aftncn',
+    b'aftnsep',
+    b'aftnsepc',
+    b'annotation',
+    b'author',
+    b'buptim',
+    b'category',
+    b'colortbl',
+    b'comment',
+    b'company',
+    b'creatim',
+    b'doccomm',
+    b'dptxbxtext',
+    b'factoidname',
+    b'fonttbl',
+    b'footer',
+    b'footerf',
+    b'footerl',
+    b'footerr',
+    b'ftncn',
+    b'ftnsep',
+    b'ftnsepc',
+    b'header',
+    b'headerf',
+    b'headerl',
+    b'headerr',
+    b'hlinkbase',
+    b'keywords',
+    b'manager',
+    b'operator',
+    b'pict',
+    b'printim',
+    b'private',
+    b'revtim',
+    b'stylesheet',
+    b'subject',
+    b'title',
+)
+
+
+def _finishTag(startText: bytes, reader: io.BytesIO) -> Tuple[bytes, Optional[bytes], Optional[int], bytes]:
+    """
+    Finishes reading a tag, returning the needed parameters to make it a
+    token.
+
+    The return is a 4 tuple of the raw token bytes, the name field, the
+    parameter field (as an int), and the next character after the tag.
+    """
+    # Very simple rules here. Anything other than a letter and we change
+    # state. If the next character is a hypen, check if the character after
+    # is a digit, otherwise return. If it is a digit or that previously
+    # mentioned next character was a digit, read digits until anything else
+    # is detected, then return.
+    name = startText[-1:]
+    param = b''
+
+    while (nextChar := reader.read(1)) != b'' and nextChar.isalpha():
+        # Read until not alpha.
+        startText += nextChar
+        name += nextChar
+
+    # Check what the next character is to decide what to do with it.
+    if nextChar == b'-':
+        # We do this as a separate check.
+        nextNext = reader.read(1)
+        if nextNext == b'':
+            raise ValueError('Unexpected end of data.')
+        elif nextNext.isdigit():
+            startText += nextChar
+            nextChar = nextNext
+
+    if nextChar.isdigit():
+        startText += nextChar
+        param += nextChar
+        while (nextChar := reader.read(1)) != b'' and nextChar.isdigit():
+            startText += nextChar
+            param += nextChar
+
+        param = int(param)
+    else:
+        param = None
+
+    # Finally, check if the next char is a space, and if it is, read one
+    # more char to replace it.
+    if nextChar == b' ':
+        nextChar = reader.read(1)
+
+    return startText, name, param, nextChar
+
+
+def _readControl(startChar: bytes, reader: io.BytesIO) -> Tuple[Tuple[Token, ...], bytes]:
+    """
+    Attempts to read the next data as a control, returning as many tokens
+    as necessary.
+    """
+    # First, read the next character, as it decides how to handle
+    # everything.
+    nextChar = reader.read(1)
+    if nextChar == b'':
+        raise ValueError('Unexpected end of data.')
+    elif nextChar.isalpha():
+        # If is an alphabetical character, so start the handling of a tag.
+        text, name, param, nextChar = _finishTag(startChar + nextChar, reader)
+        # Important, check if the name is "bin". If it is, handle that
+        # specially before returning.
+        if name == b'bin':
+            if nextChar == b'':
+                raise ValueError('Unexpected end of data.')
+            binText = nextChar + reader.read(param - 1)
+            if len(binText) != param:
+                raise ValueError('Unexpected end of data.')
+            return (Token(text, TokenType.CONTROL, name, param), Token(binText, TokenType.BINARY)), nextChar
+        elif name in _KNOWN_DESTINATIONS:
+            return (Token(text, TokenType.DESTINATION, name, param),), nextChar
+
+        return (Token(text, TokenType.CONTROL, name, param),), nextChar
+    else:
+        # Most control symbols would return immediately, but there are two
+        # exceptions.
+        startChar += nextChar
+        if nextChar == b'*':
+            # This is going to be a custom destination. First, validation.
+            if len(nextChar := reader.read(1)) != 1:
+                raise ValueError('Unexpected end of data.')
+            elif nextChar != b'\\':
+                raise ValueError(f'Bad custom destination (expected a backslash, got {nextChar}).')
+
+            startChar += nextChar
+
+            # Check the the next char is alpha.
+            if not (nextChar := reader.read(1)).isalpha():
+                raise ValueError(f'Expected alpha character for destination, got {nextChar}.')
+
+            startChar += nextChar
+
+            # Call the function to read until a clear end of tag.
+            text, name, param, nextChar = _finishTag(startChar, reader)
+            return (Token(text, TokenType.IGNORABLE_DESTINATION, name, param),), nextChar
+        elif nextChar == b'\'':
+            # This is a hex character, so immediately read 2 more bytes.
+            hexChars = reader.read(2)
+            if len(hexChars) != 2:
+                raise ValueError('Unexpected end of data.')
+            try:
+                param = int(hexChars, 16)
+            except ValueError as e:
+                context = e.__cause__ or e.__context__
+                raise ValueError(f'Hex data was not hexidecimal (got {hexChars}).') from context
+            return (Token(startChar + hexChars, TokenType.SYMBOL, None, param),), reader.read(1)
+        else:
+            # If it is a control symbol, immediately return.
+            return (Token(startChar, TokenType.SYMBOL),), reader.read(1)
+
+
+def _readText(startChar: bytes, reader: io.BytesIO) -> Tuple[Tuple[Token, ...], bytes]:
+    """
+    Attempts to read the next data as text.
+    """
+    chars = [startChar]
+    # Text is actually the easiest to read, as we just read until end of
+    # stream or until a special character. However, a few characters are
+    # simply dropped during reading.
+    while (nextChar := reader.read(1)) != b'' and nextChar not in (b'{', b'}', b'\\'):
+        # Certain characters are simply dropped.
+        if nextChar not in (b'\r', b'\n'):
+            chars.append(nextChar)
+
+    # Now, we actually are reading the text as *individual tokens*, so we
+    # need to
+
+    return tuple(Token(x, TokenType.TEXT) for x in chars), nextChar
+
+
+def tokenizeRTF(data: bytes, validateStart: bool = True) -> List[Token]:
+    """
+    Reads in the bytes and sets the tokens list to the contents after
+    tokenizing.
+
+    If tokenizing fails, the current tokens list will not be changed.
+
+    :param validateStart: If ``False``, does not check the first few tags.
+        Useful when tokenizing a snippet rather than a document.
+
+    :raises TypeError: The data is not recognized as RTF.
+    :raises ValueError: An issue with basic parsing occured.
+    """
+    reader = io.BytesIO(data)
+    if validateStart:
+        # This tokenizer *only* breaks things up. It does *not* care about
+        # groups and stuff, as that is for a parser to deal with. All we do is
+        # track the current backslash state and token state. We also simply
+        # check that the first token is "\rtf1" preceeded by a group start, and
+        # that is it.
+        start = reader.read(6)
+        if start != b'{\\rtf1':
+            raise TypeError('Data does not start with "{\\rtf1".')
+
+        tokens = [
+            Token(b'{', TokenType.GROUP_START),
+            Token(b'\\rtf1', TokenType.CONTROL, b'rtf', 1),
+        ]
+        nextChar = reader.read(1)
+
+        # If the next character is a space, ignore it.
+        if nextChar == b' ':
+            nextChar = reader.read(1)
+    else:
+        tokens = []
+        nextChar = reader.read(1)
+
+    # At every iteration, so long as there is more data, nextChar should be
+    # set. As such, use it to determine what kind of data to try to read,
+    # using the delimeter of that type of data to know what to do next.
+    while nextChar != b'':
+        # We should have exactly one character, the start of the next
+        # section. Use it to determine what to do.
+        if nextChar in (b'\r', b'\n'):
+            # Just read the next character and start the loop over.
+            nextChar = reader.read(1)
+            continue
+
+        if nextChar == b'\\':
+            newTokens, nextChar = _readControl(nextChar, reader)
+        elif nextChar == b'{':
+            # This will always be a group start, which has nothing left to
+            # read.
+            nextChar = reader.read(1)
+            newTokens = (Token(b'{', TokenType.GROUP_START),)
+        elif nextChar == b'}':
+            # This will always be a group end, which has nothing left to
+            # read.
+            nextChar = reader.read(1)
+            newTokens = (Token(b'}', TokenType.GROUP_END),)
+        else:
+            # Otherwise, it's just text.
+            newTokens, nextChar = _readText(nextChar, reader)
+
+        tokens.extend(newTokens)
+
+    return tokens