feat: support CosmosDB SDK-type bindings (#109)

* Init

* Fix

* Add code qual

* Add docs

* Fix

* Chng docs

* Chng test

* Rename

* Fix

* Fix

* Fix

* Fix

* Fix

* Fix

* test

* TODO

---------

Co-authored-by: Evan Roman <[email protected]>
Co-authored-by: Gavin Aguiar <[email protected]>

Author: 3 people

azurefunctions-extensions-bindings-blob/README.md

@@ -56,7 +56,7 @@ import logging
 import azure.functions as func
 import azurefunctions.extensions.bindings.blob as blob
 
-app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
+app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)
 
 @app.blob_trigger(arg_name="client",
                   path="PATH/TO/BLOB",

azurefunctions-extensions-bindings-blob/azurefunctions/extensions/bindings/blob/blobClient.py

@@ -56,4 +56,4 @@ def get_sdk_type(self):
                 blob=self._blobName,
             )
         else:
-            return None
+            raise ValueError(f"Unable to create {self.__class__.__name__} SDK type.")

azurefunctions-extensions-bindings-blob/azurefunctions/extensions/bindings/blob/containerClient.py

@@ -46,4 +46,4 @@ def get_sdk_type(self):
                 container=self._containerName
             )
         else:
-            return None
+            raise ValueError(f"Unable to create {self.__class__.__name__} SDK type.")

azurefunctions-extensions-bindings-blob/azurefunctions/extensions/bindings/blob/storageStreamDownloader.py

@@ -48,4 +48,4 @@ def get_sdk_type(self):
                 blob=self._blobName,
             ).download_blob()
         else:
-            return None
+            raise ValueError(f"Unable to create {self.__class__.__name__} SDK type.")

azurefunctions-extensions-bindings-blob/samples/blob_samples_blobclient/function_app.py

@@ -9,7 +9,7 @@
 import azure.functions as func
 import azurefunctions.extensions.bindings.blob as blob
 
-app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
+app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)
 
 """
 FOLDER: blob_samples_blobclient

azurefunctions-extensions-bindings-blob/samples/blob_samples_containerclient/function_app.py

@@ -9,7 +9,7 @@
 import azure.functions as func
 import azurefunctions.extensions.bindings.blob as blob
 
-app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
+app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)
 
 """
 FOLDER: blob_samples_containerclient

azurefunctions-extensions-bindings-blob/samples/blob_samples_storagestreamdownloader/function_app.py

@@ -9,7 +9,7 @@
 import azure.functions as func
 import azurefunctions.extensions.bindings.blob as blob
 
-app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
+app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)
 
 """
 FOLDER: blob_samples_storagestreamdownloader

azurefunctions-extensions-bindings-blob/tests/test_blobclient.py

@@ -94,10 +94,10 @@ def test_input_incorrect_type(self):
 
     def test_input_empty(self):
         datum: Datum = Datum(value={}, type="model_binding_data")
-        result: BlobClient = BlobClientConverter.decode(
-            data=datum, trigger_metadata=None, pytype=BlobClient
-        )
-        self.assertIsNone(result)
+        with self.assertRaises(ValueError):
+            BlobClientConverter.decode(
+                data=datum, trigger_metadata=None, pytype=BlobClient
+            )
 
     def test_input_populated(self):
         content = {

azurefunctions-extensions-bindings-blob/tests/test_containerclient.py

@@ -94,10 +94,10 @@ def test_input_incorrect_type(self):
 
     def test_input_empty(self):
         datum: Datum = Datum(value={}, type="model_binding_data")
-        result: ContainerClient = BlobClientConverter.decode(
-            data=datum, trigger_metadata=None, pytype=ContainerClient
-        )
-        self.assertIsNone(result)
+        with self.assertRaises(ValueError):
+            BlobClientConverter.decode(
+                data=datum, trigger_metadata=None, pytype=ContainerClient
+            )
 
     def test_input_populated(self):
         content = {

azurefunctions-extensions-bindings-blob/tests/test_ssd.py

@@ -97,10 +97,10 @@ def test_input_incorrect_type(self):
 
     def test_input_empty(self):
         datum: Datum = Datum(value={}, type="model_binding_data")
-        result: StorageStreamDownloader = BlobClientConverter.decode(
-            data=datum, trigger_metadata=None, pytype=StorageStreamDownloader
-        )
-        self.assertIsNone(result)
+        with self.assertRaises(ValueError):
+            BlobClientConverter.decode(
+                data=datum, trigger_metadata=None, pytype=StorageStreamDownloader
+            )
 
     def test_input_populated(self):
         content = {

azurefunctions-extensions-bindings-cosmosdb/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+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.

azurefunctions-extensions-bindings-cosmosdb/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include azure *.py *.pyi
+recursive-include tests *.py
+include LICENSE README.md

azurefunctions-extensions-bindings-cosmosdb/README.md

@@ -0,0 +1,103 @@
+# Azure Functions Extensions Bindings Cosmos DB library for Python
+This library allows Cosmos DB Input bindings in Python Function Apps to recognize and bind to client types from the
+Azure Cosmos DB SDK.
+
+Cosmos DB client types can be generated from:
+
+* Cosmos DB Input
+
+[Source code](https://github.com/Azure/azure-functions-python-extensions/tree/dev/azurefunctions-extensions-bindings-cosmosdb)
+[Package (PyPi)](https://pypi.org/project/azurefunctions-extensions-bindings-cosmosdb/)
+| [Samples](https://github.com/Azure/azure-functions-python-extensions/tree/dev/azurefunctions-extensions-bindings-cosmosdb/samples)
+
+
+## Getting started
+
+### Prerequisites
+* Python 3.9 or later is required to use this package. For more details, please read our page on [Python Functions version support policy](https://learn.microsoft.com/en-us/azure/azure-functions/functions-versions?tabs=isolated-process%2Cv4&pivots=programming-language-python#languages).
+
+* You must have an [Azure subscription](https://azure.microsoft.com/free/) and an
+[Azure storage account](https://docs.microsoft.com/azure/storage/common/storage-account-overview) to use this package.
+
+### Install the package
+Install the Azure Functions Extensions Bindings Cosmos DB library for Python with pip:
+
+```bash
+pip install azurefunctions-extensions-bindings-cosmosdb
+```
+
+### Create a storage account
+If you wish to create a new storage account, you can use the
+[Azure Portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal),
+[Azure PowerShell](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell),
+or [Azure CLI](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli):
+
+```bash
+# Create a new resource group to hold the storage account -
+# if using an existing resource group, skip this step
+az group create --name my-resource-group --location westus2
+
+# Create the storage account
+az storage account create -n my-storage-account-name -g my-resource-group
+```
+
+### Bind to the SDK-type
+The Azure Functions Extensions Bindings Cosmos DB library for Python allows you to create a function app with
+Cosmos DB Input and define the type as a CosmosClient, DatabaseProxy, or ContainerProxy. Instead of receiving
+a DocumentList, when the function is executed, the type returned will be the defined SDK-type and have all of the
+properties and methods available as seen in the Azure Storage Cosmos DB library for Python.
+
+
+```python
+import logging
+import azure.functions as func
+import azurefunctions.extensions.bindings.cosmosdb as cosmos
+
+app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)
+
+@app.route(route="cosmos")
+@app.cosmos_db_input(arg_name="container",
+                     connection="CosmosDBConnection",
+                     database_name="db_name",
+                     container_name="container_name")
+def get_docs(req: func.HttpRequest, client: cosmos.CosmosClient):
+    databases = client.list_databases()
+    for db in databases:
+        logging.info(f"Found database with ID: {db.get('id')}")
+
+    return "ok"
+```
+
+## Troubleshooting
+### General
+The SDK-types raise exceptions defined in [Azure Core](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md).
+
+This list can be used for reference to catch thrown exceptions. To get the specific error code of the exception, use the `error_code` attribute, i.e, `exception.error_code`.
+
+## Next steps
+
+### More sample code
+
+Get started with our [Cosmos DB samples](https://github.com/Azure/azure-functions-python-extensions/tree/dev/azurefunctions-extensions-bindings-cosmosdb/samples).
+
+Several samples are available in this GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Cosmos DB:
+
+* [cosmosdb_samples_cosmosclient](https://github.com/Azure/azure-functions-python-extensions/tree/dev/azurefunctions-extensions-binding-cosmosdb/samples/cosmosdb_samples_cosmosclient)  - Examples for using the CosmosClient type:
+    * From CosmosDBInput
+
+* [cosmosdb_samples_databaseproxy](https://github.com/Azure/azure-functions-python-extensions/tree/dev/azurefunctions-extensions-bindings-cosmosdb/samples/cosmosdb_samples_databaseproxy) - Examples for using the DatabaseProxy type:
+    * From CosmosDBInput
+
+* [cosmosdb_samples_containerclient](https://github.com/Azure/azure-functions-python-extensions/tree/dev/azurefunctions-extensions-bindings-cosmosdb/samples/cosmosdb_samples_containerproxy) - Examples for using the ContainerProxy type:
+    * From CosmosDBInput
+
+### Additional documentation
+For more information on the Azure Cosmos DB SDK, see the [Azure Cosmos DB documentation](https://learn.microsoft.com/en-us/azure/cosmos-db/) on learn.microsoft.com
+and the [Azure Cosmos DB README](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos).
+
+## 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.

azurefunctions-extensions-bindings-cosmosdb/azurefunctions/__init__.py

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

azurefunctions-extensions-bindings-cosmosdb/azurefunctions/extensions/__init__.py

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

azurefunctions-extensions-bindings-cosmosdb/azurefunctions/extensions/bindings/__init__.py

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

azurefunctions-extensions-bindings-cosmosdb/azurefunctions/extensions/bindings/cosmosdb/__init__.py

@@ -0,0 +1,16 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+from .cosmosClient import CosmosClient
+from .databaseProxy import DatabaseProxy
+from .containerProxy import ContainerProxy
+from .cosmosClientConverter import CosmosClientConverter
+
+__all__ = [
+    "CosmosClient",
+    "DatabaseProxy",
+    "ContainerProxy",
+    "CosmosClientConverter"
+]
+
+__version__ = "1.0.0a1"

azurefunctions-extensions-bindings-cosmosdb/azurefunctions/extensions/bindings/cosmosdb/containerProxy.py

@@ -0,0 +1,50 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+import json
+
+from azure.cosmos import ContainerProxy as ContainerProxySdk
+from azurefunctions.extensions.base import Datum, SdkType
+from .utils import get_connection_string, using_managed_identity, get_cosmos_client
+
+
+class ContainerProxy(SdkType):
+    def __init__(self, *, data: Datum) -> None:
+        # model_binding_data properties
+        self._data = data
+        self._version = None
+        self._source = None
+        self._content_type = None
+        self._database_name = None
+        self._container_name = None
+        self._connection = None
+        self._using_managed_identity = False
+        self._preferred_locations = None
+        if self._data:
+            self._version = data.version
+            self._source = data.source
+            self._content_type = data.content_type
+            content_json = json.loads(data.content)
+            self._database_name = content_json.get("DatabaseName")
+            self._container_name = content_json.get("ContainerName")
+            self._connection = get_connection_string(content_json.get("Connection"))
+            self._using_managed_identity = using_managed_identity(
+                content_json.get("Connection")
+            )
+            self._preferred_locations = content_json.get("PreferredLocations")
+
+    def get_sdk_type(self) -> ContainerProxySdk:
+        """
+        There are two ways to create a CosmosClient:
+        1. Through the constructor: this is the only option when using Managed Identity
+        2. Through from_connection_string: when not using Managed Identity
+
+        We track if Managed Identity is being used through a flag.
+        """
+        if not self._data:
+            raise ValueError(f"Unable to create {self.__class__.__name__} SDK type.")
+
+        cosmos_client = get_cosmos_client(self._using_managed_identity,
+                                          self._connection, self._preferred_locations)
+        db_client = cosmos_client.get_database_client(self._database_name)
+        return db_client.get_container_client(self._container_name)

azurefunctions-extensions-bindings-cosmosdb/azurefunctions/extensions/bindings/cosmosdb/cosmosClient.py

@@ -0,0 +1,48 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+import json
+
+from azure.cosmos import CosmosClient as CosmosClientSdk
+from azurefunctions.extensions.base import Datum, SdkType
+from .utils import get_connection_string, using_managed_identity, get_cosmos_client
+
+
+class CosmosClient(SdkType):
+    def __init__(self, *, data: Datum) -> None:
+        # model_binding_data properties
+        self._data = data
+        self._version = None
+        self._source = None
+        self._content_type = None
+        self._database_name = None
+        self._container_name = None
+        self._connection = None
+        self._using_managed_identity = False
+        self._preferred_locations = None
+        if self._data:
+            self._version = data.version
+            self._source = data.source
+            self._content_type = data.content_type
+            content_json = json.loads(data.content)
+            self._database_name = content_json.get("DatabaseName")
+            self._container_name = content_json.get("ContainerName")
+            self._connection = get_connection_string(content_json.get("Connection"))
+            self._using_managed_identity = using_managed_identity(
+                content_json.get("Connection")
+            )
+            self._preferred_locations = content_json.get("PreferredLocations")
+
+    def get_sdk_type(self) -> CosmosClientSdk:
+        """
+        There are two ways to create a CosmosClient:
+        1. Through the constructor: this is the only option when using Managed Identity
+        2. Through from_connection_string: when not using Managed Identity
+
+        We track if Managed Identity is being used through a flag.
+        """
+        if not self._data:
+            raise ValueError(f"Unable to create {self.__class__.__name__} SDK type.")
+
+        return get_cosmos_client(self._using_managed_identity,
+                                 self._connection, self._preferred_locations)