Skip to content

Api Reference

Functions

parse(msg)

Parse a GCN Kafka message from a supported topic.

Parameters:

Name Type Description Default
msg Message

Kafka-style message object with topic() and value() methods. topic() must return the GCN topic string, and value() must return the raw notice bytes.

 required

Returns:

Type Description
Notice

Parsed notice model for the message topic.

Raises:

Type Description
UnsupportedTopicError

If the message topic is not supported.
ParseError

If the topic-specific parser cannot parse or validate the message payload.
FieldParseError

If a topic-specific parser cannot extract a required field from the message payload.
Source code in gcn_parser/parse.py 
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def parse(msg: Message) -> Notice:
    """Parse a GCN Kafka message from a supported topic.

    Args:
        msg: Kafka-style message object with ``topic()`` and ``value()``
            methods. ``topic()`` must return the GCN topic string, and
            ``value()`` must return the raw notice bytes.

    Returns:
        Parsed notice model for the message topic.

    Raises:
        UnsupportedTopicError: If the message topic is not supported.
        ParseError: If the topic-specific parser cannot parse or validate the
            message payload.
        FieldParseError: If a topic-specific parser cannot extract a required
            field from the message payload.
    """
    match msg.topic():
        case Topic.FERMI_GBM_ALERT:
            return parse_fermi_gbm_alert(msg.value())
        case Topic.FERMI_GBM_FIN_POS:
            return parse_fermi_gbm_fin_pos(msg.value())
        case Topic.FERMI_GBM_FLT_POS:
            return parse_fermi_gbm_flt_pos(msg.value())
        case Topic.FERMI_GBM_GND_POS:
            return parse_fermi_gbm_gnd_pos(msg.value())
        case Topic.FERMI_LAT_OFFLINE:
            return parse_fermi_lat_offline(msg.value())
        case Topic.FERMI_LAT_POS_DIAG:
            return parse_fermi_lat_pos_diag(msg.value())
        case Topic.FERMI_LAT_POS_INI:
            return parse_fermi_lat_pos_ini(msg.value())
        case Topic.FERMI_LAT_POS_UPD:
            return parse_fermi_lat_pos_upd(msg.value())
        case Topic.EINSTEIN_PROBE_WXT_ALERT:
            return parse_einstein_probe_wxt(msg.value())
        case Topic.SVOM_ECLAIRS:
            if is_svom_retraction(msg.value()):
                return parse_svom_retraction(msg.value())
            return parse_svom_eclairs(msg.value())
        case Topic.SVOM_GRM:
            if is_svom_retraction(msg.value()):
                return parse_svom_retraction(msg.value())
            return parse_svom_grm_trigger(msg.value())
        case Topic.SVOM_MXT:
            if is_svom_retraction(msg.value()):
                return parse_svom_retraction(msg.value())
            return parse_svom_mxt(msg.value())
        case _:
            raise UnsupportedTopicError(f"Unsupported topic: {msg.topic()}")

supported_topics()

Return a list of GCN Kafka supported topics.

Returns:

Type Description
list[Topic]

List of supported topic enum members. The returned list can be passed directly to Kafka consumers that accept string-like topic values.
Source code in gcn_parser/__init__.py 
13
14
15
16
17
18
19
20
def supported_topics() -> list[Topic]:
    """Return a list of GCN Kafka supported topics.

    Returns:
        List of supported topic enum members. The returned list can be passed
            directly to Kafka consumers that accept string-like topic values.
    """
    return list(Topic)

Classes

Topic

Bases: StrEnum

GCN Kafka topics for which parsing is supported.

Source code in gcn_parser/topics.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class Topic(StrEnum):
    """GCN Kafka topics for which parsing is supported."""

    FERMI_GBM_ALERT: str = "gcn.classic.voevent.FERMI_GBM_ALERT"
    FERMI_GBM_FIN_POS: str = "gcn.classic.voevent.FERMI_GBM_FIN_POS"
    FERMI_GBM_FLT_POS: str = "gcn.classic.voevent.FERMI_GBM_FLT_POS"
    FERMI_GBM_GND_POS: str = "gcn.classic.voevent.FERMI_GBM_GND_POS"
    FERMI_LAT_OFFLINE: str = "gcn.classic.voevent.FERMI_LAT_OFFLINE"
    FERMI_LAT_POS_DIAG: str = "gcn.classic.voevent.FERMI_LAT_POS_DIAG"
    FERMI_LAT_POS_INI: str = "gcn.classic.voevent.FERMI_LAT_POS_INI"
    FERMI_LAT_POS_UPD: str = "gcn.classic.voevent.FERMI_LAT_POS_UPD"

    SVOM_GRM: str = "gcn.notices.svom.voevent.grm"
    SVOM_ECLAIRS: str = "gcn.notices.svom.voevent.eclairs"
    SVOM_MXT: str = "gcn.notices.svom.voevent.mxt"

    EINSTEIN_PROBE_WXT_ALERT: str = "gcn.notices.einstein_probe.wxt.alert"

Exceptions

ParseError

Bases: Exception

Raised when a notice cannot be parsed or validated.

Source code in gcn_parser/exceptions.py 
4
5
6
7
class ParseError(Exception):
    """Raised when a notice cannot be parsed or validated."""

    pass

FieldParseError

Bases: ParseError

Raised when a parser cannot extract a specific notice field.

Source code in gcn_parser/exceptions.py 
10
11
12
13
class FieldParseError(ParseError):
    """Raised when a parser cannot extract a specific notice field."""

    pass

UnsupportedTopicError

Bases: Exception

Raised for unsupported GCN topics.

Source code in gcn_parser/exceptions.py 
16
17
18
19
class UnsupportedTopicError(Exception):
    """Raised for unsupported GCN topics."""

    pass

Mission References

For mission-specific parser and schemas, see: