Welcome to Pigeon’s documentation!¶
Pigeon is a combination of a STOMP client, and a message definition system using Pydantic models. The message definitions can either be defined manually, or Pigeon can search for message definitions via Python entry-points. A template for message definitions is available here. Similarly, there is a template here for creating a Dockerized service using Pigeon.
- class pigeon.Pigeon(service: str, host: str = '127.0.0.1', port: int = 61616, logger: Logger = None, load_topics: bool = True, spawn_threads: bool = False, connection_timeout: float = 10, send_timeout: float = 0, ssl: bool = False, topic_prefix: str = '')¶
A STOMP client with message definitions via Pydantic
This class is a STOMP message client which will automatically serialize and deserialize message data using Pydantic models. Before sending or receiving messages, topics must be “registered”, or in other words, have a Pydantic model associated with each STOMP topic that will be used. This can be done in two ways. One is to use the register_topic(), or register_topics() methods. The other is to have message definitions in a Python package with an entry point defined in the pigeon.msgs group. This entry point should provide a tuple containing a mapping of topics to Pydantic models. Topics defined in this manner will be automatically discovered and loaded at runtime, unless this mechanism is manually disabled.
- connect(username: str = None, password: str = None)¶
Connects to the STOMP server using the provided username and password.
- Args:
username (str, optional): The username to authenticate with. Defaults to None. password (str, optional): The password to authenticate with. Defaults to None.
- Raises:
stomp.exception.ConnectFailedException: If the connection to the server fails.
- disconnect()¶
Disconnect from the STOMP message broker.
- register_topic(topic: str, msg_class: Callable)¶
Register message definition for a given topic.
- Args:
topic: The topic that this message definition applies to. msg_class: The Pydantic model definition of the message.
- register_topics(topics: Dict[str, Callable])¶
Register a number of message definitions for multiple topics.
- Args:
topics: A mapping of topics to Pydantic model message definitions.
- send(topic: str, timeout=Ellipsis, **data)¶
Sends data to the specified topic.
- Args:
topic (str): The topic to send the data to. timeout (float, None): The length of time to attempt to send the
message, or None to try indefinitely. If set to …, the default, the send_timeout value from the client constructor will be used.
**data: Keyword arguments representing the data to be sent.
- Raises:
exceptions.NoSuchTopicException: If the specified topic is not defined. TimeoutError: If the message was not able to be sent within the required
timeframe.
- subscribe(topic: str, callback: Callable)¶
Subscribes to a topic and associates a callback function to handle incoming messages.
- Args:
topic (str): The topic to subscribe to. callback (Callable): The callback function to handle incoming
messages. It may accept up to three arguments. In order, the arguments are, the received message, the topic the message was received on, and the message headers.
- Raises:
NoSuchTopicException: If the specified topic is not defined.
- subscribe_all(callback: Callable)¶
Subscribes to all registered topics.
- Args:
- callback: The function to call when a message is received. It must
accept two arguments, the topic and the message data.
include_core (bool): If true, subscribe all will subscribe the client to core messages.
- unsubscribe(topic: str)¶
Unsubscribes from a given topic.
- Args:
topic: The topic to unsubscribe from.
- class pigeon.BaseMessage¶
- exception pigeon.exceptions.NoSuchTopicException¶
- exception pigeon.exceptions.SignatureException¶