PlantUML rendering backends

c4.renderers.plantuml.renderer.PlantUMLRenderer

Renderer for converting a Diagram object into PlantUML syntax.

__init__

__init__(
    includes: list[str] | None = None,
    layout_options: LayoutOptions | None = None,
    backend: BasePlantUMLBackend | None = None,
    use_new_c4_style: bool = False,
    *args: Any,
    **kwargs: Any,
)

Parameters:

Name	Type	Description	Default
includes	list[str] | None	A list of PlantUML !include directives to be injected at the beginning of the diagram.	None
layout_options	LayoutOptions | None	Layout configuration that controls diagram rendering behavior, such as direction, spacing, and group alignment.	None
backend	BasePlantUMLBackend | None	Optional PlantUML backend responsible for converting generated PlantUML source into image bytes (e.g. PNG, SVG). If not provided, image rendering is not available.	None
use_new_c4_style	bool	If True, activates the new C4-PlantUML style by injecting the following directive into the generated source: !NEW_C4_STYLE=1	False
*args	Any	Additional positional arguments passed to the base renderer.	()
**kwargs	Any	Additional keyword arguments passed to the base renderer.	{}

render

render(diagram: Diagram) -> str

Render the given Diagram into PlantUML format.

Parameters:

Name	Type	Description	Default
diagram	Diagram	The diagram to render.	required

Returns:

Type	Description
str	A PlantUML-formatted string representing the diagram.

render_bytes

render_bytes(
    diagram: Diagram, *, format: DiagramFormat
) -> bytes

Render a Diagram and return the result as raw bytes.

This method first converts the Diagram into PlantUML source text and then delegates the actual rendering to the configured PlantUML backend.

Parameters:

Name	Type	Description	Default
diagram	Diagram	The diagram instance to render.	required
format	DiagramFormat	Output format of the rendered diagram.	required

Returns:

Type	Description
bytes	The rendered diagram content as raw bytes.

Raises:

Type	Description
PlantUMLBackendConfigurationError	If no PlantUML backend is configured for this renderer.
PlantUMLError	If the underlying PlantUML backend fails to render the diagram.

render_file

render_file(
    diagram: Diagram,
    output_path: str | Path,
    *,
    format: DiagramFormat,
    overwrite: bool = True,
) -> Path

Render a Diagram and write the result to a file.

This method first converts the Diagram into PlantUML source text and then delegates file generation to the configured PlantUML backend.

Parameters:

Name	Type	Description	Default
diagram	Diagram	The diagram instance to render.	required
output_path	str | Path	Path where the rendered diagram should be written.	required
format	DiagramFormat	Output format of the rendered diagram.	required
overwrite	bool	Whether to overwrite the output file if it already exists.	True

Returns:

Type	Description
Path	Path to the written output file.

Raises:

Type	Description
PlantUMLBackendConfigurationError	If no PlantUML backend is configured for this renderer.
FileExistsError	If the output file exists and overwrite is set to False.
PlantUMLError	If the underlying PlantUML backend fails to render or write the diagram.

c4.renderers.plantuml.backends.BasePlantUMLBackend

Generate PlantUML diagrams from plain text.

A generator takes a PlantUML diagram text and produces image bytes (or writes them to a file).

to_bytes abstractmethod

to_bytes(
    diagram: str, *, format: DiagramFormat = PNG
) -> bytes

Generate a PlantUML diagram and return the generated image as bytes.

Parameters:

Name	Type	Description	Default
diagram	str	PlantUML diagram source text.	required
format	DiagramFormat	Output image format (for example, 'svg' or 'png').	PNG

Returns:

Type	Description
bytes	Rendered image content as raw bytes.

Raises:

Type	Description
PlantUMLRenderingError	If rendering fails.
FileNotFoundError	If the required PlantUML backend is not available.

to_file

to_file(
    diagram: str,
    output_path: str | Path,
    *,
    format: DiagramFormat | None = PNG,
    overwrite: bool = True,
) -> Path

Generate a PlantUML diagram and write the generated image to a file.

Parameters:

Name	Type	Description	Default
diagram	str	PlantUML diagram source text.	required
output_path	str | Path	Path where the rendered image should be written.	required
format	DiagramFormat | None	Output image format. If None, the format is inferred from output_path suffix.	PNG
overwrite	bool	Whether to overwrite the output file if it already exists.	True

Returns:

Type	Description
Path	Path to the written output file.

Raises:

Type	Description
ValueError	If format is None and the output path has no suffix.
FileExistsError	If the output file exists and overwrite is False.
PlantUMLRenderingError	If rendering fails.
FileNotFoundError	If the required PlantUML backend is not available.

c4.renderers.plantuml.backends.LocalPlantUMLBackend

Bases: BasePlantUMLBackend

Generate PlantUML diagrams using local PlantUML binary or jar.

Env vars

• PLANTUML_BIN: executable name/path (default: 'plantuml')
• PLANTUML_JAR: path to plantuml.jar

__init__

__init__(
    *,
    plantuml_bin: str | None | _Empty = empty,
    plantuml_jar: Path | None | _Empty = empty,
    java_bin: str | None = None,
    timeout_seconds: float = DEFAULT_RENDERING_TIMEOUT_SECONDS,
    plantuml_args: Sequence[str] = (),
    java_args: Sequence[str] = (),
    env: Mapping[str, str] | None = None,
) -> None

c4.renderers.plantuml.backends.RemotePlantUMLBackend

Bases: BasePlantUMLBackend

Generate PlantUML diagrams using PlantUML server.

Env vars

• PLANTUML_SERVER_URL: PlantUML server path (default: 'https://www.plantuml.com/plantuml')

__init__

__init__(
    *,
    server_url: str | None = None,
    timeout_seconds: float = DEFAULT_RENDERING_TIMEOUT_SECONDS,
) -> None