SONARPY-2961 Rule S7502: Asyncio tasks should be saved to prevent premature garbage collection (#274)

GitOrigin-RevId: 42086ea4fa8930a7a1cf9a54d7772acfa2f8233e

Author: guillaume-dequenne

python-checks/src/main/java/org/sonar/python/checks/AsyncLongSleepCheck.java

@@ -16,8 +16,6 @@
  */
 package org.sonar.python.checks;
 
-import java.util.HashMap;
-import java.util.Map;
 import java.util.Optional;
 import org.sonar.check.Rule;
 import org.sonar.plugins.python.api.PythonSubscriptionCheck;
@@ -40,7 +38,6 @@ public class AsyncLongSleepCheck extends PythonSubscriptionCheck {
 
   private TypeCheckBuilder isTrioSleepCall;
   private TypeCheckBuilder isAnyioSleepCall;
-  private final Map<String, String> asyncLibraryAliases = new HashMap<>();
 
   @Override
   public void initialize(Context context) {
@@ -51,7 +48,6 @@ public void initialize(Context context) {
   private void setupCheck(SubscriptionContext ctx) {
     isTrioSleepCall = ctx.typeChecker().typeCheckBuilder().isTypeWithFqn("trio.sleep");
     isAnyioSleepCall = ctx.typeChecker().typeCheckBuilder().isTypeWithName("anyio.sleep");
-    asyncLibraryAliases.clear();
   }
 
   private void checkAsyncLongSleep(SubscriptionContext context) {
@@ -77,14 +73,12 @@ private void checkAsyncLongSleep(SubscriptionContext context) {
       return;
     }
     if (CommonValidationUtils.isMoreThan(durationExpr, SECONDS_IN_DAY)) {
-      String libraryAlias = asyncLibraryAliases.getOrDefault(libraryName, libraryName);
-      String message = String.format(MESSAGE, libraryAlias);
+      String message = String.format(MESSAGE, libraryName);
       context.addIssue(callExpression, message).secondary(asyncToken, "This function is async.");
     }
   }
 
   private static Optional<Expression> extractDurationExpression(CallExpression callExpression, String paramName) {
-    RegularArgument durationArgument = TreeUtils.nthArgumentOrKeyword(0, paramName, callExpression.arguments());
-    return durationArgument != null ? Optional.of(durationArgument.expression()) : Optional.empty();
+    return Optional.ofNullable(TreeUtils.nthArgumentOrKeyword(0, paramName, callExpression.arguments())).map(RegularArgument::expression);
   }
 }

python-checks/src/main/java/org/sonar/python/checks/AsyncioTaskNotStoredCheck.java

@@ -0,0 +1,63 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonSubscriptionCheck;
+import org.sonar.plugins.python.api.SubscriptionContext;
+import org.sonar.plugins.python.api.tree.CallExpression;
+import org.sonar.plugins.python.api.tree.Expression;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.types.v2.PythonType;
+import org.sonar.plugins.python.api.types.v2.TriBool;
+import org.sonar.python.tree.TreeUtils;
+import org.sonar.python.types.v2.TypeCheckBuilder;
+
+@Rule(key = "S7502")
+public class AsyncioTaskNotStoredCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Save this task in a variable to prevent premature garbage collection.";
+  private static final Set<String> TASK_CREATION_FUNCTIONS = Set.of("asyncio.create_task", "asyncio.ensure_future");
+
+  private final List<TypeCheckBuilder> asyncioTaskTypeChecks = new ArrayList<>();
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FILE_INPUT, this::setupTypeChecker);
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, this::checkCallExpression);
+  }
+
+  private void setupTypeChecker(SubscriptionContext ctx) {
+    asyncioTaskTypeChecks.clear();
+    TASK_CREATION_FUNCTIONS.forEach(fqn -> asyncioTaskTypeChecks.add(ctx.typeChecker().typeCheckBuilder().isTypeWithName(fqn)));
+  }
+
+  private void checkCallExpression(SubscriptionContext ctx) {
+    CallExpression callExpression = (CallExpression) ctx.syntaxNode();
+    Expression callee = callExpression.callee();
+    PythonType calleeType = callee.typeV2();
+    if (asyncioTaskTypeChecks.stream().noneMatch(t -> t.check(calleeType) == TriBool.TRUE)) {
+      return;
+    }
+    if (TreeUtils.firstAncestorOfKind(callExpression, Tree.Kind.ASSIGNMENT_STMT, Tree.Kind.ASSIGNMENT_EXPRESSION, Tree.Kind.CALL_EXPR) == null) {
+      ctx.addIssue(callee, MESSAGE);
+    }
+  }
+}

python-checks/src/main/java/org/sonar/python/checks/OpenSourceCheckList.java

@@ -123,6 +123,7 @@ public Stream<Class<?>> getChecks() {
       AssertOnTupleLiteralCheck.class,
       AsyncFunctionNotAsyncCheck.class,
       AsyncFunctionWithTimeoutCheck.class,
+      AsyncioTaskNotStoredCheck.class,
       AsyncLongSleepCheck.class,
       BackslashInStringCheck.class,
       BackticksUsageCheck.class,

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7502.html

@@ -0,0 +1,70 @@
+<p>This rule raises an issue when <code>asyncio.create_task()</code> or <code>asyncio.ensure_future()</code> is called without saving the returned
+task.</p>
+<h2>Why is this an issue?</h2>
+<p>When creating asyncio tasks with <code>asyncio.create_task()</code> or <code>asyncio.ensure_future()</code>, you create independent units of work
+that execute concurrently. However, if you don’t save the returned task object in a variable or collection, the task may be garbage collected at any
+time, even before it’s done.</p>
+<p>This happens because the event loop only maintains a weak reference to tasks. Without a strong reference:</p>
+<ul>
+  <li> Tasks may be terminated unpredictably before completion </li>
+  <li> Application behavior becomes inconsistent and difficult to debug </li>
+  <li> Exceptions raised within the task are silently ignored </li>
+  <li> Results of the task execution are lost </li>
+  <li> Resources may not be properly released </li>
+</ul>
+<p>For a task to run to completion and handle exceptions properly, you must save the task reference and eventually await it.</p>
+<h2>How to fix it</h2>
+<p>To properly handle asyncio tasks:</p>
+<ul>
+  <li> Store the task in a variable or collection </li>
+  <li> Eventually await the task, either directly or using <code>asyncio.gather()</code>, <code>asyncio.wait()</code>, or similar functions </li>
+  <li> Consider using <code>asyncio.TaskGroup</code> (available in Python 3.11+) for structured concurrency with better cancellation semantics and
+  error handling </li>
+</ul>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+import asyncio
+
+async def fetch_data():
+    asyncio.create_task(process_data()) # Noncompliant: task may be garbage collected before completion
+
+async def process_data():
+    await asyncio.sleep(1)
+    return {"result": "processed"}
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+import asyncio
+
+async def fetch_data():
+    task = asyncio.create_task(process_data()) # Compliant
+    await task
+
+async def process_data():
+    await asyncio.sleep(1)
+    return {"result": "processed"}
+</pre>
+<p>Or, using TaskGroup (Python 3.11+):</p>
+<pre>
+import asyncio
+
+async def fetch_data():
+    async with asyncio.TaskGroup() as tg:
+        # Tasks are managed by the TaskGroup and won't be garbage collected
+        tg.create_task(process_data())
+
+async def process_data():
+    await asyncio.sleep(1)
+    return {"result": "processed"}
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task">create_task() documentation</a> </li>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-future.html#asyncio.ensure_future">ensure_future() documentation</a> </li>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-dev.html#asyncio-dev">Developing with asyncio</a> </li>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-task.html#task-object">Task Object</a> </li>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-task.html#asyncio.TaskGroup">TaskGroup documentation</a> </li>
+</ul>
+

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7502.json

@@ -0,0 +1,25 @@
+{
+  "title": "Asyncio tasks should be saved to prevent premature garbage collection",
+  "type": "BUG",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "async",
+    "asyncio",
+    "pitfall"
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-7502",
+  "sqKey": "S7502",
+  "scope": "All",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "RELIABILITY": "HIGH"
+    },
+    "attribute": "LOGICAL"
+  }
+}

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/Sonar_way_profile.json

@@ -263,11 +263,10 @@
     "S7498",
     "S7499",
     "S7501",
+    "S7502",
+    "S7503",
     "S7506",
     "S7510",
-    "S7511",
-    "S7510",
-    "S7501",
-    "S7503"
+    "S7511"
   ]
 }

python-checks/src/test/java/org/sonar/python/checks/AsyncioTaskNotStoredCheckTest.java

@@ -0,0 +1,27 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import org.junit.jupiter.api.Test;
+import org.sonar.python.checks.utils.PythonCheckVerifier;
+
+class AsyncioTaskNotStoredCheckTest {
+  @Test
+  void test() {
+    PythonCheckVerifier.verify("src/test/resources/checks/asyncioTaskNotStored.py", new AsyncioTaskNotStoredCheck());
+  }
+}

python-checks/src/test/resources/checks/asyncioTaskNotStored.py

@@ -0,0 +1,50 @@
+import asyncio
+
+async def noncompliant_example():
+    asyncio.create_task(some_coroutine()) # Noncompliant {{Save this task in a variable to prevent premature garbage collection.}}
+#   ^^^^^^^^^^^^^^^^^^^
+    asyncio.ensure_future(some_coroutine())  # Noncompliant
+    asyncio.create_task(some_function_call(param1, param2))  # Noncompliant
+
+async def compliant_examples():
+    # Compliant - task is stored in a variable
+    task1 = asyncio.create_task(some_coroutine())
+    
+    # Compliant - task is stored in a variable
+    task2 = asyncio.ensure_future(some_coroutine())
+    
+    # Compliant - tasks are stored in a collection
+    tasks = [
+        asyncio.create_task(some_coroutine()),
+        asyncio.create_task(another_coroutine())
+    ]
+    
+    # Compliant - task is passed to another function
+    await_task(asyncio.create_task(some_coroutine()))
+    
+    # Compliant - used with gather
+    await asyncio.gather(
+        asyncio.create_task(some_coroutine()),
+        asyncio.create_task(another_coroutine())
+    )
+
+async def some_coroutine():
+    await asyncio.sleep(1)
+    return {"result": "value"}
+
+async def another_coroutine():
+    await asyncio.sleep(0.5)
+    return {"result": "other value"}
+
+def some_function_call(p1, p2):
+    return some_coroutine()
+
+async def await_task(task):
+    return await task
+
+# Python 3.11+ TaskGroup example
+async def task_group_example():
+    async with asyncio.TaskGroup() as tg:
+        # Compliant - TaskGroup manages the tasks
+        tg.create_task(some_coroutine())
+        tg.create_task(another_coroutine())