Registry / serialization / olefile

olefile

JSON →
library0.47pypypi✓ verified 24d ago

The olefile library is a Python package designed to parse, read, and write Microsoft OLE2 files, also known as Structured Storage or Compound Documents. These files are commonly used in older Microsoft Office formats (e.g., .doc, .xls, .ppt, .msg) and provide a file system within a file. It offers low-level access to streams and storages. The current version is 0.47, and the library maintains a stable release cadence with updates focused on bug fixes and robustness.

pip install olefile
INSTALL
IMPORT
SIG · OLEFILE
O
olefile
serializationpythonv0.47
Install
1.8s avg
Import
26ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.47 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.028s · 18.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.8s · import 0.024s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

olefile
import olefile
OleFileIO
from olefile import OleFileIO
Can also be accessed via olefile.OleFileIO after 'import olefile'.

This quickstart demonstrates how to open an OLE file, check if it's a valid OLE structure, list its internal streams and storages, and read content from a specific stream. Replace 'example.doc' with the actual path to your OLE file (e.g., a .doc, .xls, .ppt, or .msg file) for a real test.

import olefile import os # For a real test, replace 'path/to/your/document.doc' with an actual OLE file path. # This example uses a placeholder path and demonstrates the basic API. # If the file does not exist or is not an OLE file, appropriate messages will be printed. ole_file_path = 'example.doc' # Replace with a path to a real OLE file if olefile.isOleFile(ole_file_path): try: # Open the OLE file ole = olefile.OleFileIO(ole_file_path) print(f"Opened OLE file: {ole_file_path}") # List all streams and storages print("\nStreams and Storages:") for stream_path in ole.listdir(): print(f"- {stream_path}") # Example: check if a specific stream exists and read its content target_stream = ['WordDocument'] # Common stream in Word docs if ole.exists(target_stream): # Read stream content (returns bytes) data = ole.openstream(target_stream).read() print(f"\nContent of '{'/'.join(target_stream)}' (first 100 bytes):") print(data[:100]) else: print(f"\nStream '{'/'.join(target_stream)}' not found.") # Close the file when done ole.close() except Exception as e: print(f"Error processing OLE file '{ole_file_path}': {e}") elif os.path.exists(ole_file_path): print(f"'{ole_file_path}' exists but is not a valid OLE file.") else: print(f"'{ole_file_path}' does not exist.") print("Please provide a valid path to a Microsoft OLE2 Structured Storage file for testing.")
Debug
Known issues
breakingThe `OleFileIO.meta` attribute was removed in version 0.43. Previously, this attribute provided access to OLE properties (e.g., Author, Title). Direct access to these properties using `ole.meta` will now raise an `AttributeError`.
fix
Use `ole.getproperties()` or `ole.get_metadata()` (if applicable for your OLE file type and stream structure) to retrieve metadata and properties. The `get_metadata()` method was introduced for a more structured approach.
affects: <=0.42
gotchaThe `olefile.isOleFile()` function could return false positives for certain non-OLE files in versions prior to 0.45.1, incorrectly identifying them as OLE files. This could lead to parsing errors or unexpected behavior when attempting to open such files with `OleFileIO`.
fix
Upgrade to `olefile` version 0.45.1 or newer. Always combine `isOleFile()` with robust error handling around `OleFileIO` instantiation, especially when dealing with untrusted input files.
affects: <0.45.1
gotchaThe `olefile` library does not inherently support parsing encrypted or password-protected OLE files. While it may be able to parse the high-level structure, the actual data streams within such files will remain encrypted and unreadable by `olefile`.
fix
Ensure that any OLE files you intend to parse are unencrypted. If encryption is present, you would need to decrypt the file using external tools or libraries before processing it with `olefile`.
affects: All versions
Errors
Common errors & fixes
not an OLE2 compound document
The file being processed is either not a valid OLE2 structured storage file (e.g., it's a newer Office Open XML format like .docx, .xlsx, a plain text file, or another file type) or it is a corrupted OLE2 file.
fix
Ensure the file is a genuine OLE2 file (e.g., older .doc, .xls, .ppt, .msg). If it's a newer Office format, use a library designed for Open XML files (e.g., `python-docx`, `openpyxl`). You can use `olefile.isOleFile(filename)` to check if a file is an OLE container before attempting to open it.
ImportError: No module named olefile
The `olefile` package is not installed in the Python environment where the code is being executed.
fix
Install the `olefile` package using pip: `pip install olefile`.
FileNotFoundError: [Errno 2] No such file or directory: 'your_file.doc'
The specified file path is incorrect, the file does not exist at the given location, or the program lacks the necessary permissions to access the file. (In Python 2, this would typically appear as `IOError: [Errno 2] No such file or directory`).
fix
Double-check the file path for any typos and verify that the file exists at the specified location. Consider using an absolute path to avoid issues with the current working directory. Ensure the program has the required read permissions for the file and its parent directories.
TypeError: 'NoneType' object is not subscriptable
An `olefile` method (such as `openstream()`, `get_metadata()`, or `getproperties()`) returned `None` because the requested stream, property, or metadata was not found or accessible, and the code subsequently attempted to access it using square bracket notation (e.g., `result[0]`).
fix
Always check if the result of an `olefile` method is `None` before attempting to access its elements. For example, use an `if` statement like `stream = ole.openstream('some_stream'); if stream is not None: ...`
Upgrade
Version history
0.47latest on PyPI · released Dec 1, 2023
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
Resources
olefile — pip install olefile · libregistry