pykdebugparser is a Python library designed to parse Darwin's (iOS and macOS) kdebug events and ktraces. It provides utilities to convert raw kdebug dumps into meaningful traces, offering a more formatted output compared to tools like `fs_usage` or `ktrace`. Currently at version 1.2.7, the library is actively maintained with frequent updates for bug fixes, compatibility with newer Python versions, and expanded event handling.
Install & Compatibility
Where this runs
tested against v1.2.7 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.114s · 28.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.992s · 29MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The main class is nested within a submodule of the same name. Attempting to import directly from the top-level package will result in a ModuleNotFoundError.
from pykdebugparser.pykdebugparser import PyKdebugParser
Initialize the PyKdebugParser and attempt to open a kdebug trace file. The example includes creating a simple dummy file for demonstration purposes if a real kdebug.bin is not present. For actual usage, generate a trace using `sudo ktrace dump` on a macOS system.
import os
from pykdebugparser.pykdebugparser import PyKdebugParser
# Create a dummy kdebug.bin for demonstration if it doesn't exist
dummy_kdebug_path = 'kdebug.bin'
if not os.path.exists(dummy_kdebug_path):
print(f"Creating a dummy '{dummy_kdebug_path}' file for quickstart example.")
# A minimal, valid kdebug header (approximate structure, might not be fully functional)
# This is highly simplified and for demonstration purposes only.
# Real kdebug files require specific kernel structures.
# For a real trace, use `sudo ktrace dump` on macOS.
dummy_content = b'\x00\x00\x00\x00\x00\x00\x00\x00' * 10 # Simulate some binary data
with open(dummy_kdebug_path, 'wb') as f:
f.write(dummy_content)
parser = PyKdebugParser()
parser.color = True # Enable colored output
try:
with open(dummy_kdebug_path, 'rb') as f:
# In a real scenario, you'd iterate over parsed events or traces
# For this quickstart, we'll just demonstrate opening and a basic print.
print(f"Attempting to parse '{dummy_kdebug_path}'...")
# Note: Actual parsing methods (e.g., parser.parse_file, parser.parse_traces)
# would be used here. This example focuses on instantiation and file handling.
# If the dummy file is too simple, parse_events might return nothing or error.
# We'll just print a success message for file opening.
print(f"Successfully opened '{dummy_kdebug_path}'. Further parsing requires valid kdebug data.")
# Example of attempting to parse (may not yield meaningful results with dummy data)
# events = parser.parse_file(f)
# for event in events:
# print(event)
except FileNotFoundError:
print(f"Error: The file '{dummy_kdebug_path}' was not found. Please ensure it exists or create a real kdebug dump using `sudo ktrace dump` on macOS.")
except Exception as e:
print(f"An error occurred during parsing: {e}")
finally:
# Clean up dummy file
if os.path.exists(dummy_kdebug_path) and dummy_kdebug_path == 'kdebug.bin' and b'\x00\x00\x00\x00\x00\x00\x00\x00' * 10 in open(dummy_kdebug_path, 'rb').read():
os.remove(dummy_kdebug_path)
print(f"Cleaned up dummy '{dummy_kdebug_path}'.")
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.