extract_msg.msg_classes.msg Module

Module contents

class extract_msg.msg_classes.msg.MSGFile(path, **kwargs)

Bases: object

Base handler for all .msg files.

Parameters:

• path – Path to the MSG file in the system or the bytes of the MSG file.

• prefix – Used for extracting embedded MSG files inside the main one. Do not set manually unless you know what you are doing.

• parentMsg – Used for synchronizing instances of shared objects. Do not set this unless you know what you are doing.

• initAttachment – Optional, the method used when creating an attachment for an MSG file. MUST be a function that takes 2 arguments (the MSGFile instance and the directory in the MSG file where the attachment is) and returns an instance of AttachmentBase.

• delayAttachments – Optional, delays the initialization of attachments until the user attempts to retrieve them. Allows MSG files with bad attachments to be initialized so the other data can be retrieved.

• filename – Optional, the filename to be used by default when saving.

• errorBehavior – Optional, the behavior to use in the event of certain types of errors. Uses the ErrorBehavior enum.

• overrideEncoding – Optional, an encoding to use instead of the one specified by the MSG file. If the value is "chardet" and you have the chardet module installed, an attempt will be made to auto-detect the encoding based on some of the string properties. Do not report encoding errors caused by this.

• treePath – Internal variable used for giving representation of the path, as a tuple of objects, of the MSGFile. When passing, this is the path to the parent object of this instance.

• insecureFeatures – Optional, an enum value that specifies if certain insecure features should be enabled. These features should only be used on data that you trust. Uses the InsecureFeatures enum.

• dateFormat – Optional, the format string to use for dates.

• datetimeFormat – Optional, the format string to use for dates that include a time component.

Raises:

• InvalidFileFormatError – The file is not an OLE file or could not be parsed as an MSG file.

• StandardViolationError – Some part of the file badly violates the standard.

• IOError – There is an issue opening the MSG file.

• NameError – The encoding provided is not supported.

• PrefixError – The prefix is not a supported type.

• TypeError – The parent is not an instance of MSGFile or a subclass.

• ValueError – The path is invalid.

It’s recommended to check the error message to ensure you know why a specific exception was raised.

filename: str | None

close() → None

debug() → None

exists(filename: str | List[str] | Tuple[str], prefix: bool = True) → bool

Checks if the stream exists in the MSG file.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

sExists(filename: str | List[str] | Tuple[str], prefix: bool = True) → bool

Checks if string stream exists in the MSG file.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

existsTypedProperty(_id: str, location=None, _type=None, prefix: bool = True, propertiesInstance: PropertiesStore | None = None) → Tuple[bool, int]

Determines if the stream with the provided id exists in the location specified.

If no location is specified, the root directory is searched. The return of this function is 2 values, the first being a boolean for if anything was found, and the second being how many were found.

Because of how this method works, any folder that contains it’s own “__properties_version1.0” file should have this method called from it’s class.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

export(path) → None

Exports the contents of this MSG file to a new MSG files specified by the path given.

If this is an embedded MSG file, the embedded streams and directories will be added to it as if they were at the root, allowing you to save it as it’s own MSG file.

This function pulls directly from the source MSG file, so modifications to the properties of of an MSGFile object (or one of it’s subclasses) will not be reflected in the saved file.

Parameters:

path – A path-like object (including strings and pathlib.Path objects) or an IO device with a write method which accepts bytes.

exportBytes() → bytes

Saves a new copy of the MSG file, returning the bytes.

fixPath(inp: str | List[str] | Tuple[str], prefix: bool = True) → str

Changes paths so that they have the proper prefix (should :param prefix: be True) and are strings rather than lists or tuples.

getMultipleBinary(filename: str | List[str] | Tuple[str], prefix: bool = True) → List[bytes] | None

Gets a multiple binary property as a list of bytes objects.

Like getStringStream(), the 4 character type suffix should be omitted. So if you want the stream “__substg1.0_00011102” then the filename would simply be “__substg1.0_0001”.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

getMultipleString(filename: str | List[str] | Tuple[str], prefix: bool = True) → List[str] | None

Gets a multiple string property as a list of str objects.

Like getStringStream(), the 4 character type suffix should be omitted. So if you want the stream “__substg1.0_00011102” then the filename would simply be “__substg1.0_0001”.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

getNamedAs(propertyName: str, guid: str, overrideClass: Type[_T] | Callable[[Any], _T]) → _T | None

Returns the named property, setting the class if specified.

Parameters:

overrideClass – Class/function to use to morph the data that was read. The data will be the first argument to the class’s __init__ method 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.

getNamedProp(propertyName: str, guid: str, default: _T | None = None) → Any | _T

instance.namedProperties.get((propertyName, guid), default)

Can be override to create new behavior.

getPropertyAs(propertyName: int | str, overrideClass: Type[_T] | Callable[[Any], _T]) → _T | None

Returns the property, setting the class if found.

Parameters:

overrideClass – Class/function to use to morph the data that was read. The data will be the first argument to the class’s __init__ method 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.

getPropertyVal(name: int | str, default: _T | None = None) → Any | _T

instance.props.getValue(name, default)

Can be overridden to create new behavior.

getSingleOrMultipleBinary(filename: str | List[str] | Tuple[str], prefix: bool = True) → List[bytes] | bytes | None

Combination of getStream() and getMultipleBinary().

Checks to see if a single binary stream exists to return, otherwise tries to return the multiple binary stream of the same ID.

Like getStringStream(), the 4 character type suffix should be omitted. So if you want the stream “__substg1.0_00010102” then the filename would simply be “__substg1.0_0001”.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

getSingleOrMultipleString(filename: str | List[str] | Tuple[str], prefix: bool = True) → str | List[str] | None

Combination of getStringStream() and getMultipleString().

Checks to see if a single string stream exists to return, otherwise tries to return the multiple string stream of the same ID.

Like getStringStream(), the 4 character type suffix should be omitted. So if you want the stream “__substg1.0_0001001F” then the filename would simply be “__substg1.0_0001”.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

getStream(filename: str | List[str] | Tuple[str], prefix: bool = True) → bytes | None

Gets a binary representation of the requested stream.

This should ALWAYS return a bytes object if it was found, otherwise returns None.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

getStreamAs(streamID: str | List[str] | Tuple[str], overrideClass: Type[_T] | Callable[[Any], _T]) → _T | None

Returns the specified stream, modifying it to the specified class if it is found.

Parameters:

overrideClass – Class/function to use to morph the data that was read. The data will be the first argument to the class’s __init__ method 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.

getStringStream(filename: str | List[str] | Tuple[str], prefix: bool = True) → str | None

Gets a string representation of the requested stream.

Rather than the full filename, you should only feed this function the filename sans the type. So if the full name is “__substg1.0_001A001F”, the filename this function should receive should be “__substg1.0_001A”.

This should ALWAYS return a string if it was found, otherwise returns None.

Parameters:

prefix – Bool, whether to search for the entry at the root of the MSG file (False) or look in the current child MSG file (True). (Default: True)

getStringStreamAs(streamID: str | List[str] | Tuple[str], overrideClass: Type[_T] | Callable[[Any], _T]) → _T | None

Returns the specified string stream, modifying it to the specified class if it is found.

Parameters:

overrideClass – Class/function to use to morph the data that was read. The data will be the first argument to the class’s __init__ method 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.

listDir(streams: bool = True, storages: bool = False, includePrefix: bool = True) → List[List[str]]

Replacement for OleFileIO.listdir that runs at the current prefix directory.

Parameters:

includePrefix – If False, removes the part of the path that is the prefix.

slistDir(streams: bool = True, storages: bool = False, includePrefix: bool = True) → List[str]

Replacement for OleFileIO.listdir that runs at the current prefix directory. Returns a list of strings instead of lists.

save(**kwargs) → Tuple[SaveType, List[str] | str | None]

saveAttachments(skipHidden: bool = False, **kwargs) → None

Saves only attachments in the same folder.

Parameters:

skipHidden – If True, skips attachments marked as hidden. (Default: False)

saveRaw(path) → None

property areStringsUnicode: bool

Whether the strings are Unicode encoded or not.

property attachments: List[AttachmentBase] | List[SignedAttachment]

A list of all attachments.

property attachmentsDelayed: bool

Returns True if the attachment initialization was delayed.

property attachmentsReady: bool

Returns True if the attachments are ready to be used.

property classified: bool

Indicates whether the contents of this message are regarded as classified information.

property classType: str | None

The class type of the MSG file.

property commonEnd: datetime | None

The end time for the object.

property commonStart: datetime | None

The start time for the object.

property contactLinkEntry: ContactLinkEntry | None

A class that contains the list of Address Book EntryIDs linked to this Message object.

property contacts: List[str] | None

Contains the display name property of each Address Book EntryID referenced in the value of the contactLinkEntry property.

property currentVersion: int | None

Specifies the build number of the client application that sent the message.

property currentVersionName: str | None

Specifies the name of the client application that sent the message.

property dateFormat: str

The format string to use when converting dates to strings.

This is used for dates with no time component.

property datetimeFormat: str

The format string to use when converting datetimes to strings.

This is used for dates that have time components.

property errorBehavior: ErrorBehavior

The behavior to follow when certain errors occur.

Will be an instance of the ErrorBehavior enum.

property importance: Importance | None

The specified importance of the MSG file.

property importanceString: str | None

The importance string to use for saving.

If the importance is medium then it returns None. Mainly used for saving.

property initAttachmentFunc: Callable[[MSGFile, str], AttachmentBase]

The method for initializing attachments being used, should you need to use it externally for whatever reason.

property insecureFeatures: InsecureFeatures

An enum specifying what insecure features have been enabled for this file.

property kwargs: Dict[str, Any]

The kwargs used to initialize this message, excluding the prefix.

This is used for initializing embedded MSG files.

property named: Named

The main named properties storage.

This is not usable to access the data of the properties directly.

Raises:

ReferenceError – The parent MSGFile instance has been garbage collected.

property namedProperties: NamedProperties

The NamedProperties instances usable to access the data for named properties.

property overrideEncoding: str | None

None if the encoding has not been overridden, otherwise the encoding used for string streams.

property path

The message path if generated from a file, otherwise the data used to generate the MSGFile instance.

property prefix: str

The prefix of the MSGFile instance.

Intended for developer use.

property prefixLen: int

The number of elements in the prefix.

Dividing by 2 will typically tell you how deeply nested the MSG file is.

property prefixList: List[str]

The prefix list of the Message instance.

Intended for developer use.

property priority: Priority | None

The specified priority of the MSG file.

property props: PropertiesStore

The PropertiesStore instance used by the MSGFile instance.

property retentionDate: datetime | None

The date, in UTC, after which a Message Object is expired by the server.

If None, the Message object never expires.

property retentionFlags: RetentionFlags | None

Flags that specify the status or nature of an item’s retention tag or archive tag.

property sensitivity: Sensitivity | None

The specified sensitivity of the MSG file.

property sideEffects: SideEffect | None

Controls how a Message object is handled by the client in relation to certain user interface actions by the user, such as deleting a message.

property stringEncoding: str

property treePath: List[weakref.ReferenceType[Any]]

A path, as a list of weak reference to the instances needed to get to this instance through the MSGFile-Attachment tree.

These are weak references to ensure the garbage collector doesn’t see the references back to higher objects.