refactor, reduce lines, improve readbility

rffontenelle · rffontenelle · commit ed63a34e14e7 · 2025-01-28T23:12:16.000-03:00
diff --git a/scripts/manage_translations.py b/scripts/manage_translations.py
@@ -1,12 +1,9 @@
 #!/usr/bin/env python
-"""
-Manage translation for Python documentation
-"""
 
 # SPDX-License-Identifier: CC0-1.0
 
-
 import argparse
+import contextlib
 import logging
 import os
 import shutil
@@ -16,131 +13,95 @@
 from typing import Optional
 
 ROOTDIR = Path(__file__).resolve().parent.parent
-COMMANDS = {
-    "build",
-}
-
-# Logger configuration
-logging.basicConfig(
-    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
-)
+COMMANDS = ["build"]
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
 
 
 def configure_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description=__doc__)
+    """Configure and return the argument parser."""
+    parser = argparse.ArgumentParser(description="Manage translation for Python documentation")
     parser.add_argument("command", choices=COMMANDS, help="The command to execute")
-    parser.add_argument(
-        "--language", "-l", help="Language for the translated documentation"
-    )
-    parser.add_argument("--python-version", "-v", help="Python version to be used")
-    parser.add_argument(
-        "--logs-dir",
-        "-L",
-        default=ROOTDIR / "logs",
-        help="Directory for logs (default: 'logs')",
-    )
-    parser.add_argument(
-        "--cpython-path",
-        "-c",
-        default=ROOTDIR / "cpython",
-        type=Path,
-        help="Path to the CPython repository (default: 'cpython')",
-    )
+    parser.add_argument("-l", "--language", help="Language for the translated documentation")
+    parser.add_argument("-v", "--python-version", help="Python version to be used")
+    parser.add_argument("-L", "--logs-dir", default=ROOTDIR / "logs", type=Path, help="Directory for logs")
+    parser.add_argument("-c", "--cpython-path", default=ROOTDIR / "cpython", type=Path, help="Path to the CPython repository")
     return parser
 
 
 def get_value(env_var_name: str, arg_value: Optional[str]) -> str:
-    """
-    Return value passed via command-line interface arguments *arg_value*,
-    and if not passed, use the environment variable *env_var_name* instead.
-    """
-
+    """Return a CLI argument or environment variable value."""
     value = arg_value or os.getenv(env_var_name)
     if not value:
-        logger.error(
-            f"The environment variable {env_var_name} is not defined, and no value was provided by the command line."
-        )
+        logger.error(f"The environment variable {env_var_name} is not defined, and no value was provided.")
         sys.exit(1)
     return value
 
 
 def get_minor_version(version: str) -> int:
-    """Return Python minor *version* assuming the schema as X.Y, e.g. 3.13"""
-    return int(version.split(".")[1])
+    """Return the minor version number from a version string (e.g., '3.13')."""
+    try:
+        return int(version.split(".")[1])
+    except (IndexError, ValueError) as e:
+        logger.error(f"Invalid version format '{version}': {e}")
+        sys.exit(1)
 
 
-def build(language: str, version: str, logs_dir: Path, cpython_path: Path) -> None:
+def build_docs(language: str, version: str, logs_dir: Path, cpython_path: Path) -> None:
+    """Build the documentation using Sphinx."""
     minor_version = get_minor_version(version)
     warning_log = logs_dir / "sphinxwarnings.txt"
 
-    # Sphinx options.
-    # Append gettext_compact=False if python version is 3.11 or older,
-    # because this confval was added to conf.py only in 3.12.
-    opts = f"-E -D language={language} --keep-going -w {warning_log}"
+    sphinx_opts = f"-E -D language={language} --keep-going -w {warning_log}"
     if minor_version < 12:
-        opts += " -D gettext_compact=False"
+        sphinx_opts += "-D gettext_compact=False"
 
     try:
-        # Run the make command
-        logger.info(
-            f"Building documentation for language {language}, Python version {version}."
-        )
-        subprocess.run(
-            ["make", "-C", cpython_path / "Doc", "html", f"SPHINXOPTS={opts}"],
-            check=True,
-        )
+        logger.info(f"Building documentation for {language}, Python {version}.")
+        subprocess.run([
+            "make", "-C", str(cpython_path / "Doc"), "html", f"SPHINXOPTS={sphinx_opts}"
+        ], check=True)
+
+        if warning_log.exists() and not warning_log.stat().st_size:
+            warning_log.unlink()
+            logger.info("Empty warning log file removed.")
+
     except subprocess.CalledProcessError as e:
-        logger.error(f"Error executing the make command: {e}")
-        raise
+        logger.error(f"Make command failed: {e}")
+        sys.exit(1)
+
 
-    # Remove the warning log file if it is empty
-    if warning_log.exists() and warning_log.stat().st_size == 0:
-        warning_log.unlink()
-        logger.info("The warning log file was empty and has been removed.")
+def validate_paths(cpython_path: Path) -> None:
+    """Validate necessary paths for handling documentation."""
+    if not (cpython_path / "Doc" / "conf.py").exists():
+        logger.error(f"Missing conf.py in {cpython_path}. Invalid CPython directory.")
+        sys.exit(1)
 
 
 def main() -> None:
-    # Configure ArgumentParser
     parser = configure_parser()
     args = parser.parse_args()
 
-    # Get values from environment variables or arguments
     language = get_value("PYDOC_LANGUAGE", args.language)
     version = get_value("PYDOC_VERSION", args.python_version)
     logs_dir = Path(get_value("PYDOC_LOGS", str(args.logs_dir)))
     cpython_path = args.cpython_path
 
-    # Validate contents of the CPython local checkout
-    conf_file = cpython_path / "Doc" / "conf.py"
-    if not conf_file.exists():
-        logger.error(
-            f"Configuration file '{conf_file}' not found. Invalid CPython checkout directory."
-        )
-        sys.exit(1)
+    validate_paths(cpython_path)
 
-    # Check if the command is one of those that use Sphinx
-    if args.command in [
-        "build",
-    ]:
-        # make is required
+    if args.command == "build":
         if not shutil.which("make"):
-            logger.error("Executable 'make' not found, make sure it is installed.")
+            logger.error("'make' not found. Please install it.")
             sys.exit(1)
 
-        # Create the logs directory if it doesn't exist
         logs_dir.mkdir(exist_ok=True)
-        logger.info(f"Logs will be stored in the directory: {logs_dir}")
+        logger.info(f"Logs will be stored in: {logs_dir}")
 
-        if args.command == "build":
-            # Build the documentation
-            try:
-                build(language, version, logs_dir, cpython_path)
-                logger.info("Documentation built successfully.")
-            except Exception as e:
-                logger.error(f"Error building the documentation: {e}")
-                raise
+        build_docs(language, version, logs_dir, cpython_path)
+        logger.info("Documentation build completed successfully.")
 
 
 if __name__ == "__main__":
     main()
+
