Enhance Documentation and Type Safety with Docstrings, Type Hints, and Comments

binaries.py

@@ -8,15 +8,21 @@
 import subprocess
 import sys
 from collections import OrderedDict
+from typing import Generator, Tuple
 
-
-class environment:
+class Environment:
+    """
+    Environment class to handle the build and distribution process for different operating systems.
+    """
 
     WIN = "win"
     LINUX = "linux"
     MACOS = "macos"
 
-    def __init__(self):
+    def __init__(self) -> None:
+        """
+        Initialize the environment based on the BINARY_OS environment variable.
+        """
         os_mapping = {
             "windows-latest": self.WIN,
             "ubuntu-20.04": self.LINUX,
@@ -25,7 +31,13 @@ def __init__(self):
         self.os = os_mapping[os.getenv("BINARY_OS")]
 
     @property
-    def python(self):
+    def python(self) -> Generator[Tuple[int, str], None, None]:
+        """
+        Generator to yield the architecture and corresponding Python executable path.
+
+        Yields:
+            Generator[Tuple[int, str], None, None]: Architecture and Python executable path.
+        """
         for arch, python in self.PYTHON_BINARIES[self.os].items():
             yield arch, python
 
@@ -49,11 +61,15 @@ def python(self):
         }
     }
 
-    def run(self, command):
-        """Runs the given command via subprocess.check_output.
+    def run(self, command: str) -> None:
+        """
+        Runs the given command via subprocess.run.
 
-        Exits with -1 if the command wasn't successfull.
+        Args:
+            command (str): The command to run.
 
+        Exits:
+            Exits with -1 if the command wasn't successful.
         """
         try:
             print(f"RUNNING: {command}")
@@ -68,16 +84,18 @@ def run(self, command):
             print(e.output and e.output.decode('utf-8'))
             sys.exit(-1)
 
-    def install(self):
+    def install(self) -> None:
         """
         Install required dependencies
         """
         for arch, python in self.python:
             self.run(f"{python} -m pip install pyinstaller")
             self.run(f"{python} -m pip install -r test_requirements.txt")
 
-    def dist(self):
-        """Runs Pyinstaller producing a binary for every platform arch."""
+    def dist(self) -> None:
+        """
+        Runs PyInstaller to produce a binary for every platform architecture.
+        """
         for arch, python in self.python:
 
             # Build the binary
@@ -102,9 +120,9 @@ def dist(self):
             else:
                 self.run(f"cp {binary_path} {artifact_path}")
 
-    def test(self):
+    def test(self) -> None:
         """
-        Runs tests for every available arch on the current platform.
+        Runs tests for every available architecture on the current platform.
         """
         for arch, python in self.python:
             self.run(f"{python} -m pytest --log-level=DEBUG")
@@ -116,7 +134,7 @@ def test(self):
         print("usage: binaries.py [install|test|dist]")
         sys.exit(-1)
 
-    env = environment()
+    env = Environment()
 
     # Runs the command in sys.argv[1] (install|test|dist)
     getattr(env, sys.argv[1])()

safety/alerts/__init__.py

@@ -1,7 +1,7 @@
 import logging
 import sys
 import json
-from typing import Any
+from typing import Any, IO
 import click
 
 from dataclasses import dataclass
@@ -16,6 +16,15 @@
 
 @dataclass
 class Alert:
+    """
+    Data class for storing alert details.
+
+    Attributes:
+        report (Any): The report data.
+        key (str): The API key for the safetycli.com vulnerability database.
+        policy (Any): The policy data.
+        requirements_files (Any): The requirements files data.
+    """
     report: Any
     key: str
     policy: Any = None
@@ -29,7 +38,16 @@ class Alert:
 @click.option("--policy-file", type=SafetyPolicyFile(), default='.safety-policy.yml',
               help="Define the policy file to be used")
 @click.pass_context
-def alert(ctx, check_report, policy_file, key):
+def alert(ctx: click.Context, check_report: IO[str], policy_file: SafetyPolicyFile, key: str) -> None:
+    """
+    Command for processing the Safety Check JSON report.
+
+    Args:
+        ctx (click.Context): The Click context object.
+        check_report (IO[str]): The file containing the JSON report.
+        policy_file (SafetyPolicyFile): The policy file to be used.
+        key (str): The API key for the safetycli.com vulnerability database.
+    """
     LOG.info('alert started')
     LOG.info(f'check_report is using stdin: {check_report == sys.stdin}')
 
@@ -48,5 +66,6 @@ def alert(ctx, check_report, policy_file, key):
 
     ctx.obj = Alert(report=safety_report, policy=policy_file if policy_file else {}, key=key)
 
+# Adding subcommands for GitHub integration
 alert.add_command(github.github_pr)
 alert.add_command(github.github_issue)