feat: support ServiceBus SDK-type bindings

azurefunctions-extensions-bindings-servicebus/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-servicebus/MANIFEST.in

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

azurefunctions-extensions-bindings-servicebus/README.md

@@ -0,0 +1,113 @@
+# Azure Functions Extensions Bindings Blob library for Python
+This library allows Blob Trigger and Blob Input bindings in Python Function Apps to recognize and bind to client types from the
+Azure Storage Blob sdk.
+
+Blob client types can be generated from:
+
+* Blob Triggers
+* Blob Input
+
+[Source code](https://github.com/Azure/azure-functions-python-extensions/tree/main/azurefunctions-extensions-bindings-blob)
+[Package (PyPi)](https://pypi.org/project/azurefunctions-extensions-bindings-blob/)
+| API reference documentation
+| Product documentation
+| [Samples](hhttps://github.com/Azure/azure-functions-python-extensions/tree/main/azurefunctions-extensions-bindings-blob/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 Blob library for Python with pip:
+
+```bash
+pip install azurefunctions-extensions-bindings-blob
+```
+
+### 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 Blob library for Python allows you to create a function app with a Blob Trigger or
+Blob Input and define the type as a BlobClient, ContainerClient, or StorageStreamDownloader. Instead of receiving
+an InputStream, 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 Blob library for Python.
+
+
+```python
+import logging
+import azure.functions as func
+import azurefunctions.extensions.bindings.blob as blob
+
+@app.blob_trigger(arg_name="client",
+                  path="PATH/TO/BLOB",
+                  connection="AzureWebJobsStorage")
+def blob_trigger(client: blob.BlobClient):
+    logging.info(f"Python blob trigger function processed blob \n"
+                 f"Properties: {client.get_blob_properties()}\n"
+                 f"Blob content head: {client.download_blob(encoding="utf-8").read(size=1)}")
+
+
+@app.route(route="file")
+@app.blob_input(arg_name="client",
+                path="PATH/TO/BLOB",
+                connection="AzureWebJobsStorage")
+def blob_input(req: func.HttpRequest, client: blob.BlobClient):
+    logging.info(f"Python blob input function processed blob \n"
+                 f"Properties: {client.get_blob_properties()}\n"
+                 f"Blob content head: {client.download_blob(encoding="utf-8").read(size=1)}")
+```
+
+## 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 [Blob samples](hhttps://github.com/Azure/azure-functions-python-extensions/tree/main/azurefunctions-extensions-bindings-blob/samples).
+
+Several samples are available in this GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Storage Blobs:
+
+* [blob_samples_blobclient](https://github.com/Azure/azure-functions-python-extensions/tree/main/azurefunctions-extensions-bindings-blob/samples/blob_samples_blobclient)  - Examples for using the BlobClient type:
+    * From BlobTrigger
+    * From BlobInput
+
+* [blob_samples_containerclient](https://github.com/Azure/azure-functions-python-extensions/tree/main/azurefunctions-extensions-bindings-blob/samples/blob_samples_containerclient) - Examples for using the ContainerClient type:
+    * From BlobTrigger
+    * From BlobInput
+
+* [blob_samples_storagestreamdownloader](https://github.com/Azure/azure-functions-python-extensions/tree/main/azurefunctions-extensions-bindings-blob/samples/blob_samples_storagestreamdownloader) - Examples for using the StorageStreamDownloader type:
+    * From BlobTrigger
+    * From BlobInput
+
+### Additional documentation
+For more information on the Azure Storage Blob SDK, see the [Azure Blob storage documentation](https://docs.microsoft.com/azure/storage/blobs/) on docs.microsoft.com
+and the [Azure Storage Blobs README](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob).
+
+## 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.

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

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

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

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

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

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

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

@@ -0,0 +1,12 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+from .serviceBusReceivedMessage import ServiceBusReceivedMessage
+from .serviceBusConverter import ServiceBusConverter
+
+__all__ = [
+    "ServiceBusReceivedMessage",
+    "ServiceBusConverter",
+]
+
+__version__ = '1.0.0b1'

azurefunctions-extensions-bindings-servicebus/azurefunctions/extensions/bindings/servicebus/serviceBusConverter.py

@@ -0,0 +1,71 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+import collections.abc
+from typing import Any, get_args, get_origin
+
+from azurefunctions.extensions.base import Datum, InConverter
+from .serviceBusReceivedMessage import ServiceBusReceivedMessage
+
+
+class ServiceBusConverter(
+    InConverter,
+    binding='serviceBusTrigger', trigger=True
+):
+    @classmethod
+    def check_input_type_annotation(cls, pytype: type) -> bool:
+        if pytype is None:
+            return False
+
+        # The annotation is a class/type (not an object) - not iterable
+        if (isinstance(pytype, type)
+                and issubclass(pytype, ServiceBusReceivedMessage)):
+            return True
+
+        # An iterable who only has one inner type and is a subclass of SdkType
+        return cls._is_iterable_supported_type(pytype)
+
+    @classmethod
+    def _is_iterable_supported_type(cls, annotation: type) -> bool:
+        # Check base type from type hint. Ex: List from List[SdkType]
+        base_type = get_origin(annotation)
+        if (base_type is None
+                or not issubclass(base_type, collections.abc.Iterable)):
+            return False
+
+        inner_types = get_args(annotation)
+        if inner_types is None or len(inner_types) != 1:
+            return False
+
+        inner_type = inner_types[0]
+
+        return (isinstance(inner_type, type) 
+                and issubclass(inner_type, ServiceBusReceivedMessage))
+
+    @classmethod
+    def decode(cls, data: Datum, *, trigger_metadata, pytype) -> Any:
+        """
+        ServiceBus allows for batches to be sent. This means the cardinality can be one or many.
+        When the cardinality is one:
+            - The data is of type "model_binding_data" - each event is an independent function invocation
+        When the cardinality is many:
+            - The data is of type "collection_model_binding_data" - all events are sent in a single function invocation
+            - collection_model_binding_data has 1 or more model_binding_data objects
+        """
+        if data is None or data.type is None or pytype != ServiceBusReceivedMessage:
+            return None
+
+        data_type = data.type
+
+        if data_type == "model_binding_data":
+            return ServiceBusReceivedMessage(data=data.value).get_sdk_type()
+        elif data_type == "collection_model_binding_data":
+            try:
+                return [ServiceBusReceivedMessage(data=mbd).get_sdk_type() for mbd in data.value.model_binding_data]
+            except Exception as e:
+                raise ValueError("Failed to decode incoming ServiceBus batch: " + repr(e)) from e
+        else:
+            raise ValueError(
+                f'unexpected type of data received for the "servicebus" binding '
+                f": {data_type!r}"
+            )

azurefunctions-extensions-bindings-servicebus/azurefunctions/extensions/bindings/servicebus/serviceBusReceivedMessage.py

@@ -0,0 +1,31 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+from azure.servicebus import ServiceBusReceivedMessage as ServiceBusReceivedMessageSdk
+from azurefunctions.extensions.base import Datum, SdkType
+from .utils import get_decoded_message
+
+
+class ServiceBusReceivedMessage(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._content = None
+        self._decoded_message = None
+        if self._data:
+            self._version = data.version
+            self._source = data.source
+            self._content_type = data.content_type
+            self._content = data.content
+            self._decoded_message = get_decoded_message(self._content)
+
+    def get_sdk_type(self):
+        if self._decoded_message:
+            # Create ServiceBusReceivedMessage
+            # At this moment, settling is not yet supported
+            return ServiceBusReceivedMessageSdk(self._decoded_message, receiver=None)
+        else:
+            return None

azurefunctions-extensions-bindings-servicebus/azurefunctions/extensions/bindings/servicebus/utils.py

@@ -0,0 +1,42 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+
+import uamqp
+import uuid
+
+
+_X_OPT_LOCK_TOKEN = b"x-opt-lock-token"
+
+
+def get_lock_token(message: bytes, index: int) -> str:
+    # Get the lock token from the message
+    lock_token_encoded = message[:index]
+
+    # Convert the lock token to a UUID using the first 16 bytes
+    lock_token_uuid = uuid.UUID(bytes=lock_token_encoded[:16])
+
+    return lock_token_uuid
+
+
+def get_amqp_message(message: bytes, index: int):
+    # Get the amqp message from the model_binding_data content
+    amqp_message = message[index + len(b"x-opt-lock-token"):]
+
+    # Create the message
+    decoded_message = uamqp.Message().decode_from_bytes(amqp_message)
+
+    return decoded_message
+
+def get_decoded_message(content: bytes):
+    if content:
+        # Finds the end of the lock token
+            index = content.find(b"x-opt-lock-token")
+
+            # Get the lock token UUID and create the delivery annotations dictionary
+            lock_token = get_lock_token(content, index)
+            delivery_anno_dict = {_X_OPT_LOCK_TOKEN: lock_token}
+
+            # Get the amqp message and set the delivery annotations
+            decoded_message = get_amqp_message(content, index)
+            decoded_message.delivery_annotations = delivery_anno_dict
+    return None

azurefunctions-extensions-bindings-servicebus/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "azurefunctions-extensions-bindings-servicebus"
+dynamic = ["version"]
+requires-python = ">=3.9"
+authors = [{ name = "Azure Functions team at Microsoft Corp.", email = "azurefunctions@microsoft.com"}]
+description = "ServiceBus Python worker extension for Azure Functions."
+readme = "README.md"
+license = {text = "MIT License"}
+classifiers= [
+        'License :: OSI Approved :: MIT License',
+        'Intended Audience :: Developers',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+        'Programming Language :: Python :: 3.13',
+        'Operating System :: Microsoft :: Windows',
+        'Operating System :: POSIX',
+        'Operating System :: MacOS :: MacOS X',
+        'Environment :: Web Environment',
+        'Development Status :: 5 - Production/Stable',
+    ]
+dependencies = [
+    'azurefunctions-extensions-base',
+    'azure-servicebus~=7.*',
+    'uamqp~=1.*'
+    ]
+
+[project.optional-dependencies]
+dev = [
+    'flake8',
+    'mypy',
+    'pytest',
+    'pytest-cov',
+    'coverage',
+    'pytest-instafail',
+    'pre-commit'
+    ]
+
+[tool.setuptools.dynamic]
+version = {attr = "azurefunctions.extensions.bindings.servicebus.__version__"}
+
+[tool.setuptools.packages.find]
+exclude = [
+    'azurefunctions.extensions.bindings','azurefunctions.extensions',
+    'azurefunctions', 'tests', 'samples'
+    ]