extract_msg.properties package

Submodules

extract_msg.properties.named module

class extract_msg.properties.named.Named(msg: MSGFile)[source]

Bases: object

Class for handling access to the named properties themselves.

property dir: Returns the directory inside the MSG file where the named properties are located.

exists(filename: str | List[str] | Tuple[str]) → bool[source]

Checks if stream exists inside the named properties folder.

Raises:: ReferenceError – The associated MSGFile instance has been garbage collected.

get(propertyName: Tuple[str, str], default: _T | None = None) → NamedPropertyBase | _T[source]

Tries to get a named property based on its key.

Returns :param default: if not found. Key is a tuple of the name and the property set GUID.

getPropNameByStreamID(streamID: int | str) → Tuple[str, str] | None[source]

Gets the name of a property (as a key for the internal dict) that is stored in the specified stream.

Useful for determining if a stream/property stream entry is a named property.

Parameters:

streamID – A 4 hex character identifier that will be checked. May also be an integer that can convert to 4 hex characters.

Returns:

The name, if the stream is a named property, otherwise None.

Raises:

InvalidPropertyIdError – The Stream ID is invalid.
TypeError – The Stream ID is not a valid type.

getStream(filename: str | List[str] | Tuple[str]) → bytes | None[source]

Gets a binary representation of the requested stream.

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

Raises:: ReferenceError – The associated MSGFile instance has been garbage collected.

items() → Iterable[Tuple[Tuple[str, str], NamedPropertyBase]][source]

keys() → Iterable[Tuple[str, str]][source]

property msg: MSGFile

Returns the Message instance the attachment belongs to.

Raises:: ReferenceError – The associated MSGFile instance has been garbage collected.

property namedProperties: Dict[Tuple[str, str], NamedPropertyBase]: Returns a copy of the dictionary containing all the named properties.

pprintKeys() → None[source]: Uses the pprint function on a sorted list of keys.

values() → Iterable[NamedPropertyBase][source]

class extract_msg.properties.named.NamedProperties(named: Named, streamSource: MSGFile | AttachmentBase)[source]

Bases: object

An instance that uses a Named instance and an extract-msg class to read the data of named properties.

get(item: Tuple[str, str] | NamedPropertyBase, default: _T | None = None) → Any | _T[source]

Get a named property, returning the value of :param default: if not found. Item must be a tuple with 2 items: the name and the GUID string.

Raises:: ReferenceError – The associated instance for getting actual property data has been garbage collected.

class extract_msg.properties.named.NamedPropertyBase(entry: Dict[str, Any])[source]

Bases: ABC

property guid: str: The guid of the property’s property set.

property guidIndex: int: The guid index of the property’s property set.

abstract property identifier: Tuple[str, str]: An identifier that can be used to full identify the property.

property namedPropertyID: int: The named property id.

property propertyStreamID: str: An ID usable for grabbing the value stream.

property rawEntry: Dict[str, Any]

property rawEntryStream: bytes: The raw data used for the entry.

abstract property type: NamedPropertyType: Returns the type of the named property. This will be a member of the NamedPropertyType enum.

class extract_msg.properties.named.NumericalNamedProperty(entry: Dict)[source]

Bases: NamedPropertyBase

property identifier: Tuple[str, str]: An identifier that can be used to full identify the property.

property propertyID: str: The actualy property id of the named property.

property streamID: int: Returns the streamID of the named property. This may not be accurate.

property type: NamedPropertyType: Returns the type of the named property. This will be a member of the NamedPropertyType enum.

class extract_msg.properties.named.StringNamedProperty(entry: Dict, name: str)[source]

Bases: NamedPropertyBase

property identifier: Tuple[str, str]: An identifier that can be used to full identify the property.

property name: str: The name of the property.

property streamID: int: Returns the streamID of the named property. This may not be accurate.

property type: NamedPropertyType: Returns the type of the named property. This will be a member of the NamedPropertyType enum.

extract_msg.properties.prop module

class extract_msg.properties.prop.FixedLengthProp(data: bytes)[source]

Bases: PropBase

Class to contain the data for a single fixed length property.

Currently a work in progress.

property signedValue: Any

A signed representation of the value.

Setting the value through this property will convert it if necessary before using the default value setter.

Raises:: struct.error – The value was out of range when setting.

toBytes() → bytes[source]

Converts the property into bytes.

Raises:: ValueError – An issue occured where the value was not converted to bytes.

property value: Any: Property value.

class extract_msg.properties.prop.PropBase(data: bytes)[source]

Bases: ABC

Base class for Prop instances.

property flags: PropertyFlags: Integer that contains property flags.

property name: str: Hexadecimal representation of the property ID followed by the type.

property propertyID: int: The property ID for this property.

abstract toBytes() → bytes[source]: Converts the property into a string of 16 bytes.

property type: int: The type of property.

class extract_msg.properties.prop.VariableLengthProp(data: bytes)[source]

Bases: PropBase

Class to contain the data for a single variable length property.

property reservedFlags: int: The reserved flags field of the variable length property.

property size: int

The size of the data the property corresponds to.

For string streams, this is the number of characters contained. For multiple properties, this is the number of entries.

When setting this, the underlying length field will be set which is a manipulated value. For multiple properties of a fixed length, this will be the size value multiplied by the length of the properties. For multiple strings, this will be 4 times the size value. For multiple binary, this will be 8 times the size value. For strings, this will be the number of characters plus 1 if non-unicode, otherwise the number of characters plus 1, all multiplied by 2. For binary, this will be the size with no modification.

Size cannot be set for properties of type 0x000D and 0x0048.

Raises:

TypeError – Tried to set the size for a property that cannot have the size changed.
ValueError – The translated value for the size is too large when setting.

toBytes() → bytes[source]: Converts the property into a string of 16 bytes.

extract_msg.properties.prop.createNewProp(name: str)[source]

Creates a blank property using the specified name.

Parameters:

name – An 8 character hex string containing the property ID and type.

Raises:

TypeError – A type other than a str was given.
ValueError – The string was not 8 hex characters.
ValueError – An invalid property type was given.

extract_msg.properties.prop.createProp(data: bytes) → PropBase[source]

Creates an instance of PropBase from the specified bytes.

If the prop type is not recognized, a VariableLengthProp will be created.

extract_msg.properties.properties_store module

class extract_msg.properties.properties_store.PropertiesStore(data: bytes | None, type_: PropertiesType, writable: bool = False)[source]

Bases: object

Parser for msg properties files.

addProperty(prop: PropBase, force: bool = False) → None[source]

Adds the property if it does not exist.

Parameters:

prop – The property to add.
force – If True, the writable property will be ignored. This will not be reflected when converting to bytes if the instance is not readable.

Raises:

KeyError – A property already exists with the chosen name.
NotWritableError – The method was used on an unwritable instance.

property attachmentCount: int

The number of Attachment objects for the MSGFile object.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

property date: datetime | None: Returns the send date contained in the Properties file.

get(name: str | int, default: _T | None = None) → PropBase | _T[source]

Retrieve the property of :param name:.

Returns:: The property, or the value of :param default: if the property could not be found.

getProperties(id_: str | int) → List[PropBase][source]

Gets all properties with the specified ID.

Parameters:: ID – An 4 digit hexadecimal string or an int that is less than 0x10000.

getValue(name: str | int, default: _T | None = None) → Any | _T[source]: Attempts to get the first property

property isError: bool

Whether the instance is in an invalid state.

If the instance is not writable and was given no data, this will be True.

items() → a set-like object providing a view on D's items[source]

keys() → a set-like object providing a view on D's keys[source]

makeWritable() → PropertiesStore[source]

Returns a copy of this PropertiesStore object that allows modification.

If the instance is already writable, this will return the object.

property nextAttachmentId: int

The ID to use for naming the next Attachment object storage if one is created inside the .msg file.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

property nextRecipientId: int

The ID to use for naming the next Recipient object storage if one is created inside the .msg file.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

pprintKeys() → None[source]: Uses the pprint function on a sorted list of the keys.

property props: Dict[str, PropBase]: Returns a copy of the internal properties dict.

property recipientCount: int

The number of Recipient objects for the MSGFile object.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

removeProperty(nameOrProp: str | PropBase) → None[source]

Removes the property by name or by instance.

Due to possible ambiguities, this function does not accept an int argument nor will it be able to find a property based on the 4 character hex ID.

Raises:

KeyError – The property was not found.
NotWritableError – The instance is not writable.
TypeError – The type for :param nameOrProp: was wrong.

toBytes() → bytes[source]

values() → an object providing a view on D's values[source]

property writable: bool: Whether the instance accepts modification.

Module contents

Classes and functions involved with managing properties.

class extract_msg.properties.FixedLengthProp(data: bytes)[source]

Bases: PropBase

Class to contain the data for a single fixed length property.

Currently a work in progress.

property signedValue: Any

A signed representation of the value.

Setting the value through this property will convert it if necessary before using the default value setter.

Raises:: struct.error – The value was out of range when setting.

toBytes() → bytes[source]

Converts the property into bytes.

Raises:: ValueError – An issue occured where the value was not converted to bytes.

property value: Any: Property value.

class extract_msg.properties.Named(msg: MSGFile)[source]

Bases: object

Class for handling access to the named properties themselves.

property dir: Returns the directory inside the MSG file where the named properties are located.

exists(filename: str | List[str] | Tuple[str]) → bool[source]

Checks if stream exists inside the named properties folder.

Raises:: ReferenceError – The associated MSGFile instance has been garbage collected.

get(propertyName: Tuple[str, str], default: _T | None = None) → NamedPropertyBase | _T[source]

Tries to get a named property based on its key.

Returns :param default: if not found. Key is a tuple of the name and the property set GUID.

getPropNameByStreamID(streamID: int | str) → Tuple[str, str] | None[source]

Gets the name of a property (as a key for the internal dict) that is stored in the specified stream.

Useful for determining if a stream/property stream entry is a named property.

Parameters:

streamID – A 4 hex character identifier that will be checked. May also be an integer that can convert to 4 hex characters.

Returns:

The name, if the stream is a named property, otherwise None.

Raises:

InvalidPropertyIdError – The Stream ID is invalid.
TypeError – The Stream ID is not a valid type.

getStream(filename: str | List[str] | Tuple[str]) → bytes | None[source]

Gets a binary representation of the requested stream.

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

Raises:: ReferenceError – The associated MSGFile instance has been garbage collected.

items() → Iterable[Tuple[Tuple[str, str], NamedPropertyBase]][source]

keys() → Iterable[Tuple[str, str]][source]

property msg: MSGFile

Returns the Message instance the attachment belongs to.

Raises:: ReferenceError – The associated MSGFile instance has been garbage collected.

property namedProperties: Dict[Tuple[str, str], NamedPropertyBase]: Returns a copy of the dictionary containing all the named properties.

pprintKeys() → None[source]: Uses the pprint function on a sorted list of keys.

values() → Iterable[NamedPropertyBase][source]

class extract_msg.properties.NamedProperties(named: Named, streamSource: MSGFile | AttachmentBase)[source]

Bases: object

An instance that uses a Named instance and an extract-msg class to read the data of named properties.

get(item: Tuple[str, str] | NamedPropertyBase, default: _T | None = None) → Any | _T[source]

Get a named property, returning the value of :param default: if not found. Item must be a tuple with 2 items: the name and the GUID string.

Raises:: ReferenceError – The associated instance for getting actual property data has been garbage collected.

class extract_msg.properties.NamedPropertyBase(entry: Dict[str, Any])[source]

Bases: ABC

property guid: str: The guid of the property’s property set.

property guidIndex: int: The guid index of the property’s property set.

abstract property identifier: Tuple[str, str]: An identifier that can be used to full identify the property.

property namedPropertyID: int: The named property id.

property propertyStreamID: str: An ID usable for grabbing the value stream.

property rawEntry: Dict[str, Any]

property rawEntryStream: bytes: The raw data used for the entry.

abstract property type: NamedPropertyType: Returns the type of the named property. This will be a member of the NamedPropertyType enum.

class extract_msg.properties.NumericalNamedProperty(entry: Dict)[source]

Bases: NamedPropertyBase

property identifier: Tuple[str, str]: An identifier that can be used to full identify the property.

property propertyID: str: The actualy property id of the named property.

property streamID: int: Returns the streamID of the named property. This may not be accurate.

property type: NamedPropertyType: Returns the type of the named property. This will be a member of the NamedPropertyType enum.

class extract_msg.properties.PropBase(data: bytes)[source]

Bases: ABC

Base class for Prop instances.

property flags: PropertyFlags: Integer that contains property flags.

property name: str: Hexadecimal representation of the property ID followed by the type.

property propertyID: int: The property ID for this property.

abstract toBytes() → bytes[source]: Converts the property into a string of 16 bytes.

property type: int: The type of property.

class extract_msg.properties.PropertiesStore(data: bytes | None, type_: PropertiesType, writable: bool = False)[source]

Bases: object

Parser for msg properties files.

addProperty(prop: PropBase, force: bool = False) → None[source]

Adds the property if it does not exist.

Parameters:

prop – The property to add.
force – If True, the writable property will be ignored. This will not be reflected when converting to bytes if the instance is not readable.

Raises:

KeyError – A property already exists with the chosen name.
NotWritableError – The method was used on an unwritable instance.

property attachmentCount: int

The number of Attachment objects for the MSGFile object.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

property date: datetime | None: Returns the send date contained in the Properties file.

get(name: str | int, default: _T | None = None) → PropBase | _T[source]

Retrieve the property of :param name:.

Returns:: The property, or the value of :param default: if the property could not be found.

getProperties(id_: str | int) → List[PropBase][source]

Gets all properties with the specified ID.

Parameters:: ID – An 4 digit hexadecimal string or an int that is less than 0x10000.

getValue(name: str | int, default: _T | None = None) → Any | _T[source]: Attempts to get the first property

property isError: bool

Whether the instance is in an invalid state.

If the instance is not writable and was given no data, this will be True.

items() → a set-like object providing a view on D's items[source]

keys() → a set-like object providing a view on D's keys[source]

makeWritable() → PropertiesStore[source]

Returns a copy of this PropertiesStore object that allows modification.

If the instance is already writable, this will return the object.

property nextAttachmentId: int

The ID to use for naming the next Attachment object storage if one is created inside the .msg file.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

property nextRecipientId: int

The ID to use for naming the next Recipient object storage if one is created inside the .msg file.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

pprintKeys() → None[source]: Uses the pprint function on a sorted list of the keys.

property props: Dict[str, PropBase]: Returns a copy of the internal properties dict.

property recipientCount: int

The number of Recipient objects for the MSGFile object.

Raises:

NotWritableError – The setter was used on an unwritable instance.
TypeError – The Properties instance is not for an MSGFile object.

removeProperty(nameOrProp: str | PropBase) → None[source]

Removes the property by name or by instance.

Due to possible ambiguities, this function does not accept an int argument nor will it be able to find a property based on the 4 character hex ID.

Raises:

KeyError – The property was not found.
NotWritableError – The instance is not writable.
TypeError – The type for :param nameOrProp: was wrong.

toBytes() → bytes[source]

values() → an object providing a view on D's values[source]

property writable: bool: Whether the instance accepts modification.

class extract_msg.properties.StringNamedProperty(entry: Dict, name: str)[source]

Bases: NamedPropertyBase

property identifier: Tuple[str, str]: An identifier that can be used to full identify the property.

property name: str: The name of the property.

property streamID: int: Returns the streamID of the named property. This may not be accurate.

property type: NamedPropertyType: Returns the type of the named property. This will be a member of the NamedPropertyType enum.

class extract_msg.properties.VariableLengthProp(data: bytes)[source]

Bases: PropBase

Class to contain the data for a single variable length property.

property reservedFlags: int: The reserved flags field of the variable length property.

property size: int

The size of the data the property corresponds to.

For string streams, this is the number of characters contained. For multiple properties, this is the number of entries.

When setting this, the underlying length field will be set which is a manipulated value. For multiple properties of a fixed length, this will be the size value multiplied by the length of the properties. For multiple strings, this will be 4 times the size value. For multiple binary, this will be 8 times the size value. For strings, this will be the number of characters plus 1 if non-unicode, otherwise the number of characters plus 1, all multiplied by 2. For binary, this will be the size with no modification.

Size cannot be set for properties of type 0x000D and 0x0048.

Raises:

TypeError – Tried to set the size for a property that cannot have the size changed.
ValueError – The translated value for the size is too large when setting.

toBytes() → bytes[source]: Converts the property into a string of 16 bytes.