Metadata-Version: 2.1
Name: azure-eventgrid
Version: 2.0.0b1
Summary: Microsoft Azure Event Grid 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 Event Grid client library for Python
        
        Azure Event Grid is a fully-managed intelligent event routing service that allows for uniform event consumption using a publish-subscribe model.
        
        [Source code][python-eg-src] | [Package (PyPI)][python-eg-pypi] | [API reference documentation][python-eg-ref-docs]| [Product documentation][python-eg-product-docs] | [Samples][python-eg-samples]| [Changelog][python-eg-changelog]
        
        ## Getting started
        
        ### Prerequisites
        * Python 2.7, or 3.5 or later is required to use this package.
        * You must have an [Azure subscription][azure_subscription] and an Event Grid Topic resource to use this package.
        
        ### Install the package
        Install the Azure Event Grid client library for Python with [pip][pip]:
        
        ```bash
        pip install azure-eventgrid
        ```
        
        #### Create an Event Grid Topic
        You can create the resource using [Azure Portal][azure_portal_create_EG_resource]
        
        ### Authenticate the client
        In order to interact with the Event Grid service, you will need to create an instance of a client.
        A **topic_hostname** and **credential** are necessary to instantiate the client object.
        
        #### Looking up the endpoint
        You can find the endpoint and the hostname on the Azure portal.
        
        #### Create the client with AzureKeyCredential
        
        To use an API key as the `credential` parameter,
        pass the key as a string into an instance of [AzureKeyCredential][azure-key-credential].
        
        ```python
        from azure.core.credentials import AzureKeyCredential
        from azure.eventgrid import EventGridPublisherClient
        
        topic_hostname = "https://<name>.<region>.eventgrid.azure.net"
        credential = AzureKeyCredential("<api_key>")
        eg_publisher_client = EventGridPublisherClient(topic_hostname, credential)
        ```
        
        ## Key concepts
        
        Information about the key concepts on Event Grid, see [Concepts in Azure Event Grid][publisher-service-doc]
        
        ### EventGridPublisherClient
        `EventGridPublisherClient` provides operations to send event data to topic hostname specified during client initialization.
        Either a list or a single instance of CloudEvent/EventGridEvent/CustomEvent can be sent.
        
        ### EventGridConsumer
        `EventGridConsumer` is used to desrialize an event received.
        
        ## Examples
        
        The following sections provide several code snippets covering some of the most common Event Grid tasks, including:
        
        * [Send an Event Grid Event](#send-an-eventgrid-event)
        * [Send a Cloud Event](#send-a-cloud-event)
        * [Consume an eventgrid Event](#consume-an-eventgrid-event)
        * [Consume a cloud Event](#consume-a-cloud-event)
        
        ### Send an Event Grid Event
        
        This example publishes an Event Grid event.
        
        ```Python
        import os
        from azure.core.credentials import AzureKeyCredential
        from azure.eventgrid import EventGridPublisherClient, EventGridEvent
        
        key = os.environ["EG_ACCESS_KEY"]
        topic_hostname = os.environ["EG_TOPIC_HOSTNAME"]
        
        event = EventGridEvent(
            subject="Door1",
            data={"team": "azure-sdk"},
            event_type="Azure.Sdk.Demo",
            data_version="2.0"
        )
        
        credential = AzureKeyCredential(key)
        client = EventGridPublisherClient(topic_hostname, credential)
        
        client.send(event)
        ```
        
        ### Send a Cloud Event
        
        This example publishes a Cloud event.
        
        ```Python
        import os
        from azure.core.credentials import AzureKeyCredential
        from azure.eventgrid import EventGridPublisherClient, CloudEvent
        
        key = os.environ["CLOUD_ACCESS_KEY"]
        topic_hostname = os.environ["CLOUD_TOPIC_HOSTNAME"]
        
        event = CloudEvent(
            type="Azure.Sdk.Sample",
            source="https://egsample.dev/sampleevent",
            data={"team": "azure-sdk"}
        )
        
        credential = AzureKeyCredential(key)
        client = EventGridPublisherClient(topic_hostname, credential)
        
        client.send(event)
        ```
        
        ### Consume an Event Grid Event
        
        This example demonstrates consuming and deserializing an eventgrid event.
        
        ```Python
        import os
        from azure.eventgrid import EventGridConsumer
        
        consumer = EventGridConsumer()
        
        eg_storage_dict = {
            "id":"bbab625-dc56-4b22-abeb-afcc72e5290c",
            "subject":"/blobServices/default/containers/oc2d2817345i200097container/blobs/oc2d2817345i20002296blob",
            "data":{
                "api":"PutBlockList",
            },
            "eventType":"Microsoft.Storage.BlobCreated",
            "dataVersion":"2.0",
            "metadataVersion":"1",
            "eventTime":"2020-08-07T02:28:23.867525Z",
            "topic":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/eventgridegsub"
        }
        
        deserialized_event = consumer.decode_eventgrid_event(eg_storage_dict)
        
        # both allow access to raw properties as strings
        time_string = deserialized_event.time
        time_string = deserialized_event["time"]
        ```
        
        ### Consume a Cloud Event
        
        This example demonstrates consuming and deserializing a cloud event.
        
        ```Python
        import os
        from azure.eventgrid import EventGridConsumer
        
        consumer = EventGridConsumer()
        
        cloud_storage_dict = {
            "id":"a0517898-9fa4-4e70-b4a3-afda1dd68672",
            "source":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}",
            "data":{
                "api":"PutBlockList",
            },
            "type":"Microsoft.Storage.BlobCreated",
            "time":"2020-08-07T01:11:49.765846Z",
            "specversion":"1.0"
        }
        
        deserialized_event = consumer.decode_cloud_event(cloud_storage_dict)
        
        # both allow access to raw properties as strings
        time_string = deserialized_event.time
        time_string = deserialized_event["time"]
        ```
        
        ## Troubleshooting
        
        - Enable `azure.eventgrid` logger to collect traces from the library.
        
        ### General
        Event Grid client library will raise exceptions defined in [Azure Core][azure_core_exceptions].
        
        ### Logging
        This library uses the standard
        [logging][python_logging] library for logging.
        Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
        level.
        
        ### Optional Configuration
        
        Optional keyword arguments can be passed in at the client and per-operation level.
        The azure-core [reference documentation][azure_core_ref_docs]
        describes available configurations for retries, logging, transport protocols, and more.
        
        ## Next steps
        
        The following section provides several code snippets illustrating common patterns used in the Event Grid Python API.
        
        ### More sample code
        
        These code samples show common champion scenario operations with the Azure Event Grid client library.
        
        * Publish Custom Events to a topic: [cs1_publish_custom_events_to_a_topic.py][python-eg-sample-customevent]
        * Publish Custom events to a domain topic: [cs2_publish_custom_events_to_a_domain_topic.py][python-eg-sample-customevent-to-domain]
        * Deserialize a System Event: [cs3_consume_system_events.py][python-eg-sample-consume-systemevent]
        * Deserialize a Custom Event: [cs4_consume_custom_events.py][python-eg-sample-consume-customevent]
        * Deserialize a Cloud Event: [cs5_consume_events_using_cloud_events_1.0_schema.py][python-eg-sample-consume-cloudevent]
        * Publish a Cloud Event: [cs6_publish_events_using_cloud_events_1.0_schema.py][python-eg-sample-send-cloudevent]
        
        More samples can be found [here][python-eg-samples].
        
        ### Additional documentation
        
        For more extensive documentation on Azure Event Grid, see the [Event Grid documentation][python-eg-product-docs] 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 [cla.microsoft.com][cla].
        
        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][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
        
        <!-- LINKS -->
        
        [python-eg-src]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/
        [python-eg-pypi]: https://pypi.org/project/azure-eventgrid
        [python-eg-product-docs]: https://docs.microsoft.com/en-us/azure/event-grid/overview
        [python-eg-ref-docs]: https://aka.ms/azsdk/python/eventgrid/docs
        [python-eg-samples]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventgrid/azure-eventgrid/samples
        [python-eg-changelog]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventgrid/azure-eventgrid/CHANGELOG.md
        
        [azure_portal_create_EG_resource]: https://ms.portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.EventGrid%2Ftopics
        [azure-key-credential]: https://aka.ms/azsdk/python/core/azurekeycredential
        [azure_core_exceptions]: https://aka.ms/azsdk/python/core/docs#module-azure.core.exceptions
        [python_logging]: https://docs.python.org/3/library/logging.html
        [azure_core_ref_docs]: https://aka.ms/azsdk/python/core/docs
        [azure_subscription]: https://azure.microsoft.com/free/
        
        [python-eg-sample-customevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs1_publish_custom_events_to_a_topic.py
        [python-eg-sample-customevent-to-domain]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs2_publish_custom_events_to_a_domain_topic.py
        [python-eg-sample-consume-systemevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs3_consume_system_events.py
        [python-eg-sample-consume-customevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs4_consume_custom_events.py
        [python-eg-sample-send-cloudevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs5_publish_events_using_cloud_events_1.0_schema.py
        [python-eg-sample-consume-cloudevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs6_consume_events_using_cloud_events_1.0_schema.py
        [publisher-service-doc]: https://docs.microsoft.com/en-us/azure/event-grid/concepts
        
        [cla]: https://cla.microsoft.com
        [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
        [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
        [coc_contact]: mailto:opencode@microsoft.com
        
        
        # Release History
        
        ## 2.0.0b1 (2020-09-08)
        
          **Features**
          - Version (2.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure EventGrid.
          For more information about this, and preview releases of other Azure SDK libraries, please visit https://azure.github.io/azure-sdk/releases/latest/python.html.
          - Added Support for `CloudEvents`.
          - Implements the `EventGridPublisherClient` for the publish flow for EventGrid Events, CloudEvents and CustomEvents.
          - Implements the `EventGridConsumer` for the consume flow of the events.
        
        ## 1.3.0 (2019-05-20)
        
          - Event Schemas for new event types from IotHub, Media Services,
            Container Registry, Maps, and AppConfiguration services.
        
        ## 1.2.0 (2018-08-28)
        
          - Event Schemas for new events (IotHub DeviceConnected and
            DeviceDisconnected events, Resource events related to actions), and
            breaking changes to the schema for IotHub DeviceCreated event and
            IotHub DeviceDeleted event.
        
        ## 1.1.0 (2018-05-24)
        
          - Event Schemas for EventGrid subscription validation event, Azure
            Media events, and ServiceBus events.
        
        ## 1.0.0 (2018-04-26)
        
        **General Breaking changes**
        
        This version uses a next-generation code generator that *might*
        introduce breaking changes.
        
          - Model signatures now use only keyword-argument syntax. All
            positional arguments must be re-written as keyword-arguments. To
            keep auto-completion in most cases, models are now generated for
            Python 2 and Python 3. Python 3 uses the "*" syntax for
            keyword-only arguments.
          - Enum types now use the "str" mixin (class AzureEnum(str, Enum)) to
            improve the behavior when unrecognized enum values are encountered.
            While this is not a breaking change, the distinctions are important,
            and are documented here:
            <https://docs.python.org/3/library/enum.html#others> At a glance:
              - "is" should not be used at all.
              - "format" will return the string value, where "%s" string
                formatting will return `NameOfEnum.stringvalue`. Format syntax
                should be prefered.
          - New Long Running Operation:
              - Return type changes from
                `msrestazure.azure_operation.AzureOperationPoller` to
                `msrest.polling.LROPoller`. External API is the same.
              - Return type is now **always** a `msrest.polling.LROPoller`,
                regardless of the optional parameters used.
              - The behavior has changed when using `raw=True`. Instead of
                returning the initial call result as `ClientRawResponse`,
                without polling, now this returns an LROPoller. After polling,
                the final resource will be returned as a `ClientRawResponse`.
              - New `polling` parameter. The default behavior is
                `Polling=True` which will poll using ARM algorithm. When
                `Polling=False`, the response of the initial call will be
                returned without polling.
              - `polling` parameter accepts instances of subclasses of
                `msrest.polling.PollingMethod`.
              - `add_done_callback` will no longer raise if called after
                polling is finished, but will instead execute the callback right
                away.
        
        **Features**
        
          - Client class can be used as a context manager to keep the underlying
            HTTP session open for performance
          - Support for consuming Azure Container Registry events and Azure IoT
            Hub events published to Event Grid.
        
        ## 0.1.0 (2018-01-30)
        
          - Initial Release
        
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
