Diagrams and components

c4.diagrams.core.BaseDiagramElement

Base class for any object that belongs to a diagram.

Provides access to the current diagram context and allows attaching structured properties (e.g. key-value tables).

Source code in c4/diagrams/core.py

class BaseDiagramElement:
    """
    Base class for any object that belongs to a diagram.

    Provides access to the current diagram context and allows
    attaching structured properties (e.g. key-value tables).
    """

    _diagram: Diagram

    def __init__(self) -> None:
        """
        Initializes the element and adds it to the current diagram context.
        """
        self._diagram = current_diagram()
        self._contribute_to_diagram()
        self.properties = DiagramElementProperties()

    def _contribute_to_diagram(self) -> None:
        self._diagram.add_base_element(self)

    def set_property_header(self, *args: str) -> Self:
        """
        Sets the column headers for the element's property table.

        This must be called before adding any property rows.

        Args:
            *args: Column names to use as the property header.

        Returns:
            The updated diagram element.

        Raises:
            ValueError: If properties were already added before setting
                the header.
        """
        if not args:
            raise ValueError("The header cannot be empty")

        if self.properties.properties:
            raise ValueError(
                "Cannot change header after properties have been added. "
                "Set the header before calling add_property()."
            )

        self.properties.header = list(args)

        return self

    def without_property_header(self) -> Self:
        """
        Disables the rendering of the header row in the property table.

        Returns:
            The updated diagram element.
        """
        self.properties.show_header = False

        return self

    def add_property(self, *args: str) -> Self:
        """
        Adds a row to the property table.

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

        Args:
            *args: Values for each column in the property row.

        Returns:
            The updated diagram element.

        Raises:
            ValueError: If the number of values does not match the
                header length.
        """
        if len(args) != len(self.properties.header):
            raise ValueError(
                "The number of values does not match the header length"
            )

        self.properties.properties.append(list(args))

        return self

set_property_header

set_property_header(*args: str) -> Self

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

This must be called before adding any property rows.

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 properties were already added before setting the header.

Source code in c4/diagrams/core.py

def set_property_header(self, *args: str) -> Self:
    """
    Sets the column headers for the element's property table.

    This must be called before adding any property rows.

    Args:
        *args: Column names to use as the property header.

    Returns:
        The updated diagram element.

    Raises:
        ValueError: If properties were already added before setting
            the header.
    """
    if not args:
        raise ValueError("The header cannot be empty")

    if self.properties.properties:
        raise ValueError(
            "Cannot change header after properties have been added. "
            "Set the header before calling add_property()."
        )

    self.properties.header = list(args)

    return self

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.

Source code in c4/diagrams/core.py

def without_property_header(self) -> Self:
    """
    Disables the rendering of the header row in the property table.

    Returns:
        The updated diagram element.
    """
    self.properties.show_header = False

    return self

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.

Source code in c4/diagrams/core.py

def add_property(self, *args: str) -> Self:
    """
    Adds a row to the property table.

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

    Args:
        *args: Values for each column in the property row.

    Returns:
        The updated diagram element.

    Raises:
        ValueError: If the number of values does not match the
            header length.
    """
    if len(args) != len(self.properties.header):
        raise ValueError(
            "The number of values does not match the header length"
        )

    self.properties.properties.append(list(args))

    return self

c4.diagrams.core.Element

Bases: BaseDiagramElement, ABC

Base class for all C4 elements (e.g. Person, System, Container, Component).

Elements are automatically registered in the current diagram context.

Source code in c4/diagrams/core.py

class Element(BaseDiagramElement, abc.ABC):
    """
    Base class for all C4 elements (e.g. Person, System, Container, Component).

    Elements are automatically registered in the current diagram context.
    """

    _diagram: Diagram

    alias: str
    label: str

    def __init__(
        self,
        label: str | Required = not_provided,
        description: str = "",
        sprite: str = "",
        tags: str = "",
        link: str = "",
        type_: str = "",
        alias: str | EmptyStr = empty,
    ) -> None:
        """
        Initialize a new diagram element. Automatically adds the element to the
        current diagram.

        Args:
            label: Display name for the element. Required.
            description: Optional description text.
            sprite: Optional sprite/icon reference for rendering.
            tags: Optional comma-separated tags for grouping/styling.
            link: Optional URL associated with the element.
            type_: Optional custom type or stereotype label.
            alias: Unique identifier for the element. If not provided, it is
                autogenerated from the label.

        Raises:
            ValueError: If `label` is not provided.
        """
        self.label = self._check_label(label)
        self.alias = self._check_alias(alias, self.label)
        self.sprite = sprite
        self.type = type_
        self.tags = tags
        self.link = link

        self.description = description
        self.base_shape = ""
        self.technology = ""

        super().__init__()

    def __rshift__(self, other: Any) -> Any:
        """
        Enables:
          - Self >> "label" >> Element2   (pending relationship)
          - Self >> Element2 | "label"    (draft for later '| "label"')
        """
        if isinstance(other, str):
            # self >> "label" >> element2
            return Relationship(label=other, from_element=self)

        if isinstance(other, Element):
            # Draft for: self >> element2 | "label"
            return _EdgeDraft(source=self, destination=other)

        return NotImplemented

    def __lshift__(self, other: Any) -> Any:
        """
        Enables:
          - Element2 << "label" << Self   (pending relationship)
          - Element2 << self | "label"      (draft for later '| "label"')
        """
        if isinstance(other, str):
            # element1 << "label" << element2
            return Relationship(label=other, to_element=self)

        if isinstance(other, Element):
            # Draft for: element1 >> element2 | "label"
            return _EdgeDraft(source=other, destination=self)

        return NotImplemented

    def __rrshift__(self, other: Any) -> Any:
        """
        Enables: [Relationship(...), ...] >> Element.
        """
        if isinstance(other, list) and all(
            isinstance(r, Relationship) for r in other
        ):
            return [r._connect(r.from_element, destination=self) for r in other]

        return NotImplemented  # pragma: no cover

    def __rlshift__(self, other: Any) -> Any:
        """
        Enables: Element << [Relationship(...), ...].
        """
        if isinstance(other, list) and all(
            isinstance(r, Relationship) for r in other
        ):
            return [
                r._connect(source=self, destination=r.to_element) for r in other
            ]

        return NotImplemented  # pragma: no cover

    def _check_label(self, label: str | Required) -> str:
        if label is not_provided:
            raise ValueError("The 'label' argument is required")

        return cast(str, label)

    def _check_alias(self, alias: str | EmptyStr, label: str) -> str:
        if alias is empty:
            alias = self._generate_alias(label)

        return cast(str, alias)

    @override
    def _contribute_to_diagram(self) -> None:
        self._diagram.add(self)

    def uses(
        self,
        other: Element,
        label: str,
        relationship_type: RelationshipType = RelationshipType.REL,
        **kwargs: Any,
    ) -> Relationship:
        """
        Declare that this element uses another.

        Args:
            other: The element being used.
            label: Description of the interaction.
            relationship_type: Type of arrow to use.
            kwargs: Optional relationship kwargs.

        Returns:
            The created relationship.
        """
        relationship_class = Relationship.get_relationship_by_type(
            relationship_type
        )
        return relationship_class(
            from_element=self,
            to_element=other,
            label=label,
            **kwargs,
        )

    def used_by(
        self,
        other: Element,
        label: str,
        relationship_type: RelationshipType = RelationshipType.REL,
        **kwargs: Any,
    ) -> Relationship:
        """
        Declare that another element uses this element.

        Args:
            other: The element that uses this element.
            label: Description of the interaction.
            relationship_type: Type of arrow to use.
            kwargs: Optional relationship kwargs.

        Returns:
            The created relationship.
        """
        relationship_class = Relationship.get_relationship_by_type(
            relationship_type
        )
        return relationship_class(
            from_element=other,
            to_element=self,
            label=label,
            **kwargs,
        )

    def _generate_alias(self, label: str) -> str:
        alias = label.lower().replace(" ", "_").replace("-", "_")
        return alias + "_" + uuid4().hex[:4]

    @override
    def __str__(self) -> str:
        """Returns the string representation of the element."""
        cls_name = self.__class__.__name__
        return f"{cls_name}(alias={self.alias!r}, label={self.label!r})"

__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.

Source code in c4/diagrams/core.py

def __init__(
    self,
    label: str | Required = not_provided,
    description: str = "",
    sprite: str = "",
    tags: str = "",
    link: str = "",
    type_: str = "",
    alias: str | EmptyStr = empty,
) -> None:
    """
    Initialize a new diagram element. Automatically adds the element to the
    current diagram.

    Args:
        label: Display name for the element. Required.
        description: Optional description text.
        sprite: Optional sprite/icon reference for rendering.
        tags: Optional comma-separated tags for grouping/styling.
        link: Optional URL associated with the element.
        type_: Optional custom type or stereotype label.
        alias: Unique identifier for the element. If not provided, it is
            autogenerated from the label.

    Raises:
        ValueError: If `label` is not provided.
    """
    self.label = self._check_label(label)
    self.alias = self._check_alias(alias, self.label)
    self.sprite = sprite
    self.type = type_
    self.tags = tags
    self.link = link

    self.description = description
    self.base_shape = ""
    self.technology = ""

    super().__init__()

uses

uses(
    other: Element,
    label: str,
    relationship_type: RelationshipType = REL,
    **kwargs: Any,
) -> Relationship

Declare that this element uses another.

Parameters:

Name	Type	Description	Default
other	Element	The element being used.	required
label	str	Description of the interaction.	required
relationship_type	RelationshipType	Type of arrow to use.	REL
kwargs	Any	Optional relationship kwargs.	{}

Returns:

Type	Description
Relationship	The created relationship.

Source code in c4/diagrams/core.py

def uses(
    self,
    other: Element,
    label: str,
    relationship_type: RelationshipType = RelationshipType.REL,
    **kwargs: Any,
) -> Relationship:
    """
    Declare that this element uses another.

    Args:
        other: The element being used.
        label: Description of the interaction.
        relationship_type: Type of arrow to use.
        kwargs: Optional relationship kwargs.

    Returns:
        The created relationship.
    """
    relationship_class = Relationship.get_relationship_by_type(
        relationship_type
    )
    return relationship_class(
        from_element=self,
        to_element=other,
        label=label,
        **kwargs,
    )

used_by

used_by(
    other: Element,
    label: str,
    relationship_type: RelationshipType = REL,
    **kwargs: Any,
) -> Relationship

Declare that another element uses this element.

Parameters:

Name	Type	Description	Default
other	Element	The element that uses this element.	required
label	str	Description of the interaction.	required
relationship_type	RelationshipType	Type of arrow to use.	REL
kwargs	Any	Optional relationship kwargs.	{}

Returns:

Type	Description
Relationship	The created relationship.

Source code in c4/diagrams/core.py

def used_by(
    self,
    other: Element,
    label: str,
    relationship_type: RelationshipType = RelationshipType.REL,
    **kwargs: Any,
) -> Relationship:
    """
    Declare that another element uses this element.

    Args:
        other: The element that uses this element.
        label: Description of the interaction.
        relationship_type: Type of arrow to use.
        kwargs: Optional relationship kwargs.

    Returns:
        The created relationship.
    """
    relationship_class = Relationship.get_relationship_by_type(
        relationship_type
    )
    return relationship_class(
        from_element=other,
        to_element=self,
        label=label,
        **kwargs,
    )

c4.diagrams.core.ElementWithTechnology

Bases: Element

Base class for elements that define a technology field.

Source code in c4/diagrams/core.py

class ElementWithTechnology(Element):
    """
    Base class for elements that define a `technology` field.
    """

    def __init__(
        self,
        label: str | Required = not_provided,
        description: str = "",
        technology: str = "",
        sprite: str = "",
        tags: str = "",
        link: str = "",
        alias: str | EmptyStr = empty,
    ) -> None:
        """
        Initialize a new diagram element.

        Args:
            label: Display name for the element. Required.
            description: Optional description text.
            technology: Optional technology.
            sprite: Optional sprite/icon reference for rendering.
            tags: Optional comma-separated tags for grouping/styling.
            link: Optional URL associated with the element.
            alias: Unique identifier for the element. If not provided, it is
                autogenerated from the label.
        """
        super().__init__(
            alias=alias,
            label=label,
            description=description,
            sprite=sprite,
            tags=tags,
            link=link,
        )

        self.technology = technology

__init__

__init__(
    label: str | Required = not_provided,
    description: str = "",
    technology: str = "",
    sprite: str = "",
    tags: str = "",
    link: 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.	''
technology	str	Optional technology.	''
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.	''
alias	str | EmptyStr	Unique identifier for the element. If not provided, it is autogenerated from the label.	empty

Source code in c4/diagrams/core.py

def __init__(
    self,
    label: str | Required = not_provided,
    description: str = "",
    technology: str = "",
    sprite: str = "",
    tags: str = "",
    link: str = "",
    alias: str | EmptyStr = empty,
) -> None:
    """
    Initialize a new diagram element.

    Args:
        label: Display name for the element. Required.
        description: Optional description text.
        technology: Optional technology.
        sprite: Optional sprite/icon reference for rendering.
        tags: Optional comma-separated tags for grouping/styling.
        link: Optional URL associated with the element.
        alias: Unique identifier for the element. If not provided, it is
            autogenerated from the label.
    """
    super().__init__(
        alias=alias,
        label=label,
        description=description,
        sprite=sprite,
        tags=tags,
        link=link,
    )

    self.technology = technology

c4.diagrams.core.Boundary

Bases: Element

Represents a boundary element that groups other elements.

Boundaries can be nested, and manage their own child elements.

Source code in c4/diagrams/core.py

class Boundary(Element):
    """
    Represents a boundary element that groups other elements.

    Boundaries can be nested, and manage their own child elements.
    """

    def __init__(
        self,
        label: str | Required = not_provided,
        description: str = "",
        type_: str = "",
        tags: str = "",
        link: str = "",
        alias: str | EmptyStr = empty,
    ) -> None:
        """
        Initialize a new boundary element.

        Args:
            label: Human-readable name for the boundary. Required.
            description: Optional description.
            type_: Optional stereotype or visual marker.
            tags: Optional comma-separated tags for styling or grouping.
            link: Optional hyperlink associated with the boundary.
            alias: Unique identifier for the boundary.
                If not provided, one is autogenerated.

        Notes:
            - If the boundary is created within another boundary context, it is
              added as a nested boundary.
            - Otherwise, it is added directly to the current diagram.
        """
        self._parent = get_boundary()

        super().__init__(
            label=label,
            alias=alias,
            description=description,
            type_=type_,
            tags=tags,
            link=link,
        )

        self._elements: list[Element] = []
        self._relationships: list[Relationship] = []
        self._boundaries: list[Boundary] = []

    @override
    def _contribute_to_diagram(self) -> None:
        if self._parent:
            self._parent.add_boundary(self)
        else:
            self._diagram.add_boundary(self)

    @property
    def elements(self) -> list[Element]:
        """
        Returns the list of diagram elements added to this boundary.

        Returns:
            Child elements grouped under this boundary.
        """
        return self._elements

    @property
    def boundaries(self) -> list[Boundary]:
        """
        Returns the list of nested boundaries inside this boundary.

        Returns:
            Child boundaries nested within this boundary.
        """
        return self._boundaries

    @property
    def relationships(self) -> list[Relationship]:
        """
        Returns all relationships defined in the boundary.
        """
        return self._relationships

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

        Returns:
            The boundary instance now active as context.
        """
        set_boundary(self)
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_value: BaseException | None,
        traceback: TracebackType | None,
    ) -> None:
        """
        Exit the boundary context and restore the previous boundary.
        """
        set_boundary(self._parent)

    def add(self, element: _TElement) -> _TElement:
        """
        Add a diagram element to this boundary.

        Args:
            element: The element to add.

        Returns:
            The added element.
        """
        self._elements.append(element)

        return element

    def add_boundary(self, boundary: _TBoundary) -> _TBoundary:
        """
        Add a nested boundary to this boundary.

        Args:
            boundary: The boundary to add.

        Returns:
            The added boundary.
        """
        self._boundaries.append(boundary)

        return boundary

    def add_relationship(self, relationship: _TRelationship) -> _TRelationship:
        """
        Add a relationship between elements.

        Args:
            relationship: The relationship to add.

        Returns:
            The added relationship.
        """
        self._relationships.append(relationship)

        return relationship

__init__

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

Parameters:

Name	Type	Description	Default
label	str | Required	Human-readable name for the boundary. Required.	not_provided
description	str	Optional description.	''
type_	str	Optional stereotype or visual marker.	''
tags	str	Optional comma-separated tags for styling or grouping.	''
link	str	Optional hyperlink associated with the boundary.	''
alias	str | EmptyStr	Unique identifier for the boundary. If not provided, one is autogenerated.	empty

Notes

• If the boundary is created within another boundary context, it is added as a nested boundary.
• Otherwise, it is added directly to the current diagram.

Source code in c4/diagrams/core.py

def __init__(
    self,
    label: str | Required = not_provided,
    description: str = "",
    type_: str = "",
    tags: str = "",
    link: str = "",
    alias: str | EmptyStr = empty,
) -> None:
    """
    Initialize a new boundary element.

    Args:
        label: Human-readable name for the boundary. Required.
        description: Optional description.
        type_: Optional stereotype or visual marker.
        tags: Optional comma-separated tags for styling or grouping.
        link: Optional hyperlink associated with the boundary.
        alias: Unique identifier for the boundary.
            If not provided, one is autogenerated.

    Notes:
        - If the boundary is created within another boundary context, it is
          added as a nested boundary.
        - Otherwise, it is added directly to the current diagram.
    """
    self._parent = get_boundary()

    super().__init__(
        label=label,
        alias=alias,
        description=description,
        type_=type_,
        tags=tags,
        link=link,
    )

    self._elements: list[Element] = []
    self._relationships: list[Relationship] = []
    self._boundaries: list[Boundary] = []

elements property

elements: list[Element]

Returns the list of diagram elements added to this boundary.

Returns:

Type	Description
list[Element]	Child elements grouped under this boundary.

boundaries property

boundaries: list[Boundary]

Returns the list of nested boundaries inside this boundary.

Returns:

Type	Description
list[Boundary]	Child boundaries nested within this boundary.

relationships property

relationships: list[Relationship]

Returns all relationships defined in the boundary.

__enter__

__enter__() -> Self

Enter the boundary context.

Returns:

Type	Description
Self	The boundary instance now active as context.

Source code in c4/diagrams/core.py

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

    Returns:
        The boundary instance now active as context.
    """
    set_boundary(self)
    return self

__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None

Exit the boundary context and restore the previous boundary.

Source code in c4/diagrams/core.py

def __exit__(
    self,
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None:
    """
    Exit the boundary context and restore the previous boundary.
    """
    set_boundary(self._parent)

c4.diagrams.core.RelationshipType

Bases: StrEnum

Enum representing different types of relationships between diagram elements.

Source code in c4/diagrams/core.py

@unique
class RelationshipType(StrEnum):
    """
    Enum representing different types of relationships between
    diagram elements.
    """

    REL = "REL"
    BI_REL = "BI_REL"
    REL_BACK = "REL_BACK"
    REL_NEIGHBOR = "REL_NEIGHBOR"
    BI_REL_NEIGHBOR = "BI_REL_NEIGHBOR"
    REL_BACK_NEIGHBOR = "REL_BACK_NEIGHBOR"
    REL_D = "REL_D"
    REL_DOWN = "REL_DOWN"
    BI_REL_D = "BI_REL_D"
    BI_REL_DOWN = "BI_REL_DOWN"
    REL_U = "REL_U"
    REL_UP = "REL_UP"
    BI_REL_U = "BI_REL_U"
    BI_REL_UP = "BI_REL_UP"
    REL_L = "REL_L"
    REL_LEFT = "REL_LEFT"
    BI_REL_L = "BI_REL_L"
    BI_REL_LEFT = "BI_REL_LEFT"
    REL_R = "REL_R"
    REL_RIGHT = "REL_RIGHT"
    BI_REL_R = "BI_REL_R"
    BI_REL_RIGHT = "BI_REL_RIGHT"
    SEQUENCE_DIAGRAM_MESSAGE = "SEQUENCE_DIAGRAM_MESSAGE"

c4.diagrams.core.Relationship

Bases: BaseDiagramElement

Represents a connection between two elements.

Supports fluent chaining using >> and << operators, and subclass registration for each RelationshipType.

Source code in c4/diagrams/core.py

class Relationship(BaseDiagramElement):
    """
    Represents a connection between two elements.

    Supports fluent chaining using `>>` and `<<` operators, and
    subclass registration for each `RelationshipType`.
    """

    __relationship_by_type: ClassVar[
        dict[RelationshipType, type[Relationship]]
    ] = {}

    relationship_type: RelationshipType = RelationshipType.REL

    def __init__(
        self,
        label: str,
        description: str = "",
        technology: str = "",
        sprite: str = "",
        tags: str = "",
        link: str = "",
        index: str | BaseIndex | None = None,
        from_element: Element | None = None,
        to_element: Element | None = None,
        relationship_type: RelationshipType | None = None,
    ) -> None:
        """
        Initialize a relationship between two elements.

        Args:
            label: The label shown on the relationship edge.
            description: Additional details about the relationship.
            technology: The technology used in the communication.
            sprite: Optional sprite to represent the relationship.
            tags: Comma-separated tags for styling or grouping.
            link: URL link associated with the relationship.
            index: Index associated with the relationship.
            from_element: The source element. Optional.
            to_element: The destination element. Optional.
            relationship_type: Type of the relationship.
                Defaults to the class-level `relationship_type`.

        Notes:
            If both `from_element` and `to_element` are provided,
            the relationship will be registered in the current
            diagram immediately.
        """
        self.from_element = from_element
        self.to_element = to_element
        self.label = label
        self.technology = technology
        self.description = description
        self.sprite = sprite
        self.tags = tags
        self.link = link
        self.index = index

        self.relationship_type = relationship_type or self.relationship_type

        super().__init__()

    @override
    def __init_subclass__(cls, *args: Any, **kwargs: Any) -> None:
        """
        Registers the relationship subclass under its unique
        `relationship_type`.
        """
        super().__init_subclass__(*args, **kwargs)

        relationship_type = getattr(cls, "relationship_type", None)
        if (
            relationship_type is None
            or relationship_type in cls.__relationship_by_type
        ):
            raise TypeError(
                f"Please provide an unique `relationship_type` for this"
                f" class {cls.__name__}"
            )

        cls.__relationship_by_type[relationship_type] = cls

    def __rshift__(
        self, other: Element | list[Element]
    ) -> Relationship | list[Relationship]:
        """Implements Self >> Element and Self >> [Element]."""
        self._ensure_not_completed()

        return self._connect(source=self.from_element, destination=other)

    def __lshift__(
        self, other: Element | list[Element]
    ) -> Relationship | list[Relationship]:
        """Implements Self << Element and Self << [Element]."""
        self._ensure_not_completed()

        return self._connect(source=other, destination=self.to_element)

    def __rrshift__(
        self, other: Element | list[Element]
    ) -> Relationship | list[Relationship]:
        """Called for [Element] >> Self or Element >> Self."""
        self._ensure_not_completed()

        return self._connect(source=other, destination=self.to_element)

    def __rlshift__(
        self, other: Element | list[Element]
    ) -> Relationship | list[Relationship]:
        """Called for [Element] << Self or Element << Self."""
        self._ensure_not_completed()

        return self._connect(source=self.from_element, destination=other)

    def _connect(
        self,
        source: Element | list[Element] | None,
        destination: Element | list[Element] | None,
    ) -> Relationship | list[Relationship]:
        self._ensure_not_completed()

        if not source and not destination:
            raise ValueError("Either source or destination must be provided")

        if isinstance(source, list) and isinstance(destination, list):
            raise ValueError(  # noqa: TRY004
                "Either source or destination must be a single element"
            )

        if isinstance(source, list):
            from_iter = source
            to_iter: Iterable[Element] = repeat(destination)  # type: ignore[arg-type]
        elif isinstance(destination, list):
            from_iter: Iterable[Element] = repeat(source)  # type: ignore[no-redef]
            to_iter = destination
        else:
            # Both are single elements
            return self.copy(from_element=source, to_element=destination)

        return [
            self.copy(from_element=src, to_element=dst)
            for src, dst in zip(from_iter, to_iter, strict=False)
        ]

    def _ensure_not_completed(self) -> None:
        if self.from_element and self.to_element:
            raise ValueError(
                "Cannot modify relationship with both specified elements"
            )

    @override
    def _contribute_to_diagram(self) -> None:
        if self.from_element and self.to_element:
            self._diagram.add_relationship(self)

    def get_attrs(self) -> dict[str, Any]:
        """
        Returns a dictionary of all relationship attributes.
        """
        return {
            "from_element": self.from_element,
            "to_element": self.to_element,
            "label": self.label,
            "technology": self.technology,
            "description": self.description,
            "sprite": self.sprite,
            "tags": self.tags,
            "link": self.link,
            "index": self.index,
            "relationship_type": self.relationship_type,
        }

    def copy(self, **overrides: Any) -> Relationship:
        """
        Clone the relationship, optionally overriding fields.
        """
        attrs = {**self.get_attrs(), **overrides}

        return Relationship(**attrs)

    @classmethod
    def get_relationship_by_type(
        cls, relationship_type: RelationshipType
    ) -> type[Relationship]:
        """
        Retrieve the relationship class associated with the
        given RelationshipType.

        Args:
            relationship_type: The enum value representing the
                type of relationship.

        Returns:
            The corresponding Relationship subclass.

        Raises:
            KeyError: If no class is registered for the provided
                relationship type.
        """
        return cls.__relationship_by_type[relationship_type]

__init__

__init__(
    label: str,
    description: str = "",
    technology: str = "",
    sprite: str = "",
    tags: str = "",
    link: str = "",
    index: str | BaseIndex | None = None,
    from_element: Element | None = None,
    to_element: Element | None = None,
    relationship_type: RelationshipType | None = None,
) -> None

Parameters:

Name	Type	Description	Default
label	str	The label shown on the relationship edge.	required
description	str	Additional details about the relationship.	''
technology	str	The technology used in the communication.	''
sprite	str	Optional sprite to represent the relationship.	''
tags	str	Comma-separated tags for styling or grouping.	''
link	str	URL link associated with the relationship.	''
index	str | BaseIndex | None	Index associated with the relationship.	None
from_element	Element | None	The source element. Optional.	None
to_element	Element | None	The destination element. Optional.	None
relationship_type	RelationshipType | None	Type of the relationship. Defaults to the class-level relationship_type.	None

Notes

If both from_element and to_element are provided, the relationship will be registered in the current diagram immediately.

Source code in c4/diagrams/core.py

def __init__(
    self,
    label: str,
    description: str = "",
    technology: str = "",
    sprite: str = "",
    tags: str = "",
    link: str = "",
    index: str | BaseIndex | None = None,
    from_element: Element | None = None,
    to_element: Element | None = None,
    relationship_type: RelationshipType | None = None,
) -> None:
    """
    Initialize a relationship between two elements.

    Args:
        label: The label shown on the relationship edge.
        description: Additional details about the relationship.
        technology: The technology used in the communication.
        sprite: Optional sprite to represent the relationship.
        tags: Comma-separated tags for styling or grouping.
        link: URL link associated with the relationship.
        index: Index associated with the relationship.
        from_element: The source element. Optional.
        to_element: The destination element. Optional.
        relationship_type: Type of the relationship.
            Defaults to the class-level `relationship_type`.

    Notes:
        If both `from_element` and `to_element` are provided,
        the relationship will be registered in the current
        diagram immediately.
    """
    self.from_element = from_element
    self.to_element = to_element
    self.label = label
    self.technology = technology
    self.description = description
    self.sprite = sprite
    self.tags = tags
    self.link = link
    self.index = index

    self.relationship_type = relationship_type or self.relationship_type

    super().__init__()

get_attrs

get_attrs() -> dict[str, Any]

Returns a dictionary of all relationship attributes.

Source code in c4/diagrams/core.py

def get_attrs(self) -> dict[str, Any]:
    """
    Returns a dictionary of all relationship attributes.
    """
    return {
        "from_element": self.from_element,
        "to_element": self.to_element,
        "label": self.label,
        "technology": self.technology,
        "description": self.description,
        "sprite": self.sprite,
        "tags": self.tags,
        "link": self.link,
        "index": self.index,
        "relationship_type": self.relationship_type,
    }

copy

copy(**overrides: Any) -> Relationship

Clone the relationship, optionally overriding fields.

Source code in c4/diagrams/core.py

def copy(self, **overrides: Any) -> Relationship:
    """
    Clone the relationship, optionally overriding fields.
    """
    attrs = {**self.get_attrs(), **overrides}

    return Relationship(**attrs)

get_relationship_by_type classmethod

get_relationship_by_type(
    relationship_type: RelationshipType,
) -> type[Relationship]

Retrieve the relationship class associated with the given RelationshipType.

Parameters:

Name	Type	Description	Default
relationship_type	RelationshipType	The enum value representing the type of relationship.	required

Returns:

Type	Description
type[Relationship]	The corresponding Relationship subclass.

Raises:

Type	Description
KeyError	If no class is registered for the provided relationship type.

Source code in c4/diagrams/core.py

@classmethod
def get_relationship_by_type(
    cls, relationship_type: RelationshipType
) -> type[Relationship]:
    """
    Retrieve the relationship class associated with the
    given RelationshipType.

    Args:
        relationship_type: The enum value representing the
            type of relationship.

    Returns:
        The corresponding Relationship subclass.

    Raises:
        KeyError: If no class is registered for the provided
            relationship type.
    """
    return cls.__relationship_by_type[relationship_type]

Note

You can find a detailed description of the different relationship types in the corresponding sections of the documentation.

c4.diagrams.core.Diagram

Represents a complete C4 diagram.

Manages the registration and layout of elements, boundaries, relationships, and renderers.

Source code in c4/diagrams/core.py

class Diagram:
    """
    Represents a complete C4 diagram.

    Manages the registration and layout of elements, boundaries,
    relationships, and renderers.
    """

    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] = {}

    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,
        exc_value: BaseException | None,
        traceback: TracebackType | None,
    ) -> None:
        """
        Exit the diagram context and clear the current diagram.
        """
        set_diagram(None)

    def _check_alias(self, element: Element) -> None:
        alias = element.alias

        if existing_element := self.__aliases.get(alias):
            raise ValueError(f"Duplicated alias {alias!r}: {existing_element}")

        if not alias.isidentifier():
            raise ValueError(
                f"Alias {alias!r} of {element} must be a valid identifier"
            )

        self.__aliases[alias] = element

    @property
    def title(self) -> str | None:
        """
        Returns the title of the diagram.
        """
        return self._title

    @property
    def elements(self) -> list[Element]:
        """
        Returns a list of top-level elements in the diagram.
        """
        return self._elements

    @property
    def base_elements(self) -> list[BaseDiagramElement]:
        """
        Returns a list of base elements of the diagram that should be rendered
        in a strict order.
        """
        return self._base_elements

    @property
    def boundaries(self) -> list[Boundary]:
        """
        Returns all top-level boundaries in the diagram.
        """
        return self._boundaries

    @property
    def layouts(self) -> list[Layout]:
        """
        Returns all layout constraints defined for the diagram.
        """
        return self._layouts

    @property
    def relationships(self) -> list[Relationship]:
        """
        Returns all relationships defined in the diagram.
        """
        return self._relationships

    def add_base_element(
        self, element: BaseDiagramElement
    ) -> BaseDiagramElement:
        """
        Add a base element to the diagram.

        rgs:
            element: The base element to add.

        Returns:
            The added base element.
        """
        self._base_elements.append(element)

        return element

    def add(self, element: _TElement) -> _TElement:
        """
        Add an element to the diagram or the currently active boundary.

        Args:
            element: The element to add.

        Returns:
            The added element.
        """
        self._check_alias(element)

        if boundary := get_boundary():
            boundary.add(element)
        else:
            self._elements.append(element)

        return element

    def add_boundary(self, boundary: _TBoundary) -> _TBoundary:
        """
        Add a top-level boundary to the diagram.

        Args:
            boundary: The boundary to add.

        Returns:
            The added boundary.
        """
        self._boundaries.append(boundary)

        return boundary

    def add_relationship(self, relationship: _TRelationship) -> _TRelationship:
        """
        Add a relationship between elements.

        Args:
            relationship: The relationship to add.

        Returns:
            The added relationship.
        """
        if boundary := get_boundary():
            boundary.add_relationship(relationship)
        else:
            self._relationships.append(relationship)

        return relationship

    def add_layout(self, layout: _TLayout) -> _TLayout:
        """
        Add a layout constraint between elements.

        Args:
            layout: The layout constraint to add.

        Returns:
            The added layout.
        """
        self._layouts.append(layout)

        return layout

    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)

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

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

__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.

__enter__

__enter__() -> Self

Enter the diagram context.

Automatically sets this diagram as the current active diagram.

Returns:

Type	Description
Self	The current instance.

Source code in c4/diagrams/core.py

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

__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None

Exit the diagram context and clear the current diagram.

Source code in c4/diagrams/core.py

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

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.core.Layout

Bases: BaseDiagramElement, ABC

Represents a relative layout constraint between two elements.

Source code in c4/diagrams/core.py

class Layout(BaseDiagramElement, abc.ABC):
    """
    Represents a relative layout constraint between two elements.
    """

    layout_type: LayoutType

    def __init__(
        self,
        from_element: Element,
        to_element: Element,
    ) -> None:
        """
        Initialize a layout constraint between two elements.

        Args:
            from_element: The element to be positioned.
            to_element: The element to position relative to.

        Raises:
            ValueError: If `layout_type` is not provided and the subclass
                does not define a class-level ``layout_type``.
        """
        self.from_element = from_element
        self.to_element = to_element

        if not hasattr(self, "layout_type"):
            raise ValueError(
                "`layout_type` must be provided explicitly or defined as "
                "a class attribute"
            )

        super().__init__()

    @override
    def _contribute_to_diagram(self) -> None:
        self._diagram.add_layout(self)

__init__

__init__(
    from_element: Element, to_element: Element
) -> None

Parameters:

Name	Type	Description	Default
from_element	Element	The element to be positioned.	required
to_element	Element	The element to position relative to.	required

Raises:

Type	Description
ValueError	If layout_type is not provided and the subclass does not define a class-level layout_type.

Source code in c4/diagrams/core.py

def __init__(
    self,
    from_element: Element,
    to_element: Element,
) -> None:
    """
    Initialize a layout constraint between two elements.

    Args:
        from_element: The element to be positioned.
        to_element: The element to position relative to.

    Raises:
        ValueError: If `layout_type` is not provided and the subclass
            does not define a class-level ``layout_type``.
    """
    self.from_element = from_element
    self.to_element = to_element

    if not hasattr(self, "layout_type"):
        raise ValueError(
            "`layout_type` must be provided explicitly or defined as "
            "a class attribute"
        )

    super().__init__()

Note

You can find a detailed description of the different layout types in the corresponding sections of the documentation.