System Context Diagram¶

c4.diagrams.system_context.SystemContextDiagram ¶

Bases: Diagram

Source code in c4/diagrams/system_context.py

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

    type: ClassVar[DiagramType] = DiagramType.SYSTEM_CONTEXT_DIAGRAM

init ¶

__init__(
    title: str | None = None,
    default_renderer: BaseRenderer[Diagram] | None = None,
    render_options: RenderOptions | 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`
`render_options`	`RenderOptions \| None`	Optional renderer-specific options.	`None`

Source code in c4/diagrams/core.py

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._layouts: list[Layout] = []
    self._base_elements: list[BaseDiagramElement] = []
    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] = []

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 PlantUML 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
            [PlantUML renderer][c4.renderers.PlantUMLRenderer].

    Returns:
        The rendered PlantUML code.
    """
    renderer = self._build_plantuml_renderer(**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][c4.renderers.PlantUMLRenderer].
    """
    renderer = self._build_plantuml_renderer(**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).
    """

    type: ClassVar[DiagramType] = DiagramType.SYSTEM_LANDSCAPE_DIAGRAM

init ¶

__init__(
    title: str | None = None,
    default_renderer: BaseRenderer[Diagram] | None = None,
    render_options: RenderOptions | 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`
`render_options`	`RenderOptions \| None`	Optional renderer-specific options.	`None`

Source code in c4/diagrams/core.py

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._layouts: list[Layout] = []
    self._base_elements: list[BaseDiagramElement] = []
    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] = []

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 PlantUML 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
            [PlantUML renderer][c4.renderers.PlantUMLRenderer].

    Returns:
        The rendered PlantUML code.
    """
    renderer = self._build_plantuml_renderer(**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][c4.renderers.PlantUMLRenderer].
    """
    renderer = self._build_plantuml_renderer(**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: Required[str] = REQUIRED,
    description: str | None = None,
    sprite: str | None = None,
    tags: list[str] | None = None,
    link: str | None = None,
    type_: str | None = None,
    alias: Maybe[str] = MISSING,
) -> None

Parameters:

Name	Type	Description	Default
`label`	`Required[str]`	Display name for the element. Required.	`REQUIRED`
`description`	`str \| None`	Optional description text.	`None`
`sprite`	`str \| None`	Optional sprite/icon reference for rendering.	`None`
`tags`	`list[str] \| None`	Optional tags for styling or grouping.	`None`
`link`	`str \| None`	Optional URL associated with the element.	`None`
`type_`	`str \| None`	Optional custom type or stereotype label.	`None`
`alias`	`Maybe[str]`	Unique identifier for the element. If not provided, it is autogenerated from the label.	`MISSING`

Raises:

Type	Description
`ValueError`	If `label` is not provided.

set_property_header ¶

set_property_header(*args: str) -> Self

Sets the column headers for the element's property table.

This must be called either before adding any property rows, or the header length must match the number of values.

Parameters:

Name	Type	Description	Default
`*args`	`str`	Column names to use as the property header.	`()`

Returns:

Type	Description
`Self`	The updated diagram element.

Raises:

Type	Description
`ValueError`	If header length does not match the number of values.

without_property_header ¶

without_property_header() -> Self

Disables the rendering of the header row in the property table.

Returns:

Type	Description
`Self`	The updated diagram element.

add_property ¶

add_property(*args: str) -> Self

Adds a row to the property table.

The number of arguments must match the number of header columns.

Parameters:

Name	Type	Description	Default
`*args`	`str`	Values for each column in the property row.	`()`

Returns:

Type	Description
`Self`	The updated diagram element.

Raises:

Type	Description
`ValueError`	If the number of values does not match the header length.

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: Required[str] = REQUIRED,
    description: str | None = None,
    sprite: str | None = None,
    tags: list[str] | None = None,
    link: str | None = None,
    type_: str | None = None,
    base_shape: str | None = None,
    alias: Maybe[str] = MISSING,
) -> None

Parameters:

Name	Type	Description	Default
`label`	`Required[str]`	Human-readable name.	`REQUIRED`
`description`	`str \| None`	Optional description for the system.	`None`
`sprite`	`str \| None`	Optional icon or sprite.	`None`
`tags`	`list[str] \| None`	Optional tags for styling or grouping.	`None`
`link`	`str \| None`	Optional hyperlink associated with the element.	`None`
`type_`	`str \| None`	Custom type/stereotype string.	`None`
`base_shape`	`str \| None`	Optional override for visual shape.	`None`
`alias`	`Maybe[str]`	Unique identifier for the system.	`MISSING`

set_property_header ¶

set_property_header(*args: str) -> Self

Sets the column headers for the element's property table.

This must be called either before adding any property rows, or the header length must match the number of values.

Parameters:

Name	Type	Description	Default
`*args`	`str`	Column names to use as the property header.	`()`

Returns:

Type	Description
`Self`	The updated diagram element.

Raises:

Type	Description
`ValueError`	If header length does not match the number of values.

without_property_header ¶

without_property_header() -> Self

Disables the rendering of the header row in the property table.

Returns:

Type	Description
`Self`	The updated diagram element.

add_property ¶

add_property(*args: str) -> Self

Adds a row to the property table.

The number of arguments must match the number of header columns.

Parameters:

Name	Type	Description	Default
`*args`	`str`	Values for each column in the property row.	`()`

Returns:

Type	Description
`Self`	The updated diagram element.

Raises:

Type	Description
`ValueError`	If the number of values does not match the header length.

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.

init ¶

__init__(
    label: Required[str] = REQUIRED,
    description: str | None = None,
    tags: list[str] | None = None,
    link: str | None = None,
    alias: Maybe[str] = MISSING,
) -> None

Parameters:

Name	Type	Description	Default
`label`	`Required[str]`	Display name.	`REQUIRED`
`description`	`str \| None`	Optional description.	`None`
`tags`	`list[str] \| None`	Optional tags for styling or grouping.	`None`
`link`	`str \| None`	Optional hyperlink.	`None`
`alias`	`Maybe[str]`	Unique identifier for the boundary.	`MISSING`

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: Required[str] = REQUIRED,
    description: str | None = None,
    tags: list[str] | None = None,
    link: str | None = None,
    alias: Maybe[str] = MISSING,
) -> None

Parameters:

Name	Type	Description	Default
`label`	`Required[str]`	Display name.	`REQUIRED`
`description`	`str \| None`	Optional description.	`None`
`tags`	`list[str] \| None`	Optional tags for styling or grouping.	`None`
`link`	`str \| None`	Optional hyperlink.	`None`
`alias`	`Maybe[str]`	Unique identifier for the boundary.	`MISSING`

set_property_header ¶

set_property_header(*args: str) -> Self

Sets the column headers for the element's property table.

This must be called either before adding any property rows, or the header length must match the number of values.

Parameters:

Name	Type	Description	Default
`*args`	`str`	Column names to use as the property header.	`()`

Returns:

Type	Description
`Self`	The updated diagram element.

Raises:

Type	Description
`ValueError`	If header length does not match the number of values.

without_property_header ¶

without_property_header() -> Self

Disables the rendering of the header row in the property table.

Returns:

Type	Description
`Self`	The updated diagram element.

add_property ¶

add_property(*args: str) -> Self

Adds a row to the property table.

The number of arguments must match the number of header columns.

Parameters:

Name	Type	Description	Default
`*args`	`str`	Values for each column in the property row.	`()`

Returns:

Type	Description
`Self`	The updated diagram element.

Raises:

Type	Description
`ValueError`	If the number of values does not match the header length.

System Context Diagram¶

c4.diagrams.system_context.SystemContextDiagram ¶

__init__ ¶

title property ¶

elements property ¶

base_elements property ¶

boundaries property ¶

layouts property ¶

relationships property ¶

as_plantuml ¶

render ¶

save ¶

save_as_plantuml ¶

c4.diagrams.system_context.SystemLandscapeDiagram ¶

__init__ ¶

title property ¶

elements property ¶

base_elements property ¶

boundaries property ¶

layouts property ¶

relationships property ¶

as_plantuml ¶

render ¶

save ¶

save_as_plantuml ¶

c4.diagrams.system_context.Person ¶

__init__ ¶

set_property_header ¶

without_property_header ¶

add_property ¶

c4.diagrams.system_context.PersonExt ¶

c4.diagrams.system_context.System ¶

__init__ ¶

set_property_header ¶

without_property_header ¶

add_property ¶

c4.diagrams.system_context.SystemExt ¶

c4.diagrams.system_context.SystemDb ¶

c4.diagrams.system_context.SystemDbExt ¶

c4.diagrams.system_context.SystemQueue ¶

c4.diagrams.system_context.SystemQueueExt ¶

c4.diagrams.system_context.SystemBoundary ¶

__init__ ¶

c4.diagrams.system_context.EnterpriseBoundary ¶

__init__ ¶

set_property_header ¶

without_property_header ¶

add_property ¶

init ¶

title `property` ¶

elements `property` ¶

base_elements `property` ¶

boundaries `property` ¶

layouts `property` ¶

relationships `property` ¶

init ¶

title `property` ¶

elements `property` ¶

base_elements `property` ¶

boundaries `property` ¶

layouts `property` ¶

relationships `property` ¶

init ¶

init ¶

init ¶

init ¶