extract-msg 0.48.2__py3-none-any.whl

extract_msg/attachments/broken_att.py

@@ -0,0 +1,42 @@
+__all__ = [
+    'BrokenAttachment',
+]
+
+
+from .. import constants
+from .attachment_base import AttachmentBase
+from ..enums import AttachmentType, SaveType
+
+
+class BrokenAttachment(AttachmentBase):
+    """
+    An attachment that has suffered a fatal error.
+
+    Will not generate from a NotImplementedError exception.
+    """
+
+    def getFilename(self, **_) -> str:
+        raise NotImplementedError('Broken attachments cannot be saved.')
+
+    def save(self, **kwargs) -> constants.SAVE_TYPE:
+        """
+        Raises a NotImplementedError unless :param skipNotImplemented: is set to
+        True.
+
+        If it is, returns a value that indicates no data was saved.
+        """
+        if kwargs.get('skipNotImplemented', False):
+            return (SaveType.NONE, None)
+
+        raise NotImplementedError('Broken attachments cannot be saved.')
+
+    @property
+    def data(self) -> None:
+        """
+        Broken attachments have no data.
+        """
+        return None
+
+    @property
+    def type(self) -> AttachmentType:
+        return AttachmentType.BROKEN

extract_msg/attachments/custom_att.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'CustomAttachment',
+]
+
+
+import os
+import pathlib
+import random
+import string
+import zipfile
+
+from typing import Optional, TYPE_CHECKING
+
+from .. import constants
+from .attachment_base import AttachmentBase
+from .custom_att_handler import CustomAttachmentHandler, getHandler
+from ..enums import AttachmentType, SaveType
+from ..utils import createZipOpen, inputToString, prepareFilename
+
+
+if TYPE_CHECKING:
+    from ..msg_classes import MSGFile
+    from ..properties import PropertiesStore
+
+
+_saveDoc = AttachmentBase.save.__doc__
+
+
+class CustomAttachment(AttachmentBase):
+    """
+    The attachment entry for custom attachments.
+    """
+
+    def __init__(self, msg: MSGFile, dir_: str, propStore: PropertiesStore):
+        super().__init__(msg, dir_, propStore)
+
+        self.__customHandler = getHandler(self)
+        self.__data = self.__customHandler.data
+
+    def getFilename(self, **kwargs) -> str:
+        """
+        Returns the filename to use for the attachment.
+
+        If the filename starts with "UnknownFilename" then there is no guarantee
+        that the files will have exactly the same filename.
+
+        :param contentId: Use the contentId, if available.
+        :param customFilename: A custom name to use for the file.
+        """
+        filename = None
+        customFilename = kwargs.get('customFilename')
+        if customFilename:
+            customFilename = str(customFilename)
+            # First we need to validate it. If there are invalid characters,
+            # this will detect it.
+            if constants.re.INVALID_FILENAME_CHARS.search(customFilename):
+                raise ValueError('Invalid character found in customFilename. Must not contain any of the following characters: \\/:*?"<>|')
+            filename = customFilename
+        else:
+            # If not...
+            # Check if user wants to save the file under the Content-ID.
+            if kwargs.get('contentId', False):
+                filename = self.cid
+            # Try to get the name from the custom handler.
+            filename = self.customHandler.name
+            # If we are here, try to get the filename however else we can.
+            if not filename:
+                filename = self.name
+            # Otherwise just make something up!
+            if not filename:
+                return self.randomFilename
+
+        return filename
+
+    def regenerateRandomName(self) -> str:
+        """
+        Used to regenerate the random filename used if the attachment cannot
+        find a usable filename.
+        """
+        self.__randomName = 'UnknownFilename ' + \
+                   ''.join(random.choice(string.ascii_uppercase + string.digits)
+                           for _ in range(5)) + '.bin'
+
+    def save(self, **kwargs) -> constants.SAVE_TYPE:
+        # Immediate check to see if there is anything to save.
+        if self.data is None:
+            return (SaveType.NONE, None)
+
+        # Get the filename to use.
+        filename = self.getFilename(**kwargs)
+
+        # Someone managed to have a null character here, so let's get rid of
+        # that
+        filename = prepareFilename(inputToString(filename, self.msg.stringEncoding))
+
+        # Get the maximum name length.
+        maxNameLength = kwargs.get('maxNameLength', 256)
+
+        # Make sure the filename is not longer than it should be.
+        if len(filename) > maxNameLength:
+            name, ext = os.path.splitext(filename)
+            filename = name[:maxNameLength - len(ext)] + ext
+
+        # Check if we are doing a zip file.
+        _zip = kwargs.get('zip')
+
+        createdZip = False
+        try:
+            # ZipFile handling.
+            if _zip:
+                # If we are doing a zip file, first check that we have been given a path.
+                if isinstance(_zip, (str, pathlib.Path)):
+                    # If we have a path then we use the zip file.
+                    _zip = zipfile.ZipFile(_zip, 'a', zipfile.ZIP_DEFLATED)
+                    kwargs['zip'] = _zip
+                    createdZip = True
+                # Path needs to be done in a special way if we are in a zip file.
+                customPath = pathlib.Path(kwargs.get('customPath', ''))
+                # Set the open command to be that of the zip file.
+                _open = createZipOpen(_zip.open)
+                # Zip files use w for writing in binary.
+                mode = 'w'
+            else:
+                customPath = pathlib.Path(kwargs.get('customPath', '.')).absolute()
+                mode = 'wb'
+                _open = open
+
+            fullFilename = self._handleFnc(_zip, filename, customPath, kwargs)
+
+            with _open(str(fullFilename), mode) as f:
+                f.write(self.__data)
+
+            return (SaveType.FILE, str(fullFilename))
+        finally:
+            # Close the ZipFile if this function created it.
+            if _zip and createdZip:
+                _zip.close()
+
+
+    @property
+    def customHandler(self) -> Optional[CustomAttachmentHandler]:
+        """
+        The instance of the custom handler associated with this attachment, if
+        it has one.
+        """
+        return self.__customHandler
+
+    @property
+    def data(self) -> Optional[bytes]:
+        """
+        The attachment data, if any.
+
+        Returns ``None`` if there is no data to save.
+        """
+        return self.__data
+
+    @property
+    def randomFilename(self) -> str:
+        """
+        The random filename to be used by this attachment.
+        """
+        try:
+            return self.__randomName
+        except AttributeError:
+            self.regenerateRandomName()
+            return self.__randomName
+
+    @property
+    def type(self) -> AttachmentType:
+        return AttachmentType.CUSTOM

extract_msg/attachments/custom_att_handler/__init__.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+
+"""
+Submodule designed to help with saving and using custom attachments.
+
+Custom attachments are those follow standards not defined in the MSG
+documentation. Use the function `getHandler` to get an instance of a subclass of
+CustomAttachmentHandler.
+
+It should hopefully be completely unnecessary for your code to know what type of
+handler it is using, as the abstract base class should give all of the functions
+you would typically want.
+
+If you would like to add your own handler, simply subclass
+CustomAttachmentHandler and add it using the `registerHandler` function.
+"""
+
+__all__ = [
+    # Classes.
+    'CustomAttachmentHandler',
+    'LinkedObjectAttachment',
+    'OutlookImageDIB',
+
+    # Functions.
+    'getHandler',
+    'registerHandler',
+]
+
+
+from typing import List, Type, TYPE_CHECKING
+
+from .custom_handler import CustomAttachmentHandler
+from ...exceptions import FeatureNotImplemented
+
+
+# Create a way to register handlers.
+_knownHandlers: List[Type[CustomAttachmentHandler]] = []
+
+def registerHandler(handler: Type[CustomAttachmentHandler]) -> None:
+    """
+    Registers the CustomAttachmentHandler subclass as a handler.
+
+    :raises TypeError: The handler was not a subclass of
+        CustomAttachmentHandler.
+    """
+    # Make sure it is a subclass of CustomAttachmentHandler.
+    if not isinstance(handler, type):
+        raise ValueError(':param handler: must be a class, not an instance of a class.')
+    if not issubclass(handler, CustomAttachmentHandler): # pyright: ignore
+        raise ValueError(':param handler: must be a subclass of CustomAttachmentHandler.')
+    _knownHandlers.append(handler)
+
+
+# Import built-in handler modules. They will all automatically register their
+# respecive handler(s).
+from .outlook_image_dib import OutlookImageDIB
+from .lnk_obj_att import LinkedObjectAttachment
+
+
+if TYPE_CHECKING:
+    from ..attachment_base import AttachmentBase
+
+
+# Function designed to route to the correct handler.
+def getHandler(attachment: AttachmentBase) -> CustomAttachmentHandler:
+    """
+    Takes an attachment and uses it to find the correct handler.
+
+    Returns an instance created using the specified attachment.
+
+    :raises NotImplementedError: No handler could be found.
+    :raises ValueError: A handler was found, but something was wrong with the
+        attachment data.
+    """
+    for handler in _knownHandlers:
+        if handler.isCorrectHandler(attachment):
+            return handler(attachment)
+
+    raise FeatureNotImplemented(f'No valid handler could be found for the attachment. Contact the developers for help. If the CLSID is not all zeros, include it in the title or message. (CLSID: {attachment.clsid})')

extract_msg/attachments/custom_att_handler/custom_handler.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'CustomAttachmentHandler',
+]
+
+
+import abc
+import functools
+
+from typing import Dict, Optional, TYPE_CHECKING, TypeVar
+
+from ...constants import MSG_PATH, OVERRIDE_CLASS
+from ...structures.odt import ODTStruct
+from ...structures.ole_pres import OLEPresentationStream
+from ...structures.ole_stream_struct import OleStreamStruct
+from ...utils import msgPathToString
+
+
+if TYPE_CHECKING:
+    from ..attachment_base import AttachmentBase
+
+_T = TypeVar('_T')
+
+
+class CustomAttachmentHandler(abc.ABC):
+    """
+    A class designed to help with custom attachments that may require parsing in
+    special ways that are completely different from one another.
+    """
+
+    def __init__(self, attachment: AttachmentBase):
+        super().__init__()
+        self.__att = attachment
+
+    def getStream(self, filename: MSG_PATH) -> Optional[bytes]:
+        """
+        Gets a stream from the custom data directory.
+        """
+        return self.attachment.getStream('__substg1.0_3701000D/' + msgPathToString(filename))
+
+    def getStreamAs(self, streamID: MSG_PATH, overrideClass: OVERRIDE_CLASS[_T]) -> Optional[_T]:
+        """
+        Returns the specified stream, modifying it to the specified class if it
+        is found.
+
+        :param overrideClass: Class/function to use to morph the data that was
+            read. The data will be the first argument to the class's __init__
+            function or the function itself, if that is what is provided. If
+            the value is None, this function is not called. If you want it to
+            be called regardless, you should handle the data directly.
+        """
+        value = self.getStream(streamID)
+
+        if value is not None:
+            value = overrideClass(value)
+
+        return value
+
+    @classmethod
+    @abc.abstractmethod
+    def isCorrectHandler(cls, attachment: AttachmentBase) -> bool:
+        """
+        Checks if this is the correct handler for the attachment.
+        """
+
+    @abc.abstractmethod
+    def generateRtf(self) -> Optional[bytes]:
+        """
+        Generates the RTF to inject in place of the \\objattph tag.
+
+        If this function should do nothing, returns ``None``.
+        """
+
+    @property
+    def attachment(self) -> AttachmentBase:
+        """
+        The attachment this handler is associated with.
+        """
+        return self.__att
+
+    @property
+    @abc.abstractmethod
+    def data(self) -> Optional[bytes]:
+        """
+        Gets the data for the attachment.
+
+        If an attachment should do nothing when saving, returns ``None``.
+        """
+
+    @property
+    @abc.abstractmethod
+    def name(self) -> Optional[str]:
+        """
+        Returns the name to be used when saving the attachment.
+        """
+
+    @property
+    @abc.abstractmethod
+    def obj(self) -> Optional[object]:
+        """
+        Returns an object representing the data.
+
+        May return the same value as :property data:.
+
+        If there is no object to represent the custom attachment, including
+        ``bytes``, returns ``None``.
+        """
+
+    @functools.cached_property
+    def objInfo(self) -> Optional[ODTStruct]:
+        """
+        The structure representing the stream "\\x03ObjInfo", if it exists.
+        """
+        return self.getStreamAs('\x03ObjInfo', ODTStruct)
+
+    @functools.cached_property
+    def ole(self) -> Optional[OleStreamStruct]:
+        """
+        The structure representing the stream "\\x01Ole", if it exists.
+        """
+        return self.getStreamAs('\x01Ole', OleStreamStruct)
+
+    @functools.cached_property
+    def presentationObjs(self) -> Optional[Dict[int, OLEPresentationStream]]:
+        """
+        Returns a dict of all presentation streams, as bytes.
+        """
+        return {
+            int(x[1][-3:]): self.getStreamAs(x[-1], OLEPresentationStream)
+            for x in self.attachment.listDir()
+            if x[0] == '__substg1.0_3701000D' and x[1].startswith('\x02OlePres')
+        }

extract_msg/attachments/custom_att_handler/lnk_obj_att.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'LinkedObjectAttachment',
+]
+
+
+from functools import cached_property
+from typing import List, Optional, TYPE_CHECKING
+
+from . import registerHandler
+from .custom_handler import CustomAttachmentHandler
+from ...structures.entry_id import EntryID
+from ...structures.ole_pres import OLEPresentationStream
+
+
+if TYPE_CHECKING:
+    from ..attachment_base import AttachmentBase
+
+
+class LinkedObjectAttachment(CustomAttachmentHandler):
+    """
+    A link to an Outlook object.
+
+    Not *positive* I understand what this attachment type is, but this seems to
+    be the most likely name. Contains presentation data about how to render it
+    as well as properties with data that link to it. It looks *similar* to what
+    the documentation for Journal specifies would be it's custom attachment
+    type, however some small details don't perfectly add up.
+
+    I've also only seen this on Journal objects thus far.
+    """
+
+    def __init__(self, attachment: AttachmentBase):
+        super().__init__(attachment)
+        stream = attachment.getStream('__substg1.0_3701000D/\x03MailStream')
+        if not stream:
+            raise ValueError('MailStream could not be found.')
+        if len(stream) != 12:
+            raise ValueError('MailStream is the wrong length.')
+
+    @classmethod
+    def isCorrectHandler(cls, attachment: AttachmentBase) -> bool:
+        if attachment.clsid != '00020D09-0000-0000-C000-000000000046':
+            return False
+
+        return True
+
+    def generateRtf(self) -> Optional[bytes]:
+        # TODO
+        return None
+
+    @property
+    def data(self) -> None:
+        # This type of attachment has no direct associated data.
+        return None
+
+    @cached_property
+    def mailMsgAttFld(self) -> Optional[EntryID]:
+        """
+        The EntryID of the folder of the linked Message object.
+        """
+        return EntryID.autoCreate(self.getStream('MailMsgAttFld'))
+
+    @cached_property
+    def mailMsgAttMdb(self) -> Optional[EntryID]:
+        """
+        The EntryID of the store of the linked Message object.
+        """
+        return EntryID.autoCreate(self.getStream('MailMsgAttMdb'))
+
+    @cached_property
+    def mailMsgAttMsg(self) -> Optional[EntryID]:
+        """
+        The EntryID linked Message object, required only if the
+        mailMsgAttSrchKey property is None.
+        """
+        return EntryID.autoCreate(self.getStream('MailMsgAttMsg'))
+
+    @cached_property
+    def mailMsgAttSrchFld(self) -> Optional[EntryID]:
+        """
+        The object EntryID of the Sent Items special folder of the linked
+        Message object.
+        """
+        return EntryID.autoCreate(self.getStream('MailMsgAttSrchFld'))
+
+    @cached_property
+    def mailMsgAttSrchKey(self) -> Optional[bytes]:
+        """
+        The search key for the linked message object, required only if
+        mailMsgAttMsg is None.
+        """
+        return self.getStream('MailMsgAttSrchKey')
+
+    @property
+    def name(self) -> None:
+        # Doesn't save.
+        return None
+
+    @property
+    def obj(self) -> None:
+        # No object to represent this.
+        return None
+
+
+
+registerHandler(LinkedObjectAttachment)

extract_msg/attachments/custom_att_handler/outlook_image_dib.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'OutlookImage',
+]
+
+
+import struct
+
+from typing import Optional, TYPE_CHECKING
+
+from . import registerHandler
+from .custom_handler import CustomAttachmentHandler
+from ...enums import DVAspect, InsecureFeatures
+from ...exceptions import DependencyError, SecurityError
+
+
+if TYPE_CHECKING:
+    from ..attachment_base import AttachmentBase
+
+_ST_OLE = struct.Struct('<IIIII')
+_ST_MAILSTREAM = struct.Struct('<III')
+
+
+class OutlookImageDIB(CustomAttachmentHandler):
+    """
+    Custom handler for a special attachment type, a Device Independent Bitmap
+    stored in a way special to Outlook.
+    """
+
+    def __init__(self, attachment: AttachmentBase):
+        super().__init__(attachment)
+        # First we need to get the mailstream.
+        stream = self.getStream('\x03MailStream')
+        if not stream:
+            raise ValueError('MailStream could not be found.')
+        if len(stream) != 12:
+            raise ValueError('MailStream is the wrong length.')
+        # Next get the bitmap data.
+        self.__data = self.getStream('CONTENTS')
+        if not self.__data:
+            raise ValueError('Bitmap data could not be read for Outlook signature.')
+        # Get the OLE data.
+        oleStream = self.getStream('\x01Ole')
+        if not oleStream:
+            raise ValueError('OLE stream could not be found.')
+
+        # While I have only seen this stream be one length, it could in theory
+        # be more than one length. So long as it is *at least* 20 bytes, we
+        # call it valid.
+        if len(oleStream) < 20:
+            raise ValueError('OLE stream is too short.')
+
+        # Unpack and verify the OLE stream.
+        vals = _ST_OLE.unpack(oleStream[:20])
+        # Check the version magic.
+        if vals[0] != 0x2000001:
+            raise ValueError('OLE stream has wrong version magic.')
+        # Check the reserved bytes.
+        if vals[3] != 0:
+            raise ValueError('OLE stream has non-zero reserved int.')
+
+        # Unpack the mailstream and create the HTML tag.
+        vals = _ST_MAILSTREAM.unpack(stream)
+        self.__dvaspect = DVAspect(vals[0])
+        self.__x = vals[1]
+        self.__y = vals[2]
+        # Convert to twips for RTF.
+        self.__xtwips = int(round(self.__x / 1.7639))
+        self.__ytwips = int(round(self.__y / 1.7639))
+
+    @classmethod
+    def isCorrectHandler(cls, attachment: AttachmentBase) -> bool:
+        if attachment.clsid != '00000316-0000-0000-C000-000000000046':
+            return False
+
+        # Check for the required streams.
+        if not attachment.exists('__substg1.0_3701000D/CONTENTS'):
+            return False
+        if not attachment.exists('__substg1.0_3701000D/\x01Ole'):
+            return False
+        if not attachment.exists('__substg1.0_3701000D/\x03MailStream'):
+            return False
+
+        return True
+
+    def generateRtf(self) -> Optional[bytes]:
+        """
+        Generates the RTF to inject in place of the \\objattph tag.
+
+        If this function should do nothing, returns ``None``.
+
+        :raises DependencyError: PIL or Pillow could not be found.
+        """
+        if InsecureFeatures.PIL_IMAGE_PARSING not in self.attachment.msg.insecureFeatures:
+            raise SecurityError('Generating the RTF for a custom attachment requires the insecure feature PIL_IMAGE_PARSING.')
+
+        try:
+            import PIL.Image
+        except ImportError:
+            raise DependencyError('PIL or Pillow is required for inserting an Outlook Image into the body.')
+
+        # First, convert the bitmap into a PNG so we can insert it into the
+        # body.
+        import io
+
+        # Note, use self.data instead of self.__data to allow support for
+        # extensions.
+        with PIL.Image.open(io.BytesIO(self.data)) as img:
+            out = io.BytesIO()
+            img.save(out, 'PNG')
+
+        hexData = out.getvalue().hex()
+
+        inject = '{\\*\\shppict\n{\\pict\\picscalex100\\picscaley100'
+        inject += f'\\picw{img.width}\\pich{img.height}'
+        inject += f'\\picwgoal{self.__xtwips}\\pichgoal{self.__ytwips}\n'
+        inject += '\\pngblip ' + hexData + '}}'
+
+        return inject.encode()
+
+    @property
+    def data(self) -> bytes:
+        return self.__data
+
+    @property
+    def name(self) -> str:
+        # Try to get the name from the attachment. If that fails, name it based
+        # on the number.
+        if not (name := self.attachment.name):
+            name = f'attachment {int(self.attachment.dir[-8:], 16)}'
+        return name + '.bmp'
+
+    @property
+    def obj(self) -> bytes:
+        return self.data
+
+
+
+registerHandler(OutlookImageDIB)