Metadata-Version: 2.1
Name: azure-servicebus
Version: 7.0.0b4
Summary: Microsoft Azure Service Bus Client Library for Python
Home-page: https://github.com/Azure/azure-sdk-for-python
Author: Microsoft Corporation
Author-email: azpysdkhelp@microsoft.com
License: MIT License
Description: # 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.
        
        [Source code](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus) | [Package (PyPi)][pypi] | [API reference documentation][api_docs] | [Product documentation][product_docs] | [Samples](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples) | [Changelog](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/CHANGELOG.md)
        
        > **NOTE**: This document has instructions, links and code snippets for the **preview** of the next version of the `azure-servicebus` package
        > which has different APIs than the current version (0.50). Please view the resources below for references on the existing library.
        
        [V0.50 Source code][0_50_source] | [V0.50 Package (PyPi)][0_50_pypi] | [V0.50 API reference documentation][0_50_api_docs] | [V0.50 Product documentation][0_50_product_docs] | [V0.50 Samples][0_50_samples] | [V0.50 Changelog][0_50_changelog]
        
        We also provide a migration guide for users familiar with the existing package that would like to try the preview: [migration guide to move from Service Bus V0.50 to Service Bus V7 Preview][migration_guide]
        
        ## Getting started
        
        ### Install the package
        
        Install the Azure Service Bus client library for Python with [pip][pip]:
        
        ```Bash
        pip install azure-servicebus --pre
        ```
        
        ### Prerequisites: 
        To use this package, you must have:
        * Azure subscription - [Create a free account][azure_sub]
        * Azure Service Bus - [Namespace and management credentials][service_bus_namespace]
        * Python 2.7, 3.5 or later - [Install Python][python]
        
        
        If you need an Azure service bus namespace, you can create it via the [Azure Portal][azure_namespace_creation].
        If you do not wish to use the graphical portal UI, you can use the Azure CLI via [Cloud Shell][cloud_shell_bash], or Azure CLI run locally, to create one with this Azure CLI command:
        
        ```Bash
        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.
        
        #### Create client from connection string
        
        - Get credentials: Use the [Azure CLI][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][azure_portal] by following the step-by-step guide to [Get a service bus connection string][get_servicebus_conn_str]). The snippet is formatted for the Bash shell.
        
        ```Bash
        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 --name RootManageSharedAccessKey --query primaryConnectionString --output tsv)
        ```
        
        Once you've populated the `SERVICE_BUS_CONN_STR` environment variable, you can create the `ServiceBusClient`.
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        
        with ServiceBusClient.from_connection_string(connstr) as client:
            ...
        ```
        
        #### Create client using the azure-identity library:
        
        ```python
        import os
        from azure.servicebus import ServiceBusClient
        from azure.identity import DefaultAzureCredential
        
        credential = DefaultAzureCredential()
        
        FULLY_QUALIFIED_NAMESPACE = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE']
        with ServiceBusClient(FULLY_QUALIFIED_NAMESPACE, credential):
            ...
        ```
        
        - This constructor takes the fully qualified namespace of your Service Bus instance and a credential that implements the
        [TokenCredential][token_credential_interface]
        protocol. There are implementations of the `TokenCredential` protocol available in the
        [azure-identity package][pypi_azure_identity]. The fully qualified namespace is of the format `<yournamespace.servicebus.windows.net>`.
        - When using Azure Active Directory, your principal must be assigned a role which allows access to Service Bus, such as the
        Azure Service Bus Data Owner role. For more information about using Azure Active Directory authorization with Service Bus,
        please refer to [the associated documentation][servicebus_aad_authentication].
        
        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][queue_concept]: Allows for Sending and Receiving of message.  Often used for point-to-point communication.
        
        * [Topic][topic_concept]: 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][subscription_concept]: 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?][service_bus_overview].
        
        To interact with these resources, one should be familiar with the following SDK concepts:
        
        * [ServiceBusClient][client_reference]: 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][sender_reference]: 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](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples/sync_samples/send_queue.py).
        
        * [Receiver][receiver_reference]: To receive messages from a Queue or Subscription, one would use the corresponding `get_queue_receiver` or `get_subscription_receiver` method off of a `ServiceBusClient` instance as seen [here](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples/sync_samples/receive_queue.py).
        
        * [Message][message_reference]: 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 messages to a queue](#send-messages-to-a-queue)
        * [Receive messages from a queue](#receive-messages-from-a-queue)
        * [Send and receive a message from a session enabled queue](#send-and-receive-a-message-from-a-session-enabled-queue)
        * [Working with topics and subscriptions](#working-with-topics-and-subscriptions)
        * [Settle a message after receipt](#settle-a-message-after-receipt)
        
        To perform management tasks such as creating and deleting queues/topics/subscriptions, please utilize the azure-mgmt-servicebus library, available [here][servicebus_management_repository].
        
        Please find further examples in the [samples](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples) directory demonstrating common Service Bus scenarios such as sending, receiving, session management and message handling.
        
        ### [Send messages to a queue][send_reference]
        
        This example sends single message and array of messages to a queue that is assumed to already exist, created via the Azure portal or az commands.
        
        ```Python
        from azure.servicebus import ServiceBusClient, Message
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        with ServiceBusClient.from_connection_string(connstr) as client:
            with client.get_queue_sender(queue_name) as sender:
                # Sending a single message
                single_message = Message("Single message")
                sender.send_messages(single_message)
        
                # Sending a list of messages
                messages = [Message("First message"), Message("Second message")]
                sender.send_messages(messages)
        ```
        
        > **NOTE:** A message may be scheduled for delayed delivery using the `ServiceBusSender.schedule_messages()` method, or by specifying `Message.scheduled_enqueue_time_utc` before calling `ServiceBusSender.send_messages()`
        > For more detail on scheduling and schedule cancellation please see a sample [here](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples/sync_samples/schedule_messages_and_cancellation.py).
        
        ### Receive messages from a queue
        
        To receive from a queue, you can either perform an ad-hoc receive via "receiver.receive_messages()" or receive persistently through the receiver itself.
        
        #### Receive messages from a queue through iterating over ServiceBusReceiver
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        with ServiceBusClient.from_connection_string(connstr) as client:
            # idle_timeout specifies how long the receiver should wait with no incoming messages before stopping receipt.  
            # Default is None; to receive forever.
            with client.get_queue_receiver(queue_name, idle_timeout=30) as receiver:
                for msg in receiver:  # ServiceBusReceiver instance is a generator
                    print(str(msg))
                    # If it is desired to halt receiving early, one can break out of the loop here safely.
        ```
        
        > **NOTE:** Any message received with `mode=PeekLock` (this is the default, with the alternative ReceiveAndDelete removing the message from the queue immediately on receipt)
        > has a lock that must be renewed via `message.renew_lock()` before it expires if processing would take longer than the lock duration.  
        > See [AutoLockRenewer](#autolockrenew) for a helper to perform this in the background automatically.
        > Lock duration is set in Azure on the queue or topic itself.
        
        #### [Receive messages from a queue through `ServiceBusReceiver.receive_messages()`][receive_reference]
        
        > **NOTE:** `ServiceBusReceiver.receive_messages()` receives a single or constrained list of messages through an ad-hoc method call, as opposed to receiving perpetually from the generator. It always returns a list.
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        with ServiceBusClient.from_connection_string(connstr) as client:
            with client.get_queue_receiver(queue_name) as receiver:
                received_message_array = receiver.receive_messages(max_wait_time=10)  # try to receive a single message within 10 seconds
                if received_message_array:
                    print(str(received_message_array[0]))
        
            with client.get_queue_receiver(queue_name, prefetch=5) as receiver:
                received_message_array = receiver.receive_messages(max_batch_size=5, max_wait_time=10)  # try to receive maximum 5 messages in a batch within 10 seconds
                for message in received_message_array:
                    print(str(message))
        ```
        
        In this example, max_batch_size (and prefetch, as required by max_batch_size) declares the maximum number of messages to attempt receiving before hitting a max_wait_time as specified in seconds.
        
        > **NOTE:** It should also be noted that `ServiceBusReceiver.peek_messages()` is subtly different than receiving, as it does not lock the messages being peeked, and thus they cannot be settled.
        
        
        ### [Send][session_send_reference] and [receive][session_receive_reference] a message from a session enabled queue
        
        Sessions provide first-in-first-out and single-receiver semantics on top of a queue or subscription.  While the actual receive syntax is the same, initialization differs slightly.
        
        ```Python
        from azure.servicebus import ServiceBusClient, Message
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        session_id = os.environ['SERVICE_BUS_SESSION_ID']
        
        with ServiceBusClient.from_connection_string(connstr) as client:
            with client.get_queue_sender(queue_name) as sender:
                sender.send_messages(Message("Session Enabled Message", session_id=session_id))
        
            # If session_id is null here, will receive from the first available session.
            with client.get_queue_session_receiver(queue_name, session_id) as receiver:
                for msg in receiver:
                    print(str(msg))
        ```
        
        > **NOTE**: Messages received from a session do not need their locks renewed like a non-session receiver; instead the lock management occurs at the
        > session level with a session lock that may be renewed with `receiver.session.renew_lock()`
        
        
        ### Working with [topics][topic_reference] and [subscriptions][subscription_reference]
        
        Topics and subscriptions give an alternative to queues for sending and receiving messages.  See documents [here][topic_concept] for more overarching detail,
        and of how these differ from queues.
        
        ```Python
        from azure.servicebus import ServiceBusClient, Message
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        topic_name = os.environ['SERVICE_BUS_TOPIC_NAME']
        subscription_name = os.environ['SERVICE_BUS_SUBSCRIPTION_NAME']
        
        with ServiceBusClient.from_connection_string(connstr) as client:
            with client.get_topic_sender(topic_name) as sender:
                sender.send_messages(Message("Data"))
        
            # If session_id is null here, will receive from the first available session.
            with client.get_subscription_receiver(topic_name, subscription_name) as receiver:
                for msg in receiver:
                    print(str(msg))
        ```
        
        ### Settle a message after receipt
        
        When receiving from a queue, you have multiple actions you can take on the messages you receive.
        
        > **NOTE**: You can only settle `ReceivedMessage` objects which are received in `ReceiveSettleMode.PeekLock` mode (this is the default).
        > `ReceiveSettleMode.ReceiveAndDelete` mode removes the message from the queue on receipt.  `PeekMessage` messages
        > returned from `peek()` cannot be settled, as the message lock is not taken like it is in the aforementioned receive methods.  Sessionful messages have a similar limitation.
        
        If the message has a lock as mentioned above, settlement will fail if the message lock has expired.  
        If processing would take longer than the lock duration, it must be maintained via `message.renew_lock()` before it expires.  
        Lock duration is set in Azure on the queue or topic itself.
        See [AutoLockRenewer](#autolockrenew) for a helper to perform this in the background automatically.
        
        #### [Complete][complete_reference]
        
        Declares the message processing to be successfully completed, removing the message from the queue.
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        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()
        ```
        
        #### [Abandon][abandon_reference]
        
        Abandon processing of the message for the time being, returning the message immediately back to the queue to be picked up by another (or the same) receiver.
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        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.abandon()
        ```
        
        #### [DeadLetter][deadletter_reference]
        
        Transfer the message from the primary queue into a special "dead-letter sub-queue" where it can be accessed using the `ServiceBusClient.get_<queue|subscription>_deadletter_receiver` function and consumed from like any other receiver. (see sample [here](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples/sync_samples/receive_deadlettered_messages.py))
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        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.dead_letter()
        ```
        
        #### [Defer][defer_reference]
        
        Defer is subtly different from the prior settlement methods.  It prevents the message from being directly received from the queue
        by setting it aside such that it must be received by sequence number in a call to `ServiceBusReceiver.receive_deferred_messages` (see sample [here](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples/sync_samples/receive_deferred_message_queue.py))
        
        ```Python
        from azure.servicebus import ServiceBusClient
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        
        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.
        
        ### Timeouts
        
        There are various timeouts a user should be aware of within the library.
        - 10 minute service side link closure:  A link, once opened, will be closed after 10 minutes idle to protect the service against resource leakage.  This should largely
        be transparent to a user, but if you notice a reconnect occurring after such a duration, this is why.  Performing any operations, including management operations, on the
        link will extend this timeout.
        - idle_timeout: Provided on creation of a receiver, the time after which the underlying UAMQP link will be closed after no traffic.  This primarily dictates the length
        a generator-style receive will run for before exiting if there are no messages.  Passing None (default) will wait forever, up until the 10 minute threshold if no other action is taken.
        - max_wait_time: Provided when calling receive() to fetch a list of messages.  Dictates an upper bound for how long the receive() will wait for more messages before returning, similarly up to the aformentioned limits.  The "receive()" will return as soon as at least one message is received within the max_wait_time.
        
        > **NOTE:** If processing of a message or session is sufficiently long as to cause timeouts, as an alternative to calling `renew_lock()` manually, one can
        > leverage the `AutoLockRenew` functionality detailed below.
        
        ### [AutoLockRenew][autolockrenew_reference]
        
        `AutoLockRenew` is a simple method for ensuring your message or session remains locked even over long periods of time, if calling `renew_lock()` is impractical or undesired.
        Internally, it is not much more than shorthand for creating a concurrent watchdog to call `renew_lock()` if the object is nearing expiry.
        It should be used as follows:
        
        ```python
        from azure.servicebus import ServiceBusClient, AutoLockRenew
        
        import os
        connstr = os.environ['SERVICE_BUS_CONN_STR']
        queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
        session_id = os.environ['SERVICE_BUS_SESSION_ID']
        
        # Can also be called via "with AutoLockRenew() as renewer" to automate shutdown.
        renewer = AutoLockRenew()
        with ServiceBusClient.from_connection_string(connstr) as client:
            with client.get_queue_session_receiver(queue_name, session_id=session_id) as receiver:
                renewer.register(receiver.session, timeout=300) # Timeout for how long to maintain the lock for, in seconds.
                for msg in receiver.receive_messages():
                    renewer.register(msg, timeout=60)
                    # Do your application logic here
                    msg.complete()
        renewer.shutdown()
        ```
        
        If for any reason auto-renewal has been interrupted or failed, this can be observed via the `auto_renew_error` property on the object being renewed.
        It would also manifest when trying to take action (such as completing a message) on the specified object.
        
        ### Common Exceptions
        
        Please view the [exceptions reference docs][exception_reference] for detailed descriptions of our common Exception types.
        
        ## Next steps
        
        ### More sample code
        
        Please find further examples in the [samples](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/samples) directory demonstrating common Service Bus scenarios such as sending, receiving, session management and message handling.
        
        ### Additional documentation
        
        For more extensive documentation on the Service Bus service, see the [Service Bus documentation][service_bus_docs] on docs.microsoft.com.
        
        ### Management capabilities and documentation
        
        For users seeking to perform management operations against ServiceBus (Creating a queue/topic/etc, altering filter rules, enumerating entities)
        please see the [azure-mgmt-servicebus documentation][service_bus_mgmt_docs] for API documentation.  Terse usage examples can be found
        [here](https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-mgmt-servicebus/tests) as well.
        
        ## 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](https://opensource.microsoft.com/codeofconduct/).
        For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
        contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
        
        <!-- LINKS -->
        [azure_cli]: https://docs.microsoft.com/cli/azure
        [api_docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/index.html
        [product_docs]: https://docs.microsoft.com/azure/service-bus-messaging/
        [azure_portal]: https://portal.azure.com
        [azure_sub]: https://azure.microsoft.com/free/
        [cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview
        [cloud_shell_bash]: https://shell.azure.com/bash
        [pip]: https://pypi.org/project/pip/
        [pypi]: https://pypi.org/project/azure-servicebus/7.0.0b4/
        [python]: https://www.python.org/downloads/
        [venv]: https://docs.python.org/3/library/venv.html
        [virtualenv]: https://virtualenv.pypa.io
        [service_bus_namespace]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-create-namespace-portal
        [service_bus_overview]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview
        [queue_status_codes]: https://docs.microsoft.com/rest/api/servicebus/create-queue#response-codes
        [service_bus_docs]: https://docs.microsoft.com/azure/service-bus/
        [service_bus_mgmt_docs]: https://docs.microsoft.com/en-us/python/api/overview/azure/servicebus/management?view=azure-python
        [queue_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview#queues
        [topic_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview#topics
        [subscription_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions
        [azure_namespace_creation]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal
        [servicebus_management_repository]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/servicebus/azure-mgmt-servicebus
        [get_servicebus_conn_str]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal#get-the-connection-string
        [servicebus_aad_authentication]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-authentication-and-authorization
        [token_credential_interface]: https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/core/azure-core/azure/core/credentials.py
        [pypi_azure_identity]: https://pypi.org/project/azure-identity/
        [message_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#azure.servicebus.Message
        [receiver_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#azure.servicebus.ServiceBusReceiver
        [sender_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#azure.servicebus.ServiceBusSender
        [client_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#azure.servicebus.ServiceBusClient
        [send_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=send#azure.servicebus.ServiceBusSender.send
        [receive_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=receive#azure.servicebus.ServiceBusReceiver.receive
        [session_receive_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=receive#azure.servicebus.ServiceBusSessionReceiver.receive
        [session_send_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=session_id#azure.servicebus.Message.session_id
        [complete_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=complete#azure.servicebus.ReceivedMessage.complete
        [abandon_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=abandon#azure.servicebus.ReceivedMessage.abandon
        [defer_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=defer#azure.servicebus.ReceivedMessage.defer
        [deadletter_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=dead_letter#azure.servicebus.ReceivedMessage.dead_letter
        [autolockrenew_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#azure.servicebus.AutoLockRenew
        [exception_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#module-azure.servicebus.exceptions
        [subscription_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.aio.html?highlight=subscription#azure.servicebus.aio.ServiceBusClient.get_subscription_receiver
        [topic_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=topic#azure.servicebus.ServiceBusClient.get_topic_sender
        [0_50_source]: https://github.com/Azure/azure-sdk-for-python/tree/servicebus_v0.50.3/sdk/servicebus/azure-servicebus/
        [0_50_pypi]: https://pypi.org/project/azure-servicebus/
        [0_50_api_docs]:https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/0.50.3/index.html
        [0_50_product_docs]: https://docs.microsoft.com/azure/service-bus-messaging/
        [0_50_samples]: https://github.com/Azure/azure-sdk-for-python/tree/servicebus_v0.50.3/sdk/servicebus/azure-servicebus/samples
        [0_50_changelog]: https://github.com/Azure/azure-sdk-for-python/blob/servicebus_v0.50.3/sdk/servicebus/azure-servicebus/CHANGELOG.md
        [migration_guide]: https://github.com/Azure/azure-sdk-for-python/tree/c9442231fef287de0233da371985ef8cdc54f859/sdk/servicebus/azure-servicebus/migration_guide.md
        
        
        # Release History
        
        ## 7.0.0b4 (2020-07-06)
        
        **New Features**
        
        * Added support for management of topics, subscriptions, and rules.
        * `receive_messages()` (formerly `receive()`) now supports receiving a batch of messages (`max_batch_size` > 1) without the need to set `prefetch` parameter during `ServiceBusReceiver` initialization.
        
        **BugFixes**
        
        * Fixed bug where sync AutoLockRenew does not shutdown itself timely.
        * Fixed bug where async AutoLockRenew does not support context manager.
        
        **Breaking Changes**
        
        * Renamed `receive()`, `peek()` `schedule()` and `send()` to `receive_messages()`, `peek_messages()`, `schedule_messages()` and `send_messages()` to align with other service bus SDKs.
        * `receive_messages()` (formerly `receive()`) no longer raises a `ValueError` if `max_batch_size` is less than the `prefetch` parameter set during `ServiceBusReceiver` initialization.
        
        ## 7.0.0b3 (2020-06-08)
        
        **New Features**
        
        * Added support for management of queue entities.
            - Use `azure.servicebus.management.ServiceBusManagementClient` (`azure.servicebus.management.aio.ServiceBusManagementClient` for aio) to create, update, delete, list queues and get settings as well as runtime information of queues under a ServiceBus namespace.
        * Added methods `get_queue_deadletter_receiver` and `get_subscription_deadletter_receiver` in `ServiceBusClient` to get a `ServiceBusReceiver` for the dead-letter sub-queue of the target entity.
        
        **BugFixes**
        
        * Updated uAMQP dependency to 1.2.8.
            * Fixed bug where reason and description were not being set when dead-lettering messages.
        
        ## 7.0.0b2 (2020-05-04)
        
        **New Features**
        
        * Added method `get_topic_sender` in `ServiceBusClient` to get a `ServiceBusSender` for a topic.
        * Added method `get_subscription_receiver` in `ServiceBusClient` to get a `ServiceBusReceiver` for a subscription under specific topic.
        * Added support for scheduling messages and scheduled message cancellation.
            - Use `ServiceBusSender.schedule(messages, schedule_time_utc)` for scheduling messages.
            - Use `ServiceBusSender.cancel_scheduled_messages(sequence_numbers)` for scheduled messages cancellation.
        * `ServiceBusSender.send()` can now send a list of messages in one call, if they fit into a single batch.  If they do not fit a `ValueError` is thrown.
        * `BatchMessage.add()` and `ServiceBusSender.send()` would raise `MessageContentTooLarge` if the content is over-sized.
        * `ServiceBusReceiver.receive()` raises `ValueError` if its param `max_batch_size` is greater than param `prefetch` of `ServiceBusClient`.
        * Added exception classes `MessageError`, `MessageContentTooLarge`, `ServiceBusAuthenticationError`.
           - `MessageError`: when you send a problematic message, such as an already sent message or an over-sized message.
           - `MessageContentTooLarge`: when you send an over-sized message. A subclass of `ValueError` and `MessageError`.
           - `ServiceBusAuthenticationError`: on failure to be authenticated by the service.
        * Removed exception class `InvalidHandlerState`.
        
        **BugFixes**
        
        * Fixed bug where http_proxy and transport_type in ServiceBusClient are not propagated into Sender/Receiver creation properly.
        * Updated uAMQP dependency to 1.2.7.
            * Fixed bug in setting certificate of tlsio on MacOS. #7201
            * Fixed bug that caused segmentation fault in network tracing on MacOS when setting `logging_enable` to `True` in `ServiceBusClient`.
        
        **Breaking Changes**
        
        * Session receivers are now created via their own top level functions, e.g. `get_queue_sesison_receiver` and `get_subscription_session_receiver`.  Non session receivers no longer take session_id as a paramter.
        * `ServiceBusSender.send()` no longer takes a timeout parameter, as it should be redundant with retry options provided when creating the client.
        * Exception imports have been removed from module `azure.servicebus`. Import from `azure.servicebus.exceptions` instead.
        * `ServiceBusSender.schedule()` has swapped the ordering of parameters `schedule_time_utc` and `messages` for better consistency with `send()` syntax.
        
        ## 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`.
            * Renamed `session` to `session_id` to normalize naming when requesting a receiver against a given session.
            * `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](https://docs.microsoft.com/python/api/overview/azure/servicebus/client?view=azure-python).
        
        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.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Description-Content-Type: text/markdown
