SONARPY-2928 Rule S7486: Long sleep durations should use sleep_forever() instead of arbitrary intervals (#266)

GitOrigin-RevId: 5057e6663abe830b66c22a7ecdc76d707e624c77

Author: guillaume-dequenne

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

@@ -0,0 +1,90 @@
+/*
+ * 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.HashMap;
+import java.util.Map;
+import java.util.Optional;
+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.RegularArgument;
+import org.sonar.plugins.python.api.tree.Token;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.types.v2.TriBool;
+import org.sonar.python.checks.hotspots.CommonValidationUtils;
+import org.sonar.python.tree.TreeUtils;
+import org.sonar.python.types.v2.TypeCheckBuilder;
+
+@Rule(key = "S7486")
+public class AsyncLongSleepCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Replace this call with \"%s.sleep_forever()\" as the sleep duration exceeds 24 hours.";
+  private static final int SECONDS_IN_DAY = 86400;
+
+  private TypeCheckBuilder isTrioSleepCall;
+  private TypeCheckBuilder isAnyioSleepCall;
+  private final Map<String, String> asyncLibraryAliases = new HashMap<>();
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FILE_INPUT, this::setupCheck);
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, this::checkAsyncLongSleep);
+  }
+
+  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) {
+    CallExpression callExpression = (CallExpression) context.syntaxNode();
+    Expression callee = callExpression.callee();
+    
+    String libraryName;
+    if (isTrioSleepCall.check(callee.typeV2()) == TriBool.TRUE) {
+      libraryName = "trio";
+    } else if (isAnyioSleepCall.check(callee.typeV2()) == TriBool.TRUE) {
+      libraryName = "anyio";
+    } else {
+      return;
+    }
+
+    Token asyncToken = TreeUtils.asyncTokenOfEnclosingFunction(callExpression).orElse(null);
+    if (asyncToken == null) {
+      return;
+    }
+
+    Expression durationExpr = extractDurationExpression(callExpression, "trio".equals(libraryName) ? "seconds" : "delay").orElse(null);
+    if (durationExpr == null) {
+      return;
+    }
+    if (CommonValidationUtils.isMoreThan(durationExpr, SECONDS_IN_DAY)) {
+      String libraryAlias = asyncLibraryAliases.getOrDefault(libraryName, libraryName);
+      String message = String.format(MESSAGE, libraryAlias);
+      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();
+  }
+}

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

@@ -122,6 +122,7 @@ public Stream<Class<?>> getChecks() {
       AssertAfterRaiseCheck.class,
       AssertOnTupleLiteralCheck.class,
       AsyncFunctionWithTimeoutCheck.class,
+      AsyncLongSleepCheck.class,
       BackslashInStringCheck.class,
       BackticksUsageCheck.class,
       BareRaiseInFinallyCheck.class,

python-checks/src/main/java/org/sonar/python/checks/hotspots/CommonValidationUtils.java

@@ -46,6 +46,17 @@ static boolean isLessThan(Expression expression, int number) {
     }
   }
 
+  public static boolean isMoreThan(Expression expression, int number) {
+    try {
+      if (expression.is(Tree.Kind.NAME)) {
+        return Expressions.singleAssignedNonNameValue(((Name) expression)).map(value -> isMoreThan(value, number)).orElse(false);
+      }
+      return expression.is(Tree.Kind.NUMERIC_LITERAL) && ((NumericLiteral) expression).valueAsLong() > number;
+    } catch (NumberFormatException nfe) {
+      return false;
+    }
+  }
+
   static boolean isLessThanExponent(Expression expression, int exponent) {
     if (expression.is(Tree.Kind.SHIFT_EXPR)) {
       var shiftExpression = (BinaryExpression) expression;

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

@@ -0,0 +1,59 @@
+<p>This rules raises an issue when <code>trio.sleep()</code> or <code>anyio.sleep()</code> is called with a duration greater than 24 hours.</p>
+<h2>Why is this an issue?</h2>
+<p>When using <code>trio.sleep()</code> or <code>anyio.sleep()</code> with very long intervals (greater than 24 hours), the intent is usually to wait
+indefinitely or for an extremely long period. Both libraries provide dedicated methods specifically designed for this purpose:
+<code>trio.sleep_forever()</code> and <code>anyio.sleep_forever()</code>.</p>
+<p>Using explicit sleep durations greater than 24 hours has several drawbacks:</p>
+<ul>
+  <li> It obscures the developer’s intent. A very large number like <code>86400 * 365</code> doesn’t clearly communicate that the code intends to wait
+  indefinitely. </li>
+  <li> It makes code less maintainable, as other developers need to calculate what the large numbers actually represent. </li>
+</ul>
+<p>In summary, using <code>sleep_forever()</code> is preferable when the intent is to sleep indefinitely as it clearly conveys this purpose, avoiding
+maintainability issues caused by using arbitrarily large sleep durations.</p>
+<h2>How to fix it in Trio</h2>
+<p>Replace calls to <code>trio.sleep()</code> that use intervals greater than 24 hours with calls to <code>trio.sleep_forever()</code>.</p>
+<p>If the intention is truly to wait for a specific long duration rather than indefinitely, consider expressing that intent more clearly by using
+named variables or constants.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+import trio
+
+async def long_wait():
+    await trio.sleep(86400 * 365)  # Noncompliant
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+import trio
+
+async def long_wait():
+    await trio.sleep_forever()
+</pre>
+<h2>How to fix it in AnyIO</h2>
+<p>Replace calls to <code>anyio.sleep()</code> that use intervals greater than 24 hours with calls to <code>anyio.sleep_forever()</code>.</p>
+<p>If the intention is truly to wait for a specific long duration rather than indefinitely, consider expressing that intent more clearly by using
+named variables or constants.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="2" data-diff-type="noncompliant">
+import anyio
+
+async def long_wait():
+    await anyio.sleep(86400 * 30)  # Noncompliant
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="2" data-diff-type="compliant">
+import anyio
+
+async def long_wait():
+    await anyio.sleep_forever()
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> Trio - <a href="https://trio.readthedocs.io/en/stable/reference-core.html#trio.sleep_forever">sleep_forever() documentation</a> </li>
+  <li> AnyIO - <a href="https://anyio.readthedocs.io/en/stable/api.html#anyio.sleep_forever">sleep_forever() documentation</a> </li>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-task.html">Tasks and coroutines</a> </li>
+</ul>
+

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

@@ -0,0 +1,26 @@
+{
+  "title": "Long sleep durations should use sleep_forever() instead of arbitrary intervals",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "async",
+    "asyncio",
+    "anyio",
+    "trio"
+  ],
+  "defaultSeverity": "Minor",
+  "ruleSpecification": "RSPEC-7486",
+  "sqKey": "S7486",
+  "scope": "All",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "LOW"
+    },
+    "attribute": "CONVENTIONAL"
+  }
+}

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

@@ -262,6 +262,8 @@
     "S7498",
     "S7499",
     "S7501",
-    "S7510"
+    "S7510",
+    "S7486",
+    "S7501"
   ]
 }

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

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

python-checks/src/test/java/org/sonar/python/checks/hotspots/CommonValidationUtilsTest.java

@@ -27,10 +27,10 @@
 
 class CommonValidationUtilsTest {
 
-  class isLessThanTestCheck extends PythonSubscriptionCheck {
+  static class isLessThanMoreThanTestCheck extends PythonSubscriptionCheck {
     @Override
     public void initialize(Context context) {
-      context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, isLessThanTestCheck::checkCallExpr);
+      context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, isLessThanMoreThanTestCheck::checkCallExpr);
     }
 
     private static void checkCallExpr(SubscriptionContext ctx) {
@@ -40,6 +40,9 @@ private static void checkCallExpr(SubscriptionContext ctx) {
           if (CommonValidationUtils.isLessThan(argument.expression(), 10)) {
             ctx.addIssue(argument, "Argument is less than 10");
           }
+          if (CommonValidationUtils.isMoreThan(argument.expression(), 42)) {
+            ctx.addIssue(argument, "Argument is more than 42");
+          }
         });
       TreeUtils.nthArgumentOrKeywordOptional(1, "isEqualTo", callExpression.arguments())
         .ifPresent(argument -> {
@@ -52,6 +55,6 @@ private static void checkCallExpr(SubscriptionContext ctx) {
 
   @Test
   void isLessThan() {
-    PythonCheckVerifier.verify("src/test/resources/checks/commonValidationUtils.py", new isLessThanTestCheck());
+    PythonCheckVerifier.verify("src/test/resources/checks/commonValidationUtils.py", new isLessThanMoreThanTestCheck());
   }
-}
+}

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

@@ -0,0 +1,49 @@
+import trio
+import anyio
+import trio as t
+import anyio as a
+
+async def long_sleep_trio():
+    await trio.sleep(86401)  # Noncompliant
+
+async def long_sleep_trio():
+    await trio.sleep()  # OK
+
+async def long_sleep_anyio():
+    await anyio.sleep(86401)  # Noncompliant {{Replace this call with "anyio.sleep_forever()" as the sleep duration exceeds 24 hours.}}
+
+async def long_sleep_trio_arithmetic():
+    await trio.sleep(86400 * 2)  # FN
+
+async def long_sleep_with_arithmetic_2():
+    days = 30
+    await trio.sleep(86400 * days)  # FN
+
+async def long_sleep_with_alias():
+    await t.sleep(86401)  # Noncompliant {{Replace this call with "trio.sleep_forever()" as the sleep duration exceeds 24 hours.}}
+    await a.sleep(86401)  # Noncompliant {{Replace this call with "anyio.sleep_forever()" as the sleep duration exceeds 24 hours.}}
+
+# Compliant cases - duration <= 24 hours
+async def normal_sleep_trio():
+    await trio.sleep(3600)  # Compliant - one hour
+
+async def normal_sleep_anyio():
+    await anyio.sleep(86400)  # Compliant - exactly 24 hours
+
+def not_async_function():
+    # Not in async context, so not reported
+    trio.sleep(86400 * 10)  # Compliant - not in async context
+
+# Edge cases
+async def with_complex_expressions():
+    x = get_duration()
+    await trio.sleep(x)  # Compliant - can't determine value statically
+
+    # Complex expressions that can be evaluated
+    await anyio.sleep(24 * 60 * 60 * 2)  # FN
+    await trio.sleep(86400 / 0.5)  # FN
+
+async def sleep_forever():
+    # Already using the recommended alternatives
+    await trio.sleep_forever()  # Compliant
+    await anyio.sleep_forever()  # Compliant

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

@@ -17,3 +17,9 @@
 not_ten = 11
 callExpr(isEqualTo=not_ten)
 callExpr(12, var_wrong)
+
+var_too_big = 100
+callExpr(var_too_big) # Noncompliant {{Argument is more than 42}}
+callExpr(45) # Noncompliant {{Argument is more than 42}}
+
+callExpr(2e64)