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,8 +4,9 @@ import os
 import subprocess
 import sys
 
-os.chdir(os.path.dirname(__file__) + "/..")
 
+def run():
+    """Check files checked in to git for trailing newlines at end of file."""
     files = subprocess.run(
         [
             "git", "ls-files", "--",
@@ -24,6 +25,7 @@ files = subprocess.run(
             ":!:Kernel/FileSystem/ext2_fs.h",
             ":!:Userland/Libraries/LibELF/exec_elf.h"
         ],
+        check=True,
         capture_output=True
     ).stdout.decode().strip('\n').split('\n')
 
@@ -58,3 +60,8 @@ if 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})