Azure Service Bus client library for Python

Azure Service Bus is a high performance cloud-managed messaging service for providing real-time and fault-tolerant communication between distributed senders and receivers.

Service Bus provides multiple mechanisms for asynchronous highly reliable communication, such as structured first-in-first-out messaging, publish/subscribe capabilities, and the ability to easily scale as your needs grow.

Use the Service Bus client library for Python to communicate between applications and services and implement asynchronous messaging patterns.

• Create Service Bus namespaces, queues, topics, and subscriptions, and modify their settings
• Send and receive messages within your Service Bus channels.
• Utilize message locks, sessions, and dead letter functionality to implement complex messaging patterns.

Note: This is a preview release of the Python Service Bus SDK, and is not yet at feature parity with version 0.50. Some functionality, such as topic and subscription utilization, will be arriving in upcoming Preview releases; Thank you for your patience and interest as we roll out these changes.

Source code | Package (PyPi) | API reference documentation | Product documentation | Samples | Changelog

Getting started

Install the package

Install the Azure Service Bus client library for Python with pip:

pip install azure-servicebus --pre

Prerequisites:

To use this package, you must have:

• Azure subscription - Create a free account
• Azure Service Bus - Namespace and management credentials
• Python 2.7, 3.5, 3.6, 3.7 or 3.8 - Install Python

If you need an Azure service bus namespace, you can create it via the Azure Portal. If you do not wish to use the graphical portal UI, you can use the Azure CLI via Cloud Shell, or Azure CLI run locally, to create one with this Azure CLI command:

az servicebus namespace create --resource-group <resource-group-name> --name <servicebus-namespace-name> --location <servicebus-namespace-location>

Authenticate the client

Interaction with Service Bus starts with an instance of the ServiceBusClient class. You either need a connection string with SAS key, or a namespace and one of its account keys to instantiate the client object.

Get credentials

Use the Azure CLI snippet below to populate an environment variable with the service bus connection string (you can also find these values in the Azure portal. The snippet is formatted for the Bash shell.

RES_GROUP=<resource-group-name>
NAMESPACE_NAME=<servicebus-namespace-name>

export SERVICE_BUS_CONN_STR=$(az servicebus namespace authorization-rule keys list --resource-group $RES_GROUP --namespace-name $NAMESPACE_NAME --query RootManageSharedAccessKey --output tsv)

Create client

Once you've populated the SERVICE_BUS_CONN_STR environment variable, you can create the ServiceBusClient.

from azure.servicebus import ServiceBusClient

import os
connstr = os.environ['SERVICE_BUS_CONN_STR']

with ServiceBusClient.from_connection_string(connstr) as client:
    ...

Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.

Key concepts

Once you've initialized a ServiceBusClient, you can interact with the primary resource types within a Service Bus Namespace, of which multiple can exist and on which actual message transmission takes place, the namespace often serving as an application container:

• Queue: Allows for Sending and Receiving of messages, ordered first-in-first-out. Often used for point-to-point communication.

• Topic: As opposed to Queues, Topics are better suited to publish/subscribe scenarios. A topic can be sent to, but requires a subscription, of which there can be multiple in parallel, to consume from.

• Subscription: The mechanism to consume from a Topic. Each subscription is independent, and receives a copy of each message sent to the topic. Rules and Filters can be used to tailor which messages are received by a specific subscription.

For more information about these resources, see What is Azure Service Bus?.

To interact with these resources, one should be familiar with the following SDK concepts:

• ServiceBusClient: This is the object a user should first initialize to connect to a Service Bus Namespace. To interact with a queue, topic, or subscription, one would spawn a sender or receiver off of this client.

• Sender: To send messages to a Queue or Topic, one would use the corresponding get_queue_sender or get_topic_sender method off of a ServiceBusClient instance as seen here.

• Receiver: To receive messages from a Queue or Subscription, one would use the corrosponding get_queue_receiver or get_subscription_receiver method off of a ServiceBusClient instance as seen here.

• Message: When sending, this is the type you will construct to contain your payload. When receiving, this is where you will access the payload and control how the message is "settled" (completed, dead-lettered, etc); these functions are only available on a received message.

Examples

The following sections provide several code snippets covering some of the most common Service Bus tasks, including:

• Send a message to a queue
• Receive a message from a queue
• Defer a message on receipt

Send to a queue

This example sends a message to a queue that is assumed to already exist, created via the Azure portal or az commands.

from azure.servicebus import ServiceBusClient

import os
connstr = os.environ['SERVICE_BUS_CONN_STR']

with ServiceBusClient.from_connection_string(connstr) as client:
    with client.get_queue_sender(queue_name):

        message = Message("Single message")
        queue_sender.send(message)

Receive from a queue

To receive from a queue, you can either perform a one-off receive via "receiver.receive()" or receive persistently as follows:

from azure.servicebus import ServiceBusClient

import os
connstr = os.environ['SERVICE_BUS_CONN_STR']

with ServiceBusClient.from_connection_string(connstr) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver:
            print(str(msg))
            msg.complete()

Defer a message

When receiving from a queue, you have multiple actions you can take on the messages you receive. Where the prior example completes a message, permanently removing it from the queue and marking as complete, this example demonstrates how to defer the message, sending it back to the queue such that it must now be received via sequence number:

from azure.servicebus import ServiceBusClient

import os
connstr = os.environ['SERVICE_BUS_CONN_STR']

with ServiceBusClient.from_connection_string(connstr) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver:
            print(str(msg))
            msg.defer()

Troubleshooting

Logging

• Enable azure.servicebus logger to collect traces from the library.
• Enable uamqp logger to collect traces from the underlying uAMQP library.
• Enable AMQP frame level trace by setting logging_enable=True when creating the client.

Next steps

More sample code

Please find further examples in the samples directory demonstrating common Service Bus scenarios such as sending, receiving, and message handling.

Additional documentation

For more extensive documentation on the Service Bus service, see the Service Bus documentation on docs.microsoft.com.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release History

7.0.0b1 (2020-04-06)

Version 7.0.0b1 is a preview of our efforts to create a client library that is user friendly and idiomatic to the Python ecosystem. The reasons for most of the changes in this update can be found in the Azure SDK Design Guidelines for Python. For more information, please visit https://aka.ms/azure-sdk-preview1-python.

• Note: Not all historical functionality exists in this version at this point. Topics, Subscriptions, scheduling, dead_letter management and more will be added incrementally over upcoming preview releases.

New Features

• Added new configuration parameters when creating ServiceBusClient.
  • credential: The credential object used for authentication which implements TokenCredential interface of getting tokens.
  • http_proxy: A dictionary populated with proxy settings.
  • For detailed information about configuration parameters, please see docstring in ServiceBusClient and/or the reference documentation for more information.
• Added support for authentication using Azure Identity credentials.
• Added support for retry policy.
• Added support for http proxy.
• Manually calling reconnect should no longer be necessary, it is now performed implicitly.
• Manually calling open should no longer be necessary, it is now performed implicitly.
  • Note: close()-ing is still required if a context manager is not used, to avoid leaking connections.
• Added support for sending a batch of messages destined for heterogenous sessions.

Breaking changes

• Simplified API and set of clients
  • get_queue no longer exists, utilize get_queue_sender/receiver instead.
  • peek and other queue_client functions have moved to their respective sender/receiver.
  • Renamed fetch_next to receive.
  • reconnect no longer exists, and is performed implicitly if needed.
  • open no longer exists, and is performed implicitly if needed.
• Normalized top level client parameters with idiomatic and consistent naming.
  • Renamed debug in ServiceBusClient initializer to logging_enable.
  • Renamed service_namespace in ServiceBusClient initializer to fully_qualified_namespace.
• New error hierarchy, with more specific semantics
  • azure.servicebus.exceptions.ServiceBusError
  • azure.servicebus.exceptions.ServiceBusConnectionError
  • azure.servicebus.exceptions.ServiceBusResourceNotFound
  • azure.servicebus.exceptions.ServiceBusAuthorizationError
  • azure.servicebus.exceptions.NoActiveSession
  • azure.servicebus.exceptions.OperationTimeoutError
  • azure.servicebus.exceptions.InvalidHandlerState
  • azure.servicebus.exceptions.AutoLockRenewTimeout
  • azure.servicebus.exceptions.AutoLockRenewFailed
  • azure.servicebus.exceptions.EventDataSendError
  • azure.servicebus.exceptions.MessageSendFailed
  • azure.servicebus.exceptions.MessageLockExpired
  • azure.servicebus.exceptions.MessageSettleFailed
  • azure.servicebus.exceptions.MessageAlreadySettled
  • azure.servicebus.exceptions.SessionLockExpired
• BatchMessage creation is now initiated via create_batch on a Sender, using add() on the batch to add messages, in order to enforce service-side max batch sized limitations.
• Session is now set on the message itself, via session_id parameter or property, as opposed to on Send or get_sender via session. This is to allow sending a batch of messages destined to varied sessions.
• Session management is now encapsulated within a property of a receiver, e.g. receiver.session, to better compartmentalize functionality specific to sessions.
  • To use AutoLockRenew against sessions, one would simply pass the inner session object, instead of the receiver itself.

0.50.2 (2019-12-09)

New Features

• Added support for delivery tag lock tokens

BugFixes

• Fixed bug where Message would pass through invalid kwargs on init when attempting to thread through subject.
• Increments UAMQP dependency min version to 1.2.5, to include a set of fixes, including handling of large messages and mitigation of segfaults.

0.50.1 (2019-06-24)

BugFixes

• Fixed bug where enqueued_time and scheduled_enqueue_time of message being parsed as local timestamp rather than UTC.

0.50.0 (2019-01-17)

Breaking changes

• Introduces new AMQP-based API.
• Original HTTP-based API still available under new namespace: azure.servicebus.control_client
• For full API changes, please see updated reference documentation.

Within the new namespace, the original HTTP-based API from version 0.21.1 remains unchanged (i.e. no additional features or bugfixes) so for those intending to only use HTTP operations - there is no additional benefit in updating at this time.

New Features

• New API supports message send and receive via AMQP with improved performance and stability.
• New asynchronous APIs (using asyncio) for send, receive and message handling.
• Support for message and session auto lock renewal via background thread or async operation.
• Now supports scheduled message cancellation.

0.21.1 (2017-04-27)

This wheel package is now built with the azure wheel extension

0.21.0 (2017-01-13)

New Features

• str messages are now accepted in Python 3 and will be encoded in 'utf-8' (will not raise TypeError anymore)
• broker_properties can now be defined as a dict, and not only a JSON str. datetime, int, float and boolean are converted.
• #902 add send_topic_message_batch operation (takes an iterable of messages)
• #902 add send_queue_message_batch operation (takes an iterable of messages)

Bugfixes

• #820 the code is now more robust to unexpected changes on the SB RestAPI

0.20.3 (2016-08-11)

News

• #547 Add get dead letter path static methods to Python
• #513 Add renew lock

Bugfixes

• #628 Fix custom properties with double quotes

0.20.2 (2016-06-28)

Bugfixes

• New header in Rest API which breaks the SDK #658 #657

0.20.1 (2015-09-14)

News

• Create a requests.Session() if the user doesn't pass one in.

0.20.0 (2015-08-31)

Initial release of this package, from the split of the azure package. See the azure package release note for 1.0.0 for details and previous history on Service Bus.