Merge pull request #255 from realpython/subprocess

Python `subprocess`

Author: KateFinegan

subprocess/README.md

@@ -0,0 +1,7 @@
+# Python `subprocess` Examples
+
+Here are supporting materials for the Real Python tutorial [The `subprocess` Module: Wrapping Programs With Python](https://realpython.com/python-subprocess/).
+
+Be aware that some examples are designed for particular operating systems. The `basics_unix.py` file won't work on Windows, for instance.
+
+You'll find quick descriptions of what the different scripts do in the docstring of each file.

subprocess/basics_unix.py

@@ -0,0 +1,11 @@
+"""
+**Only works on Linux or macOS**
+
+Demonstrates basic usage of `subprocess.run()`.
+"""
+
+import subprocess
+
+subprocess.run(["sh", "-c", "ls"])
+
+subprocess.run(["ls"], shell=True)

subprocess/basics_win.py

@@ -0,0 +1,15 @@
+"""
+**Only works on Windows**
+
+Demonstrates basic usage of `subprocess.run()`.
+"""
+
+import subprocess
+
+# https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmd
+subprocess.run("dir", shell=True)  # COMSPEC env variable
+subprocess.run(["cmd.exe", "/c", "dir"])
+
+# https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_pwsh?view=powershell-7.2
+subprocess.run(["powershell", "-Command", "ls"])
+subprocess.run(["python", "helloworld.py"])

subprocess/create_project.py

@@ -0,0 +1,55 @@
+"""
+Uses `subprocess` to creates a Python project, complete with a virtual
+environment and initialized Git repository.
+
+Must have Git installed on the system with the `git` command available.
+
+If your Python command is `python3`, change the `PYTHON_COMMAND` variable.
+"""
+
+from argparse import ArgumentParser
+from pathlib import Path
+import subprocess
+
+PYTHON_COMMAND = "python"
+
+
+def create_new_project(name):
+    project_folder = Path.cwd().absolute() / name
+    project_folder.mkdir()
+    (project_folder / "README.md").touch()
+    with open(project_folder / ".gitignore", mode="w") as f:
+        f.write("\n".join(["venv", "__pycache__"]))
+    commands = [
+        [
+            PYTHON_COMMAND,
+            "-m",
+            "venv",
+            f"{project_folder}/venv",
+        ],
+        ["git", "-C", project_folder, "init"],
+        ["git", "-C", project_folder, "add", "."],
+        ["git", "-C", project_folder, "commit", "-m", "Initial commit"],
+    ]
+    for command in commands:
+        try:
+            subprocess.run(command, check=True, timeout=60)
+        except FileNotFoundError as exc:
+            print(
+                f"Command {command} failed because the process "
+                f"could not be found.\n{exc}"
+            )
+        except subprocess.CalledProcessError as exc:
+            print(
+                f"Command {command} failed because the process "
+                f"did not return a successful return code.\n{exc}"
+            )
+        except subprocess.TimeoutExpired as exc:
+            print(f"Command {command} timed out.\n {exc}")
+
+
+if __name__ == "__main__":
+    parser = ArgumentParser()
+    parser.add_argument("project_name", type=str)
+    args = parser.parse_args()
+    create_new_project(args.project_name)

subprocess/custom_exit.py

@@ -0,0 +1,21 @@
+"""
+Raises custom exit codes:
+
+```shell
+$ python custom_exit.py 3
+```
+
+This will exit with error code `3`. By default, will exit with code `0`.
+"""
+
+import sys
+
+print(sys.argv)
+
+try:
+    raise SystemExit(int(sys.argv[1]))
+except IndexError as e:
+    raise SystemExit(0) from e
+except ValueError as e:
+    print("Argument must be an integer")
+    raise SystemExit() from e

subprocess/error_handling.py

@@ -0,0 +1,20 @@
+"""
+Demonstrates error handling with `subprocess.run()`, catching common errors
+that `subprocess.run()` can encounter. Try changing the commands in
+`subprocess.run()` to raise different errors.
+"""
+
+import subprocess
+
+
+try:
+    subprocess.run(["python", "timer.py", "10"], timeout=5, check=True)
+except FileNotFoundError as exc:
+    print(f"Process failed because the executable could not be found.\n{exc}")
+except subprocess.CalledProcessError as exc:
+    print(
+        f"Process failed because did not return a successful return code. "
+        f"Returned {exc.returncode}\n{exc}"
+    )
+except subprocess.TimeoutExpired as exc:
+    print(f"Process timed out.\n{exc}")

subprocess/exiter.py

@@ -0,0 +1,7 @@
+"""
+Immediately exits with exit code 1
+"""
+
+import sys
+
+sys.exit(1)

subprocess/exiter_run.py

@@ -0,0 +1,13 @@
+"""
+Calls [custom_exit.py](custom_exit.py) with `subprocess.run()`,
+demonstrating the `check` argument to `.run()`.
+"""
+
+import subprocess
+
+subprocess.run(["python", "custom_exit.py", "5"], check=False)
+
+try:
+    subprocess.run(["python", "custom_exit.py", "5"], check=True)
+except subprocess.CalledProcessError as exc:
+    print(exc)

subprocess/popen_pipe.py

@@ -0,0 +1,15 @@
+"""
+**Only works on Linux or macOS**
+
+Demonstrates using `subprocess.Popen()` to pipe one command into the other.
+"""
+
+import subprocess
+
+ls_process = subprocess.Popen(["ls", "/usr/bin"], stdout=subprocess.PIPE)
+grep_process = subprocess.Popen(
+    ["grep", "python"], stdin=ls_process.stdout, stdout=subprocess.PIPE
+)
+
+for line in grep_process.stdout:
+    print(line.decode("utf-8").strip())

subprocess/popen_timer.py

@@ -0,0 +1,20 @@
+"""
+Demonstrates `subprocess.Popen()` calling [timer.py](timer.py).
+"""
+
+import subprocess
+from time import sleep
+
+with subprocess.Popen(
+    ["python", "timer.py", "5"], stdout=subprocess.PIPE
+) as process:
+
+    def poll_and_read():
+        print(f"Output from poll: {process.poll()}")
+        print(f"Output from stdout: {process.stdout.read1().decode('utf-8')}")
+
+    poll_and_read()
+    sleep(3)
+    poll_and_read()
+    sleep(3)
+    poll_and_read()