D2 (d2lang) Python Wrapper: Use D2Lang in Python Projects

Diego Carrasco G. — Fri, 22 Nov 2024 08:00:00 GMT

TLDR: I created a Python wrapper for D2 diagram language that bundles D2's binaries, allowing you to render D2 diagrams in your Python projects without manual binary installation or subprocess management. You can install it with pip.

Context

I needed a way to render D2 diagrams programmatically in Python, specifically for this Nikola static site and other Python projects. While D2 is a powerful diagram scripting language (which I now love) with a CLI tool written in Go, installing the binary manually in each environment wasn't practical (and also not possible afaik in Cloudflare Pages). After searching for "D2 lang Python" and "D2 diagram Python wrapper" without finding a solution that bundled the binaries or that could render d2 code, I created d2-python-wrapper. It's a thin Python layer around D2's official binary, distributed as a Python package that includes the necessary executables for each platform.

I found D2 while exploring options for adding diagrams to my digital marketing book and I wanted to use it to add a diagram in this article about Tailscale and LXC containers. If you're familiar with Mermaid or PlantUML, D2 is similar but with a more intuitive syntax and (in my opinion) better-looking output.

Here's where it got interesting: I couldn't install D2's CLI tools directly in Cloudflare Pages. Rather than depend on third-party services (I tried kroki, I decided to create a wrapper that bundles the binaries. That's how d2-python-wrapper was born, and now you can install it directly from PyPI.

What I Built

I wanted something simple - no complex subprocess management or command-line hassles. Just clean Python code like this:

from d2_python import D2

d2 = D2()
d2.render("x -> y", "output.svg")

Instead of installing D2 separately, I can just use pip to install the package and have everything ready to go. I can also fix specific version of the package with specific versions of the d2 binary.

What You Get

When you install d2-python-wrapper, you get:

A simple Python API for D2 diagram rendering
The D2 binaries included in the package
Automatic platform detection (Linux, Windows, MacOS)
Multiple output formats (SVG, PNG, PDF)
Theme customization options
Layout engine selection
Proper cleanup of temporary files

Basically, an interface in Python for d2 bin 😁

Real-World Usage

I'm currently working on a Nikola plugin for D2 diagrams (not yet released). Here's how I use it in my site with a shortcode:

direction: down
Internet -> Server
Server -> Database

If you're interested in using D2 with Nikola, keep an eye out for the plugin release or just let me know in Mastodon or LinkedIn. In the meantime, you can still use d2-python-wrapper directly in your Python projects.

How to Get Started

First, install via pip:

pip install d2-python-wrapper

Then use it in your code:

from d2_python import D2

d2 = D2()

# From string input
d2.render("x -> y", "output.svg")

# Or with more options
d2.render("diagram.d2", "output.svg", 
          theme="1",
          format="svg"
          )

Testing Approach

I wanted to make sure the wrapper produces exactly the same output as the original D2 binary. Here's one of the tests that verifies this:

def test_wrapper_vs_binary_output(d2, tmp_path):
    diagram = "x -> y"
    wrapper_output = tmp_path / "wrapper.svg"
    binary_output = tmp_path / "binary.svg"

    # Test both outputs are identical
    d2.render(diagram, str(wrapper_output))
    subprocess.run([d2.binary_path, str(input_file), str(binary_output)])
    assert wrapper_output.read_bytes() == binary_output.read_bytes()

Build Automation

I'm using GitHub Actions to automatically bundle D2 binaries for Linux, Windows, and MacOS. While I've primarily tested this on Linux, the setup should support all major platforms:

- name: Download and extract D2 releases
  run: |
    mkdir -p d2_python/bin/{linux,win32,darwin}
    # Platform-specific binary downloads and setup...

If you're using Windows or MacOS and want to help test, feel free to give it a try and let me know how it goes!

What's Next

I built this primarily for my own use with Nikola and other Python projects, but I'm open to expanding it. If you have ideas for new features or find any bugs, please open an issue on GitHub.

When to Use This

You might find d2-python-wrapper useful if you're: - Generating static sites - Automating documentation - Creating reports - Working on any Python project where you need programmatic diagram rendering

I'm releasing this under the Mozilla Public License Version 2.0 (same as D2 itself), so feel free to use and modify it for your projects.

Diego A. Carrasco Gubernatis | Personal Website (Posts about development)