Skip to content

Converters

c4.converters.json.converter.JSONToDiagramConverter

Convert a validated JSON diagram schema into a diagram object.

Diagram elements are created within the diagram/boundary context, so they will be added to the current diagram/boundary automatically.

__init__ 

__init__(data: Mapping[str, Any]) -> None

Parameters:

Name Type Description Default
data Mapping[str, Any]

Parsed diagram payload that matches the expected JSON schema structure.

 required

parse_diagram_backend staticmethod 

parse_diagram_backend(
    data: Mapping[str, Any],
) -> RendererEnum | None

Parse and resolve the diagram backend.

convert 

convert() -> Diagram

Build the full diagram and return the populated instance.

c4.converters.json.converter.diagram_from_dict 

diagram_from_dict(
    data: Mapping[str, Any],
) -> tuple[Diagram, RendererEnum | None]

Build a diagram from a parsed JSON mapping.

c4.converters.json.converter.diagram_backend_from_json 

diagram_backend_from_json(
    src: str | bytes | Path | IO[str] | IO[bytes],
) -> RendererEnum | None

Parse JSON diagram schema and return its declared backend.

This validates the payload with the same schema selection logic used by full JSON diagram conversion, but does not build diagram relationships.

c4.converters.json.converter.diagram_from_json 

diagram_from_json(
    src: str | bytes | Path | IO[str] | IO[bytes],
) -> tuple[Diagram, RendererEnum | None]

Parse JSON into a Diagram.

Parameters:

Name Type Description Default
src str | bytes | Path | IO[str] | IO[bytes]

JSON string/bytes, a Path, or a file-like object.

 required

Raises:

Type Description
ValueError

Invalid JSON or invalid structure/schema.
TypeError

Wrong types in the JSON payload.

c4.converters.python.converter.PythonCodegen

Generate Python DSL code that recreates an existing Diagram.

The generated output is intended to be:

  • Readable: stable ordering, minimal noise, consistent spacing.
  • Executable: contains imports required to run the DSL.
  • Semantically equivalent: recreates the same structure (elements, boundaries, relationships, layouts, and macro-like ordered statements).

Rendering rules / invariants:

  • Scope children are rendered directly from ordered_elements, matching the declaration stream used by runtime renderers.

The codegen relies on __repr__ implementations of DSL objects being valid DSL.

__init__ 

__init__(backend: RendererEnum | None = None) -> None

generate 

generate(diagram: Diagram) -> str

Generate Python DSL that recreates diagram.

Parameters:

Name Type Description Default
diagram Diagram

The diagram instance to serialize into Python DSL.

 required

Returns:

Type Description
str

A Python source string that can be executed to reconstruct
str

the diagram.

c4.converters.python.converter.diagram_to_python_code 

diagram_to_python_code(
    diagram: Diagram, backend: RendererEnum | None = None
) -> str

Convenience helper to generate Python DSL from a diagram.

Parameters:

Name Type Description Default
diagram Diagram

The diagram instance to serialize.

 required
backend RendererEnum | None

Optional rendering backend type.

 None

Returns:

Type Description
str

Python code that recreates the given diagram.