Moving descriptions from README to docstrings

Author: iansedano

subprocess/README.md

@@ -4,80 +4,4 @@ Here are supporting materials for the Real Python tutorial [The `subprocess` Mod
 
 Be aware that some examples are designed for particular operating systems. The `basics_unix.py` file won't work on Windows, for instance.
 
-Below, you'll find quick descriptions of what the different scripts do.
-
-## [basics_unix.py](basics_unix.py)
-
-**Only works on Linux or macOS**
-
-Demonstrates basic usage of `subprocess.run()`.
-
-## [basics_win.py](basics_win.py)
-
-**Only works on Windows**
-
-Demonstrates basic usage of `subprocess.run()`.
-
-## [custom_exit.py](custom_exit.py)
-
-Raises custom exit codes:
-
-```shell
-$ python custom_exit.py 3
-```
-
-This will exit with error code `3`. By default, will exit with code `0`.
-
-## [exiter_run.py](exiter_run.py)
-
-Calls [custom_exit.py](custom_exit.py) with `subprocess.run()`, demonstrating the `check` argument to `.run()`.
-
-## [error_handling.py](error_handling.py)
-
-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.
-
-## [timer.py](timer.py)
-
-Accepts an integer argument and will sleep for the given time. For example:
-
-```
-$ python timer.py 5
-Starting timer of 5 seconds
-.....Done!
-```
-
-## [popen_pipe.py](popen_pipe.py)
-
-**Only works on Linux or macOS**
-
-Demonstrates using `subprocess.Popen()` to pipe one command into the other.
-
-## [popen_timer.py](popen_timer.py)
-
-Demonstrates `subprocess.Popen()` calling [timer.py](timer.py).
-
-## [random_num_gen.py](random_num_gen.py)
-
-Generates and prints a random number.
-
-## [random_num_gen_check_output.py](random_num_gen_check_output.py)
-
-Uses `subprocess.run()` to call [random_num_gen.py](random_num_gen.py) to generate a random number, read the output, and then print it.
-
-## [reaction_game.py](reaction_game.py)
-
-Tests your reaction times.
-
-Note that this game can be cheated by pressing enter before the game prompts you to press enter.
-
-## [reaction_game_v2.py](reaction_game_v2.py)
-
-Tests your reaction times, but guards against the cheating described above by making you input a random letter instead.
-
-## [reaction_game_v2_hack.py](reaction_game_v2_hack.py)
-
-Uses `subprocess.Popen()` to cheat the second version of the reaction game.
-
-## [create_project.py](create_project.py)
-
-Creates a Python project, complete with a virtual environment and initialized Git repository.
+You'll find quick descriptions of what the different scripts do in the docstring of each file.

subprocess/basics_unix.py

@@ -1,6 +1,10 @@
-import subprocess
+"""
+**Only works on Linux or macOS**
+
+Demonstrates basic usage of `subprocess.run()`.
+"""
 
-# LINUX examples
+import subprocess
 
 subprocess.run(["sh", "-c", "ls"])
 

subprocess/basics_win.py

@@ -1,3 +1,9 @@
+"""
+**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/create_project.py

@@ -1,7 +1,18 @@
+"""
+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
@@ -11,7 +22,7 @@ def create_new_project(name):
         f.write("\n".join(["venv", "__pycache__"]))
     commands = [
         [
-            "python",
+            PYTHON_COMMAND,
             "-m",
             "venv",
             f"{project_folder}/venv",

subprocess/custom_exit.py

@@ -1,3 +1,13 @@
+"""
+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)

subprocess/error_handling.py

@@ -1,3 +1,9 @@
+"""
+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
 
 

subprocess/exiter.py

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

subprocess/exiter_run.py

@@ -1,3 +1,8 @@
+"""
+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)

subprocess/popen_pipe.py

@@ -1,3 +1,9 @@
+"""
+**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)

subprocess/popen_timer.py

@@ -1,3 +1,7 @@
+"""
+Demonstrates `subprocess.Popen()` calling [timer.py](timer.py).
+"""
+
 import subprocess
 from time import sleep