Skip to content

gds_software.common

Shared types, errors, and compilation utilities.

Diagram Kinds

Bases: StrEnum

The six software architecture diagram types.

Source code in packages/gds-software/gds_software/common/types.py 
 6
 7
 8
 9
10
11
12
13
14
class DiagramKind(StrEnum):
    """The six software architecture diagram types."""

    DFD = "dfd"
    STATE_MACHINE = "state_machine"
    COMPONENT = "component"
    C4 = "c4"
    ERD = "erd"
    DEPENDENCY = "dependency"

Errors

Bases: GDSError

Base exception for software architecture DSL errors.

Source code in packages/gds-software/gds_software/common/errors.py 
6
7
class SWError(GDSError):
    """Base exception for software architecture DSL errors."""

Bases: SWError

Raised when a software architecture model fails structural validation.

Source code in packages/gds-software/gds_software/common/errors.py 
10
11
class SWValidationError(SWError):
    """Raised when a software architecture model fails structural validation."""

Bases: SWError

Raised when compilation of a software architecture model fails.

Source code in packages/gds-software/gds_software/common/errors.py 
14
15
class SWCompilationError(SWError):
    """Raised when compilation of a software architecture model fails."""

Compilation Utilities

Compose a list of blocks in parallel.

Source code in packages/gds-software/gds_software/common/compile_utils.py 
17
18
19
20
21
22
def parallel_tier(blocks: list[Block]) -> Block:
    """Compose a list of blocks in parallel."""
    tier: Block = blocks[0]
    for b in blocks[1:]:
        tier = tier | b
    return tier

Build explicit wirings between two tiers based on port token overlap.

For each output port in the first tier, find matching input ports in the second tier (by token intersection). This replaces auto-wiring so we can use explicit StackComposition and bypass the token overlap validator.

Source code in packages/gds-software/gds_software/common/compile_utils.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def build_inter_tier_wirings(
    first_tier_blocks: list[Block],
    second_tier_blocks: list[Block],
) -> list[Wiring]:
    """Build explicit wirings between two tiers based on port token overlap.

    For each output port in the first tier, find matching input ports in the
    second tier (by token intersection). This replaces auto-wiring so we can
    use explicit StackComposition and bypass the token overlap validator.
    """
    wirings: list[Wiring] = []
    for first_block in first_tier_blocks:
        for out_port in first_block.interface.forward_out:
            for second_block in second_tier_blocks:
                for in_port in second_block.interface.forward_in:
                    if out_port.type_tokens & in_port.type_tokens:
                        wirings.append(
                            Wiring(
                                source_block=first_block.name,
                                source_port=out_port.name,
                                target_block=second_block.name,
                                target_port=in_port.name,
                            )
                        )
    return wirings

Compose two tiers sequentially with explicit wiring.

Uses StackComposition directly to bypass the auto-wire token overlap check. If no wirings found, falls back to auto-wiring via >>.

Source code in packages/gds-software/gds_software/common/compile_utils.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def sequential_with_explicit_wiring(
    first: Block,
    second: Block,
    wiring: list[Wiring],
) -> Block:
    """Compose two tiers sequentially with explicit wiring.

    Uses StackComposition directly to bypass the auto-wire token overlap check.
    If no wirings found, falls back to auto-wiring via >>.
    """
    if wiring:
        return StackComposition(
            name=f"{first.name} >> {second.name}",
            first=first,
            second=second,
            wiring=wiring,
        )
    return first >> second