extract-msg 0.48.2__py3-none-any.whl

extract_msg/attachments/__init__.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+
+"""
+Submodule for attachment classes.
+"""
+
+__all__ = [
+    # Modules.
+    'custom_att_handler',
+
+    # Classes.
+    'Attachment',
+    'AttachmentBase',
+    'BrokenAttachment',
+    'CustomAttachmentHandler',
+    'EmbeddedMsgAttachment',
+    'SignedAttachment',
+    'UnsupportedAttachment',
+    'WebAttachment',
+
+    # Functions.
+    'initStandardAttachment',
+    'registerHandler',
+]
+
+
+from . import custom_att_handler
+from .attachment import Attachment
+from .attachment_base import AttachmentBase
+from .broken_att import BrokenAttachment
+from .custom_att import CustomAttachment
+from .custom_att_handler import CustomAttachmentHandler, registerHandler
+from .emb_msg_att import EmbeddedMsgAttachment
+from .signed_att import SignedAttachment
+from .unsupported_att import UnsupportedAttachment
+from .web_att import WebAttachment
+
+import logging as _logging
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from ..msg_classes import MSGFile
+
+_logger = _logging.getLogger(__name__)
+_logger.addHandler(_logging.NullHandler())
+
+
+def initStandardAttachment(msg: MSGFile, dir_: str) -> AttachmentBase:
+    """
+    Returns an instance of AttachmentBase for the attachment in the MSG file at
+    the specified internal directory.
+
+    :param errorBehavior: Used to tell the function what to do on errors.
+    """
+    from ..properties import PropertiesStore
+    from ..enums import ErrorBehavior, PropertiesType
+    from ..exceptions import (
+            FeatureNotImplemented, StandardViolationError,
+            UnrecognizedMSGTypeError
+        )
+
+    # First, create the properties store to check things like attachment type.
+    propertiesStream = msg.getStream([dir_, '__properties_version1.0'])
+    propStore = PropertiesStore(propertiesStream, PropertiesType.ATTACHMENT)
+
+    try:
+        # Now that we have the properties store, attempt to check what type it
+        # is.
+        if '37050003' not in propStore:
+                from ..properties.prop import createProp
+
+                _logger.warning(f'Attachment method property not found on attachment {dir_}. Code will attempt to guess the type.')
+                _logger.log(5, propStore)
+
+                # Because this condition is actually kind of a violation of the
+                # standard, we are just going to do this in a dumb way.
+                # Basically we are going to try to set the attach method
+                # *manually* just so I don't have to go and modify the
+                # following code.
+                if msg.exists([dir_, '__substg1.0_37010102']):
+                    # Set it as data and call it a day.
+                    propData = b'\x03\x00\x057\x07\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00'
+                elif msg.exists([dir_, '__substg1.0_3701000D']):
+                    # If it is a folder and we have properties, call it an MSG
+                    # file.
+                    if msg.exists([dir_, '__substg1.0_3701000D/__properties_version1.0']):
+                        propData = b'\x03\x00\x057\x07\x00\x00\x00\x05\x00\x00\x00\x00\x00\x00\x00'
+                    else:
+                        # Call if custom attachment data.
+                        propData = b'\x03\x00\x057\x07\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00'
+                else:
+                    # Can't autodetect it, so throw an error.
+                    raise StandardViolationError(f'Attachment method missing on attachment {dir_}, and it could not be determined automatically.')
+
+                propStore.addProperty(createProp(propData), True)
+
+        attMethod = propStore.getValue('37050003', 0) & 7
+
+        if msg.exists([dir_, '__substg1.0_37010102']):
+                return Attachment(msg, dir_, propStore)
+        if msg.exists([dir_, '__substg1.0_3701000D']):
+            if attMethod != 5:
+                return CustomAttachment(msg, dir_, propStore)
+            else:
+                return EmbeddedMsgAttachment(msg, dir_, propStore)
+
+        if attMethod == 7:
+            return WebAttachment(msg, dir_, propStore)
+
+        # Error handling.
+        if attMethod == 1:
+            raise StandardViolationError('Attachments of type data MUST have a data stream.')
+        if attMethod == 0:
+            raise NotImplementedError('extract-msg does not support attachments of type afNone.')
+        if attMethod == 2:
+            raise NotImplementedError('extract-msg does not support attachments of type afByReference. Contact the developer for support.')
+        if attMethod == 4:
+            raise NotImplementedError('extract-msg does not support attachments of type afByReferenceOnly. Contact the developer for support.')
+
+        raise NotImplementedError(f'Could not determine attachment type ({attMethod})!')
+
+    except (FeatureNotImplemented,
+            NotImplementedError,
+            UnrecognizedMSGTypeError):
+        if ErrorBehavior.ATTACH_NOT_IMPLEMENTED in msg.errorBehavior:
+            _logger.exception(f'Error processing attachment at {dir_}')
+            return UnsupportedAttachment(msg, dir_, propStore)
+        else:
+            raise
+    except StandardViolationError:
+        if ErrorBehavior.STANDARDS_VIOLATION in msg.errorBehavior:
+            _logger.exception(f'Unresolvable standards violation in  {dir_}')
+            return BrokenAttachment(msg, dir_, propStore)
+        else:
+            raise
+    except Exception:
+        if ErrorBehavior.ATTACH_BROKEN in msg.errorBehavior:
+            _logger.exception(f'Error processing attachment at {dir_}')
+            return BrokenAttachment(msg, dir_, propStore)
+        else:
+            raise

extract_msg/attachments/attachment.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'Attachment',
+]
+
+
+import logging
+import os
+import pathlib
+import random
+import string
+import zipfile
+
+from typing import TYPE_CHECKING
+
+from .. import constants
+from .attachment_base import AttachmentBase
+from ..enums import AttachmentType, SaveType
+from ..utils import createZipOpen, inputToString, prepareFilename
+from ..properties import PropertiesStore
+
+
+# Allow for nice type checking.
+if TYPE_CHECKING:
+    from ..msg_classes.msg import MSGFile
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+class Attachment(AttachmentBase):
+    """
+    A standard data attachment of an MSG file.
+    """
+
+    def __init__(self, msg: MSGFile, dir_: str, propStore: PropertiesStore):
+        super().__init__(msg, dir_, propStore)
+        self.__data = self.getStream('__substg1.0_37010102')
+
+    def getFilename(self, **kwargs) -> str:
+        """
+        Returns the filename to use for the attachment.
+
+        :param contentId: Use the contentId, if available.
+        :param customFilename: A custom name to use for the file.
+
+        If the filename starts with "UnknownFilename" then there is no guarantee
+        that the files will have exactly the same filename.
+        """
+        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
+            # 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 = inputToString('UnknownFilename ' + \
+                   ''.join(random.choice(string.ascii_uppercase + string.digits)
+                           for _ in range(5)) + '.bin', 'ascii')
+
+    def save(self, **kwargs) -> constants.SAVE_TYPE:
+        """
+        Saves the attachment data.
+
+        The name of the file is determined by several factors. The first
+        thing that is checked is if you have provided :param customFilename:
+        to this function. If you have, that is the name that will be used.
+        If no custom name has been provided and :param contentId: is ``True``,
+        the file will be saved using the content ID of the attachment. If
+        it is not found or :param contentId: is ``False``, the long filename
+        will be used. If the long filename is not found, the short one will
+        be used. If after all of this a usable filename has not been found, a
+        random one will be used (accessible from :meth:`randomFilename`).
+        After the name to use has been determined, it will then be shortened to
+        make sure that it is not more than the value of :param maxNameLength:.
+
+        To change the directory that the attachment is saved to, set the value
+        of :param customPath: when calling this function. The default save
+        directory is the working directory.
+
+        If you want to save the contents into a ``ZipFile`` or similar object,
+        either pass a path to where you want to create one or pass an instance
+        to :param zip:. If :param zip: is an instance, :param customPath: will
+        refer to a location inside the zip file.
+
+        :param extractEmbedded: If ``True``, causes the attachment, should it
+            be an embedded MSG file, to save as a .msg file instead of calling
+            it's save function.
+        :param skipEmbedded: If ``True``, skips saving this attachment if it is
+            an embedded MSG file.
+        """
+        # 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 data(self) -> bytes:
+        """
+        The bytes making up the attachment data.
+        """
+        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.DATA