Azure Communication Services Network Traversal - GetRelayConfiguration SDK (Azure#19583)

* Add private preview azure-communication-network-traversal python SDK

* Add recordings

* Fix config/build and format for PR

* Update, pylint checks

* Update PR

* Update PR

* Disable pylint warnings

* Supress unused-import pylint warning, when I'm actually using it.

* Update documentation

* Make shared folder consistent with other packages under communication

* Rename namespace name from network-traversal to networktraversal

Author: AriZavala2

sdk/communication/azure-communication-networktraversal/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Release History
+
+## 1.0.0b1 (2021-07-19)
+- Preview release of `azure-communication-networktraversal`.
+
+The first preview of the Azure Communication Relay Client has the following features:
+
+- get a Relay Configuration by creating a CommunicationRelayClient
+
+### Added
+- Added CommunicationRelayClient in preview.
+- Added CommunicationRelayClient.get_relay_configuration in preview.
+
+<!-- LINKS -->
+[read_me]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/communication/

sdk/communication/azure-communication-networktraversal/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdk/communication/azure-communication-networktraversal/MANIFEST.in

@@ -0,0 +1,6 @@
+include *.md
+include azure/__init__.py
+include azure/communication/__init__.py
+include LICENSE.txt
+recursive-include tests *.py
+recursive-include samples *.py *.md

sdk/communication/azure-communication-networktraversal/README.md

@@ -0,0 +1,104 @@
+# Azure Communication Network Traversal Package client library for Python
+
+Azure Communication Network Traversal is managing TURN credentials for Azure Communication Services.
+
+It will provide TURN credentials to a user.
+
+[Source code](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/communication) | [API reference documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/communication)
+
+# Getting started
+
+### Prerequisites
+
+- Python 2.7, or 3.6 or later is required to use this package.
+- You must have an [Azure subscription](https://azure.microsoft.com/free/)
+- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.
+
+### Install the package
+
+Install the Azure Communication Identity client library for Python with [pip](https://pypi.org/project/pip/):
+Install the Azure Communication Relay Client library for Python with [pip](https://pypi.org/project/pip/):
+
+```bash
+pip install azure-communication-identity
+pip install azure-communication-networktraversal
+```
+
+# Key concepts
+
+## Examples
+
+### Initializing Relay Client
+
+The following section provides code snippets covering some of the most common Azure Communication Network Traversal tasks, including:
+
+- [Getting the relay configuration](#getting-the-relay-configuration)
+
+```python
+# You can find your endpoint and access token from your resource in the Azure Portal
+import os
+from azure.communication.networktraversal import CommunicationRelayClient
+from azure.identity import DefaultAzureCredential
+from azure.communication.identity import CommunicationIdentityClient
+
+connection_str = "endpoint=ENDPOINT;accessKey=KEY"
+endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
+
+# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have
+# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
+# We also need Identity client to get a User Identifier
+identity_client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())
+relay_client = CommunicationRelayClient(endpoint, DefaultAzureCredential())
+```
+
+#You can also authenticate using your connection string
+
+```python
+identity_client = CommunicationIdentityClient.from_connection_string(self.connection_string)
+relay_client = CommunicationRelayClient.from_connection_string(self.connection_string)
+```
+
+### Getting the relay configuration 
+
+```python
+# We need a user from Identity
+user = identity_client.create_user()
+relay_configuration = relay_client.get_relay_configuration(user)
+
+for iceServer in config.ice_servers:
+    assert iceServer.username is not None
+    print('Username: ' + iceServer.username)
+
+    assert iceServer.credential is not None
+    print('Credential: ' + iceServer.credential)
+    
+    assert iceServer.urls is not None
+    for url in iceServer.urls:
+        print('Url:' + url)
+```
+
+# Troubleshooting
+
+The Azure Communication Relay client will raise exceptions defined in [Azure Core][azure_core].
+
+# Next steps
+
+## More sample code
+
+## Provide Feedback
+
+If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project
+
+# 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 [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+<!-- LINKS -->
+[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md

sdk/communication/azure-communication-networktraversal/azure/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

sdk/communication/azure-communication-networktraversal/azure/communication/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

sdk/communication/azure-communication-networktraversal/azure/communication/networktraversal/__init__.py

@@ -0,0 +1,8 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+# pylint: disable=bad-option-value, unused-import
+from ._communication_relay_client import CommunicationRelayClient

sdk/communication/azure-communication-networktraversal/azure/communication/networktraversal/_communication_relay_client.py

@@ -0,0 +1,99 @@
+# coding=utf-8
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+from typing import TYPE_CHECKING, Any
+
+from azure.core.tracing.decorator import distributed_trace
+from azure.communication.identity import CommunicationUserIdentifier
+
+from ._generated._communication_network_traversal_client\
+    import CommunicationNetworkTraversalClient\
+        as CommunicationNetworkTraversalClientGen
+from ._shared.utils import parse_connection_str, get_authentication_policy
+from ._version import SDK_MONIKER
+from ._generated.models import CommunicationRelayConfiguration
+
+if TYPE_CHECKING:
+    from azure.core.credentials import TokenCredential
+
+class CommunicationRelayClient(object):
+    """Azure Communication Services Relay client.
+
+    :param str endpoint:
+        The endpoint url for Azure Communication Service resource.
+    :param TokenCredential credential:
+        The TokenCredential we use to authenticate against the service.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/network_traversal_samples.py
+            :language: python
+            :dedent: 8
+    """
+    def __init__(
+            self,
+            endpoint, # type: str
+            credential, # type: TokenCredential
+            **kwargs # type: Any
+        ):
+        # type: (...) -> None
+        # pylint: disable=bad-option-value, disable=raise-missing-from
+        try:
+            if not endpoint.lower().startswith('http'):
+                endpoint = "https://" + endpoint
+        except AttributeError:
+            raise ValueError("Account URL must be a string.")
+
+        if not credential:
+            raise ValueError(
+                "You need to provide account shared key to authenticate.")
+
+        self._endpoint = endpoint
+        self._network_traversal_service_client = CommunicationNetworkTraversalClientGen(
+            self._endpoint,
+            authentication_policy=get_authentication_policy(endpoint, credential),
+            sdk_moniker=SDK_MONIKER,
+            **kwargs)
+
+    @classmethod
+    def from_connection_string(
+            cls, conn_str,  # type: str
+            **kwargs  # type: Any
+        ):  # type: (...) -> CommunicationRelayClient
+        """Create CommunicationRelayClient from a Connection String.
+
+        :param str conn_str: A connection string to an Azure Communication Service resource.
+        :returns: Instance of CommunicationRelayClient.
+        :rtype: ~azure.communication.networktraversal.CommunicationRelayClient
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/network_traversal_samples_async.py
+                :start-after: [START auth_from_connection_string]
+                :end-before: [END auth_from_connection_string]
+                :language: python
+                :dedent: 8
+                :caption: Creating the CommunicationRelayClient from a connection string.
+        """
+        endpoint, access_key = parse_connection_str(conn_str)
+
+        return cls(endpoint, access_key, **kwargs)
+
+    @distributed_trace
+    def get_relay_configuration(
+            self,
+            user, # type: CommunicationUserIdentifier
+            **kwargs # type: Any
+    ):
+        # type: (Any) -> CommunicationRelayConfiguration
+        """get a Communication Relay configuration
+        :param: CommunicationUserIdentifier user: A user from which we will get an id
+        :return: CommunicationRelayConfiguration
+        :rtype: ~azure.communication.networktraversal.CommunicationRelayConfiguration
+        """
+        return self._network_traversal_service_client.communication_network_traversal.issue_relay_configuration(
+            user.properties['id'],
+            **kwargs)

sdk/communication/azure-communication-networktraversal/azure/communication/networktraversal/_generated/__init__.py

@@ -0,0 +1,16 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# Code generated by Microsoft (R) AutoRest Code Generator.
+# Changes may cause incorrect behavior and will be lost if the code is regenerated.
+# --------------------------------------------------------------------------
+
+from ._communication_network_traversal_client import CommunicationNetworkTraversalClient
+__all__ = ['CommunicationNetworkTraversalClient']
+
+try:
+    from ._patch import patch_sdk  # type: ignore
+    patch_sdk()
+except ImportError:
+    pass

sdk/communication/azure-communication-networktraversal/azure/communication/networktraversal/_generated/_communication_network_traversal_client.py

@@ -0,0 +1,81 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# Code generated by Microsoft (R) AutoRest Code Generator.
+# Changes may cause incorrect behavior and will be lost if the code is regenerated.
+# --------------------------------------------------------------------------
+
+from typing import TYPE_CHECKING
+
+from azure.core import PipelineClient
+from msrest import Deserializer, Serializer
+
+if TYPE_CHECKING:
+    # pylint: disable=unused-import,ungrouped-imports
+    from typing import Any
+
+    from azure.core.pipeline.transport import HttpRequest, HttpResponse
+
+from ._configuration import CommunicationNetworkTraversalClientConfiguration
+from .operations import CommunicationNetworkTraversalOperations
+from . import models
+
+
+class CommunicationNetworkTraversalClient(object):
+    """Azure Communication Networking Service.
+
+    :ivar communication_network_traversal: CommunicationNetworkTraversalOperations operations
+    :vartype communication_network_traversal: azure.communication.networktraversal.operations.CommunicationNetworkTraversalOperations
+    :param endpoint: The communication resource, for example https://my-resource.communication.azure.com.
+    :type endpoint: str
+    """
+
+    def __init__(
+        self,
+        endpoint,  # type: str
+        **kwargs  # type: Any
+    ):
+        # type: (...) -> None
+        base_url = '{endpoint}'
+        self._config = CommunicationNetworkTraversalClientConfiguration(endpoint, **kwargs)
+        self._client = PipelineClient(base_url=base_url, config=self._config, **kwargs)
+
+        client_models = {k: v for k, v in models.__dict__.items() if isinstance(v, type)}
+        self._serialize = Serializer(client_models)
+        self._serialize.client_side_validation = False
+        self._deserialize = Deserializer(client_models)
+
+        self.communication_network_traversal = CommunicationNetworkTraversalOperations(
+            self._client, self._config, self._serialize, self._deserialize)
+
+    def _send_request(self, http_request, **kwargs):
+        # type: (HttpRequest, Any) -> HttpResponse
+        """Runs the network request through the client's chained policies.
+
+        :param http_request: The network request you want to make. Required.
+        :type http_request: ~azure.core.pipeline.transport.HttpRequest
+        :keyword bool stream: Whether the response payload will be streamed. Defaults to True.
+        :return: The response of your network call. Does not do error handling on your response.
+        :rtype: ~azure.core.pipeline.transport.HttpResponse
+        """
+        path_format_arguments = {
+            'endpoint': self._serialize.url("self._config.endpoint", self._config.endpoint, 'str', skip_quote=True),
+        }
+        http_request.url = self._client.format_url(http_request.url, **path_format_arguments)
+        stream = kwargs.pop("stream", True)
+        pipeline_response = self._client._pipeline.run(http_request, stream=stream, **kwargs)
+        return pipeline_response.http_response
+
+    def close(self):
+        # type: () -> None
+        self._client.close()
+
+    def __enter__(self):
+        # type: () -> CommunicationNetworkTraversalClient
+        self._client.__enter__()
+        return self
+
+    def __exit__(self, *exc_details):
+        # type: (Any) -> None
+        self._client.__exit__(*exc_details)