feat: add support for async functions (GoogleCloudPlatform#364)

* feat: Introduce functions_framework.aio submodule that support async function execution.

* Remove httpx.

* Update pyproject.toml to include extra async package.

* Update test deps.

* Improve test coverage.

* Make linter happy.

* Fix test harness to support py37.

* Remove version filter in tox file.

* Remove dependency-groups in pyproject.toml for now.

* Use py3.8 compatible types.

* Fix more incompatibility with python38

* Pin cloudevent sdk to python37 compatible version.

* Fix more py37 incompatibility.

* fix: Prevent test_aio.py collection errors on Python 3.7

Add pytest_ignore_collect hook to skip test_aio.py entirely on Python 3.7
to prevent ImportError during test collection. The previous approach using
only pytest_collection_modifyitems was too late in the process - the error
occurred when pytest tried to import the module before skip markers could
be applied.

Both hooks are marked as safe to remove when Python 3.7 support is dropped.

* style: Apply black formatting to conftest.py

* fix: Use modern pytest collection_path parameter and return None

- Replace deprecated 'path' parameter with 'collection_path' in pytest_ignore_collect
- Return None instead of False to let pytest use default behavior
- This should fix the issue where pytest was collecting tests from .tox/.pkg/

* fix: Skip tests parametrized with None on Python 3.7

Simplify the check to just skip any test parametrized with None value.
On Python 3.7, create_asgi_app is always None due to the conditional
import, so this catches all async-related parametrized tests.

* fix: Replace asyncio.to_thread with Python 3.8 compatible code

Use asyncio.get_event_loop().run_in_executor() instead of
asyncio.to_thread() for Python 3.8 compatibility. Added TODO
comments to switch back when Python 3.8 support is dropped.

* fix: Improve async test detection for Python 3.7

- Use a list of async keywords (async, asgi, aio, starlette)
- Check for these keywords in test names, file paths, and parameters
- This catches more async-related tests including those with "aio" prefix

* fix: Handle Flask vs Starlette redirect behavior differences

- Remove unnecessary follow_redirects=True from Starlette TestClient
- Make test_http_function_request_url_empty_path aware of framework differences
- Starlette TestClient normalizes empty path "" to "/" while Flask preserves it
- Test now expects appropriate behavior for each framework

* fix: Exclude aio module from coverage on Python 3.7

Add special coverage configuration for Python 3.7 that excludes
the aio module since it requires Python 3.8+ due to Starlette
dependency. This prevents coverage failures on Python 3.7.

* fix: Simplify conftest.py.

* fix: Use full environment names for py37 coverage exclusion

The tox environment names in GitHub Actions include the OS suffix
(e.g., py37-ubuntu-22.04), so we need to match the full names.

* fix: Explicitly list each py37 environment for coverage exclusion

- List py37-ubuntu-22.04 and py37-macos-13 explicitly
- Place py37 settings before general windows-latest setting
- This should properly exclude aio module from coverage on Python 3.7

* fix: Add Python 3.7 specific coverage configuration

- Create .coveragerc-py37 to exclude aio module from coverage on Python 3.7
- Use --cov-config flag to specify this file for py37 environments only
- This prevents the aio module exclusion from affecting Python 3.8+ tests

Author: taeold

.coveragerc-py37

@@ -0,0 +1,10 @@
+[run]
+# Coverage configuration specifically for Python 3.7 environments
+# Excludes the aio module which requires Python 3.8+ (Starlette dependency)
+# This file is only used by py37-* tox environments
+omit = 
+    */functions_framework/aio/*
+    */.tox/*
+    */tests/*
+    */venv/*
+    */.venv/*

conftest.py

@@ -42,3 +42,53 @@ def isolate_logging():
         sys.stderr = sys.__stderr__
         logging.shutdown()
         reload(logging)
+
+
+# Safe to remove when we drop Python 3.7 support
+def pytest_ignore_collect(collection_path, config):
+    """Ignore async test files on Python 3.7 since Starlette requires Python 3.8+"""
+    if sys.version_info >= (3, 8):
+        return None
+
+    # Skip test_aio.py entirely on Python 3.7
+    if collection_path.name == "test_aio.py":
+        return True
+
+    return None
+
+
+# Safe to remove when we drop Python 3.7 support
+def pytest_collection_modifyitems(config, items):
+    """Skip async-related tests on Python 3.7 since Starlette requires Python 3.8+"""
+    if sys.version_info >= (3, 8):
+        return
+
+    skip_async = pytest.mark.skip(
+        reason="Async features require Python 3.8+ (Starlette dependency)"
+    )
+
+    # Keywords that indicate async-related tests
+    async_keywords = ["async", "asgi", "aio", "starlette"]
+
+    for item in items:
+        skip_test = False
+
+        if hasattr(item, "callspec") and hasattr(item.callspec, "params"):
+            for param_name, param_value in item.callspec.params.items():
+                # Check if test has fixtures with async-related parameters
+                if isinstance(param_value, str) and any(
+                    keyword in param_value.lower() for keyword in async_keywords
+                ):
+                    skip_test = True
+                    break
+                # Skip tests parametrized with None (create_asgi_app on Python 3.7)
+                if param_value is None:
+                    skip_test = True
+                    break
+
+        # Skip tests that explicitly test async functionality
+        if any(keyword in item.name.lower() for keyword in async_keywords):
+            skip_test = True
+
+        if skip_test:
+            item.add_marker(skip_async)

pyproject.toml

@@ -3,7 +3,7 @@ name = "functions-framework"
 version = "3.8.3"
 description = "An open source FaaS (Function as a service) framework for writing portable Python functions -- brought to you by the Google Cloud Functions team."
 readme = "README.md"
-requires-python = ">=3.5, <4"
+requires-python = ">=3.7, <4"
 # Once we drop support for Python 3.7 and 3.8, this can become
 # license = "Apache-2.0"
 license = { text = "Apache-2.0" }
@@ -29,11 +29,15 @@ dependencies = [
   "gunicorn>=22.0.0; platform_system!='Windows'",
   "cloudevents>=1.2.0,<=1.11.0",                  # Must support python 3.7
   "Werkzeug>=0.14,<4.0.0",
+  "httpx>=0.24.1",
 ]
 
 [project.urls]
 Homepage = "https://github.com/googlecloudplatform/functions-framework-python"
 
+[project.optional-dependencies]
+async = ["starlette>=0.37.0,<1.0.0; python_version>='3.8'"]
+
 [project.scripts]
 ff = "functions_framework._cli:_cli"
 functions-framework = "functions_framework._cli:_cli"

setup.py

@@ -0,0 +1,72 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from io import open
+from os import path
+
+from setuptools import find_packages, setup
+
+here = path.abspath(path.dirname(__file__))
+
+# Get the long description from the README file
+with open(path.join(here, "README.md"), encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="functions-framework",
+    version="3.8.2",
+    description="An open source FaaS (Function as a service) framework for writing portable Python functions -- brought to you by the Google Cloud Functions team.",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/googlecloudplatform/functions-framework-python",
+    author="Google LLC",
+    author_email="[email protected]",
+    classifiers=[
+        "Development Status :: 5 - Production/Stable ",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+    keywords="functions-framework",
+    packages=find_packages(where="src"),
+    package_data={"functions_framework": ["py.typed"]},
+    namespace_packages=["google", "google.cloud"],
+    package_dir={"": "src"},
+    python_requires=">=3.5, <4",
+    install_requires=[
+        "flask>=1.0,<4.0",
+        "click>=7.0,<9.0",
+        "watchdog>=1.0.0",
+        "gunicorn>=22.0.0; platform_system!='Windows'",
+        "cloudevents>=1.2.0,<2.0.0",
+        "Werkzeug>=0.14,<4.0.0",
+    ],
+    extras_require={
+        "async": ["starlette>=0.37.0,<1.0.0"],
+    },
+    entry_points={
+        "console_scripts": [
+            "ff=functions_framework._cli:_cli",
+            "functions-framework=functions_framework._cli:_cli",
+            "functions_framework=functions_framework._cli:_cli",
+            "functions-framework-python=functions_framework._cli:_cli",
+            "functions_framework_python=functions_framework._cli:_cli",
+        ]
+    },
+)