blockdiag

Common errors

• ModuleNotFoundError: No module named 'blockdiag.command'

  cause 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

  cause 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'

  cause 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'

  cause 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`).

Warnings

• breaking Blockdiag 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.
• gotcha The `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`.
• gotcha Font 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`).
• gotcha The 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`.

Install

• pip install blockdiag Install core library

Imports

• parse_string
  wrong:

  from blockdiag.blockdiag import parse_string

  correct:

  from blockdiag.parser import parse_string

  The parser is located in the `parser` submodule, not directly under the main package.
• generate_image
  wrong:

  from blockdiag import generate_image

  correct:

  from blockdiag.command.blockdiag import generate_image

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

Quickstart

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}")