System Context Diagram

c4.diagrams.system_context.SystemContextDiagram

Bases: Diagram

Represents a C4 System Context Diagram.

Source code in c4/diagrams/system_context.py

class SystemContextDiagram(Diagram):
    """
    Represents a [C4 System Context Diagram](https://c4model.com/diagrams/system-context).
    """

__init__

__init__(
    title: str | None = None,
    default_renderer: BaseRenderer[Diagram] | None = None,
) -> None

Parameters:

Name	Type	Description	Default
title	str | None	Optional title to label the diagram.	None
default_renderer	BaseRenderer[Diagram] | None	Optional default renderer to use for rendering.	None

Source code in c4/diagrams/core.py

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

    Args:
        title: Optional title to label the diagram.
        default_renderer: Optional default renderer to use for rendering.
    """
    self._title = title
    self._default_renderer = default_renderer
    self._elements: list[Element] = []
    self._boundaries: list[Boundary] = []
    self._relationships: list[Relationship] = []
    self._layouts: list[Layout] = []
    self._base_elements: list[BaseDiagramElement] = []

    self.__aliases: dict[str, Element] = {}

title property

title: str | None

Returns the title of the diagram.

elements property

elements: list[Element]

Returns a list of top-level elements in the diagram.

base_elements property

base_elements: list[BaseDiagramElement]

Returns a list of base elements of the diagram that should be rendered in a strict order.

boundaries property

boundaries: list[Boundary]

Returns all top-level boundaries in the diagram.

layouts property

layouts: list[Layout]

Returns all layout constraints defined for the diagram.

relationships property

relationships: list[Relationship]

Returns all relationships defined in the diagram.

as_plantuml

as_plantuml(**kwargs: Any) -> str

Render the diagram using the built-in PlantUML renderer.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Optional keyword arguments passed to the renderer.	{}

Returns:

Type	Description
str	The rendered PlantUML code.

Source code in c4/diagrams/core.py

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

    Args:
        **kwargs: Optional keyword arguments passed to the renderer.

    Returns:
        The rendered PlantUML code.
    """
    from c4.renderers import PlantUMLRenderer

    renderer = PlantUMLRenderer(**kwargs)
    return self.render(renderer)

render

render(
    renderer: BaseRenderer[Diagram] | None = None,
) -> str

Render the diagram to a string using the given or default renderer.

Parameters:

Name	Type	Description	Default
renderer	BaseRenderer[Diagram] | None	Optional renderer to override the default.	None

Returns:

Type	Description
str	The rendered diagram output.

Raises:

Type	Description
ValueError	If no renderer is provided and no default renderer is set.

Source code in c4/diagrams/core.py

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)

save

save(
    path: str | Path,
    renderer: BaseRenderer[Diagram] | None = None,
) -> None

Render and save the diagram to a file.

Parameters:

Name	Type	Description	Default
path	str | Path	Target path to save the rendered output.	required
renderer	BaseRenderer[Diagram] | None	Optional renderer to override the default.	None

Source code in c4/diagrams/core.py

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")

save_as_plantuml

save_as_plantuml(path: str | Path, **kwargs: Any) -> None

Render and save the diagram using the PlantUML renderer.

Parameters:

Name	Type	Description	Default
path	str | Path	Target file path.	required
**kwargs	Any	Optional kwargs passed to the PlantUML renderer.	{}

Source code in c4/diagrams/core.py

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.
    """
    from c4.renderers import PlantUMLRenderer

    renderer = PlantUMLRenderer(**kwargs)
    return self.save(path, renderer=renderer)

c4.diagrams.system_context.SystemLandscapeDiagram

Bases: Diagram

Represents a C4 System Landscape Diagram.

Source code in c4/diagrams/system_context.py

class SystemLandscapeDiagram(Diagram):
    """
    Represents a [C4 System Landscape Diagram](https://c4model.com/diagrams/system-landscape).
    """

__init__

__init__(
    title: str | None = None,
    default_renderer: BaseRenderer[Diagram] | None = None,
) -> None

Parameters:

Name	Type	Description	Default
title	str | None	Optional title to label the diagram.	None
default_renderer	BaseRenderer[Diagram] | None	Optional default renderer to use for rendering.	None

Source code in c4/diagrams/core.py

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

    Args:
        title: Optional title to label the diagram.
        default_renderer: Optional default renderer to use for rendering.
    """
    self._title = title
    self._default_renderer = default_renderer
    self._elements: list[Element] = []
    self._boundaries: list[Boundary] = []
    self._relationships: list[Relationship] = []
    self._layouts: list[Layout] = []
    self._base_elements: list[BaseDiagramElement] = []

    self.__aliases: dict[str, Element] = {}

title property

title: str | None

Returns the title of the diagram.

elements property

elements: list[Element]

Returns a list of top-level elements in the diagram.

base_elements property

base_elements: list[BaseDiagramElement]

Returns a list of base elements of the diagram that should be rendered in a strict order.

boundaries property

boundaries: list[Boundary]

Returns all top-level boundaries in the diagram.

layouts property

layouts: list[Layout]

Returns all layout constraints defined for the diagram.

relationships property

relationships: list[Relationship]

Returns all relationships defined in the diagram.

as_plantuml

as_plantuml(**kwargs: Any) -> str

Render the diagram using the built-in PlantUML renderer.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Optional keyword arguments passed to the renderer.	{}

Returns:

Type	Description
str	The rendered PlantUML code.

Source code in c4/diagrams/core.py

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

    Args:
        **kwargs: Optional keyword arguments passed to the renderer.

    Returns:
        The rendered PlantUML code.
    """
    from c4.renderers import PlantUMLRenderer

    renderer = PlantUMLRenderer(**kwargs)
    return self.render(renderer)

render

render(
    renderer: BaseRenderer[Diagram] | None = None,
) -> str

Render the diagram to a string using the given or default renderer.

Parameters:

Name	Type	Description	Default
renderer	BaseRenderer[Diagram] | None	Optional renderer to override the default.	None

Returns:

Type	Description
str	The rendered diagram output.

Raises:

Type	Description
ValueError	If no renderer is provided and no default renderer is set.

Source code in c4/diagrams/core.py

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)

save

save(
    path: str | Path,
    renderer: BaseRenderer[Diagram] | None = None,
) -> None

Render and save the diagram to a file.

Parameters:

Name	Type	Description	Default
path	str | Path	Target path to save the rendered output.	required
renderer	BaseRenderer[Diagram] | None	Optional renderer to override the default.	None

Source code in c4/diagrams/core.py

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")

save_as_plantuml

save_as_plantuml(path: str | Path, **kwargs: Any) -> None

Render and save the diagram using the PlantUML renderer.

Parameters:

Name	Type	Description	Default
path	str | Path	Target file path.	required
**kwargs	Any	Optional kwargs passed to the PlantUML renderer.	{}

Source code in c4/diagrams/core.py

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.
    """
    from c4.renderers import PlantUMLRenderer

    renderer = PlantUMLRenderer(**kwargs)
    return self.save(path, renderer=renderer)

c4.diagrams.system_context.Person

Bases: Element

Represents a person (actor) interacting with the system.

__init__

__init__(
    label: str | Required = not_provided,
    description: str = "",
    sprite: str = "",
    tags: str = "",
    link: str = "",
    type_: str = "",
    alias: str | EmptyStr = empty,
) -> None

Parameters:

Name	Type	Description	Default
label	str | Required	Display name for the element. Required.	not_provided
description	str	Optional description text.	''
sprite	str	Optional sprite/icon reference for rendering.	''
tags	str	Optional comma-separated tags for grouping/styling.	''
link	str	Optional URL associated with the element.	''
type_	str	Optional custom type or stereotype label.	''
alias	str | EmptyStr	Unique identifier for the element. If not provided, it is autogenerated from the label.	empty

Raises:

Type	Description
ValueError	If label is not provided.

c4.diagrams.system_context.PersonExt

Bases: Person

Represents an external person (actor) interacting with the system.

c4.diagrams.system_context.System

Bases: Element

Represents a software system in the C4 model.

__init__

__init__(
    label: str | Required = not_provided,
    description: str = "",
    sprite: str = "",
    tags: str = "",
    link: str = "",
    type_: str = "",
    base_shape: str = "",
    alias: str | EmptyStr = empty,
) -> None

Parameters:

Name	Type	Description	Default
label	str | Required	Human-readable name.	not_provided
description	str	Optional description for the system.	''
sprite	str	Optional icon or sprite.	''
tags	str	Comma-separated tags.	''
link	str	Optional hyperlink associated with the element.	''
type_	str	Custom type/stereotype string.	''
base_shape	str	Optional override for visual shape.	''
alias	str | EmptyStr	Unique identifier for the system.	empty

c4.diagrams.system_context.SystemExt

Bases: System

Represents an external system interacting with the system under consideration.

c4.diagrams.system_context.SystemDb

Bases: Element

Represents a system database (storage-centric system) in the C4 model.

c4.diagrams.system_context.SystemDbExt

Bases: Element

Represents an external system database.

c4.diagrams.system_context.SystemQueue

Bases: Element

Represents a message queue or streaming system in the C4 model.

c4.diagrams.system_context.SystemQueueExt

Bases: Element

Represents an external system queue or messaging system.

c4.diagrams.system_context.SystemBoundary

Bases: Boundary

Represents the boundary around a specific system.

Used to group containers or components that belong to a single system.

c4.diagrams.system_context.EnterpriseBoundary

Bases: Boundary

Represents an enterprise boundary in a system landscape or context diagram.

Used to group systems and actors that belong to the same organizational unit.

__init__

__init__(
    label: str | Required = not_provided,
    description: str = "",
    tags: str = "",
    link: str = "",
    alias: str | EmptyStr = empty,
) -> None

Parameters:

Name	Type	Description	Default
label	str | Required	Display name.	not_provided
description	str	Optional description.	''
tags	str	Optional comma-separated tags.	''
link	str	Optional hyperlink.	''
alias	str | EmptyStr	Unique identifier for the boundary.	empty