SONARPY-2960 Rule S7489: Async functions should not contain synchronous OS calls (#277)

GitOrigin-RevId: 34af3b4d68243a7494680466f2b2a98302596ef0

Author: guillaume-dequenne

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

@@ -363,8 +363,9 @@ public Stream<Class<?>> getChecks() {
       SklearnPipelineParameterAreCorrectCheck.class,
       SuperfluousCurlyBraceCheck.class,
       SynchronousFileOperationsInAsyncCheck.class,
-      TempFileCreationCheck.class,
       SynchronousHttpOperationsInAsyncCheck.class,
+      SynchronousOsCallsInAsyncCheck.class,
+      TempFileCreationCheck.class,
       ImplicitlySkippedTestCheck.class,
       TimeSleepInAsyncCheck.class,
       ToDoCommentCheck.class,

python-checks/src/main/java/org/sonar/python/checks/SynchronousOsCallsInAsyncCheck.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.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.Tree;
+import org.sonar.python.tree.TreeUtils;
+import org.sonar.python.types.v2.TypeCheckMap;
+
+@Rule(key = "S7489")
+public class SynchronousOsCallsInAsyncCheck extends PythonSubscriptionCheck {
+  private static final String MESSAGE = "Use a thread executor to wrap blocking OS calls in this async function.";
+  private static final String SECONDARY_MESSAGE = "This function is async.";
+
+  private static final Set<String> OS_BLOCKING_CALLS = Set.of(
+    "os.wait",
+    "os.waitpid",
+    "os.waitid"
+  );
+
+  private final TypeCheckMap<Object> syncOsCallsTypeChecks = new TypeCheckMap<>();
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FILE_INPUT, this::setupTypeChecks);
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, this::checkSyncOsCallsInAsync);
+  }
+
+  private void setupTypeChecks(SubscriptionContext ctx) {
+    var object = new Object();
+    OS_BLOCKING_CALLS.forEach(path -> 
+      syncOsCallsTypeChecks.put(ctx.typeChecker().typeCheckBuilder().isTypeOrInstanceWithName(path), object));
+  }
+
+  private void checkSyncOsCallsInAsync(SubscriptionContext ctx) {
+    var callExpression = (CallExpression) ctx.syntaxNode();
+    var asyncToken = TreeUtils.asyncTokenOfEnclosingFunction(callExpression).orElse(null);
+    if (asyncToken == null) {
+      return;
+    }
+
+    syncOsCallsTypeChecks.getOptionalForType(callExpression.callee().typeV2())
+      .ifPresent(object -> ctx.addIssue(callExpression.callee(), MESSAGE).secondary(asyncToken, SECONDARY_MESSAGE));
+  }
+}

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

@@ -0,0 +1,101 @@
+<p>This rule raises an issue when synchronous OS calls like <code>os.wait()</code> are used within asynchronous functions.</p>
+<h2>Why is this an issue?</h2>
+<p>Using synchronous operating system calls like <code>os.wait()</code>, <code>os.waitpid()</code>, or similar functions in asynchronous code blocks
+the entire event loop. This undermines the primary advantage of asynchronous programming - the ability to perform concurrent operations without
+blocking execution.</p>
+<p>When an async function makes a synchronous OS call:</p>
+<ul>
+  <li> The event loop is completely blocked until the OS operation completes </li>
+  <li> No other coroutines can run during this time, even if they’re ready to execute </li>
+  <li> The responsiveness of the application is degraded </li>
+  <li> In server applications, this can cause timeouts or failures for other concurrent requests </li>
+</ul>
+<p>Instead, async libraries provide mechanisms to run blocking operations in separate threads without blocking the event loop:</p>
+<ul>
+  <li> <code>asyncio.loop.run_in_executor()</code> for asyncio </li>
+  <li> <code>trio.to_thread.run_sync()</code> for Trio </li>
+  <li> <code>anyio.to_thread.run_sync()</code> for AnyIO </li>
+</ul>
+<p>Using these constructs allows other tasks to continue executing while waiting for the blocking OS call to complete.</p>
+<h2>How to fix it in Asyncio</h2>
+<p>Use <code>asyncio.loop.run_in_executor()</code> to run blocking OS calls in a separate thread pool.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+import os
+
+async def wait_for_child_process(pid):
+    pid, status = os.waitpid(pid, 0)  # Noncompliant
+    return status
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+import asyncio
+import os
+
+async def wait_for_child_process(pid):
+    loop = asyncio.get_running_loop()
+    pid, status = await loop.run_in_executor(
+        None,
+        os.waitpid, pid, 0
+    )
+    return status
+</pre>
+<h2>How to fix it in Trio</h2>
+<p>Use <code>trio.to_thread.run_sync()</code> to run blocking OS calls in a worker thread.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="2" data-diff-type="noncompliant">
+import os
+
+async def wait_for_child_process(pid):
+    pid, status = os.waitpid(pid, 0)  # Noncompliant
+    return status
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="2" data-diff-type="compliant">
+import trio
+import os
+
+async def wait_for_child_process(pid):
+    pid, status = await trio.to_thread.run_sync(
+        os.waitpid, pid, 0
+    )
+    return status
+</pre>
+<h2>How to fix it in AnyIO</h2>
+<p>Use <code>anyio.to_thread.run_sync()</code> to run blocking OS calls in a worker thread.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="3" data-diff-type="noncompliant">
+import os
+
+async def wait_for_child_process(pid):
+    pid, status = os.waitpid(pid, 0)  # Noncompliant
+    return status
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="3" data-diff-type="compliant">
+import anyio
+import os
+
+async def wait_for_child_process(pid):
+    pid, status = await anyio.to_thread.run_sync(
+        os.waitpid, pid, 0
+    )
+    return status
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor">run_in_executor()
+  documentation</a> </li>
+  <li> Trio - <a href="https://trio.readthedocs.io/en/stable/reference-core.html#trio.to_thread.run_sync">to_thread.run_sync() documentation</a> </li>
+  <li> AnyIO - <a href="https://anyio.readthedocs.io/en/stable/threads.html">Thread handling</a> </li>
+  <li> Python OS - <a href="https://docs.python.org/3/library/os.html#os.waitpid">os.waitpid() documentation</a> </li>
+</ul>
+<h3>Articles &amp; blog posts</h3>
+<ul>
+  <li> Python - <a href="https://realpython.com/python-concurrency/">Concurrency and Parallelism in Python</a> </li>
+</ul>
+

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

@@ -0,0 +1,26 @@
+{
+  "title": "Async functions should not contain synchronous OS calls",
+  "type": "BUG",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "async",
+    "asyncio",
+    "anyio",
+    "trio"
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-7489",
+  "sqKey": "S7489",
+  "scope": "All",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "RELIABILITY": "HIGH"
+    },
+    "attribute": "EFFICIENT"
+  }
+}

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

@@ -257,6 +257,7 @@
     "S7483",
     "S7486",
     "S7488",
+    "S7489",
     "S7491",
     "S7493",
     "S7494",

python-checks/src/test/java/org/sonar/python/checks/SynchronousOsCallsInAsyncCheckTest.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 SynchronousOsCallsInAsyncCheckTest {
+
+  @Test
+  void test() {
+    PythonCheckVerifier.verify("src/test/resources/checks/synchronousOsCallsInAsync.py", new SynchronousOsCallsInAsyncCheck());
+  }
+}

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

@@ -0,0 +1,32 @@
+import asyncio
+import os
+import trio
+import anyio
+from functools import partial
+
+async def asyncio_with_os_waitpid():
+#^[sc=1;ec=5]> {{This function is async.}}
+    pid, status = os.waitpid(123, 0)  # Noncompliant {{Use a thread executor to wrap blocking OS calls in this async function.}}
+#                 ^^^^^^^^^^
+
+async def asyncio_with_os_wait():
+    pid, status = os.wait()  # Noncompliant
+
+
+# Framework compliant solutions
+async def asyncio_compliant():
+    loop = asyncio.get_running_loop()
+    pid, status = await loop.run_in_executor(None, partial(os.waitpid, 123, 0))
+    pid, status = await loop.run_in_executor(None, os.wait)
+    res = await loop.run_in_executor(None, partial(os.waitid, os.P_PID, 123, os.WEXITED))
+
+    def nested_sync_function():
+        return os.waitpid(123, 0)
+
+async def trio_compliant():
+    pid, status = await trio.to_thread.run_sync(os.waitpid, 123, 0)
+    pid, status = await trio.to_thread.run_sync(os.wait)
+
+async def anyio_compliant():
+    pid, status = await anyio.to_thread.run_sync(os.waitpid, 123, 0)
+    pid, status = await anyio.to_thread.run_sync(os.wait)