Meta: Resolve some pylint violations in Python lint scripts

Resolves:

* all: consider-using-sys-exit
* all: wrong-import-order
* all: TODO: Require that a few keys are set? (fixme)
* some: missing-function-docstring
* some: line-too-long

Meta/check-newlines-at-eof.py

@@ -4,57 +4,64 @@ import os
 import subprocess
 import sys
 
-os.chdir(os.path.dirname(__file__) + "/..")
 
-files = subprocess.run(
-    [
-        "git", "ls-files", "--",
-        "*.cpp",
-        "*.h",
-        "*.gml",
-        "*.html",
-        "*.js",
-        "*.css",
-        "*.sh",
-        "*.py",
-        "*.json",
-        "CMake*.txt",
-        "**/CMake*.txt",
-        ":!:AK/Tests/*.json",
-        ":!:Kernel/FileSystem/ext2_fs.h",
-        ":!:Userland/Libraries/LibELF/exec_elf.h"
-    ],
-    capture_output=True
-).stdout.decode().strip('\n').split('\n')
+def run():
+    """Check files checked in to git for trailing newlines at end of file."""
+    files = subprocess.run(
+        [
+            "git", "ls-files", "--",
+            "*.cpp",
+            "*.h",
+            "*.gml",
+            "*.html",
+            "*.js",
+            "*.css",
+            "*.sh",
+            "*.py",
+            "*.json",
+            "CMake*.txt",
+            "**/CMake*.txt",
+            ":!:AK/Tests/*.json",
+            ":!:Kernel/FileSystem/ext2_fs.h",
+            ":!:Userland/Libraries/LibELF/exec_elf.h"
+        ],
+        check=True,
+        capture_output=True
+    ).stdout.decode().strip('\n').split('\n')
 
-no_newline_at_eof_errors = []
-blank_lines_at_eof_errors = []
+    no_newline_at_eof_errors = []
+    blank_lines_at_eof_errors = []
 
-did_fail = False
-for filename in files:
-    with open(filename, "r") as f:
-        f.seek(0, os.SEEK_END)
+    did_fail = False
+    for filename in files:
+        with open(filename, "r") as f:
+            f.seek(0, os.SEEK_END)
 
-        f.seek(f.tell() - 1, os.SEEK_SET)
-        if f.read(1) != '\n':
-            did_fail = True
-            no_newline_at_eof_errors.append(filename)
-            continue
-
-        while True:
-            f.seek(f.tell() - 2, os.SEEK_SET)
-            char = f.read(1)
-            if not char.isspace():
-                break
-            if char == '\n':
+            f.seek(f.tell() - 1, os.SEEK_SET)
+            if f.read(1) != '\n':
                 did_fail = True
-                blank_lines_at_eof_errors.append(filename)
-                break
+                no_newline_at_eof_errors.append(filename)
+                continue
 
-if no_newline_at_eof_errors:
-    print("Files with no newline at the end:", " ".join(no_newline_at_eof_errors))
-if blank_lines_at_eof_errors:
-    print("Files that have blank lines at the end:", " ".join(blank_lines_at_eof_errors))
+            while True:
+                f.seek(f.tell() - 2, os.SEEK_SET)
+                char = f.read(1)
+                if not char.isspace():
+                    break
+                if char == '\n':
+                    did_fail = True
+                    blank_lines_at_eof_errors.append(filename)
+                    break
 
-if did_fail:
-    sys.exit(1)
+    if no_newline_at_eof_errors:
+        print("Files with no newline at the end:", " ".join(no_newline_at_eof_errors))
+    if blank_lines_at_eof_errors:
+        print("Files that have blank lines at the end:", " ".join(blank_lines_at_eof_errors))
+
+    if did_fail:
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    os.chdir(os.path.dirname(__file__) + "/..")
+    run()

Meta/lint-keymaps.py

@@ -2,7 +2,7 @@
 
 import json
 import os
-
+import sys
 
 PERMITTED_MAPS = ['map', 'shift_map', 'alt_map', 'altgr_map', 'shift_altgr_map']
 REQUIRED_MAPS = ['map', 'shift_map', 'alt_map']
@@ -12,10 +12,27 @@ GOOD_MAP_LENGTHS = {90, 128}
 
 
 def report(filename, problem):
+    """Print a lint problem to stdout.
+
+    Args:
+        filename (str): keymap file name
+        problem (str): problem message
+    """
     print('{}: {}'.format(filename, problem))
 
 
 def validate_single_map(filename, mapname, values):
+    """Validate a key map.
+
+    Args:
+        filename (str): keymap file name
+        mapname (str): map name (altgr_map, alt_map, shift_altgr_map)
+        values (list): key values
+
+    Returns:
+        bool: key map is valid
+    """
+
     all_good = True
 
     if not isinstance(values, list):
@@ -31,7 +48,9 @@ def validate_single_map(filename, mapname, values):
             report(filename, 'more than one character ("{}") for charmap index {} of {}'.format(c, i, mapname))
             all_good = False
 
-    # TODO: Require that a few keys are set?
+    if len(values) == 0:
+        report(filename, 'map {} is empty.'.format(mapname))
+        all_good = False
 
     if len(values) not in GOOD_MAP_LENGTHS:
         report(filename, 'length {} of map {} is suspicious. Off-by-one?'.format(len(values), mapname))
@@ -41,6 +60,16 @@ def validate_single_map(filename, mapname, values):
 
 
 def validate_fullmap(filename, fullmap):
+    """Validate a full key map for all map names (including maps for key modifiers).
+
+    Args:
+        filename (str): keymap file name
+        fullmap (dict): key mappings
+
+    Returns:
+        bool: keymap file contains valid key mappings
+    """
+
     all_good = True
 
     if not isinstance(fullmap, dict):
@@ -73,6 +102,15 @@ def validate_fullmap(filename, fullmap):
 
 
 def run_with(filenames):
+    """Check list of keymap files for errors.
+
+    Args:
+        filenames (list): keymap files to check
+
+    Returns:
+        bool: All keymap files are valid
+    """
+
     passed = 0
     for filename in filenames:
         with open(filename, 'r') as fp:
@@ -85,6 +123,12 @@ def run_with(filenames):
 
 
 def list_files_here():
+    """Retrieve a list of all '.json' files in the working directory.
+
+    Returns:
+        list: JSON file names
+    """
+
     filelist = []
     for filename in os.listdir():
         if filename.endswith('.json'):
@@ -98,10 +142,16 @@ def list_files_here():
 
 
 def run_here():
+    """Check all keymap files in the working directory for errors.
+
+    Returns:
+        bool: All keymap files are valid
+    """
+
     return run_with(list_files_here())
 
 
 if __name__ == '__main__':
     os.chdir(os.path.dirname(__file__) + "/../Base/res/keymaps/")
     if not run_here():
-        exit(1)
+        sys.exit(1)

Meta/lint-ports.py

@@ -2,20 +2,42 @@
 
 import os
 import re
+import sys
 
 # Matches e.g. "| [`bash`]..." and captures "bash" in group 1
 PORT_TABLE_REGEX = re.compile(r'^\| \[`([^`]+)`\][^`]+$', re.MULTILINE)
 
 PORT_TABLE_FILE = 'AvailablePorts.md'
-IGNORE_FILES = {'.gitignore', '.port_include.sh', PORT_TABLE_FILE, 'build_all.sh', 'build_installed.sh', 'ReadMe.md'}
+IGNORE_FILES = {
+    '.gitignore',
+    '.port_include.sh',
+    PORT_TABLE_FILE,
+    'build_all.sh',
+    'build_installed.sh',
+    'ReadMe.md'
+}
 
 
 def read_port_table(filename):
+    """Open a file and find all PORT_TABLE_REGEX matches.
+
+    Args:
+        filename (str): file name
+
+    Returns:
+        set: all PORT_TABLE_REGEX matches
+    """
     with open(filename, 'r') as fp:
         return set(PORT_TABLE_REGEX.findall(fp.read()))
 
 
 def read_port_dirs():
+    """Check Ports directory for unexpected files and check each port has a package.sh file.
+
+    Returns:
+        list: all ports (set), errors encountered (bool)
+    """
+
     ports = set()
     all_good = True
     for entry in os.listdir():
@@ -35,6 +57,8 @@ def read_port_dirs():
 
 
 def run():
+    """Check Ports directory contents for errors."""
+
     from_table = read_port_table(PORT_TABLE_FILE)
     from_fs, all_good = read_port_dirs()
 
@@ -51,12 +75,11 @@ def run():
             print('    {}'.format(port))
 
     if not all_good:
-        exit(1)
+        sys.exit(1)
 
     print('No issues found.')
 
 
 if __name__ == '__main__':
     os.chdir(os.path.dirname(__file__) + "/../Ports")
-    # Ignore argv
     run()

Meta/notify_irc.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 
 import json
-import requests
 import sys
+import requests
 
 # Must be exactly three lines each!
 # No trailing newline! (I.e. keep it as backslash-newline-tripleapostrophe.)
@@ -83,6 +83,12 @@ def compute_lines(wrapper):
 
 
 def send_notification(line):
+    """Send a message to IRC channel via HTTP bridge.
+
+    Ars:
+        line (str): message to send
+    """
+
     print('> ' + line)
     try:
         response = requests.post(SERENITY_BOT, data={'msg': line})