blockdiag

library3.0.0pypypi✓ verified 85d ago

blockdiag generates block-diagram images from simple text definitions. It is part of the diag suite of tools for various diagrams and is currently at version 3.0.0. Its release cadence is feature-driven, providing updates for new Python versions and enhancements.

devops serialization

pip install blockdiag

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BLOCKDIAG

blockdiag

devopspythonv3.0.0

Install

2.7s avg

Import

37ms

Disk

45MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.0 · 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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.037s · 43.2MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.7s · import 0.037s · 44MB

45MB installed

● package 45MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse_string

✓ from blockdiag.parser import parse_string

✗ from blockdiag.blockdiag import parse_string

The parser is located in the `parser` submodule, not directly under the main package.

generate_image

✓ from blockdiag.command.blockdiag import generate_image

✗ from blockdiag import generate_image

The main image generation utility is found in the `command.blockdiag` submodule, typically for programmatic use.

This quickstart demonstrates how to programmatically generate a block diagram. It parses a diagram definition string, then uses `generate_image` to create a PNG image into a BytesIO object, which is then saved to a file.

from blockdiag.parser import parse_string from blockdiag.command.blockdiag import generate_image from io import BytesIO import os diagram_text = """ diagram { A -> B -> C; B -> D; } """ try: # Parse the diagram definition tree = parse_string(diagram_text) # Generate the image to a BytesIO object output_image_stream = BytesIO() generate_image(tree, format='png', output_filename=output_image_stream) # You can now save output_image_stream.getvalue() to a file output_filename = os.environ.get('BLOCKDIAG_OUTPUT_FILE', 'example_diagram.png') with open(output_filename, "wb") as f: f.write(output_image_stream.getvalue()) print(f"Diagram generated to {output_filename}") except ImportError as e: print(f"Error: {e}. Make sure blockdiag and Pillow are installed.") except Exception as e: print(f"An unexpected error occurred: {e}")

blockdiag --version

Debug

Known issues

breakingBlockdiag 3.x removed support for Python 2.x. It now requires Python 3.7 or newer.

fix

Upgrade your Python environment to 3.7+ and ensure all dependencies are compatible. For older Python 2 projects, stick to blockdiag 2.x.

affects: >=3.0.0

gotchaThe `Pillow` library is a mandatory runtime dependency for generating raster images (e.g., PNG, JPEG). Without it, image generation will fail or only SVG output will be possible.

fix

Always ensure Pillow is installed alongside blockdiag: `pip install blockdiag Pillow`.

affects: All versions

gotchaFont rendering can be inconsistent across different operating systems or headless environments. Missing fonts can lead to default fallback fonts or incorrect text display.

fix

Explicitly specify a font using the `font` argument (programmatic) or `-f` option (CLI) with a path to a universally available font (e.g., DejaVu Sans). On Linux servers, install common font packages (e.g., `fonts-dejavu-core`).

affects: All versions

gotchaThe programmatic API for blockdiag is not always immediately obvious. Many users mistakenly try to import directly from `blockdiag` instead of specific submodules like `blockdiag.parser` or `blockdiag.command.blockdiag`.

fix

Refer to the official documentation or quickstart examples for correct import paths, typically `from blockdiag.parser import parse_string` and `from blockdiag.command.blockdiag import generate_image`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'blockdiag.command'

Incorrect import path for programmatic usage, commonly when trying to guess the location of the `generate_image` function.

fix

The `generate_image` function is located in `blockdiag.command.blockdiag`. Correct imports are `from blockdiag.parser import parse_string` and `from blockdiag.command.blockdiag import generate_image`.

blockdiag: command not found

The `blockdiag` command-line tool is not in your system's PATH, or the package was not installed with its entry points.

fix

Ensure `blockdiag` is installed in the active virtual environment (`pip install blockdiag`). If using a global install, make sure the Python user scripts directory (e.g., `~/.local/bin` on Linux) is included in your system's PATH.

IOError: Unable to load font '/path/to/font.ttf'

The specified font file (via the `font` argument or `-f` CLI option) could not be found, is inaccessible, or is corrupt.

fix

Verify the font file exists and the path is correct and accessible to the process running blockdiag. For headless servers, ensure necessary font packages (e.g., `fonts-dejavu-core` on Debian/Ubuntu) are installed.

AttributeError: 'module' object has no attribute 'Image'

This usually indicates that the `Pillow` library, a core dependency for image output, is either not installed, an incompatible version is present, or there's a conflict with an old `PIL` installation.

fix

Install or upgrade Pillow to a compatible version: `pip install Pillow>=6.0.0`. If an old `PIL` (Python Imaging Library) is present, uninstall it first (`pip uninstall PIL`).

Upgrade

Version history

3.0.0latest on PyPI · released Dec 6, 2021

Audit

Dependencies

PillowrequiredRequired for generating PNG and other raster image formats.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/blockdiag/blockdiag ↗

packagehttps://pypi.org/project/blockdiag/ ↗

homepagehttp://blockdiag.com/ ↗