def authenticate_client_by_jwt():
# Create the JWTTokenAuth object
auth_uri = "<amqp endpoint uri for authentication>" # The AMQP endpoint URI for authentication.
token_audience = "<token audience>" # The token audience field.
auth = authentication.JWTTokenAuth(audience=token_audience,
uri=auth_uri,
get_token=get_token)
# Instantiate the SendClient with the JWTTokenAuth object
target = "<target amqp service endpoint>" # The target AMQP service endpoint.
send_client = SendClient(target=target, auth=auth)
# Send a message
message = Message(b'data')
send_client.send_message(message)
send_client.close()
class ServiceBusSender(BaseHandler, SenderMixin):
"""The ServiceBusSender class defines a high level interface for
sending messages to the Azure Service Bus Queue or Topic.
:ivar fully_qualified_namespace: The fully qualified host name for the Service Bus namespace.
The namespace format is: `<yournamespace>.servicebus.windows.net`.
:vartype fully_qualified_namespace: str
:ivar entity_name: The name of the entity that the client connects to.
:vartype entity_name: str
:param str fully_qualified_namespace: The fully qualified host name for the Service Bus namespace.
The namespace format is: `<yournamespace>.servicebus.windows.net`.
:param ~azure.core.credentials.TokenCredential credential: The credential object used for authentication which
implements a particular interface for getting tokens. It accepts
:class:`ServiceBusSharedKeyCredential<azure.servicebus.ServiceBusSharedKeyCredential>`, or credential objects
generated by the azure-identity library and objects that implement the `get_token(self, *scopes)` method.
:keyword str queue_name: The path of specific Service Bus Queue the client connects to.
:keyword str topic_name: The path of specific Service Bus Topic the client connects to.
:keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
:keyword int retry_total: The total number of attempts to redo a failed operation when an error occurs.
Default value is 3.
:keyword transport_type: The type of transport protocol that will be used for communicating with
the Service Bus service. Default is `TransportType.Amqp`.
:paramtype transport_type: ~azure.servicebus.TransportType
:keyword dict http_proxy: HTTP proxy settings. This must be a dictionary with the following
keys: `'proxy_hostname'` (str value) and `'proxy_port'` (int value).
Additionally the following keys may also be present: `'username', 'password'`.
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START create_servicebus_sender_sync]
:end-before: [END create_servicebus_sender_sync]
:language: python
:dedent: 4
:caption: Create a new instance of the ServiceBusSender.
"""
def __init__(
self,
fully_qualified_namespace,
credential,
**kwargs
):
# type: (str, TokenCredential, Any) -> None
if kwargs.get("entity_name"):
super(ServiceBusSender, self).__init__(
fully_qualified_namespace=fully_qualified_namespace,
credential=credential,
**kwargs
)
else:
queue_name = kwargs.get("queue_name")
topic_name = kwargs.get("topic_name")
if queue_name and topic_name:
raise ValueError("Queue/Topic name can not be specified simultaneously.")
entity_name = queue_name or topic_name
if not entity_name:
raise ValueError("Queue/Topic name is missing. Please specify queue_name/topic_name.")
super(ServiceBusSender, self).__init__(
fully_qualified_namespace=fully_qualified_namespace,
credential=credential,
entity_name=entity_name,
**kwargs
)
self._max_message_size_on_link = 0
self._create_attribute()
self._connection = kwargs.get("connection")
def _create_handler(self, auth):
# type: (AMQPAuth) -> None
self._handler = SendClient(
self._entity_uri,
auth=auth,
debug=self._config.logging_enable,
properties=self._properties,
error_policy=self._error_policy,
client_name=self._name,
encoding=self._config.encoding
)
def _open(self):
# pylint: disable=protected-access
if self._running:
return
if self._handler:
self._handler.close()
auth = None if self._connection else create_authentication(self)
self._create_handler(auth)
try:
self._handler.open(connection=self._connection)
while not self._handler.client_ready():
time.sleep(0.05)
self._running = True
self._max_message_size_on_link = self._handler.message_handler._link.peer_max_message_size \
or uamqp.constants.MAX_MESSAGE_LENGTH_BYTES
except:
self.close()
raise
def _send(self, message, timeout=None, last_exception=None):
# type: (Message, Optional[float], Exception) -> None
self._open()
self._set_msg_timeout(timeout, last_exception)
self._handler.send_message(message.message)
def schedule(self, messages, schedule_time_utc):
# type: (Union[Message, List[Message]], datetime.datetime) -> List[int]
"""Send Message or multiple Messages to be enqueued at a specific time.
Returns a list of the sequence numbers of the enqueued messages.
:param messages: The message or list of messages to schedule.
:type messages: ~azure.servicebus.Message or list[~azure.servicebus.Message]
:param schedule_time_utc: The utc date and time to enqueue the messages.
:type schedule_time_utc: ~datetime.datetime
:rtype: list[int]
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START scheduling_messages]
:end-before: [END scheduling_messages]
:language: python
:dedent: 4
:caption: Schedule a message to be sent in future
"""
# pylint: disable=protected-access
self._open()
if isinstance(messages, Message):
request_body = self._build_schedule_request(schedule_time_utc, messages)
else:
request_body = self._build_schedule_request(schedule_time_utc, *messages)
return self._mgmt_request_response_with_retry(
REQUEST_RESPONSE_SCHEDULE_MESSAGE_OPERATION,
request_body,
mgmt_handlers.schedule_op
)
def cancel_scheduled_messages(self, sequence_numbers):
# type: (Union[int, List[int]]) -> None
"""
Cancel one or more messages that have previously been scheduled and are still pending.
:param sequence_numbers: The sequence numbers of the scheduled messages.
:type sequence_numbers: int or list[int]
:rtype: None
:raises: ~azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message already
cancelled or enqueued.
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START cancel_scheduled_messages]
:end-before: [END cancel_scheduled_messages]
:language: python
:dedent: 4
:caption: Cancelling messages scheduled to be sent in future
"""
self._open()
if isinstance(sequence_numbers, int):
numbers = [types.AMQPLong(sequence_numbers)]
else:
numbers = [types.AMQPLong(s) for s in sequence_numbers]
request_body = {MGMT_REQUEST_SEQUENCE_NUMBERS: types.AMQPArray(numbers)}
return self._mgmt_request_response_with_retry(
REQUEST_RESPONSE_CANCEL_SCHEDULED_MESSAGE_OPERATION,
request_body,
mgmt_handlers.default
)
@classmethod
def from_connection_string(
cls,
conn_str,
**kwargs
):
# type: (str, Any) -> ServiceBusSender
"""Create a ServiceBusSender from a connection string.
:param conn_str: The connection string of a Service Bus.
:keyword str queue_name: The path of specific Service Bus Queue the client connects to.
Only one of queue_name or topic_name can be provided.
:keyword str topic_name: The path of specific Service Bus Topic the client connects to.
Only one of queue_name or topic_name can be provided.
:keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
:keyword int retry_total: The total number of attempts to redo a failed operation when an error occurs.
Default value is 3.
:keyword transport_type: The type of transport protocol that will be used for communicating with
the Service Bus service. Default is `TransportType.Amqp`.
:paramtype transport_type: ~azure.servicebus.TransportType
:keyword dict http_proxy: HTTP proxy settings. This must be a dictionary with the following
keys: `'proxy_hostname'` (str value) and `'proxy_port'` (int value).
Additionally the following keys may also be present: `'username', 'password'`.
:rtype: ~azure.servicebus.ServiceBusSenderClient
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START create_servicebus_sender_from_conn_str_sync]
:end-before: [END create_servicebus_sender_from_conn_str_sync]
:language: python
:dedent: 4
:caption: Create a new instance of the ServiceBusSender from connection string.
"""
constructor_args = _convert_connection_string_to_kwargs(
conn_str,
ServiceBusSharedKeyCredential,
**kwargs
)
return cls(**constructor_args)
def send(self, message):
# type: (Union[Message, BatchMessage, List[Message]]) -> None
"""Sends message and blocks until acknowledgement is received or operation times out.
If a list of messages was provided, attempts to send them as a single batch, throwing a
`ValueError` if they cannot fit in a single batch.
:param message: The ServiceBus message to be sent.
:type message: ~azure.servicebus.Message or ~azure.servicebus.BatchMessage or list[~azure.servicebus.Message]
:rtype: None
:raises:
:class: ~azure.servicebus.exceptions.OperationTimeoutError if sending times out.
:class: ~azure.servicebus.exceptions.MessageContentTooLarge if the size of the message is over
service bus frame size limit.
:class: ~azure.servicebus.exceptions.MessageSendFailed if the message fails to send
:class: ~azure.servicebus.exceptions.ServiceBusError when other errors happen such as connection
error, authentication error, and any unexpected errors.
It's also the top-level root class of above errors.
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START send_sync]
:end-before: [END send_sync]
:language: python
:dedent: 4
:caption: Send message.
"""
try:
batch = self.create_batch()
batch._from_list(message) # pylint: disable=protected-access
message = batch
except TypeError: # Message was not a list or generator.
pass
if isinstance(message, BatchMessage) and len(message) == 0: # pylint: disable=len-as-condition
raise ValueError("A BatchMessage or list of Message must have at least one Message")
self._do_retryable_operation(
self._send,
message=message,
require_timeout=True,
require_last_exception=True
)
def create_batch(self, max_size_in_bytes=None):
# type: (int) -> BatchMessage
"""Create a BatchMessage object with the max size of all content being constrained by max_size_in_bytes.
The max_size should be no greater than the max allowed message size defined by the service.
:param int max_size_in_bytes: The maximum size of bytes data that a BatchMessage object can hold. By
default, the value is determined by your Service Bus tier.
:rtype: ~azure.servicebus.BatchMessage
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START create_batch_sync]
:end-before: [END create_batch_sync]
:language: python
:dedent: 4
:caption: Create BatchMessage object within limited size
"""
if not self._max_message_size_on_link:
self._open_with_retry()
if max_size_in_bytes and max_size_in_bytes > self._max_message_size_on_link:
raise ValueError(
"Max message size: {} is too large, acceptable max batch size is: {} bytes.".format(
max_size_in_bytes, self._max_message_size_on_link
)
)
return BatchMessage(
max_size_in_bytes=(max_size_in_bytes or self._max_message_size_on_link)
)
class ServiceBusSender(BaseHandler, SenderMixin):
"""The ServiceBusSender class defines a high level interface for
sending messages to the Azure Service Bus Queue or Topic.
**Please use the `get_<queue/topic>_sender` method of ~azure.servicebus.ServiceBusClient to create a
ServiceBusSender instance.**
:ivar fully_qualified_namespace: The fully qualified host name for the Service Bus namespace.
The namespace format is: `<yournamespace>.servicebus.windows.net`.
:vartype fully_qualified_namespace: str
:ivar entity_name: The name of the entity that the client connects to.
:vartype entity_name: str
:param str fully_qualified_namespace: The fully qualified host name for the Service Bus namespace.
The namespace format is: `<yournamespace>.servicebus.windows.net`.
:param ~azure.core.credentials.TokenCredential credential: The credential object used for authentication which
implements a particular interface for getting tokens. It accepts
:class: credential objects generated by the azure-identity library and objects that implement the
`get_token(self, *scopes)` method.
:keyword str queue_name: The path of specific Service Bus Queue the client connects to.
:keyword str topic_name: The path of specific Service Bus Topic the client connects to.
:keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
:keyword transport_type: The type of transport protocol that will be used for communicating with
the Service Bus service. Default is `TransportType.Amqp`.
:paramtype transport_type: ~azure.servicebus.TransportType
:keyword dict http_proxy: HTTP proxy settings. This must be a dictionary with the following
keys: `'proxy_hostname'` (str value) and `'proxy_port'` (int value).
Additionally the following keys may also be present: `'username', 'password'`.
:keyword str user_agent: If specified, this will be added in front of the built-in user agent string.
"""
def __init__(self, fully_qualified_namespace, credential, **kwargs):
# type: (str, TokenCredential, Any) -> None
if kwargs.get("entity_name"):
super(ServiceBusSender, self).__init__(
fully_qualified_namespace=fully_qualified_namespace,
credential=credential,
**kwargs)
else:
queue_name = kwargs.get("queue_name")
topic_name = kwargs.get("topic_name")
if queue_name and topic_name:
raise ValueError(
"Queue/Topic name can not be specified simultaneously.")
entity_name = queue_name or topic_name
if not entity_name:
raise ValueError(
"Queue/Topic name is missing. Please specify queue_name/topic_name."
)
super(ServiceBusSender, self).__init__(
fully_qualified_namespace=fully_qualified_namespace,
credential=credential,
entity_name=entity_name,
**kwargs)
self._max_message_size_on_link = 0
self._create_attribute()
self._connection = kwargs.get("connection")
@classmethod
def _from_connection_string(cls, conn_str, **kwargs):
# type: (str, Any) -> ServiceBusSender
"""Create a ServiceBusSender from a connection string.
:param conn_str: The connection string of a Service Bus.
:type conn_str: str
:keyword str queue_name: The path of specific Service Bus Queue the client connects to.
Only one of queue_name or topic_name can be provided.
:keyword str topic_name: The path of specific Service Bus Topic the client connects to.
Only one of queue_name or topic_name can be provided.
:keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
:keyword transport_type: The type of transport protocol that will be used for communicating with
the Service Bus service. Default is `TransportType.Amqp`.
:paramtype transport_type: ~azure.servicebus.TransportType
:keyword dict http_proxy: HTTP proxy settings. This must be a dictionary with the following
keys: `'proxy_hostname'` (str value) and `'proxy_port'` (int value).
Additionally the following keys may also be present: `'username', 'password'`.
:keyword str user_agent: If specified, this will be added in front of the built-in user agent string.
:rtype: ~azure.servicebus.ServiceBusSender
:raises ~azure.servicebus.ServiceBusAuthenticationError: Indicates an issue in token/identity validity.
:raises ~azure.servicebus.ServiceBusAuthorizationError: Indicates an access/rights related failure.
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START create_servicebus_sender_from_conn_str_sync]
:end-before: [END create_servicebus_sender_from_conn_str_sync]
:language: python
:dedent: 4
:caption: Create a new instance of the ServiceBusSender from connection string.
"""
constructor_args = cls._convert_connection_string_to_kwargs(
conn_str, **kwargs)
return cls(**constructor_args)
def _create_handler(self, auth):
# type: (AMQPAuth) -> None
self._handler = SendClient(
self._entity_uri,
auth=auth,
debug=self._config.logging_enable,
properties=self._properties,
error_policy=self._error_policy,
client_name=self._name,
keep_alive_interval=self._config.keep_alive,
encoding=self._config.encoding,
)
def _open(self):
# pylint: disable=protected-access
if self._running:
return
if self._handler:
self._handler.close()
auth = None if self._connection else create_authentication(self)
self._create_handler(auth)
try:
self._handler.open(connection=self._connection)
while not self._handler.client_ready():
time.sleep(0.05)
self._running = True
self._max_message_size_on_link = (
self._handler.message_handler._link.peer_max_message_size
or uamqp.constants.MAX_MESSAGE_LENGTH_BYTES)
except:
self._close_handler()
raise
def _send(self, message, timeout=None, last_exception=None):
# type: (Union[ServiceBusMessage, ServiceBusMessageBatch], Optional[float], Exception) -> None
self._open()
default_timeout = self._handler._msg_timeout # pylint: disable=protected-access
try:
self._set_msg_timeout(timeout, last_exception)
self._handler.send_message(message.message)
finally: # reset the timeout of the handler back to the default value
self._set_msg_timeout(default_timeout, None)
def schedule_messages(self, messages, schedule_time_utc, **kwargs):
# type: (Union[ServiceBusMessage, List[ServiceBusMessage]], datetime.datetime, Any) -> List[int]
"""Send Message or multiple Messages to be enqueued at a specific time.
Returns a list of the sequence numbers of the enqueued messages.
:param messages: The message or list of messages to schedule.
:type messages: Union[~azure.servicebus.ServiceBusMessage, List[~azure.servicebus.ServiceBusMessage]]
:param schedule_time_utc: The utc date and time to enqueue the messages.
:type schedule_time_utc: ~datetime.datetime
:keyword float timeout: The total operation timeout in seconds including all the retries. The value must be
greater than 0 if specified. The default value is None, meaning no timeout.
:rtype: List[int]
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START scheduling_messages]
:end-before: [END scheduling_messages]
:language: python
:dedent: 4
:caption: Schedule a message to be sent in future
"""
# pylint: disable=protected-access
self._check_live()
timeout = kwargs.pop("timeout", None)
if timeout is not None and timeout <= 0:
raise ValueError("The timeout must be greater than 0.")
with send_trace_context_manager(
span_name=SPAN_NAME_SCHEDULE) as send_span:
if isinstance(messages, ServiceBusMessage):
request_body = self._build_schedule_request(
schedule_time_utc, send_span, messages)
else:
if len(messages) == 0:
return [] # No-op on empty list.
request_body = self._build_schedule_request(
schedule_time_utc, send_span, *messages)
if send_span:
self._add_span_request_attributes(send_span)
return self._mgmt_request_response_with_retry(
REQUEST_RESPONSE_SCHEDULE_MESSAGE_OPERATION,
request_body,
mgmt_handlers.schedule_op,
timeout=timeout,
)
def cancel_scheduled_messages(self, sequence_numbers, **kwargs):
# type: (Union[int, List[int]], Any) -> None
"""
Cancel one or more messages that have previously been scheduled and are still pending.
:param sequence_numbers: The sequence numbers of the scheduled messages.
:type sequence_numbers: int or list[int]
:keyword float timeout: The total operation timeout in seconds including all the retries. The value must be
greater than 0 if specified. The default value is None, meaning no timeout.
:rtype: None
:raises: ~azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message already
cancelled or enqueued.
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START cancel_scheduled_messages]
:end-before: [END cancel_scheduled_messages]
:language: python
:dedent: 4
:caption: Cancelling messages scheduled to be sent in future
"""
self._check_live()
timeout = kwargs.pop("timeout", None)
if timeout is not None and timeout <= 0:
raise ValueError("The timeout must be greater than 0.")
if isinstance(sequence_numbers, int):
numbers = [types.AMQPLong(sequence_numbers)]
else:
numbers = [types.AMQPLong(s) for s in sequence_numbers]
if len(numbers) == 0:
return None # no-op on empty list.
request_body = {
MGMT_REQUEST_SEQUENCE_NUMBERS: types.AMQPArray(numbers)
}
return self._mgmt_request_response_with_retry(
REQUEST_RESPONSE_CANCEL_SCHEDULED_MESSAGE_OPERATION,
request_body,
mgmt_handlers.default,
timeout=timeout,
)
def send_messages(self, message, **kwargs):
# type: (Union[ServiceBusMessage, ServiceBusMessageBatch, List[ServiceBusMessage]], Any) -> None
"""Sends message and blocks until acknowledgement is received or operation times out.
If a list of messages was provided, attempts to send them as a single batch, throwing a
`ValueError` if they cannot fit in a single batch.
:param message: The ServiceBus message to be sent.
:type message: Union[~azure.servicebus.ServiceBusMessage,~azure.servicebus.ServiceBusMessageBatch,
list[~azure.servicebus.ServiceBusMessage]]
:keyword Optional[float] timeout: The total operation timeout in seconds including all the retries.
The value must be greater than 0 if specified. The default value is None, meaning no timeout.
:rtype: None
:raises:
:class: ~azure.servicebus.exceptions.OperationTimeoutError if sending times out.
:class: ~azure.servicebus.exceptions.MessageSizeExceededError if the size of the message is over
service bus frame size limit.
:class: ~azure.servicebus.exceptions.ServiceBusError when other errors happen such as connection
error, authentication error, and any unexpected errors.
It's also the top-level root class of above errors.
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START send_sync]
:end-before: [END send_sync]
:language: python
:dedent: 4
:caption: Send message.
"""
self._check_live()
timeout = kwargs.pop("timeout", None)
if timeout is not None and timeout <= 0:
raise ValueError("The timeout must be greater than 0.")
with send_trace_context_manager() as send_span:
# Ensure message is sendable (not a ReceivedMessage), and if needed (a list) is batched. Adds tracing.
message = transform_messages_to_sendable_if_needed(message)
try:
for each_message in iter(
message
): # type: ignore # Ignore type (and below) as it will except if wrong.
add_link_to_send(each_message, send_span)
batch = self.create_message_batch()
batch._from_list(message, send_span) # type: ignore # pylint: disable=protected-access
message = batch
except TypeError: # Message was not a list or generator. Do needed tracing.
if isinstance(message, ServiceBusMessageBatch):
for (batch_message) in message.message._body_gen: # pylint: disable=protected-access
add_link_to_send(batch_message, send_span)
elif isinstance(message, ServiceBusMessage):
trace_message(message, send_span)
add_link_to_send(message, send_span)
if (isinstance(message, ServiceBusMessageBatch)
and len(message) == 0): # pylint: disable=len-as-condition
return # Short circuit noop if an empty list or batch is provided.
if not isinstance(message,
ServiceBusMessageBatch) and not isinstance(
message, ServiceBusMessage):
raise TypeError(
"Can only send azure.servicebus.<ServiceBusMessageBatch,ServiceBusMessage> "
"or lists of ServiceBusMessage.")
if send_span:
self._add_span_request_attributes(send_span)
self._do_retryable_operation(
self._send,
message=message,
timeout=timeout,
operation_requires_timeout=True,
require_last_exception=True,
)
def create_message_batch(self, max_size_in_bytes=None):
# type: (Optional[int]) -> ServiceBusMessageBatch
"""Create a ServiceBusMessageBatch object with the max size of all content being constrained by
max_size_in_bytes. The max_size should be no greater than the max allowed message size defined by the service.
:param Optional[int] max_size_in_bytes: The maximum size of bytes data that a ServiceBusMessageBatch object can
hold. By default, the value is determined by your Service Bus tier.
:rtype: ~azure.servicebus.ServiceBusMessageBatch
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/sample_code_servicebus.py
:start-after: [START create_batch_sync]
:end-before: [END create_batch_sync]
:language: python
:dedent: 4
:caption: Create ServiceBusMessageBatch object within limited size
"""
self._check_live()
if not self._max_message_size_on_link:
self._open_with_retry()
if max_size_in_bytes and max_size_in_bytes > self._max_message_size_on_link:
raise ValueError(
"Max message size: {} is too large, acceptable max batch size is: {} bytes."
.format(max_size_in_bytes, self._max_message_size_on_link))
return ServiceBusMessageBatch(max_size_in_bytes=(
max_size_in_bytes or self._max_message_size_on_link))
class EventHubProducer(object):
"""
A producer responsible for transmitting EventData to a specific Event Hub,
grouped together in batches. Depending on the options specified at creation, the producer may
be created to allow event data to be automatically routed to an available partition or specific
to a partition.
"""
def __init__(self,
client,
target,
partition=None,
send_timeout=60,
keep_alive=None,
auto_reconnect=True):
"""
Instantiate an EventHubProducer. EventHubProducer should be instantiated by calling the `create_producer` method
in EventHubClient.
:param client: The parent EventHubClient.
:type client: ~azure.eventhub.client.EventHubClient.
:param target: The URI of the EventHub to send to.
:type target: str
:param partition: The specific partition ID to send to. Default is None, in which case the service
will assign to all partitions using round-robin.
:type partition: str
:param send_timeout: The timeout in seconds for an individual event to be sent from the time that it is
queued. Default value is 60 seconds. If set to 0, there will be no timeout.
:type send_timeout: float
:param keep_alive: The time interval in seconds between pinging the connection to keep it alive during
periods of inactivity. The default value is None, i.e. no keep alive pings.
:type keep_alive: float
:param auto_reconnect: Whether to automatically reconnect the producer if a retryable error occurs.
Default value is `True`.
:type auto_reconnect: bool
"""
self.running = False
self.client = client
self.target = target
self.partition = partition
self.timeout = send_timeout
self.redirected = None
self.error = None
self.keep_alive = keep_alive
self.auto_reconnect = auto_reconnect
self.retry_policy = errors.ErrorPolicy(
max_retries=self.client.config.max_retries,
on_error=_error_handler)
self.reconnect_backoff = 1
self.name = "EHProducer-{}".format(uuid.uuid4())
self.unsent_events = None
if partition:
self.target += "/Partitions/" + partition
self.name += "-partition{}".format(partition)
self._handler = SendClient(self.target,
auth=self.client.get_auth(),
debug=self.client.config.network_tracing,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client._create_properties(
self.client.config.user_agent)) # pylint: disable=protected-access
self._outcome = None
self._condition = None
def __enter__(self):
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.close(exc_val)
def _open(self):
"""
Open the EventHubProducer using the supplied connection.
If the handler has previously been redirected, the redirect
context will be used to create a new handler before opening it.
"""
# pylint: disable=protected-access
self._check_closed()
if self.redirected:
self.target = self.redirected.address
self._handler = SendClient(
self.target,
auth=self.client.get_auth(),
debug=self.client.config.network_tracing,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client._create_properties(
self.client.config.user_agent))
if not self.running:
self._connect()
self.running = True
def _connect(self):
connected = self._build_connection()
if not connected:
time.sleep(self.reconnect_backoff)
while not self._build_connection(is_reconnect=True):
time.sleep(self.reconnect_backoff)
def _build_connection(self, is_reconnect=False):
"""
:param is_reconnect: True - trying to reconnect after fail to connect or a connection is lost.
False - the 1st time to connect
:return: True - connected. False - not connected
"""
# pylint: disable=protected-access
if is_reconnect:
self._handler.close()
self._handler = SendClient(
self.target,
auth=self.client.get_auth(),
debug=self.client.config.network_tracing,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client._create_properties(
self.client.config.user_agent))
try:
self._handler.open()
while not self._handler.client_ready():
time.sleep(0.05)
return True
except errors.AuthenticationException as shutdown:
if is_reconnect:
log.info(
"EventHubProducer couldn't authenticate. Shutting down. (%r)",
shutdown)
error = AuthenticationError(str(shutdown), shutdown)
self.close(exception=error)
raise error
else:
log.info(
"EventHubProducer couldn't authenticate. Attempting reconnect."
)
return False
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry:
log.info("EventHubProducer detached. Attempting reconnect.")
return False
else:
log.info("EventHubProducer detached. Shutting down.")
error = ConnectError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if is_reconnect:
log.info("EventHubProducer detached. Shutting down.")
error = ConnectError(str(shutdown), shutdown)
self.close(exception=error)
raise error
else:
log.info("EventHubProducer detached. Attempting reconnect.")
return False
except errors.AMQPConnectionError as shutdown:
if is_reconnect:
log.info(
"EventHubProducer connection error (%r). Shutting down.",
shutdown)
error = AuthenticationError(str(shutdown), shutdown)
self.close(exception=error)
raise error
else:
log.info(
"EventHubProducer couldn't authenticate. Attempting reconnect."
)
return False
except compat.TimeoutException as shutdown:
if is_reconnect:
log.info(
"EventHubProducer authentication timed out. Shutting down."
)
error = AuthenticationError(str(shutdown), shutdown)
self.close(exception=error)
raise error
else:
log.info(
"EventHubProducer authentication timed out. Attempting reconnect."
)
return False
except Exception as e:
log.info(
"Unexpected error occurred when building connection (%r). Shutting down.",
e)
error = EventHubError(
"Unexpected error occurred when building connection", e)
self.close(exception=error)
raise error
def _reconnect(self):
return self._build_connection(is_reconnect=True)
def _send_event_data(self):
self._open()
max_retries = self.client.config.max_retries
connecting_count = 0
while True:
connecting_count += 1
try:
if self.unsent_events:
self._handler.queue_message(*self.unsent_events)
self._handler.wait()
self.unsent_events = self._handler.pending_messages
if self._outcome != constants.MessageSendResult.Ok:
EventHubProducer._error(self._outcome, self._condition)
return
except (errors.MessageAccepted, errors.MessageAlreadySettled,
errors.MessageModified, errors.MessageRejected,
errors.MessageReleased,
errors.MessageContentTooLarge) as msg_error:
raise EventDataError(str(msg_error), msg_error)
except errors.MessageException as failed:
log.error("Send event data error (%r)", failed)
error = EventDataSendError(str(failed), failed)
self.close(exception=error)
raise error
except errors.AuthenticationException as auth_error:
if connecting_count < max_retries:
log.info(
"EventHubProducer disconnected due to token error. Attempting reconnect."
)
self._reconnect()
else:
log.info(
"EventHubProducer authentication failed. Shutting down."
)
error = AuthenticationError(str(auth_error), auth_error)
self.close(auth_error)
raise error
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry:
log.info(
"EventHubProducer detached. Attempting reconnect.")
self._reconnect()
else:
log.info("EventHubProducer detached. Shutting down.")
error = ConnectionLostError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if connecting_count < max_retries:
log.info(
"EventHubProducer detached. Attempting reconnect.")
self._reconnect()
else:
log.info("EventHubProducer detached. Shutting down.")
error = ConnectionLostError(str(shutdown), shutdown)
self.close(error)
raise error
except errors.AMQPConnectionError as shutdown:
if connecting_count < max_retries:
log.info(
"EventHubProducer connection lost. Attempting reconnect."
)
self._reconnect()
else:
log.info(
"EventHubProducer connection lost. Shutting down.")
error = ConnectionLostError(str(shutdown), shutdown)
self.close(error)
raise error
except compat.TimeoutException as shutdown:
if connecting_count < max_retries:
log.info(
"EventHubProducer timed out sending event data. Attempting reconnect."
)
self._reconnect()
else:
log.info("EventHubProducer timed out. Shutting down.")
self.close(shutdown)
raise ConnectionLostError(str(shutdown), shutdown)
except Exception as e:
log.info("Unexpected error occurred (%r). Shutting down.", e)
error = EventHubError("Send failed: {}".format(e), e)
self.close(exception=error)
raise error
def _check_closed(self):
if self.error:
raise EventHubError(
"This producer has been closed. Please create a new producer to send event data.",
self.error)
@staticmethod
def _set_partition_key(event_datas, partition_key):
ed_iter = iter(event_datas)
for ed in ed_iter:
ed._set_partition_key(partition_key)
yield ed
def _on_outcome(self, outcome, condition):
"""
Called when the outcome is received for a delivery.
:param outcome: The outcome of the message delivery - success or failure.
:type outcome: ~uamqp.constants.MessageSendResult
:param condition: Detail information of the outcome.
"""
self._outcome = outcome
self._condition = condition
@staticmethod
def _error(outcome, condition):
if outcome != constants.MessageSendResult.Ok:
raise condition
def send(self, event_data, partition_key=None):
# type:(Union[EventData, Union[List[EventData], Iterator[EventData], Generator[EventData]]], Union[str, bytes]) -> None
"""
Sends an event data and blocks until acknowledgement is
received or operation times out.
:param event_data: The event to be sent. It can be an EventData object, or iterable of EventData objects
:type event_data: ~azure.eventhub.common.EventData, Iterator, Generator, list
:param partition_key: With the given partition_key, event data will land to
a particular partition of the Event Hub decided by the service.
:type partition_key: str
:raises: ~azure.eventhub.AuthenticationError, ~azure.eventhub.ConnectError, ~azure.eventhub.ConnectionLostError,
~azure.eventhub.EventDataError, ~azure.eventhub.EventDataSendError, ~azure.eventhub.EventHubError
:return: None
:rtype: None
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_sync_send]
:end-before: [END eventhub_client_sync_send]
:language: python
:dedent: 4
:caption: Sends an event data and blocks until acknowledgement is received or operation times out.
"""
self._check_closed()
if isinstance(event_data, EventData):
if partition_key:
event_data._set_partition_key(partition_key)
wrapper_event_data = event_data
else:
event_data_with_pk = self._set_partition_key(
event_data, partition_key)
wrapper_event_data = _BatchSendEventData(
event_data_with_pk, partition_key=partition_key
) if partition_key else _BatchSendEventData(event_data)
wrapper_event_data.message.on_send_complete = self._on_outcome
self.unsent_events = [wrapper_event_data.message]
self._send_event_data()
def close(self, exception=None):
# type:(Exception) -> None
"""
Close down the handler. If the handler has already closed,
this will be a no op. An optional exception can be passed in to
indicate that the handler was shutdown due to error.
:param exception: An optional exception if the handler is closing
due to an error.
:type exception: Exception
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_sender_close]
:end-before: [END eventhub_client_sender_close]
:language: python
:dedent: 4
:caption: Close down the handler.
"""
self.running = False
if self.error:
return
if isinstance(exception, errors.LinkRedirect):
self.redirected = exception
elif isinstance(exception, EventHubError):
self.error = exception
elif exception:
self.error = EventHubError(str(exception))
else:
self.error = EventHubError("This send handler is now closed.")
self._handler.close()
class Sender(object):
"""
Implements a Sender.
"""
def __init__(self,
client,
target,
partition=None,
send_timeout=60,
keep_alive=None,
auto_reconnect=True):
"""
Instantiate an EventHub event Sender handler.
:param client: The parent EventHubClient.
:type client: ~azure.eventhub.client.EventHubClient.
:param target: The URI of the EventHub to send to.
:type target: str
:param partition: The specific partition ID to send to. Default is None, in which case the service
will assign to all partitions using round-robin.
:type partition: str
:param send_timeout: The timeout in seconds for an individual event to be sent from the time that it is
queued. Default value is 60 seconds. If set to 0, there will be no timeout.
:type send_timeout: int
:param keep_alive: The time interval in seconds between pinging the connection to keep it alive during
periods of inactivity. The default value is None, i.e. no keep alive pings.
:type keep_alive: int
:param auto_reconnect: Whether to automatically reconnect the sender if a retryable error occurs.
Default value is `True`.
:type auto_reconnect: bool
"""
self.running = False
self.client = client
self.target = target
self.partition = partition
self.timeout = send_timeout
self.redirected = None
self.error = None
self.keep_alive = keep_alive
self.auto_reconnect = auto_reconnect
self.retry_policy = errors.ErrorPolicy(max_retries=3,
on_error=_error_handler)
self.reconnect_backoff = 1
self.name = "EHSender-{}".format(uuid.uuid4())
if partition:
self.target += "/Partitions/" + partition
self.name += "-partition{}".format(partition)
self._handler = SendClient(self.target,
auth=self.client.get_auth(),
debug=self.client.debug,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client.create_properties())
self._outcome = None
self._condition = None
def open(self):
"""
Open the Sender using the supplied conneciton.
If the handler has previously been redirected, the redirect
context will be used to create a new handler before opening it.
:param connection: The underlying client shared connection.
:type: connection: ~uamqp.connection.Connection
"""
self.running = True
if self.redirected:
self.target = self.redirected.address
self._handler = SendClient(
self.target,
auth=self.client.get_auth(),
debug=self.client.debug,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client.create_properties())
self._handler.open()
while not self._handler.client_ready():
time.sleep(0.05)
def _reconnect(self):
# pylint: disable=protected-access
self._handler.close()
unsent_events = self._handler.pending_messages
self._handler = SendClient(self.target,
auth=self.client.get_auth(),
debug=self.client.debug,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client.create_properties())
try:
self._handler.open()
self._handler.queue_message(*unsent_events)
self._handler.wait()
return True
except errors.TokenExpired as shutdown:
log.info("Sender disconnected due to token expiry. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry and self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
return False
log.info("Sender reconnect failed. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
return False
log.info("Sender reconnect failed. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.AMQPConnectionError as shutdown:
if str(shutdown).startswith("Unable to open authentication session"
) and self.auto_reconnect:
log.info("Sender couldn't authenticate. Attempting reconnect.")
return False
log.info("Sender connection error (%r). Shutting down.", shutdown)
error = EventHubError(str(shutdown))
self.close(exception=error)
raise error
except Exception as e:
log.info("Unexpected error occurred (%r). Shutting down.", e)
error = EventHubError("Sender Reconnect failed: {}".format(e))
self.close(exception=error)
raise error
def reconnect(self):
"""If the Sender was disconnected from the service with
a retryable error - attempt to reconnect."""
while not self._reconnect():
time.sleep(self.reconnect_backoff)
def get_handler_state(self):
"""
Get the state of the underlying handler with regards to start
up processes.
:rtype: ~uamqp.constants.MessageSenderState
"""
# pylint: disable=protected-access
return self._handler._message_sender.get_state()
def has_started(self):
"""
Whether the handler has completed all start up processes such as
establishing the connection, session, link and authentication, and
is not ready to process messages.
**This function is now deprecated and will be removed in v2.0+.**
:rtype: bool
"""
# pylint: disable=protected-access
timeout = False
auth_in_progress = False
if self._handler._connection.cbs:
timeout, auth_in_progress = self._handler._auth.handle_token()
if timeout:
raise EventHubError("Authorization timeout.")
if auth_in_progress:
return False
if not self._handler._client_ready():
return False
return True
def close(self, exception=None):
"""
Close down the handler. If the handler has already closed,
this will be a no op. An optional exception can be passed in to
indicate that the handler was shutdown due to error.
:param exception: An optional exception if the handler is closing
due to an error.
:type exception: Exception
"""
self.running = False
if self.error:
return
if isinstance(exception, errors.LinkRedirect):
self.redirected = exception
elif isinstance(exception, EventHubError):
self.error = exception
elif exception:
self.error = EventHubError(str(exception))
else:
self.error = EventHubError("This send handler is now closed.")
self._handler.close()
def send(self, event_data):
"""
Sends an event data and blocks until acknowledgement is
received or operation times out.
:param event_data: The event to be sent.
:type event_data: ~azure.eventhub.common.EventData
:raises: ~azure.eventhub.common.EventHubError if the message fails to
send.
:return: The outcome of the message send.
:rtype: ~uamqp.constants.MessageSendResult
"""
if self.error:
raise self.error
if not self.running:
raise ValueError("Unable to send until client has been started.")
if event_data.partition_key and self.partition:
raise ValueError(
"EventData partition key cannot be used with a partition sender."
)
event_data.message.on_send_complete = self._on_outcome
try:
self._handler.send_message(event_data.message)
if self._outcome != constants.MessageSendResult.Ok:
raise Sender._error(self._outcome, self._condition)
except errors.MessageException as failed:
error = EventHubError(str(failed), failed)
self.close(exception=error)
raise error
except (errors.TokenExpired, errors.AuthenticationException):
log.info(
"Sender disconnected due to token error. Attempting reconnect."
)
self.reconnect()
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry and self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except Exception as e:
log.info("Unexpected error occurred (%r). Shutting down.", e)
error = EventHubError("Send failed: {}".format(e))
self.close(exception=error)
raise error
else:
return self._outcome
def transfer(self, event_data, callback=None):
"""
Transfers an event data and notifies the callback when the operation is done.
:param event_data: The event to be sent.
:type event_data: ~azure.eventhub.common.EventData
:param callback: Callback to be run once the message has been send.
This must be a function that accepts two arguments.
:type callback: callable[~uamqp.constants.MessageSendResult, ~azure.eventhub.common.EventHubError]
"""
if self.error:
raise self.error
if not self.running:
raise ValueError("Unable to send until client has been started.")
if event_data.partition_key and self.partition:
raise ValueError(
"EventData partition key cannot be used with a partition sender."
)
if callback:
event_data.message.on_send_complete = lambda o, c: callback(
o, Sender._error(o, c))
self._handler.queue_message(event_data.message)
def wait(self):
"""
Wait until all transferred events have been sent.
"""
if self.error:
raise self.error
if not self.running:
raise ValueError("Unable to send until client has been started.")
try:
self._handler.wait()
except (errors.TokenExpired, errors.AuthenticationException):
log.info(
"Sender disconnected due to token error. Attempting reconnect."
)
self.reconnect()
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry and self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except Exception as e:
log.info("Unexpected error occurred (%r).", e)
raise EventHubError("Send failed: {}".format(e))
def _on_outcome(self, outcome, condition):
"""
Called when the outcome is received for a delivery.
:param outcome: The outcome of the message delivery - success or failure.
:type outcome: ~uamqp.constants.MessageSendResult
"""
self._outcome = outcome
self._condition = condition
@staticmethod
def _error(outcome, condition):
return None if outcome == constants.MessageSendResult.Ok else EventHubError(
outcome, condition)
class Sender(object):
"""
Implements a Sender.
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START create_eventhub_client_sender_instance]
:end-before: [END create_eventhub_client_sender_instance]
:language: python
:dedent: 4
:caption: Create a new instance of the Sender.
"""
def __init__(self, client, target, partition=None, send_timeout=60, keep_alive=None, auto_reconnect=True):
"""
Instantiate an EventHub event Sender handler.
:param client: The parent EventHubClient.
:type client: ~azure.eventhub.client.EventHubClient.
:param target: The URI of the EventHub to send to.
:type target: str
:param partition: The specific partition ID to send to. Default is None, in which case the service
will assign to all partitions using round-robin.
:type partition: str
:param send_timeout: The timeout in seconds for an individual event to be sent from the time that it is
queued. Default value is 60 seconds. If set to 0, there will be no timeout.
:type send_timeout: int
:param keep_alive: The time interval in seconds between pinging the connection to keep it alive during
periods of inactivity. The default value is None, i.e. no keep alive pings.
:type keep_alive: int
:param auto_reconnect: Whether to automatically reconnect the sender if a retryable error occurs.
Default value is `True`.
:type auto_reconnect: bool
"""
self.running = False
self.client = client
self.target = target
self.partition = partition
self.timeout = send_timeout
self.redirected = None
self.error = None
self.keep_alive = keep_alive
self.auto_reconnect = auto_reconnect
self.retry_policy = errors.ErrorPolicy(max_retries=3, on_error=_error_handler)
self.reconnect_backoff = 1
self.name = "EHSender-{}".format(uuid.uuid4())
if partition:
self.target += "/Partitions/" + partition
self.name += "-partition{}".format(partition)
self._handler = SendClient(
self.target,
auth=self.client.get_auth(),
debug=self.client.debug,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client.create_properties())
self._outcome = None
self._condition = None
def open(self):
"""
Open the Sender using the supplied conneciton.
If the handler has previously been redirected, the redirect
context will be used to create a new handler before opening it.
:param connection: The underlying client shared connection.
:type: connection: ~uamqp.connection.Connection
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_sender_open]
:end-before: [END eventhub_client_sender_open]
:language: python
:dedent: 4
:caption: Open the Sender using the supplied conneciton.
"""
self.running = True
if self.redirected:
self.target = self.redirected.address
self._handler = SendClient(
self.target,
auth=self.client.get_auth(),
debug=self.client.debug,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client.create_properties())
self._handler.open()
while not self._handler.client_ready():
time.sleep(0.05)
def _reconnect(self):
# pylint: disable=protected-access
self._handler.close()
unsent_events = self._handler.pending_messages
self._handler = SendClient(
self.target,
auth=self.client.get_auth(),
debug=self.client.debug,
msg_timeout=self.timeout,
error_policy=self.retry_policy,
keep_alive_interval=self.keep_alive,
client_name=self.name,
properties=self.client.create_properties())
try:
self._handler.open()
self._handler.queue_message(*unsent_events)
self._handler.wait()
return True
except errors.TokenExpired as shutdown:
log.info("Sender disconnected due to token expiry. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry and self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
return False
log.info("Sender reconnect failed. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
return False
log.info("Sender reconnect failed. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.AMQPConnectionError as shutdown:
if str(shutdown).startswith("Unable to open authentication session") and self.auto_reconnect:
log.info("Sender couldn't authenticate. Attempting reconnect.")
return False
log.info("Sender connection error (%r). Shutting down.", shutdown)
error = EventHubError(str(shutdown))
self.close(exception=error)
raise error
except Exception as e:
log.info("Unexpected error occurred (%r). Shutting down.", e)
error = EventHubError("Sender Reconnect failed: {}".format(e))
self.close(exception=error)
raise error
def reconnect(self):
"""If the Sender was disconnected from the service with
a retryable error - attempt to reconnect."""
while not self._reconnect():
time.sleep(self.reconnect_backoff)
def get_handler_state(self):
"""
Get the state of the underlying handler with regards to start
up processes.
:rtype: ~uamqp.constants.MessageSenderState
"""
# pylint: disable=protected-access
return self._handler._message_sender.get_state()
def has_started(self):
"""
Whether the handler has completed all start up processes such as
establishing the connection, session, link and authentication, and
is not ready to process messages.
**This function is now deprecated and will be removed in v2.0+.**
:rtype: bool
"""
# pylint: disable=protected-access
timeout = False
auth_in_progress = False
if self._handler._connection.cbs:
timeout, auth_in_progress = self._handler._auth.handle_token()
if timeout:
raise EventHubError("Authorization timeout.")
if auth_in_progress:
return False
if not self._handler._client_ready():
return False
return True
def close(self, exception=None):
"""
Close down the handler. If the handler has already closed,
this will be a no op. An optional exception can be passed in to
indicate that the handler was shutdown due to error.
:param exception: An optional exception if the handler is closing
due to an error.
:type exception: Exception
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_sender_close]
:end-before: [END eventhub_client_sender_close]
:language: python
:dedent: 4
:caption: Close down the handler.
"""
self.running = False
if self.error:
return
if isinstance(exception, errors.LinkRedirect):
self.redirected = exception
elif isinstance(exception, EventHubError):
self.error = exception
elif exception:
self.error = EventHubError(str(exception))
else:
self.error = EventHubError("This send handler is now closed.")
self._handler.close()
def send(self, event_data):
"""
Sends an event data and blocks until acknowledgement is
received or operation times out.
:param event_data: The event to be sent.
:type event_data: ~azure.eventhub.common.EventData
:raises: ~azure.eventhub.common.EventHubError if the message fails to
send.
:return: The outcome of the message send.
:rtype: ~uamqp.constants.MessageSendResult
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_sync_send]
:end-before: [END eventhub_client_sync_send]
:language: python
:dedent: 4
:caption: Sends an event data and blocks until acknowledgement is received or operation times out.
"""
if self.error:
raise self.error
if not self.running:
raise ValueError("Unable to send until client has been started.")
if event_data.partition_key and self.partition:
raise ValueError("EventData partition key cannot be used with a partition sender.")
event_data.message.on_send_complete = self._on_outcome
try:
self._handler.send_message(event_data.message)
if self._outcome != constants.MessageSendResult.Ok:
raise Sender._error(self._outcome, self._condition)
except errors.MessageException as failed:
error = EventHubError(str(failed), failed)
self.close(exception=error)
raise error
except (errors.TokenExpired, errors.AuthenticationException):
log.info("Sender disconnected due to token error. Attempting reconnect.")
self.reconnect()
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry and self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except Exception as e:
log.info("Unexpected error occurred (%r). Shutting down.", e)
error = EventHubError("Send failed: {}".format(e))
self.close(exception=error)
raise error
else:
return self._outcome
def transfer(self, event_data, callback=None):
"""
Transfers an event data and notifies the callback when the operation is done.
:param event_data: The event to be sent.
:type event_data: ~azure.eventhub.common.EventData
:param callback: Callback to be run once the message has been send.
This must be a function that accepts two arguments.
:type callback: callable[~uamqp.constants.MessageSendResult, ~azure.eventhub.common.EventHubError]
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_transfer]
:end-before: [END eventhub_client_transfer]
:language: python
:dedent: 4
:caption: Transfers an event data and notifies the callback when the operation is done.
"""
if self.error:
raise self.error
if not self.running:
raise ValueError("Unable to send until client has been started.")
if event_data.partition_key and self.partition:
raise ValueError("EventData partition key cannot be used with a partition sender.")
if callback:
event_data.message.on_send_complete = lambda o, c: callback(o, Sender._error(o, c))
self._handler.queue_message(event_data.message)
def wait(self):
"""
Wait until all transferred events have been sent.
Example:
.. literalinclude:: ../examples/test_examples_eventhub.py
:start-after: [START eventhub_client_transfer]
:end-before: [END eventhub_client_transfer]
:language: python
:dedent: 4
:caption: Wait until all transferred events have been sent.
"""
if self.error:
raise self.error
if not self.running:
raise ValueError("Unable to send until client has been started.")
try:
self._handler.wait()
except (errors.TokenExpired, errors.AuthenticationException):
log.info("Sender disconnected due to token error. Attempting reconnect.")
self.reconnect()
except (errors.LinkDetach, errors.ConnectionClose) as shutdown:
if shutdown.action.retry and self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except errors.MessageHandlerError as shutdown:
if self.auto_reconnect:
log.info("Sender detached. Attempting reconnect.")
self.reconnect()
else:
log.info("Sender detached. Shutting down.")
error = EventHubError(str(shutdown), shutdown)
self.close(exception=error)
raise error
except Exception as e:
log.info("Unexpected error occurred (%r).", e)
raise EventHubError("Send failed: {}".format(e))
def _on_outcome(self, outcome, condition):
"""
Called when the outcome is received for a delivery.
:param outcome: The outcome of the message delivery - success or failure.
:type outcome: ~uamqp.constants.MessageSendResult
"""
self._outcome = outcome
self._condition = condition
@staticmethod
def _error(outcome, condition):
return None if outcome == constants.MessageSendResult.Ok else EventHubError(outcome, condition)
class Sender:
"""
Implements a Sender.
"""
TIMEOUT = 60.0
def __init__(self, client, target, partition=None):
"""
Instantiate an EventHub event Sender handler.
:param client: The parent EventHubClient.
:type client: ~azure.eventhub.client.EventHubClient.
:param target: The URI of the EventHub to send to.
:type target: str
"""
self.redirected = None
self.error = None
self.debug = client.debug
self.partition = partition
if partition:
target += "/Partitions/" + partition
self._handler = SendClient(target,
auth=client.auth,
debug=self.debug,
msg_timeout=Sender.TIMEOUT)
self._outcome = None
self._condition = None
def open(self, connection):
"""
Open the Sender using the supplied conneciton.
If the handler has previously been redirected, the redirect
context will be used to create a new handler before opening it.
:param connection: The underlying client shared connection.
:type: connection: ~uamqp.connection.Connection
"""
if self.redirected:
self._handler = SendClient(self.redirected.address,
auth=None,
debug=self.debug,
msg_timeout=Sender.TIMEOUT)
self._handler.open(connection)
def get_handler_state(self):
"""
Get the state of the underlying handler with regards to start
up processes.
:rtype: ~uamqp.constants.MessageSenderState
"""
# pylint: disable=protected-access
return self._handler._message_sender.get_state()
def has_started(self):
"""
Whether the handler has completed all start up processes such as
establishing the connection, session, link and authentication, and
is not ready to process messages.
:rtype: bool
"""
# pylint: disable=protected-access
timeout = False
auth_in_progress = False
if self._handler._connection.cbs:
timeout, auth_in_progress = self._handler._auth.handle_token()
if timeout:
raise EventHubError("Authorization timeout.")
elif auth_in_progress:
return False
elif not self._handler._client_ready():
return False
else:
return True
def close(self, exception=None):
"""
Close down the handler. If the handler has already closed,
this will be a no op. An optional exception can be passed in to
indicate that the handler was shutdown due to error.
:param exception: An optional exception if the handler is closing
due to an error.
:type exception: Exception
"""
if self.error:
return
elif isinstance(exception, errors.LinkRedirect):
self.redirected = exception
elif isinstance(exception, EventHubError):
self.error = exception
elif exception:
self.error = EventHubError(str(exception))
else:
self.error = EventHubError("This send handler is now closed.")
self._handler.close()
def send(self, event_data):
"""
Sends an event data and blocks until acknowledgement is
received or operation times out.
:param event_data: The event to be sent.
:type event_data: ~azure.eventhub.common.EventData
:raises: ~azure.eventhub.common.EventHubError if the message fails to
send.
:return: The outcome of the message send.
:rtype: ~uamqp.constants.MessageSendResult
"""
if self.error:
raise self.error
if event_data.partition_key and self.partition:
raise ValueError(
"EventData partition key cannot be used with a partition sender."
)
event_data.message.on_send_complete = self._on_outcome
try:
self._handler.send_message(event_data.message)
if self._outcome != constants.MessageSendResult.Ok:
raise Sender._error(self._outcome, self._condition)
except errors.LinkDetach as detach:
error = EventHubError(str(detach))
self.close(exception=error)
raise error
except Exception as e:
error = EventHubError("Send failed: {}".format(e))
self.close(exception=error)
raise error
else:
return self._outcome
def transfer(self, event_data, callback=None):
"""
Transfers an event data and notifies the callback when the operation is done.
:param event_data: The event to be sent.
:type event_data: ~azure.eventhub.common.EventData
:param callback: Callback to be run once the message has been send.
This must be a function that accepts two arguments.
:type callback: func[~uamqp.constants.MessageSendResult, ~azure.eventhub.common.EventHubError]
"""
if self.error:
raise self.error
if event_data.partition_key and self.partition:
raise ValueError(
"EventData partition key cannot be used with a partition sender."
)
if callback:
event_data.message.on_send_complete = lambda o, c: callback(
o, Sender._error(o, c))
self._handler.queue_message(event_data.message)
def wait(self):
"""
Wait until all transferred events have been sent.
"""
if self.error:
raise self.error
try:
self._handler.wait()
except Exception as e:
raise EventHubError("Send failed: {}".format(e))
def _on_outcome(self, outcome, condition):
"""
Called when the outcome is received for a delivery.
:param outcome: The outcome of the message delivery - success or failure.
:type outcome: ~uamqp.constants.MessageSendResult
"""
self._outcome = outcome
self._condition = condition
@staticmethod
def _error(outcome, condition):
return None if outcome == constants.MessageSendResult.Ok else EventHubError(
outcome, condition)
