SONARPY-2962 Rule S7487: Async functions should not contain synchronous subprocess calls (#280)

GitOrigin-RevId: 00d3f288d80d7bb3d39d9a3e7e6ca79f12d5d3df

Author: ghislainpiot

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

@@ -364,6 +364,7 @@ public Stream<Class<?>> getChecks() {
       SuperfluousCurlyBraceCheck.class,
       SynchronousFileOperationsInAsyncCheck.class,
       SynchronousHttpOperationsInAsyncCheck.class,
+      SynchronousSubprocessOperationsInAsyncCheck.class,
       SynchronousOsCallsInAsyncCheck.class,
       TempFileCreationCheck.class,
       ImplicitlySkippedTestCheck.class,

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

@@ -0,0 +1,85 @@
+/*
+ * 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.QualifiedExpression;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.python.tree.TreeUtils;
+import org.sonar.python.types.v2.TypeCheckMap;
+
+@Rule(key = "S7487")
+public class SynchronousSubprocessOperationsInAsyncCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Use an async subprocess call in this async function instead of a synchronous one.";
+  private static final String SECONDARY_MESSAGE = "This function is async.";
+
+  private static final Set<String> SYNC_SUBPROCESS_CALLS = Set.of(
+    "subprocess.run",
+    "subprocess.Popen",
+    "subprocess.call",
+    "subprocess.check_call",
+    "subprocess.check_output",
+    "subprocess.getstatusoutput",
+    "subprocess.getoutput",
+    "os.system",
+    "os.popen",
+    "os.spawnl",
+    "os.spawnle",
+    "os.spawnlp",
+    "os.spawnlpe",
+    "os.spawnv",
+    "os.spawnve",
+    "os.spawnvp",
+    "os.spawnvpe");
+
+  private TypeCheckMap<Object> allSyncTypeChecks;
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FILE_INPUT, this::initializeTypeCheckMap);
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, this::checkCallExpression);
+  }
+
+  private void initializeTypeCheckMap(SubscriptionContext ctx) {
+    var marker = new Object();
+    allSyncTypeChecks = new TypeCheckMap<>();
+    SYNC_SUBPROCESS_CALLS.forEach(fqn -> allSyncTypeChecks.put(ctx.typeChecker().typeCheckBuilder().isTypeOrInstanceWithName(fqn), marker));
+  }
+
+  private void checkCallExpression(SubscriptionContext ctx) {
+    var call = (CallExpression) ctx.syntaxNode();
+    var asyncToken = TreeUtils.asyncTokenOfEnclosingFunction(call).orElse(null);
+    if (asyncToken == null) {
+      return;
+    }
+
+    if (allSyncTypeChecks.getOptionalForType(call.callee().typeV2()).isPresent()) {
+      ctx.addIssue(call.callee(), MESSAGE).secondary(asyncToken, SECONDARY_MESSAGE);
+      return;
+    }
+
+    if (call.callee() instanceof QualifiedExpression member && allSyncTypeChecks.getOptionalForType(member.qualifier().typeV2()).isPresent()) {
+      ctx.addIssue(call.callee(), MESSAGE).secondary(asyncToken, SECONDARY_MESSAGE);
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+<p>This rule raises an issue when synchronous subprocess calls are used within asynchronous functions.</p>
+<h2>Why is this an issue?</h2>
+<p>Using synchronous subprocess calls like <code>subprocess.Popen</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 call to create a subprocess:</p>
+<ul>
+  <li> The event loop is completely blocked until the subprocess 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 dedicated APIs for running subprocesses in a non-blocking way:</p>
+<ul>
+  <li> <code>asyncio.create_subprocess_exec()</code> and <code>asyncio.create_subprocess_shell()</code> for asyncio </li>
+  <li> <code>trio.run_process()</code> for Trio </li>
+  <li> <code>anyio.run_process()</code> for AnyIO </li>
+</ul>
+<p>Using these APIs allows other tasks to continue executing while waiting for the subprocess to complete.</p>
+<h2>How to fix it in Asyncio</h2>
+<p>Replace synchronous subprocess calls with <code>asyncio.create_subprocess_exec()</code> or <code>asyncio.create_subprocess_shell()</code> depending
+on whether you need to run a specific command with arguments or a shell command string.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+import subprocess
+
+async def process_data():
+    subprocess.run(["wget", "https://example.com/file.zip"])  # Noncompliant
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+import asyncio
+
+async def process_data():
+    proc = await asyncio.create_subprocess_exec("wget", "https://example.com/file.zip")
+    result = await proc.wait()
+</pre>
+<h2>How to fix it in Trio</h2>
+<p>Replace synchronous subprocess calls with <code>trio.run_process()</code>, which handles both command arrays and shell commands.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="2" data-diff-type="noncompliant">
+import trio
+import subprocess
+
+async def download_files():
+    result = subprocess.run(["wget", "https://example.com/file.zip"])  # Noncompliant
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="2" data-diff-type="compliant">
+import trio
+
+async def download_files():
+    result = await trio.run_process(["wget", "https://example.com/file.zip"])
+</pre>
+<h2>How to fix it in AnyIO</h2>
+<p>Replace synchronous subprocess calls with <code>anyio.run_process()</code>, which works similar to Trio’s API and supports both command arrays and
+shell commands.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="3" data-diff-type="noncompliant">
+import subprocess
+
+async def process_image():
+    result = subprocess.run(["wget", "https://example.com/file.zip"])  # Noncompliant
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="3" data-diff-type="compliant">
+import anyio
+
+async def process_image():
+    result = await anyio.run_process(["wget", "https://example.com/file.zip"])
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> Python asyncio - <a href="https://docs.python.org/3/library/asyncio-subprocess.html">Subprocess</a> </li>
+  <li> Trio - <a href="https://trio.readthedocs.io/en/stable/reference-io.html#trio.run_process">run_process() documentation</a> </li>
+  <li> AnyIO - <a href="https://anyio.readthedocs.io/en/stable/subprocesses.html">Subprocesses</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/S7487.json

@@ -0,0 +1,26 @@
+{
+  "title": "Async functions should not contain synchronous subprocess calls",
+  "type": "BUG",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "async",
+    "asyncio",
+    "anyio",
+    "trio"
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-7487",
+  "sqKey": "S7487",
+  "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

@@ -256,6 +256,7 @@
     "S6985",
     "S7483",
     "S7486",
+    "S7487",
     "S7488",
     "S7489",
     "S7491",

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

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

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

@@ -0,0 +1,109 @@
+import asyncio
+import subprocess
+import trio
+import anyio
+import os
+
+
+# Asyncio cases
+async def asyncio_with_subprocess_run():
+    # ^[sc=1;ec=5]> {{This function is async.}}
+    result = subprocess.run(["echo", "Hello World"])  # Noncompliant {{Use an async subprocess call in this async function instead of a synchronous one.}}
+#            ^^^^^^^^^^^^^^
+
+async def asyncio_with_subprocess_popen():
+    proc = subprocess.Popen(["ls", "-l"])  # Noncompliant
+    proc.wait()  # Noncompliant
+
+async def asyncio_with_subprocess_call():
+    subprocess.call(["date"])  # Noncompliant
+
+async def asyncio_with_subprocess_check_call():
+    subprocess.check_call(["whoami"])  # Noncompliant
+
+async def asyncio_with_subprocess_check_output():
+    output = subprocess.check_output(["hostname"])  # Noncompliant
+
+async def asyncio_with_os_system():
+    os.system("echo Hello")  # Noncompliant
+
+async def asyncio_with_popen_communicate():
+    proc = subprocess.Popen(["echo", "test"])  # Noncompliant
+    stdout, stderr = proc.communicate()  # Noncompliant
+
+async def asyncio_with_os_spawn():
+    os.spawnl(os.P_WAIT, "/bin/echo", "echo", "hello")  # Noncompliant
+
+async def asyncio_with_subprocess_getstatusoutput():
+    status, output = subprocess.getstatusoutput("ls")  # Noncompliant
+
+async def asyncio_with_subprocess_getoutput():
+    output = subprocess.getoutput("whoami")  # Noncompliant
+
+async def asyncio_compliant():
+    proc = await asyncio.create_subprocess_exec(
+        "echo", "Hello World",
+        stdout=asyncio.subprocess.PIPE
+    )
+    stdout, _ = await proc.communicate()
+
+    # Shell version
+    shell_proc = await asyncio.create_subprocess_shell(
+        "ls -l",
+        stdout=asyncio.subprocess.PIPE
+    )
+    await shell_proc.wait()
+
+
+# Trio cases
+async def trio_with_subprocess_run():
+    async with trio.open_nursery() as nursery:
+        result = subprocess.run(["ping", "-c", "1", "localhost"])  # Noncompliant
+
+async def trio_with_subprocess_popen():
+    async with trio.open_nursery() as nursery:
+        proc = subprocess.Popen(["python", "--version"])  # Noncompliant
+
+async def trio_with_popen_communicate():
+    async with trio.open_nursery() as nursery:
+        proc = subprocess.Popen(["echo", "trio test"])  # Noncompliant
+        stdout, stderr = proc.communicate()  # Noncompliant
+
+async def trio_compliant():
+    async with trio.open_nursery() as nursery:
+        stdout = await trio.run_process(["echo", "Hello Trio"])
+
+
+# AnyIO cases
+async def anyio_with_subprocess_run():
+    async with anyio.create_task_group() as tg:
+        result = subprocess.run(["find", ".", "-name", "*.py"])  # Noncompliant
+
+async def anyio_with_subprocess_check_output():
+    async with anyio.create_task_group() as tg:
+        output = subprocess.check_output(["ls", "-la"])  # Noncompliant
+
+async def anyio_with_popen_communicate():
+    async with anyio.create_task_group() as tg:
+        proc = subprocess.Popen(["cat", "/etc/hostname"])  # Noncompliant
+        stdout, stderr = proc.communicate()  # Noncompliant
+
+async def anyio_with_os_spawn():
+    async with anyio.create_task_group() as tg:
+        os.spawnv(os.P_WAIT, "/bin/ls", ["ls", "-l"])  # Noncompliant
+
+async def anyio_compliant():
+    async with anyio.create_task_group() as tg:
+        result = await anyio.run_process(["echo", "Hello AnyIO"])
+
+# Test cases outside async functions (should not be flagged)
+def sync_function_with_subprocess():
+    result = subprocess.run(["echo", "This is fine"])
+    proc = subprocess.Popen(["ls"])
+    proc.wait()
+    proc.communicate()
+
+def sync_function_with_os_calls():
+    os.system("echo This is also fine")
+    file_obj = os.popen("date")
+    os.spawnl(os.P_WAIT, "/bin/echo", "echo", "fine")