extract_msg.properties Package

Subpackages/Submodules

Package 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.

toBytes() → bytes[source]

Converts the property into bytes.

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

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.

property value: Any: Property value.

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

Bases: object

Class for handling access to the named properties themselves.

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]

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

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

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

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.

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.

Parameters:

named – The Named instance to refer to for named properties entries.
streamSource – The source to use for acquiring the data of a named property.

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.

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

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.

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.

Reads a properties stream or creates a brand new PropertiesStore object.

Parameters:

data – The bytes of the properties instance. Setting to None or empty bytes will cause the properties instance to not be valid unless writable is set to True. If that is the case, the instance will be setup for creating a new properties stream.
type – The type of properties stream this instance represents.
writable – Whether this properties stream should accept modification.

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.

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

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.

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

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 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.

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.

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.

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.

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.

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

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.

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