System Context Diagram¶

def __init__(
    self,
    title: str | None = None,
    default_renderer: BaseRenderer[Diagram] | None = None,
    render_options: RenderOptions | None = None,
) -> None:
    """
    Initialize a new diagram.

    Args:
        title: Optional title to label the diagram.
        default_renderer: Optional default renderer to use for rendering.
        render_options: Optional renderer-specific options.
    """
    self._title = title
    self._default_renderer = default_renderer
    self._elements: list[Element] = []
    self._boundaries: list[Boundary] = []
    self._relationships: list[Relationship] = []
    self._render_options = render_options

    self.__elements_by_alias: dict[str, Element] = {}
    self.__elements_by_label: dict[str, list[Element]] = {}
    self.__alias_generator = AliasGenerator()
    self.__referenced_elements: list[str] = []
    self.__ordered_elements: list[BaseDiagramElement] = []

def get_element_by_alias(self, alias: str) -> Element | None:
    """Return the element with the given alias."""
    return self.__elements_by_alias.get(alias)

def get_elements_by_label(self, label: str) -> list[Element]:
    """Return all elements that share the given label."""
    return self.__elements_by_label.get(label, [])

def generate_alias(
    self,
    label: str,
    alias: str | None = None,
    fallback_prefix: str | None = None,
) -> str:
    """
    Generate a unique alias.

    Args:
        label: Source label used to derive the alias when `alias` is None.
        alias: Optional explicit alias. If provided, it must be unique.
        fallback_prefix: Prefix to use when the label cannot produce a
            valid alias.

    Returns:
        A unique alias string.

    Raises:
        ValueError: If alias already exists.
    """
    return self.__alias_generator.generate(label, alias, fallback_prefix)

def __enter__(self) -> Self:
    """
    Enter the diagram context.

    Automatically sets this diagram as the current active diagram.

    Returns:
        The current instance.
    """
    set_diagram(self)
    return self

def __exit__(
    self,
    exc_type: type[BaseException] | None,  # type: ignore[valid-type]
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None:
    """
    Exit the diagram context and clear the current diagram.
    """
    set_diagram(None)

def as_plantuml(self, **kwargs: Any) -> str:
    """
    Render the diagram using the built-in PlantUML renderer.

    Args:
        **kwargs: Optional keyword arguments passed to the
            [PlantUML renderer][c4.renderers.PlantUMLRenderer].

    Returns:
        The rendered PlantUML code.
    """
    renderer = self._build_plantuml_renderer(**kwargs)

    return self.render(renderer)

def as_mermaid(self, **kwargs: Any) -> str:
    """
    Render the diagram using the built-in Mermaid renderer.

    Args:
        **kwargs: Optional keyword arguments passed to the
            [Mermaid renderer][c4.renderers.MermaidRenderer].

    Returns:
        The rendered Mermaid code.
    """
    renderer = self._build_mermaid_renderer(**kwargs)

    return self.render(renderer)

def render(self, renderer: BaseRenderer[Diagram] | None = None) -> str:
    """
    Render the diagram to a string using the given or default renderer.

    Args:
        renderer: Optional renderer to override the default.

    Returns:
        The rendered diagram output.

    Raises:
        ValueError: If no renderer is provided and no default
            renderer is set.
    """
    renderer = renderer or self._default_renderer
    if not renderer:
        raise ValueError("No renderer provided and no default_renderer set")

    return renderer.render(self)

def save(
    self,
    path: str | Path,
    renderer: BaseRenderer[Diagram] | None = None,
) -> None:
    """
    Render and save the diagram to a file.

    Args:
        path: Target path to save the rendered output.
        renderer: Optional renderer to override the default.
    """
    path = Path(path)

    path.parent.mkdir(parents=True, exist_ok=True)

    content = self.render(renderer)

    path.write_text(content, encoding="utf-8")

def save_as_plantuml(self, path: str | Path, **kwargs: Any) -> None:
    """
    Render and save the diagram using the PlantUML renderer.

    Args:
        path: Target file path.
        **kwargs: Optional kwargs passed to the
            [PlantUML renderer][c4.renderers.PlantUMLRenderer].
    """
    renderer = self._build_plantuml_renderer(**kwargs)

    return self.save(path, renderer=renderer)

def save_as_mermaid(self, path: str | Path, **kwargs: Any) -> None:
    """
    Render and save the diagram using the Mermaid renderer.

    Args:
        path: Target file path.
        **kwargs: Optional kwargs passed to the
            [Mermaid renderer][c4.renderers.MermaidRenderer].
    """
    renderer = self._build_mermaid_renderer(**kwargs)

    return self.save(path, renderer=renderer)

def set_render_options(
    self,
    *,
    plantuml: Maybe[PlantUMLRenderOptions] = MISSING,
    mermaid: Maybe[MermaidRenderOptions] = MISSING,
) -> Self:
    """
    Patch renderer-specific options for this diagram.

    Omitted renderer keys are left unchanged. Passing `None` clears that
    renderer's diagram-level defaults.
    """
    if self._render_options is None:
        from c4.renderers import RenderOptions

        self._render_options = RenderOptions()

    if plantuml is not MISSING:
        self._render_options.plantuml = plantuml

    if mermaid is not MISSING:
        self._render_options.mermaid = mermaid

    return self

def __init__(
    self,
    title: str | None = None,
    default_renderer: BaseRenderer[Diagram] | None = None,
    render_options: RenderOptions | None = None,
) -> None:
    """
    Initialize a new diagram.

    Args:
        title: Optional title to label the diagram.
        default_renderer: Optional default renderer to use for rendering.
        render_options: Optional renderer-specific options.
    """
    self._title = title
    self._default_renderer = default_renderer
    self._elements: list[Element] = []
    self._boundaries: list[Boundary] = []
    self._relationships: list[Relationship] = []
    self._render_options = render_options

    self.__elements_by_alias: dict[str, Element] = {}
    self.__elements_by_label: dict[str, list[Element]] = {}
    self.__alias_generator = AliasGenerator()
    self.__referenced_elements: list[str] = []
    self.__ordered_elements: list[BaseDiagramElement] = []

def get_element_by_alias(self, alias: str) -> Element | None:
    """Return the element with the given alias."""
    return self.__elements_by_alias.get(alias)

def get_elements_by_label(self, label: str) -> list[Element]:
    """Return all elements that share the given label."""
    return self.__elements_by_label.get(label, [])

def generate_alias(
    self,
    label: str,
    alias: str | None = None,
    fallback_prefix: str | None = None,
) -> str:
    """
    Generate a unique alias.

    Args:
        label: Source label used to derive the alias when `alias` is None.
        alias: Optional explicit alias. If provided, it must be unique.
        fallback_prefix: Prefix to use when the label cannot produce a
            valid alias.

    Returns:
        A unique alias string.

    Raises:
        ValueError: If alias already exists.
    """
    return self.__alias_generator.generate(label, alias, fallback_prefix)

def __enter__(self) -> Self:
    """
    Enter the diagram context.

    Automatically sets this diagram as the current active diagram.

    Returns:
        The current instance.
    """
    set_diagram(self)
    return self

def __exit__(
    self,
    exc_type: type[BaseException] | None,  # type: ignore[valid-type]
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None:
    """
    Exit the diagram context and clear the current diagram.
    """
    set_diagram(None)

def as_plantuml(self, **kwargs: Any) -> str:
    """
    Render the diagram using the built-in PlantUML renderer.

    Args:
        **kwargs: Optional keyword arguments passed to the
            [PlantUML renderer][c4.renderers.PlantUMLRenderer].

    Returns:
        The rendered PlantUML code.
    """
    renderer = self._build_plantuml_renderer(**kwargs)

    return self.render(renderer)

def as_mermaid(self, **kwargs: Any) -> str:
    """
    Render the diagram using the built-in Mermaid renderer.

    Args:
        **kwargs: Optional keyword arguments passed to the
            [Mermaid renderer][c4.renderers.MermaidRenderer].

    Returns:
        The rendered Mermaid code.
    """
    renderer = self._build_mermaid_renderer(**kwargs)

    return self.render(renderer)

def render(self, renderer: BaseRenderer[Diagram] | None = None) -> str:
    """
    Render the diagram to a string using the given or default renderer.

    Args:
        renderer: Optional renderer to override the default.

    Returns:
        The rendered diagram output.

    Raises:
        ValueError: If no renderer is provided and no default
            renderer is set.
    """
    renderer = renderer or self._default_renderer
    if not renderer:
        raise ValueError("No renderer provided and no default_renderer set")

    return renderer.render(self)

def save(
    self,
    path: str | Path,
    renderer: BaseRenderer[Diagram] | None = None,
) -> None:
    """
    Render and save the diagram to a file.

    Args:
        path: Target path to save the rendered output.
        renderer: Optional renderer to override the default.
    """
    path = Path(path)

    path.parent.mkdir(parents=True, exist_ok=True)

    content = self.render(renderer)

    path.write_text(content, encoding="utf-8")

def save_as_plantuml(self, path: str | Path, **kwargs: Any) -> None:
    """
    Render and save the diagram using the PlantUML renderer.

    Args:
        path: Target file path.
        **kwargs: Optional kwargs passed to the
            [PlantUML renderer][c4.renderers.PlantUMLRenderer].
    """
    renderer = self._build_plantuml_renderer(**kwargs)

    return self.save(path, renderer=renderer)

def save_as_mermaid(self, path: str | Path, **kwargs: Any) -> None:
    """
    Render and save the diagram using the Mermaid renderer.

    Args:
        path: Target file path.
        **kwargs: Optional kwargs passed to the
            [Mermaid renderer][c4.renderers.MermaidRenderer].
    """
    renderer = self._build_mermaid_renderer(**kwargs)

    return self.save(path, renderer=renderer)

def set_render_options(
    self,
    *,
    plantuml: Maybe[PlantUMLRenderOptions] = MISSING,
    mermaid: Maybe[MermaidRenderOptions] = MISSING,
) -> Self:
    """
    Patch renderer-specific options for this diagram.

    Omitted renderer keys are left unchanged. Passing `None` clears that
    renderer's diagram-level defaults.
    """
    if self._render_options is None:
        from c4.renderers import RenderOptions

        self._render_options = RenderOptions()

    if plantuml is not MISSING:
        self._render_options.plantuml = plantuml

    if mermaid is not MISSING:
        self._render_options.mermaid = mermaid

    return self