scripts/set-*.py: refactor even further

scripts/_common.py

@@ -7,16 +7,31 @@
 
 from pathlib import Path
 from unittest.mock import patch
+from enum import Enum
 import os
 import argparse
 import subprocess
 
 IGNORE_FILES = (".DS_Store",)
 
 
+class Colors(str, Enum):
+    def __str__(self):
+        return str(
+            self.value
+        )  # make str(Colors.COLOR) return the ANSI code instead of an Enum object
+
+    RED = "\x1b[31m"
+    GREEN = "\x1b[32m"
+    BLUE = "\x1b[34m"
+    CYAN = "\x1b[36m"
+    RESET = "\x1b[0m"
+
+
 def test_ignore_files():
     assert IGNORE_FILES == (".DS_Store",)
     assert ".DS_Store" in IGNORE_FILES
+    assert "tldr.md" not in IGNORE_FILES
 
 
 def get_tldr_root(lookup_path: Path = None) -> Path:
@@ -43,7 +58,7 @@ def get_tldr_root(lookup_path: Path = None) -> Path:
     elif "TLDR_ROOT" in os.environ:
         return Path(os.environ["TLDR_ROOT"])
     raise SystemExit(
-        "\x1b[31mPlease set TLDR_ROOT to the location of a clone of https://github.com/tldr-pages/tldr."
+        f"{Colors.RED}Please set TLDR_ROOT to the location of a clone of https://github.com/tldr-pages/tldr.{Colors.RESET}"
     )
 
 
@@ -151,32 +166,44 @@ def get_status(action: str, dry_run: bool, type: str) -> str:
 
     match action:
         case "added":
-            status_prefix = "\x1b[36m"  # Cyan color
+            start_color = Colors.CYAN  # Cyan color
         case "updated":
-            status_prefix = "\x1b[34m"  # Blue color
+            start_color = Colors.BLUE  # Blue color
         case _:
-            status_prefix = "\x1b[31m"  # Red color (default)
+            start_color = Colors.RED  # Red color (default)
 
     if dry_run:
         status = f"{type} would be {action}"
     else:
         status = f"{type} {action}"
 
-    return create_colored_line(status_prefix, status)
+    return create_colored_line(start_color, status)
 
 
 def test_get_status():
     # Test dry run status
-    assert get_status("added", True, "alias") == "\x1b[36malias would be added\x1b[0m"
-    assert get_status("updated", True, "link") == "\x1b[34mlink would be updated\x1b[0m"
+    assert (
+        get_status("added", True, "alias")
+        == f"{Colors.CYAN}alias would be added{Colors.RESET}"
+    )
+    assert (
+        get_status("updated", True, "link")
+        == f"{Colors.BLUE}link would be updated{Colors.RESET}"
+    )
 
     # Test non-dry run status
-    assert get_status("added", False, "alias") == "\x1b[36malias added\x1b[0m"
-    assert get_status("updated", False, "link") == "\x1b[34mlink updated\x1b[0m"
+    assert (
+        get_status("added", False, "alias") == f"{Colors.CYAN}alias added{Colors.RESET}"
+    )
+    assert (
+        get_status("updated", False, "link")
+        == f"{Colors.BLUE}link updated{Colors.RESET}"
+    )
 
     # Test default color for unknown action
     assert (
-        get_status("unknown", True, "alias") == "\x1b[31malias would be unknown\x1b[0m"
+        get_status("unknown", True, "alias")
+        == f"{Colors.RED}alias would be unknown{Colors.RESET}"
     )
 
 
@@ -186,12 +213,14 @@ def create_colored_line(start_color: str, text: str) -> str:
     str: A colored line
     """
 
-    return f"{start_color}{text}\x1b[0m"
+    return f"{start_color}{text}{Colors.RESET}"
 
 
 def test_create_colored_line():
-    assert create_colored_line("\x1b[36m", "TLDR") == "\x1b[36mTLDR\x1b[0m"
-    assert create_colored_line("Hello", "TLDR") == "HelloTLDR\x1b[0m"
+    assert (
+        create_colored_line(Colors.CYAN, "TLDR") == f"{Colors.CYAN}TLDR{Colors.RESET}"
+    )
+    assert create_colored_line("Hello", "TLDR") == f"HelloTLDR{Colors.RESET}"
 
 
 def create_argument_parser(description: str) -> argparse.ArgumentParser:

scripts/set-alias-page.py

@@ -36,21 +36,13 @@
        python3 scripts/set-alias-page.py -S
        python3 scripts/set-alias-page.py --sync
 
-    3. Read English alias pages, synchronize them into all translations and stage modified pages for commit:
-       python3 scripts/set-more-info-link.py -Ss
-       python3 scripts/set-more-info-link.py --sync --stage
-
-    4. Read English alias pages and show what changes would be made:
-       python3 scripts/set-alias-page.py -Sn
-       python3 scripts/set-alias-page.py --sync --dry-run
-
-    4. Read English alias pages and synchronize them for Brazilian Portuguese pages only:
+    3. Read English alias pages and synchronize them for Brazilian Portuguese pages only:
        python3 scripts/set-alias-page.py -S -l pt_BR
        python3 scripts/set-alias-page.py --sync --language pt_BR
 
     4. Read English alias pages, synchronize them into all translations and stage modified pages for commit:
-       python3 scripts/set-more-info-link.py -Ss
-       python3 scripts/set-more-info-link.py --sync --stage
+       python3 scripts/set-alias-page.py -Ss
+       python3 scripts/set-alias-page.py --sync --stage
 
     5. Read English alias pages and show what changes would be made:
        python3 scripts/set-alias-page.py -Sn
@@ -61,6 +53,7 @@
 from pathlib import Path
 from _common import (
     IGNORE_FILES,
+    Colors,
     get_tldr_root,
     get_pages_dir,
     get_locale,
@@ -73,6 +66,16 @@
 IGNORE_FILES += ("tldr.md", "aria2.md")
 
 
+def test_ignore_files():
+    assert IGNORE_FILES == (
+        ".DS_Store",
+        "tldr.md",
+        "aria2.md",
+    )
+    assert ".DS_Store" in IGNORE_FILES
+    assert "tldr.md" in IGNORE_FILES
+
+
 def get_templates(root: Path):
     """
     Get all alias page translation templates from
@@ -117,28 +120,9 @@ def get_templates(root: Path):
     return templates
 
 
-def get_alias_page(path: Path):
-    """
-    Determine whether the given path is an alias page.
-
-    Parameters:
-    path (Path): Path to a page
-
-    Returns:
-    str: "" If the path doesn't exit or is not an alias page,
-         otherwise return what command the alias stands for.
-    """
-
-    if not path.exists():
-        return ""
-    with open(path, "r", encoding="utf-8") as f:
-        for line in f:
-            if match := re.search(r"^`tldr (.+)`", line):
-                return match[1]
-    return ""
-
-
-def set_alias_page(path: Path, command: str, dry_run=False, language_to_update=""):
+def set_alias_page(
+    path: Path, command: str, dry_run=False, language_to_update=""
+) -> str:
     """
     Write an alias page to disk.
 
@@ -184,7 +168,28 @@ def set_alias_page(path: Path, command: str, dry_run=False, language_to_update="
     return status
 
 
-def sync_alias(
+def get_alias_page(path: Path):
+    """
+    Determine whether the given path is an alias page.
+
+    Parameters:
+    path (Path): Path to a page
+
+    Returns:
+    str: "" If the path doesn't exit or is not an alias page,
+         otherwise return what command the alias stands for.
+    """
+
+    if not path.exists():
+        return ""
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            if match := re.search(r"^`tldr (.+)`", line):
+                return match[1]
+    return ""
+
+
+def sync(
     root: Path,
     pages_dirs: list[str],
     alias_name: str,
@@ -213,7 +218,7 @@ def sync_alias(
         if status != "":
             rel_path = "/".join(path.parts[-3:])
             rel_paths.append(rel_path)
-            print(f"\x1b[32m{rel_path} {status}\x1b[0m")
+            print(create_colored_line(Colors.GREEN, f"{rel_path} {status}"))
     return rel_paths
 
 
@@ -251,7 +256,7 @@ def main():
             rel_path = "/".join(path.parts[-3:])
             status = set_alias_page(path, args.command)
             if status != "":
-                print(create_colored_line("\x1b[32m", f"{rel_path} {status}"))
+                print(create_colored_line(Colors.GREEN, f"{rel_path} {status}"))
 
     # Use '--sync' option
     elif args.sync:
@@ -268,7 +273,7 @@ def main():
             for command in commands:
                 original_command = get_alias_page(root / "pages" / command)
                 if original_command != "":
-                    target_paths += sync_alias(
+                    target_paths += sync(
                         root,
                         pages_dirs,
                         command,

scripts/set-more-info-link.py

@@ -5,16 +5,18 @@
 A Python script to add or update the "More information" link for all translations of a page.
 
 Note: If the current directory or one of its parents is called "tldr", the script will assume it is the tldr root, i.e., the directory that contains a clone of https://github.com/tldr-pages/tldr
-If you aren't, the script will use TLDR_ROOT as the tldr root. Also, ensure 'git' is available.
+If the script doesn't find it in the current path, the environment variable TLDR_ROOT will be used as the tldr root. Also, ensure 'git' is available.
 
 Usage:
-    python3 scripts/set-more-info-link.py [-p PAGE] [-S] [-s] [-n] [LINK]
+    python3 scripts/set-more-info-link.py [-p PAGE] [-S] [-l LANGUAGE] [-s] [-n] [LINK]
 
 Options:
     -p, --page PAGE
-        Specify the alias page in the format "platform/alias_command.md". This option allows setting the link for a specific page.
+        Specify the alias page in the format "platform/alias_command". This option allows setting the link for a specific page.
     -S, --sync
         Synchronize each translation's more information link (if exists) with that of the English page.
+    -l, --language LANGUAGE
+        Specify the language, a POSIX Locale Name in the form of "ll" or "ll_CC" (e.g. "fr" or "pt_BR").
     -s, --stage
         Stage modified pages (requires 'git' on $PATH and TLDR_ROOT to be a Git repository).
     -n, --dry-run
@@ -25,18 +27,22 @@
 
 Examples:
     1. Set the link for a specific page:
-       python3 scripts/set-more-info-link.py -p common/tar.md https://example.com
-       python3 scripts/set-more-info-link.py --page common/tar.md https://example.com
+       python3 scripts/set-more-info-link.py -p common/tar https://example.com
+       python3 scripts/set-more-info-link.py --page common/tar https://example.com
 
-    2. Read English pages and synchronize more information links across translations:
+    2. Read English pages and synchronize the "More information" link across translations:
        python3 scripts/set-more-info-link.py -S
        python3 scripts/set-more-info-link.py --sync
 
-    3. Read English pages, synchronize more information links across translations and stage modified pages for commit:
+    3. Read English pages and synchronize the "More information" link for Brazilian Portuguese pages only:
+       python3 scripts/set-page-title.py -S -l pt_BR
+       python3 scripts/set-page-title.py --sync --language pt_BR
+
+    4. Read English pages, synchronize the "More information" link across translations and stage modified pages for commit:
        python3 scripts/set-more-info-link.py -Ss
        python3 scripts/set-more-info-link.py --sync --stage
 
-    4. Show what changes would be made across translations:
+    5. Show what changes would be made across translations:
        python3 scripts/set-more-info-link.py -Sn
        python3 scripts/set-more-info-link.py --sync --dry-run
 """
@@ -45,6 +51,7 @@
 from pathlib import Path
 from _common import (
     IGNORE_FILES,
+    Colors,
     get_tldr_root,
     get_pages_dir,
     get_locale,
@@ -95,7 +102,7 @@
 }
 
 
-def set_link(path: Path, link: str, dry_run=False) -> str:
+def set_link(path: Path, link: str, dry_run=False, language_to_update="") -> str:
     with path.open(encoding="utf-8") as f:
         lines = f.readlines()
 
@@ -111,6 +118,9 @@ def set_link(path: Path, link: str, dry_run=False) -> str:
             break
 
     locale = get_locale(path)
+    if language_to_update != "" and locale != language_to_update:
+        # return empty status to indicate that no changes were made
+        return ""
 
     # build new line
     if locale in ["bn", "hi", "ne"]:
@@ -167,17 +177,22 @@ def get_link(path: Path) -> str:
 
 
 def sync(
-    root: Path, pages_dirs: list[str], command: str, link: str, dry_run=False
+    root: Path,
+    pages_dirs: list[str],
+    command: str,
+    link: str,
+    dry_run=False,
+    language_to_update="",
 ) -> list[str]:
     paths = []
     for page_dir in pages_dirs:
         path = root / page_dir / command
         if path.exists():
             rel_path = "/".join(path.parts[-3:])
-            status = set_link(path, link, dry_run)
+            status = set_link(path, link, dry_run, language_to_update)
             if status != "":
                 paths.append(path)
-                print(f"\x1b[32m{rel_path} {status}\x1b[0m")
+                print(create_colored_line(Colors.GREEN, f"{rel_path} {status}"))
     return paths
 
 
@@ -211,7 +226,7 @@ def main():
             rel_path = "/".join(path.parts[-3:])
             status = set_link(path, args.link)
             if status != "":
-                print(create_colored_line("\x1b[32m", f"{rel_path} {status}"))
+                print(create_colored_line(Colors.GREEN, f"{rel_path} {status}"))
 
     # Use '--sync' option
     elif args.sync: