olefile (version 0.42, 2015-01-24) | index .\olefile.py

`# olefile (formerly OleFileIO_PL) version 0.42 2015-01-24
#
# Module to read/write Microsoft OLE2 files (also called Structured Storage or
# Microsoft Compound Document File Format), such as Microsoft Office 97-2003
# documents, Image Composer and FlashPix files, Outlook messages, ...
# This version is compatible with Python 2.6+ and 3.x
#
# Project website: http://www.decalage.info/olefile
#
# olefile is copyright (c) 2005-2015 Philippe Lagadec (http://www.decalage.info)
#
# olefile is based on the OleFileIO module from the PIL library v1.1.6
# See: http://www.pythonware.com/products/pil/index.htm
#
# The Python Imaging Library (PIL) is
# Copyright (c) 1997-2005 by Secret Labs AB
# Copyright (c) 1995-2005 by Fredrik Lundh
#
# See source code and LICENSE.txt for information on usage and redistribution.`

Modules
`` |  |
array datetime | io os | struct sys |

Classes
`` |  | OleFileIO OleMetadata
class OleFileIO
`` | `OLE container object This class encapsulates the interface to an OLE 2 structured storage file. Use the listdir and openstream methods to access the contents of this file. Object names are given as a list of strings, one for each subentry level. The root entry should be omitted. For example, the following code extracts all image streams from a Microsoft Image Composer file:: ole = OleFileIO("fan.mic") for entry in ole.listdir(): if entry[1:2] == "Image": fin = ole.openstream(entry) fout = open(entry[0:1], "wb") while True: s = fin.read(8192) if not s: break fout.write(s) You can use the viewer application provided with the Python Imaging Library to view the resulting files (which happens to be standard TIFF files).`
| Methods defined here: __init__(self, filename=None, raise_defects=40, write_mode=False, debug=False, path_encoding='utf-8') `Constructor for the OleFileIO class. :param filename: file to open. - if filename is a string smaller than 1536 bytes, it is the path of the file to open. (bytes or unicode string) - if filename is a string longer than 1535 bytes, it is parsed as the content of an OLE file in memory. (bytes type only) - if filename is a file-like object (with read, seek and tell methods), it is parsed as-is. :param raise_defects: minimal level for defects to be raised as exceptions. (use DEFECT_FATAL for a typical application, DEFECT_INCORRECT for a security-oriented application, see source code for details) :param write_mode: bool, if True the file is opened in read/write mode instead of read-only by default. :param debug: bool, set debug mode :param path_encoding: None or str, name of the codec to use for path names (streams and storages), or None for Unicode. Unicode by default on Python 3+, UTF-8 on Python 2.x. (new in olefile 0.42, was hardcoded to Latin-1 until olefile v0.41)` close(self) `close the OLE file, to release the file object` dumpdirectory(self) `Dump directory (for debugging only)` dumpfat(self, fat, firstindex=0) `Displays a part of FAT in human-readable form for debugging purpose` dumpsect(self, sector, firstindex=0) `Displays a sector in a human-readable form, for debugging purpose.` exists(self, filename) `Test if given filename exists as a stream or a storage in the OLE container. Note: filename is case-insensitive. :param filename: path of stream in storage tree. (see openstream for syntax) :returns: True if object exist, else False.` get_metadata(self) `Parse standard properties streams, return an OleMetadata object containing all the available metadata. (also stored in the metadata attribute of the OleFileIO object) new in version 0.25` get_rootentry_name(self) `Return root entry name. Should usually be 'Root Entry' or 'R' in most implementations.` get_size(self, filename) `Return size of a stream in the OLE container, in bytes. :param filename: path of stream in storage tree (see openstream for syntax) :returns: size in bytes (long integer) :exception IOError: if file not found :exception TypeError: if this is not a stream.` get_type(self, filename) `Test if given filename exists as a stream or a storage in the OLE container, and return its type. :param filename: path of stream in storage tree. (see openstream for syntax) :returns: False if object does not exist, its entry type (>0) otherwise: - STGTY_STREAM: a stream - STGTY_STORAGE: a storage - STGTY_ROOT: the root entry` getctime(self, filename) `Return creation time of a stream/storage. :param filename: path of stream/storage in storage tree. (see openstream for syntax) :returns: None if creation time is null, a python datetime object otherwise (UTC timezone) new in version 0.26` getmtime(self, filename) `Return modification time of a stream/storage. :param filename: path of stream/storage in storage tree. (see openstream for syntax) :returns: None if modification time is null, a python datetime object otherwise (UTC timezone) new in version 0.26` getproperties(self, filename, convert_time=False, no_conversion=None) `Return properties described in substream. :param filename: path of stream in storage tree (see openstream for syntax) :param convert_time: bool, if True timestamps will be converted to Python datetime :param no_conversion: None or list of int, timestamps not to be converted (for example total editing time is not a real timestamp) :returns: a dictionary of values indexed by id (integer)` getsect(self, sect) `Read given sector from file on disk. :param sect: int, sector index :returns: a string containing the sector data.` listdir(self, streams=True, storages=False) `Return a list of streams and/or storages stored in this file :param streams: bool, include streams if True (True by default) - new in v0.26 :param storages: bool, include storages if True (False by default) - new in v0.26 (note: the root storage is never included) :returns: list of stream and/or storage paths` loaddirectory(self, sect) `Load the directory. :param sect: sector index of directory stream.` loadfat(self, header) `Load the FAT table.` loadfat_sect(self, sect) `Adds the indexes of the given sector to the FAT :param sect: string containing the first FAT sector, or array of long integers :returns: index of last FAT sector.` loadminifat(self) `Load the MiniFAT table.` open(self, filename, write_mode=False) `Open an OLE2 file in read-only or read/write mode. Read and parse the header, FAT and directory. :param filename: string-like or file-like object, OLE file to parse - if filename is a string smaller than 1536 bytes, it is the path of the file to open. (bytes or unicode string) - if filename is a string longer than 1535 bytes, it is parsed as the content of an OLE file in memory. (bytes type only) - if filename is a file-like object (with read, seek and tell methods), it is parsed as-is. :param write_mode: bool, if True the file is opened in read/write mode instead of read-only by default. (ignored if filename is not a path)` openstream(self, filename) `Open a stream as a read-only file object (BytesIO). Note: filename is case-insensitive. :param filename: path of stream in storage tree (except root entry), either: - a string using Unix path syntax, for example: 'storage_1/storage_1.2/stream' - or a list of storage filenames, path to the desired stream/storage. Example: ['storage_1', 'storage_1.2', 'stream'] :returns: file object (read-only) :exception IOError: if filename not found, or if this is not a stream.` sect2array(self, sect) `convert a sector to an array of 32 bits unsigned integers, swapping bytes on big endian CPUs such as PowerPC (old Macs)` write_sect(self, sect, data, padding='\x00') `Write given sector to file on disk. :param sect: int, sector index :param data: bytes, sector data :param padding: single byte, padding character if data < sector size` write_stream(self, stream_name, data) `Write a stream to disk. For now, it is only possible to replace an existing stream by data of the same size. :param stream_name: path of stream in storage tree (except root entry), either: - a string using Unix path syntax, for example: 'storage_1/storage_1.2/stream' - or a list of storage filenames, path to the desired stream/storage. Example: ['storage_1', 'storage_1.2', 'stream'] :param data: bytes, data to be written, must be the same size as the original stream.`
class OleMetadata
`` | `class to parse and store metadata from standard properties of OLE files. Available attributes: codepage, title, subject, author, keywords, comments, template, last_saved_by, revision_number, total_edit_time, last_printed, create_time, last_saved_time, num_pages, num_words, num_chars, thumbnail, creating_application, security, codepage_doc, category, presentation_target, bytes, lines, paragraphs, slides, notes, hidden_slides, mm_clips, scale_crop, heading_pairs, titles_of_parts, manager, company, links_dirty, chars_with_spaces, unused, shared_doc, link_base, hlinks, hlinks_changed, version, dig_sig, content_type, content_status, language, doc_version Note: an attribute is set to None when not present in the properties of the OLE file. References for SummaryInformation stream: - http://msdn.microsoft.com/en-us/library/dd942545.aspx - http://msdn.microsoft.com/en-us/library/dd925819%28v=office.12%29.aspx - http://msdn.microsoft.com/en-us/library/windows/desktop/aa380376%28v=vs.85%29.aspx - http://msdn.microsoft.com/en-us/library/aa372045.aspx - http://sedna-soft.de/summary-information-stream/ - http://poi.apache.org/apidocs/org/apache/poi/hpsf/SummaryInformation.html References for DocumentSummaryInformation stream: - http://msdn.microsoft.com/en-us/library/dd945671%28v=office.12%29.aspx - http://msdn.microsoft.com/en-us/library/windows/desktop/aa380374%28v=vs.85%29.aspx - http://poi.apache.org/apidocs/org/apache/poi/hpsf/DocumentSummaryInformation.html new in version 0.25`
| Methods defined here: __init__(self) `Constructor for OleMetadata All attributes are set to None by default` dump(self) `Dump all metadata, for debugging purposes.` parse_properties(self, olefile) `Parse standard properties of an OLE file, from the streams "SummaryInformation" and "DocumentSummaryInformation", if present. Properties are converted to strings, integers or python datetime objects. If a property is not present, its value is set to None.` Data and other attributes defined here: DOCSUM_ATTRIBS = ['codepage_doc', 'category', 'presentation_target', 'bytes', 'lines', 'paragraphs', 'slides', 'notes', 'hidden_slides', 'mm_clips', 'scale_crop', 'heading_pairs', 'titles_of_parts', 'manager', 'company', 'links_dirty', 'chars_with_spaces', 'unused', 'shared_doc', 'link_base', ...] SUMMARY_ATTRIBS = ['codepage', 'title', 'subject', 'author', 'keywords', 'comments', 'template', 'last_saved_by', 'revision_number', 'total_edit_time', 'last_printed', 'create_time', 'last_saved_time', 'num_pages', 'num_words', 'num_chars', 'thumbnail', 'creating_application', 'security']

Functions
`` |  | debug = debug_pass(msg) debug_pass(msg) debug_print(msg) filetime2datetime(filetime) `convert FILETIME (64 bits int) to Python datetime.datetime` i16(c, o=0) `Converts a 2-bytes (16 bits) string to an integer. :param c: string containing bytes to convert :param o: offset of bytes to convert in string` i32(c, o=0) `Converts a 4-bytes (32 bits) string to an integer. :param c: string containing bytes to convert :param o: offset of bytes to convert in string` i8(c) `# version for Python 2.x` isOleFile(filename) `Test if a file is an OLE container (according to the magic bytes in its header). :param filename: string-like or file-like object, OLE file to parse - if filename is a string smaller than 1536 bytes, it is the path of the file to open. (bytes or unicode string) - if filename is a string longer than 1535 bytes, it is parsed as the content of an OLE file in memory. (bytes type only) - if filename is a file-like object (with read and seek methods), it is parsed as-is. :returns: True if OLE, False otherwise.` set_debug_mode(debug_mode) `Set debug mode on or off, to control display of debugging messages. :param mode: True or False`

Data
`` |  | DEBUG_MODE = False DEFAULT_PATH_ENCODING = 'utf-8' DEFECT_FATAL = 40 DEFECT_INCORRECT = 30 DEFECT_POTENTIAL = 20 DEFECT_UNSURE = 10 DIFSECT = 4294967292L ENDOFCHAIN = 4294967294L FATSECT = 4294967293L FREESECT = 4294967295L KEEP_UNICODE_NAMES = True MAGIC = '\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1' MAXREGSECT = 4294967290L MAXREGSID = 4294967290L MINIMAL_OLEFILE_SIZE = 1536 NOSTREAM = 4294967295L STGTY_EMPTY = 0 STGTY_LOCKBYTES = 3 STGTY_PROPERTY = 4 STGTY_ROOT = 5 STGTY_STORAGE = 1 STGTY_STREAM = 2 UINT32 = 'L' VT = {0: 'VT_EMPTY', 1: 'VT_NULL', 2: 'VT_I2', 3: 'VT_I4', 4: 'VT_R4', 5: 'VT_R8', 6: 'VT_CY', 7: 'VT_DATE', 8: 'VT_BSTR', 9: 'VT_DISPATCH', ...} VT_BLOB = 65 VT_BLOB_OBJECT = 70 VT_BOOL = 11 VT_BSTR = 8 VT_CARRAY = 28 VT_CF = 71 VT_CLSID = 72 VT_CY = 6 VT_DATE = 7 VT_DECIMAL = 14 VT_DISPATCH = 9 VT_EMPTY = 0 VT_ERROR = 10 VT_FILETIME = 64 VT_HRESULT = 25 VT_I1 = 16 VT_I2 = 2 VT_I4 = 3 VT_I8 = 20 VT_INT = 22 VT_LPSTR = 30 VT_LPWSTR = 31 VT_NULL = 1 VT_PTR = 26 VT_R4 = 4 VT_R8 = 5 VT_SAFEARRAY = 27 VT_STORAGE = 67 VT_STORED_OBJECT = 69 VT_STREAM = 66 VT_STREAMED_OBJECT = 68 VT_UI1 = 17 VT_UI2 = 18 VT_UI4 = 19 VT_UI8 = 21 VT_UINT = 23 VT_UNKNOWN = 13 VT_USERDEFINED = 29 VT_VARIANT = 12 VT_VECTOR = 4096 VT_VOID = 24 WORD_CLSID = '00020900-0000-0000-C000-000000000046' __author__ = 'Philippe Lagadec' __date__ = '2015-01-24' __version__ = '0.42' keyword = 'VT_UNKNOWN' print_function = _Feature((2, 6, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 65536) var = 13

Author
`` |  | Philippe Lagadec