Rendering diagrams

We support rendering SVG and ASCII diagrams:

syntax_diagrams.render_svg(element: Element[T], /, *, max_width: int | None = None, settings: SvgRenderSettings | None = None, reverse: bool | None = None, href_resolver: HrefResolver[T] | None = None, convert_resolver_data: None = None) → str
syntax_diagrams.render_svg(element: Element[U], /, *, max_width: int | None = None, settings: SvgRenderSettings | None = None, reverse: bool | None = None, href_resolver: HrefResolver[T] | None = None, convert_resolver_data: Callable[[U | None], T | None] | None) → str

Render diagram as an SVG.

Parameters:

  • node – root diagram node.

  • max_width – if given, overrides max_width from settings.

  • settings – rendering settings.

  • reverse – if given, overrides reverse from settings.

  • href_resolver – hyperlink resolver (may be used to transform text).

  • convert_resolver_data – a custom function to parse resolver_data, used when loading elements from JSON or other untrusted source.

Returns:

a string with a rendered diagram.

Throws:

LoadingError

syntax_diagrams.render_text(element: Element[T], /, *, max_width: int | None = None, settings: TextRenderSettings | None = None, reverse: bool | None = None, href_resolver: HrefResolver[T] | None = None, convert_resolver_data: None = None) → str
syntax_diagrams.render_text(element: Element[U], /, *, max_width: int | None = None, settings: TextRenderSettings | None = None, reverse: bool | None = None, href_resolver: HrefResolver[T] | None = None, convert_resolver_data: Callable[[U | None], T | None] | None) → str

Render diagram as an SVG.

Parameters:

  • node – root diagram node.

  • max_width – if given, overrides max_width from settings.

  • settings – rendering settings.

  • reverse – if given, overrides reverse from settings.

  • href_resolver – hyperlink resolver (may be used to transform text).

  • convert_resolver_data – a custom function to parse resolver_data, used when loading elements from JSON or other untrusted source.

Returns:

a string with a rendered diagram.

Throws:

LoadingError

Settings

class syntax_diagrams.SvgRenderSettings(**kwargs)

Settings for SVG rendering engine.

arc_margin: int = 5

Margin around arcs.

arc_radius: int = 10

Arc radius of railroads. 10px by default.

arrow_cross_length: int = 4

Length of an arrow across its line.

arrow_length: int = 10

Length of an arrow along its line.

arrow_style: ArrowStyle = 'NONE'

Style of arrows to draw.

comment_horizontal_padding: int = 3

Horizontal padding around text in comment nodes.

comment_radius: int = 0

Border radius in comment nodes.

comment_text_measure: TextMeasure

Service used to measure size of text inside of text nodes.

By default, set up to match default CSS settings.

comment_vertical_padding: int = 3

Vertical padding around text in comment nodes.

css_class: str = ''

Class attribute for the <svg> element.

css_style: dict[str, dict[str, str]] | str | None

CSS style that should be embedded into the diagram.

description: str | None = None

Title text that will be added to <desc> element.

end_class: EndClass = 'COMPLEX'

Controls how diagram start and end look like.

group_horizontal_margin: int = 10

Horizontal margin outside of group elements.

group_horizontal_padding: int = 10

Horizontal padding inside of group elements.

group_radius: int = 0

Border radius in groups.

group_text_horizontal_offset: int = 10

Offset from group rectangle to its heading.

group_text_measure: TextMeasure

Service used to measure size of text of groups.

By default, set up to match default CSS settings.

group_text_vertical_offset: int = 0

Offset from group rectangle to its heading.

group_vertical_margin: int = 5

Vertical margin outside of group elements.

group_vertical_padding: int = 10

Vertical padding inside of group elements.

horizontal_seq_separation: int = 10

Horizontal space between adjacent nodes.

max_width: int = 600

Max width after which a sequence will be wrapped. This option is used to automatically convert sequences to stacks. Note that this is a suggestive option, there is no guarantee that the diagram will fit to its max_width.

non_terminal_horizontal_padding: int = 10

Horizontal padding around text in non-terminal nodes.

non_terminal_radius: int = 0

Border radius in non-terminal nodes.

non_terminal_text_measure: TextMeasure

Service used to measure size of text inside of text nodes.

By default, set up to match default CSS settings.

non_terminal_vertical_padding: int = 3

Vertical padding around text in non-terminal nodes.

padding: tuple[int, int, int, int] = (1, 1, 1, 1)

Array of four positive integers denoting top, right, bottom and left padding between the diagram and its container.

reverse: bool = False

If enabled, diagram is rendered right-to-left.

terminal_horizontal_padding: int = 10

Horizontal padding around text in terminal nodes.

terminal_radius: int = 10

Border radius in terminal nodes.

terminal_text_measure: TextMeasure

Service used to measure size of text inside of text nodes.

By default, set up to match default CSS settings.

terminal_vertical_padding: int = 3

Vertical padding around text in terminal nodes.

title: str | None = None

Title text that will be added to <title> element and aria-label attribute.

vertical_choice_separation: int = 9

Vertical space between nodes in a choice() block.

vertical_choice_separation_outer: int = 9

Vertical space between nodes in a choice() block, if it contains another choice block.

vertical_seq_separation: int = 18

Vertical space between nodes in a stack() block.

vertical_seq_separation_outer: int = 18

Vertical space between nodes in a stack() block, if it appears outside of any choice block.

class syntax_diagrams.TextRenderSettings(**kwargs)

Settings for text rendering engine.

end_class: EndClass = 'COMPLEX'

Controls how diagram start and end look like.

group_horizontal_margin: int = 2

Horizontal margin outside of group elements.

group_horizontal_padding: int = 2

Horizontal padding inside of group elements.

group_text_horizontal_offset: int = 2

Offset from group rectangle to its heading.

group_text_vertical_offset: int = -1

Offset from group rectangle to its heading.

group_vertical_margin: int = 0

Vertical margin outside of group elements.

group_vertical_padding: int = 1

Vertical padding inside of group elements.

horizontal_seq_separation: int = 2

Horizontal space between adjacent nodes.

max_width: int = 80

Max width after which a sequence will be wrapped. This option is used to automatically convert sequences to stacks. Note that this is a suggestive option, there is no guarantee that the diagram will fit to its max_width.

padding: tuple[int, int, int, int] = (0, 0, 0, 0)

Array of four positive integers denoting top, right, bottom and left padding between the diagram and its container.

reverse: bool = False

If enabled, diagram is rendered right-to-left.

vertical_choice_separation: int = 1

Vertical space between nodes in a choice() block.

vertical_choice_separation_outer: int = 1

Vertical space between nodes in a choice() block, if it contains another choice block.

vertical_seq_separation: int = 1

Vertical space between nodes in a stack() block.

vertical_seq_separation_outer: int = 1

Vertical space between nodes in a stack() block, if it appears outside of any choice block.

class syntax_diagrams.EndClass(*values)

Controls how diagram start and end look like.

COMPLEX = 'COMPLEX'

A T-shaped ending with vertical line doubled.

Complex

SIMPLE = 'SIMPLE'

A simple T-shaped ending.

Simple

class syntax_diagrams.ArrowStyle(*values)

Arrow shapes for SVG diagrams.

BARB = 'BARB'

An error that consists of two lines.

node

HARPOON = 'HARPOON'

Half of a triangle arrow.

node

HARPOON_UP = 'HARPOON_UP'

Another half of a triangle arrow.

node

NONE = 'NONE'

Arrows are not rendered.

node

STEALTH = 'STEALTH'

Pointier triangle arrows.

node

TRIANGLE = 'TRIANGLE'

Simple triangle arrows.

node

Errors

class syntax_diagrams.LoadingError

Indicates incorrect diagram value.