FastAPI 0.123.5: Async Wrappers Issue With @wraps
FastAPI, a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints, has recently encountered an issue in its version 0.123.5. This version introduces a breaking change related to the use of functools.wraps with asynchronous wrappers. This article delves into the specifics of the problem, its causes, and potential workarounds.
Understanding the Issue
The core problem arises when using @wraps to decorate an asynchronous wrapper function that wraps a synchronous function. In FastAPI 0.123.5, this pattern leads to an Internal Server Error accompanied by a ValueError. The error message typically includes TypeError exceptions, indicating that a 'coroutine' object is not iterable or that vars() argument must have __dict__ attribute. This issue stems from how FastAPI now determines whether a handler is a coroutine function.
The root cause lies in a change introduced in FastAPI 0.123.5, specifically within the Dependant.is_coroutine_callable function. This function now utilizes inspect.unwrap() to trace back to the original function being wrapped. When an asynchronous wrapper is used with @wraps, inspect.unwrap() follows the __wrapped__ attribute back to the synchronous function. Consequently, FastAPI incorrectly identifies the handler as synchronous, even though the actual registered handler is asynchronous. This misidentification leads to the observed ValueError during runtime. To illustrate, consider a scenario where you have a synchronous function decorated with an asynchronous wrapper using @wraps. Prior to version 0.123.5, FastAPI correctly recognized the asynchronous nature of the wrapper. However, with the changes in 0.123.5, the framework now sees the underlying synchronous function, causing a mismatch in expected behavior and resulting in the error.
The implications of this issue are significant for developers who rely on this pattern of wrapping synchronous functions with asynchronous handlers. Such patterns are common in scenarios where you might want to add asynchronous behavior, such as logging or authentication, around existing synchronous functions without modifying the original function's code. This breaking change necessitates a careful review of existing codebases and potentially requires adjustments to avoid the ValueError.
Code Example Demonstrating the Issue
To better illustrate the problem, let’s examine the code snippet provided in the original discussion:
from functools import wraps
import uvicorn
from fastapi import FastAPI
app = FastAPI()
def my_decorator(func):
"""A decorator that wraps a sync function with an async handler."""
@wraps(func)
async def wrapper():
func()
return 'OK'
return wrapper
@app.get('/')
@my_decorator
def index():
"""A simple sync page function."""
print('Hello!')
if __name__ == '__main__':
uvicorn.run(app)
In this example, my_decorator is designed to wrap the synchronous function index with an asynchronous wrapper. The @wraps(func) decorator is used to preserve the metadata of the original function. However, in FastAPI 0.123.5, when you visit the "/" endpoint, you’ll encounter an Internal Server Error due to the ValueError. This error occurs because FastAPI incorrectly identifies the wrapper function as synchronous, leading to the aforementioned type mismatches and exceptions.
The synchronous index function, decorated by the asynchronous wrapper, should ideally execute without issues. The wrapper is designed to handle the asynchronous context while still invoking the synchronous function. However, the change in how FastAPI determines the coroutine status of the handler disrupts this intended behavior.
This example succinctly demonstrates the core issue: the combination of @wraps with asynchronous wrappers around synchronous functions triggers a critical error in FastAPI 0.123.5. Developers utilizing this pattern will need to address this issue to ensure their applications function correctly with the updated framework version.
Technical Explanation: Diving Deeper into the Cause
To fully grasp why FastAPI 0.123.5 introduces this breaking change, it's essential to delve into the technical details of the underlying mechanism. The key lies in how FastAPI's Dependant.is_coroutine_callable function now utilizes inspect.unwrap().
Prior to this version, FastAPI likely relied on directly inspecting the decorated function to determine if it was a coroutine. This approach would correctly identify the asynchronous wrapper function as a coroutine, even though it was wrapping a synchronous function. However, the introduction of inspect.unwrap() changes this behavior significantly. inspect.unwrap() is designed to resolve the chain of decorators and trace back to the original, undecorated function.
When @wraps is used, it sets the __wrapped__ attribute on the wrapper function to point to the original function. inspect.unwrap() follows this __wrapped__ attribute chain. In the context of the example, it traces back from the asynchronous wrapper to the synchronous index function. Consequently, Dependant.is_coroutine_callable incorrectly identifies the handler as synchronous because it is evaluating the original synchronous function rather than the asynchronous wrapper.
This misidentification has cascading effects. FastAPI's internal routing and dependency injection mechanisms are predicated on correctly identifying whether a handler is asynchronous or synchronous. When a handler is incorrectly identified as synchronous, the framework attempts to invoke it in a synchronous manner, leading to errors when it encounters the coroutine object returned by the asynchronous wrapper.
The ValueError and TypeError exceptions observed are a direct result of this mismatch. The framework expects a synchronous return value but receives a coroutine, triggering the 'coroutine' object is not iterable error. Additionally, the attempt to access attributes or methods expected in a synchronous context, but not available in the coroutine object, leads to further errors.
In essence, the change in Dependant.is_coroutine_callable to use inspect.unwrap() exposes a subtle but critical interaction between @wraps and asynchronous wrappers, causing FastAPI to misinterpret the nature of the handler and resulting in the observed breaking change.
Workarounds and Solutions
Several workarounds and solutions can be employed to address the issue introduced in FastAPI 0.123.5. The most appropriate approach will depend on the specific context and requirements of your application.
1. Avoid Using @wraps with Async Wrappers
The most direct solution is to avoid using @wraps when creating asynchronous wrappers around synchronous functions. While @wraps is helpful for preserving function metadata (such as docstrings and name), it is the root cause of the problem in this scenario. By omitting @wraps, inspect.unwrap() will not trace back to the original synchronous function, and FastAPI will correctly identify the handler as asynchronous.
However, this approach comes with a trade-off. Without @wraps, you may lose some of the metadata associated with the original function. If preserving this metadata is crucial, you'll need to consider alternative approaches.
2. Manually Preserve Metadata
If you need to preserve metadata while avoiding @wraps, you can manually copy the relevant attributes from the original function to the wrapper. This involves explicitly assigning attributes like __name__, __doc__, and others as needed.
from functools import wraps
import uvicorn
from fastapi import FastAPI
app = FastAPI()
def my_decorator(func):
"""A decorator that wraps a sync function with an async handler."""
async def wrapper():
func()
return 'OK'
wrapper.__name__ = func.__name__
wrapper.__doc__ = func.__doc__
return wrapper
@app.get('/')
@my_decorator
def index():
"""A simple sync page function."""
print('Hello!')
if __name__ == '__main__':
uvicorn.run(app)
This approach provides more control over which metadata is preserved but requires more boilerplate code.
3. Downgrade FastAPI Version
If modifying your code is not immediately feasible, you can temporarily downgrade your FastAPI version to a version prior to 0.123.5. This will revert to the previous behavior where @wraps did not cause issues with asynchronous wrappers. However, this is a short-term solution, and you should plan to address the underlying problem eventually to benefit from the latest FastAPI features and bug fixes.
4. Modify FastAPI Internals (Advanced)
An advanced workaround involves modifying FastAPI's internal code to avoid using inspect.unwrap() in Dependant.is_coroutine_callable. This approach is not recommended for most users, as it involves directly altering the framework's code and may lead to compatibility issues in future updates. However, it is a potential option for those who need a specific behavior and are willing to maintain their custom modifications.
5. Wait for an Official Fix
The FastAPI team is aware of this issue and is actively working on a fix. The most prudent approach may be to monitor the FastAPI GitHub repository for updates and wait for an official patch. Once a fix is released, upgrading to the patched version will resolve the problem without requiring code modifications or workarounds.
Conclusion
FastAPI 0.123.5 introduced a breaking change related to the use of functools.wraps with asynchronous wrappers around synchronous functions. This issue stems from the framework's updated mechanism for determining whether a handler is a coroutine, which now incorrectly identifies the handler as synchronous when @wraps is used. Several workarounds are available, ranging from avoiding @wraps to manually preserving metadata. The FastAPI team is actively addressing this issue, and an official fix is expected. In the meantime, developers should carefully consider their options and choose the most appropriate solution for their specific needs. For further reading on FastAPI and its features, you might find valuable information on the FastAPI Official Documentation.
