Added User Agent Suffix (Azure#40904)

* added suffix with tests

* added documentation in client functions

* added changes from comments in pr

* added to changelog

* edited changelog

---------

Co-authored-by: Andrew Mathew <[email protected]>

Author: andrewmathew1

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -1,9 +1,10 @@
 ## Release History
 
 ### 4.12.0b2 (Unreleased)
-* Added ability to use request level `excluded_locations` on metadata calls, such as getting container properties. See [PR 40905](https://github.com/Azure/azure-sdk-for-python/pull/40905)
 
 #### Features Added
+* Added ability to set a user agent suffix at the client level. See [PR 40904](https://github.com/Azure/azure-sdk-for-python/pull/40904)
+* Added ability to use request level `excluded_locations` on metadata calls, such as getting container properties. See [PR 40905](https://github.com/Azure/azure-sdk-for-python/pull/40905)
 
 #### Bugs Fixed
 * Fixed issue where Query Change Feed did not return items if the container uses legacy Hash V1 Partition Keys. This also fixes issues with not being able to change feed query for Specific Partition Key Values for HPK. See [PR 41270](https://github.com/Azure/azure-sdk-for-python/pull/41270/)

sdk/cosmos/azure-cosmos/azure/cosmos/_cosmos_client_connection.py

@@ -197,7 +197,8 @@ def __init__( # pylint: disable=too-many-statements
             proxy = host if url.port else host + ":" + str(self.connection_policy.ProxyConfiguration.Port)
             proxies.update({url.scheme: proxy})
 
-        self._user_agent: str = _utils.get_user_agent()
+        suffix = kwargs.pop('user_agent_suffix', None)
+        self._user_agent: str = _utils.get_user_agent(suffix)
 
         credentials_policy = None
         if self.aad_credentials:

sdk/cosmos/azure-cosmos/azure/cosmos/_utils.py

@@ -31,17 +31,21 @@
 from ._version import VERSION
 
 
-def get_user_agent() -> str:
+def get_user_agent(suffix: Optional[str]) -> str:
     os_name = safe_user_agent_header(platform.platform())
     python_version = safe_user_agent_header(platform.python_version())
     user_agent = "azsdk-python-cosmos/{} Python/{} ({})".format(VERSION, python_version, os_name)
+    if suffix:
+        user_agent += f" {suffix}"
     return user_agent
 
 
-def get_user_agent_async() -> str:
+def get_user_agent_async(suffix: Optional[str]) -> str:
     os_name = safe_user_agent_header(platform.platform())
     python_version = safe_user_agent_header(platform.python_version())
     user_agent = "azsdk-python-cosmos-async/{} Python/{} ({})".format(VERSION, python_version, os_name)
+    if suffix:
+        user_agent += f" {suffix}"
     return user_agent
 
 

sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client.py

@@ -172,6 +172,7 @@ class CosmosClient:  # pylint: disable=client-accepts-api-version-keyword
     :keyword bool no_response_on_write: Indicates whether service should be instructed to skip sending 
         response payloads for write operations on items by default unless specified differently per operation.
     :keyword int throughput_bucket: The desired throughput bucket for the client
+    :keyword str user_agent_suffix: Allows user agent suffix to be specified when creating client
 
     .. admonition:: Example:
 

sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client_connection_async.py

@@ -202,7 +202,8 @@ def __init__( # pylint: disable=too-many-statements
             proxy = host if url.port else host + ":" + str(self.connection_policy.ProxyConfiguration.Port)
             proxies.update({url.scheme: proxy})
 
-        self._user_agent = _utils.get_user_agent_async()
+        suffix = kwargs.pop('user_agent_suffix', None)
+        self._user_agent = _utils.get_user_agent_async(suffix)
 
         credentials_policy = None
         if self.aad_credentials:

sdk/cosmos/azure-cosmos/azure/cosmos/cosmos_client.py

@@ -193,6 +193,7 @@ class CosmosClient:  # pylint: disable=client-accepts-api-version-keyword
     :keyword bool no_response_on_write: Indicates whether service should be instructed to skip sending 
         response payloads on rite operations for items.
     :keyword int throughput_bucket: The desired throughput bucket for the client
+    :keyword str user_agent_suffix: Allows user agent suffix to be specified when creating client
 
     .. admonition:: Example:
 

sdk/cosmos/azure-cosmos/tests/test_client_user_agent.py

@@ -10,7 +10,7 @@
 from test_config import TestConfig
 
 
-@pytest.mark.skip
+@pytest.mark.cosmosEmulator
 class TestClientUserAgent(unittest.IsolatedAsyncioTestCase):
 
     async def test_client_user_agent(self):
@@ -21,6 +21,14 @@ async def test_client_user_agent(self):
             self.assertTrue(client_async.client_connection._user_agent.startswith("azsdk-python-cosmos-async/"))
             self.assertTrue(client_async.client_connection._user_agent != client_sync.client_connection._user_agent)
 
+    async def test_client_user_agent_suffix(self):
+        async with async_client(url=TestConfig.host, credential=TestConfig.masterKey, user_agent_suffix="testAsyncSuffix") as client_async:
+            client_sync = sync_client(url=TestConfig.host, credential=TestConfig.masterKey, user_agent_suffix="testSyncSuffix")
+
+            self.assertTrue(client_sync.client_connection._user_agent.endswith(" testSyncSuffix"))
+            self.assertTrue(client_async.client_connection._user_agent.endswith(" testAsyncSuffix"))
+            self.assertTrue(client_async.client_connection._user_agent != client_sync.client_connection._user_agent)
+
 
 if __name__ == "__main__":
     unittest.main()