mark unwrapFirstError deprecated

matrix-org · Mar 1, 2022 · 95d2bcb · 95d2bcb
1 parent eb152c8
commit 95d2bcb
Showing 1 changed file with 3 additions and 1 deletion.
diff --git a/synapse/util/__init__.py b/synapse/util/__init__.py
@@ -81,7 +81,9 @@ def _handle_frozendict(obj: Any) -> Dict[Any, Any]:
 
 
 def unwrapFirstError(failure: Failure) -> Failure:
-    # defer.gatherResults and DeferredLists wrap failures.
+    # Deprecated: you probably just want to catch defer.FirstError and reraise
+    # the subFailure's value, which will do a better job of preserving stacktraces.
+    # (actually, you probably want to use yieldable_gather_results anyway)
     failure.trap(defer.FirstError)
     return failure.value.subFailure  # type: ignore[union-attr]  # Issue in Twisted's annotations