Skip to content
Events Service

TrimbleCloud.Events

TrimbleCloud

TrimbleCloud.Events.Core.Session

Session

class Session()

Represents a session for interacting with the Trimble Cloud Events service.

Arguments:

  • endpoint str - The endpoint URL of the service.
  • client_id str - The client ID for authentication.
  • client_secret str - The client secret for authentication.
  • tid_scope str, optional - The TID scope for authentication. Defaults to None.
  • auth_url str - The authentication URL.
  • enable_batch bool, optional - Enable batch processing. Defaults to False.
  • batch_buffer_size int, optional - The size of the batch buffer. Required if enable_batch is True.
  • batch_buffer_ms int, optional - The time in milliseconds to wait before sending a batch. Required if enable_batch is True.
  • batch_expiry_ms int, optional - The time in milliseconds after which a batch expires. Required if enable_batch is True.
  • workflow Workflow - The workflow type (PUBLISHER or CONSUMER).
  • call_back callable - The callback function to handle events.
  • retry_count int - The number of times to retry connection.
  • ack_wait_ms int, optional - The time in milliseconds to wait for acknowledgement. Required for PUBLISHER workflow with enable_batch is True or CONSUMER workflow.
  • ack_retry int, optional - The number of times to retry acknowledgement. Required for PUBLISHER workflow with enable_batch is True or CONSUMER workflow.
  • client_acknowledge bool, optional - Enable client acknowledgement. Required for CONSUMER workflow.
  • enable_metrics bool - Enable metrics recording.
  • datadog_api_key str, optional - The API key for Datadog integration. Required if enable_metrics is True.
  • datadog_application_key str, optional - The application key for Datadog integration. Required if enable_metrics is True.
  • datadog_metrics_tags dict, optional - The tags for Datadog metrics. Required if enable_metrics is True.
  • metric_recorder str, optional - The metric recorder type. Required if enable_metrics is True.

Raises:

  • ValueError - If any required argument is missing or has an invalid value.
  • TypeError - If any argument has an invalid type.

Attributes:

  • url str - The endpoint URL of the service.
  • active bool - Indicates if the session is active.
  • connection_status Status - The connection status of the session.

url

@property
def url()

Returns the endpoint URL for the session.

Returns:

The endpoint URL.

active

@property
def active()

Check if the session is active.

Returns:

  • bool - True if the session is active, False otherwise.

connection_status

@property
def connection_status()

Returns the current connection status of the session.

Returns:

  • Status - The connection status.

send

def send(batch)

Sends a batch of events to the server.

Arguments:

  • batch Batch - The batch of events to send.

Raises:

  • ConnectionClosedException - If the connection is already closed or still connecting.
  • PublisherException - If there is an exception while sending the batch or if the batch does not contain any events.

publish_message

def publish_message(event)

Publishes an event message.

Arguments:

  • event Event - The event object to be published.

Raises:

  • PublisherException - If batching is disabled.

poll

def poll(event)

Polls for an event from the server.

Arguments:

  • event Event - The event to poll for.

Raises:

  • ConnectionClosedException - If the connection is already closed.
  • ConnectionClosedException - If the connection is still connecting.
  • ConsumerException - If an exception occurs during consume.
  • ConsumerException - If a long poll is already in progress.

Returns:

None

acknowledge

def acknowledge(acknowledgment_id)

Method to explicitly acknowledge the receipt of a message with the given acknowledgment ID.

Arguments:

  • acknowledgment_id str - The ID of the message to acknowledge.

Raises:

  • ConnectionClosedException - If the connection is already closed or in the process of connecting.
  • ConsumerException - If an exception occurs while sending the acknowledgment.

close

def close()

Closes the session and stops all associated components.

Returns:

  • list - A list of events generated during the session.

on_message

def on_message(message, websocket)

Handles incoming messages from the websocket.

Arguments:

  • message str - The message received from the websocket.
  • websocket - The websocket object.

Returns:

None

on_error

def on_error(error)

Handles the error response received from the server.

Arguments:

  • error Exception - The error response received from the server.

Returns:

None

TrimbleCloud.Events._version

TrimbleCloud.Events

set_stream_logger

def set_stream_logger(name='ens', level=logging.ERROR, format_string=None)

Add a stream handler for the given name and level to the logging module.

By default, this logs all ens messages to stdout.

For debugging purposes a good choice is to set the stream logger to '' which is equivalent to saying “log everything”.

.. WARNING:: Be aware that when logging anything from 'ens' the full wire trace will appear in your logs. If your payloads contain sensitive data this should not be used in production.

Arguments:

  • name (string): Log name
  • level (int): Logging level, e.g. logging.INFO
  • format_string (str): Log message format

client

def client(**kwargs)

Create a low-level service client by name using the default session.

See :py:meth:boto3.session.Session.client.

TrimbleCloud.Events.Models.Event

Event

class Event()

Represents an event in the Trimble Cloud Events system.

__init__

def __init__(product_key,
             namespace,
             event,
             event_version,
             client_id,
             visibility_timeout=None,
             additional_fields=None)

Initializes a new instance of the Event class.

Arguments:

  • product_key str - The product key associated with the event.
  • namespace str - The namespace of the event.
  • event str - The name of the event.
  • event_version str - The version of the event.
  • client_id str - The client ID associated with the event.
  • visibility_timeout int, optional - The visibility timeout of the event in milliseconds. Defaults to None.
  • additional_fields dict, optional - Additional fields associated with the event. Defaults to None.

productKey

@property
def productKey()

The read-only product_key.

namespace

@property
def namespace()

The read-only namespace.

event

@property
def event()

The read-only event.

eventVersion

@property
def eventVersion()

The read-only event_version.

clientId

@property
def clientId()

The read-only client_id.

TrimbleCloud.Events.Models.ConsumeEvent

ConsumeEvent

class ConsumeEvent(Event)

Represents a consumed event.

Inherits from the base Event class and provides additional functionality for consuming events.

Attributes:

  • product_key str - The product key associated with the event.

  • namespace str - The namespace of the event.

  • event str - The event name.

  • event_version str - The version of the event.

  • client_id str - The client ID associated with the event.

  • visibility_timeout int - A period of time to prevent consumer from receiving and processing the message (Minimum value = 3 seconds & Maximum value = 60 minutes)

  • additional_fields dict - Additional fields associated with the event.

    Properties:

  • creation_time float - The read-only creation time of the event.

Methods:

  • to_dict() - Converts the ConsumeEvent object to a dictionary.
  • to_json() - Converts the ConsumeEvent object to a JSON string.

creation_time

@property
def creation_time()

The read-only creation_time.

Returns:

float: The creation time of the event.

to_dict

def to_dict()

Converts the ConsumeEvent object to a dictionary.

Returns:

dict: A dictionary representation of the ConsumeEvent object.

to_json

def to_json()

Converts the ConsumeEvent object to a JSON string.

Returns:

str: A JSON string representation of the ConsumeEvent object.

TrimbleCloud.Events.Models

TrimbleCloud.Events.Models.Response

Response

class Response()

Represents a response object.

Attributes:

  • response_type str - The response type.
  • acknowledgment_id str - The acknowledgment ID.
  • consumer_group_id str - The consumer group ID.
  • error_message str - The error message.
  • response_messages list - The list of response messages.
  • consumer_request Namespace - The consumer request.

get_kafka_response_list

def get_kafka_response_list(response_messages)

Get the list of Kafka responses.

Arguments:

  • response_messages list - The list of response messages.

Returns:

  • list - The list of Kafka responses.

__init__

def __init__(message)

Initialize a Response object.

Arguments:

  • message str - The response message.

response_type

@property
def response_type()

Get the response type.

Returns:

  • str - The response type.

acknowledgment_id

@property
def acknowledgment_id()

Get the acknowledgment ID.

Returns:

  • str - The acknowledgment ID.

consumer_group_id

@property
def consumer_group_id()

Get the consumer group ID.

Returns:

  • str - The consumer group ID.

error_message

@property
def error_message()

Get the error message.

Returns:

  • str - The error message.

response_messages

@property
def response_messages()

Get the list of response messages.

Returns:

  • list - The list of response messages.

consumer_request

@property
def consumer_request()

Get the consumer request.

Returns:

  • Namespace - The consumer request.

to_dict

def to_dict()

Convert the Response object to a dictionary.

Returns:

  • dict - The Response object as a dictionary.

to_json

def to_json()

Convert the Response object to a JSON string.

Returns:

  • str - The Response object as a JSON string.

TrimbleCloud.Events.Models.ConnectionStatus

Status

class Status(enum.Enum)

Represents the connection status.

Attributes:

  • RUNNING - The connection is currently running.
  • STOPPED - The connection has been stopped.
  • CONNECTING - The connection is in the process of connecting.

TrimbleCloud.Events.Models.PublishEvent

PublishEvent

class PublishEvent(Event)

Represents a publish event.

Inherits from the base Event class and provides additional functionality for publishing events.

Arguments:

  • product_key str - The product key.
  • namespace str - The namespace.
  • event str - The event.
  • event_version str - The event version.
  • client_id str - The client ID.
  • entity_id str - The entity ID.
  • payload dict - The payload.

Attributes:

  • connId str - The connection ID.
  • id str - The ID.
  • topicName str - The topic name.
  • feedback str - The feedback.

entityId

@property
def entityId()

The read-only entity_id.

payload

@property
def payload()

The read-only payload.

to_dict

def to_dict()

Convert the PublishEvent object to a dictionary.

Returns:

  • dict - The PublishEvent object as a dictionary.

from_response

@classmethod
def from_response(response_message)

Create a PublishEvent object from a response message.

Arguments:

  • response_message str - The response message.

Returns:

  • PublishEvent - The PublishEvent object.

TrimbleCloud.Events.Models.KafkaResponse

KafkaResponse

class KafkaResponse()

Represents a response from Kafka.

acknowledgment_id

@property
def acknowledgment_id()

The read-only acknowledgment_id.

entity_id

@property
def entity_id()

The read-only entity_id.

message

@property
def message()

The read-only message.

TrimbleCloud.Events.Models.EventsBatch

EventsBatch

class EventsBatch()

creation_time

@property
def creation_time()

The read-only creation_time.

TrimbleCloud.Events.Models.Workflow

Workflow

class Workflow(enum.Enum)

Represents the type of workflow.

Attributes:

  • PUBLISHER - The workflow is a publisher.
  • CONSUMER - The workflow is a consumer.

TrimbleCloud.Events.Models.BatchAck

BatchAck

class BatchAck()

__init__

def __init__(batch_id)

Initializes a new instance of the BatchAck class.

Arguments:

  • batch_id str - The ID of the batch.

type

@property
def type()

Gets the read-only type.

Returns:

  • str - The type.

batch_id

@property
def batch_id()

Gets the read-only batch ID.

Returns:

  • str - The batch ID.

to_json

def to_json()

Converts the BatchAck object to a JSON string.

Returns:

  • str - The JSON representation of the BatchAck object.

to_dict

def to_dict()

Converts the BatchAck object to a dictionary.

Returns:

  • dict - The dictionary representation of the BatchAck object.

TrimbleCloud.Events.Exceptions.ConsumerException

ConsumerException

class ConsumerException(Exception)

Exception raised when there is an error in the consumer.

TrimbleCloud.Events.Exceptions

TrimbleCloud.Events.Exceptions.ValidationException

ValidationException

class ValidationException(Exception)

Exception raised for validation errors.

TrimbleCloud.Events.Exceptions.ConnectionClosedException

ConnectionClosedException

class ConnectionClosedException(Exception)

Exception raised when a connection is closed unexpectedly.

to_json

def to_json()

Convert the exception to a JSON string.

Returns:

  • str - The JSON representation of the exception.

TrimbleCloud.Events.Exceptions.PublisherException

PublisherException

class PublisherException(Exception)

Exception raised when there is an error in the publisher.

to_json

def to_json()

Converts the exception to a JSON string.

Returns:

  • str - The JSON representation of the exception.

TrimbleCloud.Events.Exceptions.WebSocketException

WebSocketException

class WebSocketException(Exception)

Represents an exception that occurs in the WebSocket communication.

to_json

def to_json()

Converts the WebSocketException object to a JSON string.

Returns:

  • str - The JSON representation of the WebSocketException object.

TrimbleCloud.Events.Services.ConnectionHandler

ConnectionHandler

class ConnectionHandler(threading.Thread)

A Connection Handler manages all the old connections and close them after specified time

Arguments:

  • workflow (Workflow): client workflow
  • ack_wait_ms (int): time to wait before closing connection (Publisher)
  • create_web_socket_client (function): function to create websocket client
  • switch_connection (function): function to switch connection
  • endpoint (string): connection endpoint

TrimbleCloud.Events.Services

TrimbleCloud.Events.Services.ExpiryCache

TrimbleCloud.Events.Services.TID