{"id":7578,"library":"pykdebugparser","title":"pykdebugparser","description":"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.","status":"active","version":"1.2.7","language":"en","source_language":"en","source_url":"https://github.com/matan1008/pykdebugparser","tags":["parsing","kdebug","macos","ios","kernel-tracing","binary-parsing"],"install":[{"cmd":"pip install pykdebugparser","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from pykdebugparser import PyKdebugParser","symbol":"PyKdebugParser","correct":"from pykdebugparser.pykdebugparser import PyKdebugParser"}],"quickstart":{"code":"import os\nfrom pykdebugparser.pykdebugparser import PyKdebugParser\n\n# Create a dummy kdebug.bin for demonstration if it doesn't exist\ndummy_kdebug_path = 'kdebug.bin'\nif not os.path.exists(dummy_kdebug_path):\n    print(f\"Creating a dummy '{dummy_kdebug_path}' file for quickstart example.\")\n    # A minimal, valid kdebug header (approximate structure, might not be fully functional)\n    # This is highly simplified and for demonstration purposes only.\n    # Real kdebug files require specific kernel structures.\n    # For a real trace, use `sudo ktrace dump` on macOS.\n    dummy_content = b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00' * 10 # Simulate some binary data\n    with open(dummy_kdebug_path, 'wb') as f:\n        f.write(dummy_content)\n\nparser = PyKdebugParser()\nparser.color = True # Enable colored output\n\ntry:\n    with open(dummy_kdebug_path, 'rb') as f:\n        # In a real scenario, you'd iterate over parsed events or traces\n        # For this quickstart, we'll just demonstrate opening and a basic print.\n        print(f\"Attempting to parse '{dummy_kdebug_path}'...\")\n        # Note: Actual parsing methods (e.g., parser.parse_file, parser.parse_traces)\n        # would be used here. This example focuses on instantiation and file handling.\n        # If the dummy file is too simple, parse_events might return nothing or error.\n        # We'll just print a success message for file opening.\n        print(f\"Successfully opened '{dummy_kdebug_path}'. Further parsing requires valid kdebug data.\")\n        # Example of attempting to parse (may not yield meaningful results with dummy data)\n        # events = parser.parse_file(f)\n        # for event in events:\n        #     print(event)\nexcept FileNotFoundError:\n    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.\")\nexcept Exception as e:\n    print(f\"An error occurred during parsing: {e}\")\nfinally:\n    # Clean up dummy file\n    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():\n        os.remove(dummy_kdebug_path)\n        print(f\"Cleaned up dummy '{dummy_kdebug_path}'.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure trace files originate from a Darwin-based system. On macOS, use `sudo ktrace dump` to generate compatible kdebug traces.","message":"The `pykdebugparser` library is designed exclusively for parsing kdebug events from Darwin (iOS and macOS) systems. Using it with trace files from other operating systems (e.g., Linux `perf` or Windows ETW) will lead to parsing errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.8 or later.","message":"Official CI support for Python 3.7 was removed in `v1.2.5`. While the library might still function on Python 3.7, it is highly recommended to upgrade to Python 3.8 or newer to ensure full compatibility, stability, and ongoing support.","severity":"deprecated","affected_versions":">=1.2.5"},{"fix":"Verify the integrity and format of your kdebug trace file. Ensure it was generated as a raw binary dump from a Darwin system (e.g., using `ktrace dump`).","message":"The `PyKdebugParser` expects raw binary kdebug trace files. Passing incorrectly formatted, corrupted, or non-binary files will result in low-level parsing failures such as `struct.error` or `IndexError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement to `from pykdebugparser.pykdebugparser import PyKdebugParser`.","cause":"The `PyKdebugParser` class is nested within a submodule of the same name. Users often attempt to import it directly from the top-level package.","error":"ModuleNotFoundError: No module named 'pykdebugparser.pykdebugparser'"},{"fix":"Ensure the kdebug trace file exists in the specified location. On macOS, you can generate a `ktrace` file using `sudo ktrace dump`.","cause":"The specified kdebug trace file does not exist at the given path or the path is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'kdebug.bin'"},{"fix":"Verify the integrity and source of your `kdebug` file. Ensure it is a genuine, uncorrupted binary trace generated by a Darwin system. Try generating a fresh trace file.","cause":"This error occurs when the input binary file is corrupted, malformed, or not a valid kdebug trace, causing the internal `struct` unpacking to fail.","error":"struct.error: unpack requires a buffer of ... bytes"}]}