SONARPY-2939 Rule S7503: Async functions should use async features (#262)

GitOrigin-RevId: 32d1c0f183dbb7a398b72bc5968bc15300fbeded

Author: guillaume-dequenne

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

@@ -0,0 +1,131 @@
+/*
+ * 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 javax.annotation.Nullable;
+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.AwaitExpression;
+import org.sonar.plugins.python.api.tree.BaseTreeVisitor;
+import org.sonar.plugins.python.api.tree.ForStatement;
+import org.sonar.plugins.python.api.tree.FunctionDef;
+import org.sonar.plugins.python.api.tree.Statement;
+import org.sonar.plugins.python.api.tree.StatementList;
+import org.sonar.plugins.python.api.tree.Token;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.tree.WithStatement;
+import org.sonar.plugins.python.api.tree.YieldExpression;
+import org.sonar.plugins.python.api.tree.YieldStatement;
+import org.sonar.python.checks.utils.CheckUtils;
+
+@Rule(key = "S7503")
+public class AsyncFunctionNotAsyncCheck extends PythonSubscriptionCheck {
+  
+  private static final String MESSAGE = "Use asynchronous features in this function or remove the `async` keyword.";
+  
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FUNCDEF, AsyncFunctionNotAsyncCheck::checkAsyncFunction);
+  }
+  
+  private static void checkAsyncFunction(SubscriptionContext ctx) {
+    FunctionDef functionDef = (FunctionDef) ctx.syntaxNode();
+    
+    Token asyncKeyword = functionDef.asyncKeyword();
+    if (asyncKeyword == null || isException(functionDef)) {
+      return;
+    }
+    AsyncFeatureVisitor visitor = new AsyncFeatureVisitor();
+    functionDef.body().accept(visitor);
+    
+    if (!visitor.hasAsyncFeature()) {
+      ctx.addIssue(functionDef.name(), MESSAGE).secondary(asyncKeyword, "This function is async.");
+    }
+  }
+
+  private static boolean isException(FunctionDef functionDef) {
+    return CheckUtils.isAbstract(functionDef) || isEmptyFunction(functionDef.body());
+  }
+  
+  private static boolean isEmptyFunction(StatementList body) {
+    for (Statement statement : body.statements()) {
+      if (!CheckUtils.isEmptyStatement(statement)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  
+  private static class AsyncFeatureVisitor extends BaseTreeVisitor {
+    
+    private boolean asyncFeatureFound = false;
+    
+    public boolean hasAsyncFeature() {
+      return asyncFeatureFound;
+    }
+    
+    @Override
+    public void visitAwaitExpression(AwaitExpression awaitExpression) {
+      asyncFeatureFound = true;
+    }
+    
+    @Override
+    public void visitForStatement(ForStatement forStatement) {
+      if (forStatement.isAsync()) {
+        asyncFeatureFound = true;
+        return;
+      }
+      if (!asyncFeatureFound) {
+        super.visitForStatement(forStatement);
+      }
+    }
+    
+    @Override
+    public void visitWithStatement(WithStatement withStatement) {
+      if (withStatement.isAsync()) {
+        asyncFeatureFound = true;
+      }
+      if (!asyncFeatureFound) {
+        super.visitWithStatement(withStatement);
+      }
+    }
+    
+    @Override
+    public void visitYieldStatement(YieldStatement yieldStatement) {
+      asyncFeatureFound = true;
+    }
+    
+    @Override
+    public void visitYieldExpression(YieldExpression yieldExpression) {
+      asyncFeatureFound = true;
+    }
+    
+    @Override
+    public void visitFunctionDef(FunctionDef functionDef) {
+      // Skip nested functions
+    }
+    
+    @Override
+    protected void scan(@Nullable Tree tree) {
+      // Stop scanning if we've already found an async feature
+      if (!asyncFeatureFound && tree != null) {
+        tree.accept(this);
+      }
+    }
+  }
+}

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

@@ -121,6 +121,7 @@ public Stream<Class<?>> getChecks() {
       AssertOnDissimilarTypesCheck.class,
       AssertAfterRaiseCheck.class,
       AssertOnTupleLiteralCheck.class,
+      AsyncFunctionNotAsyncCheck.class,
       AsyncFunctionWithTimeoutCheck.class,
       AsyncLongSleepCheck.class,
       BackslashInStringCheck.class,

python-checks/src/main/java/org/sonar/python/checks/utils/CheckUtils.java

@@ -26,12 +26,14 @@
 import org.sonar.plugins.python.api.tree.ClassDef;
 import org.sonar.plugins.python.api.tree.DictionaryLiteral;
 import org.sonar.plugins.python.api.tree.Expression;
+import org.sonar.plugins.python.api.tree.ExpressionStatement;
 import org.sonar.plugins.python.api.tree.FunctionDef;
 import org.sonar.plugins.python.api.tree.ListLiteral;
 import org.sonar.plugins.python.api.tree.Name;
 import org.sonar.plugins.python.api.tree.Parameter;
 import org.sonar.plugins.python.api.tree.ParameterList;
 import org.sonar.plugins.python.api.tree.SetLiteral;
+import org.sonar.plugins.python.api.tree.Statement;
 import org.sonar.plugins.python.api.tree.Tree;
 import org.sonar.plugins.python.api.tree.Tuple;
 import org.sonar.plugins.python.api.types.BuiltinTypes;
@@ -180,6 +182,19 @@ public static boolean isAbstract(FunctionDef funDef) {
       .anyMatch(foundDeco -> ABC_ABSTRACTMETHOD_DECORATORS.stream().anyMatch(abcDeco -> abcDeco.equals(foundDeco)));
   }
 
+  public static boolean isEmptyStatement(Statement statement) {
+    return statement.is(Tree.Kind.PASS_STMT) ||
+      (statement.is(Tree.Kind.EXPRESSION_STMT) && isStringLiteralOrEllipsis((ExpressionStatement) statement));
+  }
+
+  private static boolean isStringLiteralOrEllipsis(ExpressionStatement statement) {
+    Tree expression = statement.expressions().get(0);
+    if (expression.is(STRING_LITERAL)) {
+      return true;
+    }
+    return expression.is(Tree.Kind.ELLIPSIS);
+  }
+
   /**
    * Simple check whether the given expression is the "self" name expression.
    *

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

@@ -0,0 +1,49 @@
+<p>This rule raises an issue when a function is declared async but does not use any asynchronous features.</p>
+<h2>Why is this an issue?</h2>
+<p>Declaring a function with <code>async def</code> signals that it’s a coroutine, typically because it needs to use <code>await</code> for
+non-blocking operations (like I/O), or employs other asynchronous features like <code>async for</code> or <code>async with</code>.</p>
+<p>If none of these asynchronous mechanisms are utilized within the function’s body, the <code>async</code> declaration is superfluous.</p>
+<p>Using <code>async</code> unnecessarily can:</p>
+<ul>
+  <li> <strong>Reduce Code Clarity:</strong> It misleads developers into thinking the function performs asynchronous operations when it doesn’t,
+  making the codebase harder to understand and reason about. </li>
+  <li> <strong>Introduce Minor Overhead:</strong> Calling an <code>async def</code> function creates a coroutine object. While modern Python is
+  efficient, this still incurs more overhead than a direct synchronous function call if the asynchronicity isn’t actually leveraged. The function’s
+  body will execute synchronously until an <code>await</code> (if any) is encountered. If there’s no <code>await</code> or other async feature, it
+  essentially runs synchronously but wrapped as a coroutine. </li>
+  <li> <strong>Complicate Usage:</strong> Callers must use <code>await</code> (or schedule it as a task) to execute the coroutine and get its result.
+  This is an unnecessary ceremony if the function itself isn’t truly asynchronous. </li>
+</ul>
+<h2>How to fix it</h2>
+<p>Either remove the <code>async</code> keyword, or start using the appropriate asynchronous features.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+async def my_function():  # Noncompliant
+    print("Hello from my function")
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+def my_function():  # Compliant
+    print("Hello from my function")
+</pre>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="2" data-diff-type="noncompliant">
+def another_function(): ...
+
+async def my_function():  # Noncompliant
+    return another_function()
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="2" data-diff-type="compliant">
+async def another_function(): ...
+
+async def my_function():  # Compliant
+    return await another_function()
+</pre>
+<h2>Resources</h2>
+<h3>Articles &amp; blog posts</h3>
+<ul>
+  <li> <a href="https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/">What Color Is Your Function? - Bob Nystrom</a> </li>
+</ul>
+

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

@@ -0,0 +1,24 @@
+{
+  "title": "Async functions should use async features",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "async"
+  ],
+  "defaultSeverity": "Minor",
+  "ruleSpecification": "RSPEC-7503",
+  "sqKey": "S7503",
+  "scope": "All",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "MEDIUM",
+      "RELIABILITY": "LOW"
+    },
+    "attribute": "CONVENTIONAL"
+  }
+}

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

@@ -265,6 +265,9 @@
     "S7501",
     "S7506",
     "S7510",
-    "S7511"
+    "S7511",
+    "S7510",
+    "S7501",
+    "S7503"
   ]
 }

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

@@ -0,0 +1,28 @@
+/*
+ * 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 AsyncFunctionNotAsyncCheckTest {
+  @Test
+  void test() {
+    PythonCheckVerifier.verify("src/test/resources/checks/asyncFunctionNotAsync.py", new AsyncFunctionNotAsyncCheck());
+  }
+
+}

python-checks/src/test/java/org/sonar/python/checks/utils/CheckUtilsTest.java

@@ -98,6 +98,14 @@ void lambda_equivalence() {
     assertThat(CheckUtils.areEquivalent(parse("x = lambda a : a + 10"), parse("x = lambda a : a + 5"))).isFalse();
   }
 
+  @Test
+  void isEmptyStatement() {
+    assertThat(CheckUtils.isEmptyStatement(parse("pass").statements().statements().get(0))).isTrue();
+    assertThat(CheckUtils.isEmptyStatement(parse("...").statements().statements().get(0))).isTrue();
+    assertThat(CheckUtils.isEmptyStatement(parse("\"hello\"").statements().statements().get(0))).isTrue();
+    assertThat(CheckUtils.isEmptyStatement(parse("x = \"hello\"").statements().statements().get(0))).isFalse();
+  }
+
   @Test
   void no_parent_class() {
     FileInput file = (FileInput) parse("" +
@@ -211,7 +219,7 @@ void findFirstParameterSymbolTest() throws IOException {
     }
   }
 
-  private static Tree parse(String content) {
+  private static FileInput parse(String content) {
     PythonParser parser = PythonParser.create();
     AstNode astNode = parser.parse(content);
     FileInput parse = new PythonTreeMaker().fileInput(astNode);
@@ -220,7 +228,7 @@ private static Tree parse(String content) {
 
   private static FileInput parseFile(String path) throws IOException {
     try (var sourceFile = new Scanner(new File(path)).useDelimiter("\\Z")) {
-      return (FileInput) parse(sourceFile.next());
+      return parse(sourceFile.next());
     }
   }