{"id":10347,"library":"wavedrom","title":"WaveDrom Python Library","description":"The `wavedrom` Python library provides a command-line utility and programmatic API for generating digital waveform diagrams from WaveJSON/WaveJSON5 input. It's compatible with the WaveDrom JavaScript library specification, allowing users to define waveform signals in a simple JSON format and render them into SVG images. The current version is 2.0.3.post3, with active maintenance and occasional releases addressing bugs and minor features.","status":"active","version":"2.0.3.post3","language":"en","source_language":"en","source_url":"https://github.com/wallento/wavedrompy","tags":["wavedrom","waveform","digital-design","svg","electronics","json"],"install":[{"cmd":"pip install wavedrom","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for parsing WaveJSON5 input format, which extends standard JSON.","package":"json5","optional":false},{"reason":"Used for parsing and handling color names in WaveDrom specifications.","package":"webcolors","optional":false}],"imports":[{"note":"The primary rendering function is exposed via `wavedrom.render` in v2.x. Direct `wavedrom.render_svg()` or other old patterns are incorrect.","wrong":"import wavedrom; wavedrom.render_svg()","symbol":"render_wavedrom_svg","correct":"from wavedrom.render import render_wavedrom_svg"}],"quickstart":{"code":"import json\nfrom wavedrom.render import render_wavedrom_svg\n\n# Define your WaveJSON/WaveJSON5 data as a string\nwavejson_data = '''\n{\n  \"signal\": [\n    { \"name\": \"clk\", \"wave\": \"p.....|...\" },\n    { \"name\": \"d\",   \"wave\": \"x.345x|x.23\" },\n    { \"name\": \"q\",   \"wave\": \"10101x|1010\" }\n  ],\n  \"head\": { \"text\": \"My Simple Waveform\" }\n}\n'''\n\n# Render the WaveJSON string to an SVG string\nsvg_output = render_wavedrom_svg(wavejson_data)\n\n# You can now save the SVG string to a file or embed it\n# with open(\"waveform.svg\", \"w\") as f:\n#     f.write(svg_output)\n\n# print(svg_output[:200]) # Print start of SVG to confirm","lang":"python","description":"This quickstart demonstrates how to programmatically render a WaveJSON string into an SVG image using the `render_wavedrom_svg` function. The input is a multi-line string containing the WaveJSON specification."},"warnings":[{"fix":"Upgrade to `wavedrom` v2.x and update import paths to `from wavedrom.render import render_wavedrom_svg` for programmatic usage.","message":"The `wavedrom` library underwent a significant rewrite with version 2.0. The primary programmatic API for rendering changed. Older examples relying on direct `wavedrom.render_svg()` or accessing internal components may no longer work.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"If you have your WaveDrom data as a Python dictionary, serialize it to a JSON/JSON5 string first using `json.dumps()` or `json5.dumps()` before passing it to `render_wavedrom_svg`.","message":"The `render_wavedrom_svg` function expects a *string* containing valid WaveJSON or WaveJSON5 data. Passing a Python dictionary directly will result in an error, as it's not automatically serialized.","severity":"gotcha","affected_versions":">= 2.0.0"},{"fix":"For programmatic use within Python scripts, import `render_wavedrom_svg`. For quick conversions or shell scripting, use the `wavedrom-cli` executable installed to your PATH.","message":"While `wavedrom` provides a Python API, its name and `setup.py` entrypoint `wavedrom-cli` suggest it's often used as a command-line tool. Ensure you understand if you need the CLI (`wavedrom-cli input.json > output.svg`) or the Python library API.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `wavedrom` is installed in your current environment using `pip install wavedrom`. If using virtual environments, activate the correct one.","cause":"Attempting to import `wavedrom.render` but `wavedrom` is not installed or the environment is not correctly activated.","error":"ModuleNotFoundError: No module named 'wavedrom.render'"},{"fix":"Upgrade to `wavedrom` v2.x (`pip install --upgrade wavedrom`) and use `from wavedrom.render import render_wavedrom_svg`.","cause":"You are likely using an outdated version of `wavedrom` (pre-2.0) that had a different API, or you're trying an incorrect import path.","error":"AttributeError: module 'wavedrom' has no attribute 'render_wavedrom_svg' (or 'render_svg')"},{"fix":"Carefully review your WaveJSON string for any syntax mistakes, unclosed brackets, missing commas, or incorrect escaping. Online JSON validators can help identify issues.","cause":"The input string passed to `render_wavedrom_svg` is not valid JSON or WaveJSON5, or contains syntax errors.","error":"json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)"}]}