API Reference

svblock can be used as a Python library in addition to the CLI. This page documents the public API.

Data Model

Port direction enum for SystemVerilog module ports.

class svblock.model.port_types.PortDirection(*values)[source]

Direction of a module port.

INPUT = 'input'
OUTPUT = 'output'
INOUT = 'inout'
INTERFACE = 'interface'
REF = 'ref'

Intermediate representation for parsed SystemVerilog modules.

class svblock.model.module_ir.PortDef(name, direction, port_type='logic', is_bus=False, bus_range=None, is_interface=False, modport=None, group=None, has_clock_marker=False, has_active_low_marker=False)[source]

Definition of a single module port.

Parameters:
name: str
direction: PortDirection
port_type: str = 'logic'
is_bus: bool = False
bus_range: tuple[str, str] | None = None
is_interface: bool = False
modport: str | None = None
group: str | None = None
has_clock_marker: bool = False
has_active_low_marker: bool = False
class svblock.model.module_ir.ParamDef(name, param_type='integer', default_value=None, is_localparam=False)[source]

Definition of a single module parameter.

Parameters:

  • name (str)

  • param_type (str)

  • default_value (str | None)

  • is_localparam (bool)

name: str
param_type: str = 'integer'
default_value: str | None = None
is_localparam: bool = False
class svblock.model.module_ir.GroupDef(name, label=None, port_names=<factory>)[source]

A named group of ports for visual grouping in the diagram.

Parameters:
name: str
label: str | None = None
port_names: list[str]
class svblock.model.module_ir.ModuleIR(name, file_path, ports=<factory>, params=<factory>, groups=<factory>)[source]

Intermediate representation of a parsed SystemVerilog module.

Parameters:
name: str
file_path: str
ports: list[PortDef]
params: list[ParamDef]
groups: list[GroupDef]

Parser

SystemVerilog parsing and annotation extraction.

exception svblock.parser.ParseError[source]

Raised when a SystemVerilog file cannot be parsed.

svblock.parser.extract_module(file_path, module_name, include_paths=None)[source]

Extract a specific module by name from a SystemVerilog file.

Raises:

ParseError: If the file cannot be parsed or the module is not found.

Parameters:
Return type:

ModuleIR

svblock.parser.extract_modules(file_path, include_paths=None)[source]

Parse a SystemVerilog file and return a ModuleIR for each module found.

Args:

file_path: Path to the .sv or .v file. include_paths: Optional directories to search for include files.

Returns:

List of ModuleIR, one per module definition in the file.

Raises:

ParseError: If the file cannot be read or parsed.

Parameters:
Return type:

list[ModuleIR]

Parse // @sym comment annotations from SystemVerilog source files.

svblock.parser.annotation.parse_annotations_from_text(source_text, port_lines)[source]

Parse @sym annotations and associate them with ports by line number.

Args:

source_text: The raw SystemVerilog source text. port_lines: Mapping of port name to its source line number (1-based).

Returns:

Mapping of port name to its annotation key-value pairs.

Parameters:
Return type:

dict[str, dict[str, str]]

svblock.parser.annotation.parse_annotations_from_file(file_path, port_lines)[source]

Parse @sym annotations from a file.

Args:

file_path: Path to the .sv or .v file. port_lines: Mapping of port name to its source line number.

Returns:

Mapping of port name to its annotation key-value pairs.

Parameters:
Return type:

dict[str, dict[str, str]]

Layout

Layout engine: computes box geometry and pin coordinates.

class svblock.layout.engine.PinSide(*values)[source]
LEFT = 'left'
RIGHT = 'right'
class svblock.layout.engine.DecoratorType(*values)[source]
NONE = 'none'
CLOCK = 'clock'
ACTIVE_LOW = 'active_low'
BUS = 'bus'
INTERFACE = 'interface'
INOUT = 'inout'
class svblock.layout.engine.PinRow(port_name: 'str', side: 'PinSide', y: 'float', label_text: 'str', decorator: 'DecoratorType', bus_label: 'str | None' = None, group_name: 'str | None' = None)[source]
Parameters:
port_name: str
side: PinSide
y: float
label_text: str
decorator: DecoratorType
bus_label: str | None = None
group_name: str | None = None
class svblock.layout.engine.GroupSeparator(y: 'float', label: 'str')[source]
Parameters:
y: float
label: str
class svblock.layout.engine.HeaderRect(x: 'float', y: 'float', width: 'float', height: 'float')[source]
Parameters:
x: float
y: float
width: float
height: float
class svblock.layout.engine.LayoutConfig(pin_row_height: 'float' = 20.0, interface_row_height: 'float' = 28.0, group_header_height: 'float' = 18.0, header_base_height: 'float' = 36.0, header_param_line_height: 'float' = 16.0, min_box_width: 'float' = 240.0, box_padding: 'float' = 12.0, pin_label_padding: 'float' = 8.0, pin_stub_length: 'float' = 30.0, decorator_width: 'float' = 12.0, port_font_size: 'float' = 13.0, header_font_size: 'float' = 15.0, group_font_size: 'float' = 11.0, param_font_size: 'float' = 11.0, no_params: 'bool' = False, no_groups: 'bool' = False, no_decorators: 'bool' = False)[source]
Parameters:
pin_row_height: float = 20.0
interface_row_height: float = 28.0
group_header_height: float = 18.0
header_base_height: float = 36.0
header_param_line_height: float = 16.0
min_box_width: float = 240.0
box_padding: float = 12.0
pin_label_padding: float = 8.0
pin_stub_length: float = 30.0
decorator_width: float = 12.0
port_font_size: float = 13.0
header_font_size: float = 15.0
group_font_size: float = 11.0
param_font_size: float = 11.0
no_params: bool = False
no_groups: bool = False
no_decorators: bool = False
class svblock.layout.engine.LayoutSpec(box_x: 'float', box_y: 'float', box_width: 'float', box_height: 'float', header_rect: 'HeaderRect', module_name: 'str', params_text: 'list[str]', pin_rows: 'list[PinRow]' = <factory>, group_separators: 'list[GroupSeparator]' = <factory>, total_width: 'float' = 0.0, total_height: 'float' = 0.0)[source]
Parameters:
box_x: float
box_y: float
box_width: float
box_height: float
header_rect: HeaderRect
module_name: str
params_text: list[str]
pin_rows: list[PinRow]
group_separators: list[GroupSeparator]
total_width: float = 0.0
total_height: float = 0.0
svblock.layout.engine.compute_layout(module, config=None)[source]

Compute the full layout geometry for a module symbol.

Args:

module: A ModuleIR with groups already assigned. config: Layout configuration. Uses defaults if None.

Returns:

A LayoutSpec with all coordinates computed.

Parameters:
Return type:

LayoutSpec

Heuristic port grouping when no @sym annotations are present.

svblock.layout.grouping.apply_grouping(module, *, flat=False)[source]

Assign ports to groups and return a new ModuleIR with groups populated.

Explicit annotation groups (port.group is not None) are preserved. Remaining ports are grouped by heuristic name patterns.

Args:

module: Input ModuleIR (not mutated). flat: If True, put all ports in a single default group.

Returns:

A new ModuleIR with groups fully populated.

Parameters:
Return type:

ModuleIR

Text width measurement for SVG layout sizing.

svblock.layout.text_metrics.measure_text(text, font_size, font_family='monospace')[source]

Measure the rendered width of a text string in SVG user units.

Args:

text: The string to measure. font_size: Font size in SVG user units (pixels). font_family: Either “monospace” or “proportional”.

Returns:

Estimated width in SVG user units.

Parameters:
Return type:

float

Renderer

Pure Python SVG renderer for module symbols.

class svblock.renderer.svg_renderer.RenderOptions(no_decorators: 'bool' = False, no_params: 'bool' = False, standalone: 'bool' = True)[source]
Parameters:
svblock.renderer.svg_renderer.render_svg(layout, theme=None, options=None)[source]

Render a LayoutSpec as an SVG string.

Args:

layout: Computed layout geometry. theme: CSS variable overrides. Merged with DEFAULT_THEME. options: Rendering options.

Returns:

Complete SVG string.

Parameters:
Return type:

str

Built-in themes for svblock SVG output.

Configuration

Configuration and theme loading for svblock.

svblock.config.load_theme(theme_name_or_path)[source]

Load a theme by built-in name or from a file path.

Built-in themes: default, dark, minimal, print. File themes: TOML or YAML files that map CSS variable names to values. Custom values are merged with the default theme (custom overrides).

Args:

theme_name_or_path: Built-in name or path to theme file.

Returns:

Complete theme dict (all CSS variables guaranteed present).

Parameters:

theme_name_or_path (str)

Return type:

dict[str, str]

Exporters

PNG export via cairosvg.

svblock.exporters.png.svg_to_png(svg_content, output_path, scale=2.0)[source]

Convert SVG string to a PNG file.

Args:

svg_content: SVG markup string. output_path: Destination path for the PNG file. scale: Resolution multiplier (default 2x for retina).

Raises:

ImportError: If cairosvg is not installed.

Parameters:
Return type:

None

PDF export via cairosvg.

svblock.exporters.pdf.svg_to_pdf(svg_content, output_path)[source]

Convert SVG string to a PDF file.

Args:

svg_content: SVG markup string. output_path: Destination path for the PDF file.

Raises:

ImportError: If cairosvg is not installed.

Parameters:
Return type:

None

Programmatic Usage

Here is a complete example of using svblock as a library:

from pathlib import Path

from svblock.parser import extract_modules
from svblock.layout.grouping import apply_grouping
from svblock.layout.engine import LayoutConfig, compute_layout
from svblock.renderer.svg_renderer import RenderOptions, render_svg
from svblock.renderer.themes import BUILTIN_THEMES

# Parse a SystemVerilog file
modules = extract_modules(Path("fifo.sv"))
module = modules[0]

# Apply automatic grouping
module = apply_grouping(module)

# Compute layout
config = LayoutConfig()
layout = compute_layout(module, config)

# Render SVG with dark theme
theme = BUILTIN_THEMES["dark"]
options = RenderOptions(standalone=True)
svg_string = render_svg(layout, theme, options)

# Write to file
Path("fifo.svg").write_text(svg_string, encoding="utf-8")