WaveDrom Python Library

2.0.3.post3 · active · verified Fri Apr 17

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.

Common errors

```
ModuleNotFoundError: No module named 'wavedrom.render'
```
cause Attempting to import `wavedrom.render` but `wavedrom` is not installed or the environment is not correctly activated.

fix Ensure `wavedrom` is installed in your current environment using `pip install wavedrom`. If using virtual environments, activate the correct one.
```
AttributeError: module 'wavedrom' has no attribute 'render_wavedrom_svg' (or 'render_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.

fix Upgrade to `wavedrom` v2.x (`pip install --upgrade wavedrom`) and use `from wavedrom.render import render_wavedrom_svg`.
```
json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)
```
cause The input string passed to `render_wavedrom_svg` is not valid JSON or WaveJSON5, or contains syntax errors.

fix Carefully review your WaveJSON string for any syntax mistakes, unclosed brackets, missing commas, or incorrect escaping. Online JSON validators can help identify issues.

Warnings

breaking 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.
Fix: Upgrade to `wavedrom` v2.x and update import paths to `from wavedrom.render import render_wavedrom_svg` for programmatic usage.
gotcha 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.
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`.
gotcha 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.
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.

Install

pip install wavedrom Install stable version

Imports

render_wavedrom_svg
wrong:
```
import wavedrom; wavedrom.render_svg()
```
correct:
```
from wavedrom.render import render_wavedrom_svg
```
The primary rendering function is exposed via `wavedrom.render` in v2.x. Direct `wavedrom.render_svg()` or other old patterns are incorrect.

Quickstart

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.

import json
from wavedrom.render import render_wavedrom_svg

# Define your WaveJSON/WaveJSON5 data as a string
wavejson_data = '''
{
  "signal": [
    { "name": "clk", "wave": "p.....|..." },
    { "name": "d",   "wave": "x.345x|x.23" },
    { "name": "q",   "wave": "10101x|1010" }
  ],
  "head": { "text": "My Simple Waveform" }
}
'''

# Render the WaveJSON string to an SVG string
svg_output = render_wavedrom_svg(wavejson_data)

# You can now save the SVG string to a file or embed it
# with open("waveform.svg", "w") as f:
#     f.write(svg_output)

# print(svg_output[:200]) # Print start of SVG to confirm

view raw JSON →