Skip to content

type_bridge.typeql.annotations

annotations

Shared TypeQL annotation formatting utilities.

This module centralizes the formatting logic for TypeQL annotations to avoid duplication across the codebase.

format_card_annotation 

format_card_annotation(min_val, max_val)

Format a @card(min..max) annotation string.

Parameters:

Name Type Description Default
min_val int | None

Minimum cardinality (None means unspecified, defaults to 0)

 required
max_val int | None

Maximum cardinality (None means unbounded)

 required

Returns:

Type Description
str | None

Formatted annotation string like "@card(1..5)" or "@card(2..)",
str | None

or None if both min and max are None.

Examples:

>>> format_card_annotation(1, 5)
'@card(1..5)'
>>> format_card_annotation(2, None)
'@card(2..)'
>>> format_card_annotation(0, 1)
'@card(0..1)'
>>> format_card_annotation(None, None)
None
Source code in type_bridge/typeql/annotations.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def format_card_annotation(
    min_val: int | None,
    max_val: int | None,
) -> str | None:
    """Format a @card(min..max) annotation string.

    Args:
        min_val: Minimum cardinality (None means unspecified, defaults to 0)
        max_val: Maximum cardinality (None means unbounded)

    Returns:
        Formatted annotation string like "@card(1..5)" or "@card(2..)",
        or None if both min and max are None.

    Examples:
        >>> format_card_annotation(1, 5)
        '@card(1..5)'
        >>> format_card_annotation(2, None)
        '@card(2..)'
        >>> format_card_annotation(0, 1)
        '@card(0..1)'
        >>> format_card_annotation(None, None)
        None
    """
    if min_val is None and max_val is None:
        return None

    min_v = min_val if min_val is not None else 0
    if max_val is None:
        return f"@card({min_v}..)"
    return f"@card({min_v}..{max_val})"

format_type_annotations 

format_type_annotations(*, abstract=False, independent=False)

Format type-level annotations (@abstract, @independent).

Parameters:

Name Type Description Default
abstract bool

Whether to include @abstract annotation

 False
independent bool

Whether to include @independent annotation

 False

Returns:

Type Description
list[str]

List of annotation strings (may be empty)

Examples:

>>> format_type_annotations(abstract=True)
['@abstract']
>>> format_type_annotations(abstract=True, independent=True)
['@abstract', '@independent']
>>> format_type_annotations()
[]
Source code in type_bridge/typeql/annotations.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def format_type_annotations(
    *,
    abstract: bool = False,
    independent: bool = False,
) -> list[str]:
    """Format type-level annotations (@abstract, @independent).

    Args:
        abstract: Whether to include @abstract annotation
        independent: Whether to include @independent annotation

    Returns:
        List of annotation strings (may be empty)

    Examples:
        >>> format_type_annotations(abstract=True)
        ['@abstract']
        >>> format_type_annotations(abstract=True, independent=True)
        ['@abstract', '@independent']
        >>> format_type_annotations()
        []
    """
    annotations = []
    if abstract:
        annotations.append("@abstract")
    if independent:
        annotations.append("@independent")
    return annotations