Coding style.

- Started to add docstrings.

vigil/__main__.py

@@ -1093,7 +1093,7 @@ def check_arguments():
 
 def entry_point():
     root_path, worker_count, editor_command, theme = check_arguments()
-    with terminal.console_title("vigil: " + os.path.basename(root_path)):
+    with terminal.terminal_title("vigil: " + os.path.basename(root_path)):
         manage_cache(root_path)
         with chdir(root_path):  # FIX: Don't change directory if possible.
             loop = asyncio.get_event_loop()

vigil/gut.py

@@ -3,6 +3,13 @@
 # Copyright (C) 2015-2018 Andrew Hamilton. All rights reserved.
 # Licensed under the Artistic License 2.0.
 
+
+"""Gut shows a python file with the bodies of functions and methods removed.
+
+This can be useful when initially reading a codebase.
+"""
+
+
 import re
 import sys
 
@@ -16,7 +23,7 @@ INDENT_SIZE = 4
 TAB_SIZE = 4
 
 
-def indentation_of_line(line):
+def _indentation_of_line(line):
     indentation = 0
     for character in line:
         if character == " ":
@@ -29,30 +36,31 @@ def indentation_of_line(line):
             return indentation
 
 
-def is_start_line_of_signature(line):
+def _is_start_line_of_signature(line):
     return re.match("^\s*(async)?\s*def\s", line) is not None
 
 
-def is_end_line_of_signature(line):
+def _is_end_line_of_signature(line):
     return (re.match(".*\):\s*\n$", line) is not None or
             re.match(".*\):\s*#.*\n$", line) is not None)
 
 
 def gut_module(module_contents):
+    """Gut a string of a module's contents."""
     SIGNATURE, BODY, TOP_LEVEL = 1, 2, 3
     state = TOP_LEVEL
     body_depth = 0
     result = []
     for line in module_contents.splitlines(keepends=True):
-        indent = indentation_of_line(line)
+        indent = _indentation_of_line(line)
         if state == BODY and indent is not None and \
            indent < body_depth:
             state = TOP_LEVEL
             result.append("\n")
-        if state == TOP_LEVEL and is_start_line_of_signature(line):
+        if state == TOP_LEVEL and _is_start_line_of_signature(line):
             state = SIGNATURE
             body_depth = indent + INDENT_SIZE
-        if state == SIGNATURE and is_end_line_of_signature(line):
+        if state == SIGNATURE and _is_end_line_of_signature(line):
             result.append(line)
             state = BODY
         elif state != BODY:
@@ -61,6 +69,7 @@ def gut_module(module_contents):
 
 
 def main(module_path):
+    """Gut the module at module_path."""
     with open(module_path) as module_file:
         print(gut_module(module_file.read()))
 

vigil/lscolors.py

@@ -2,6 +2,13 @@
 # Copyright (C) 2011, 2015-2018 Andrew Hamilton. All rights reserved.
 # Licensed under the Artistic License 2.0.
 
+
+"""Determine a color for a file based on its file type.
+
+This is done in the same way as the ls command.
+"""
+
+
 import os
 import os.path
 import stat
@@ -49,6 +56,7 @@ _DEFAULT_COLOR_CODES = \
 
 
 def get_color_codes(environment):
+    """Get a dictionary of the color of every file type."""
     if "LS_COLORS" in environment:
         try:
             return _parse_ls_colors(environment["LS_COLORS"])
@@ -59,6 +67,7 @@ def get_color_codes(environment):
 
 
 def color_key_for_path(path, color_codes, is_link_target=True):
+    """Get the high level type (key) of a file."""
     # see print_color_indicator in the file 'ls.c' in the coreutils codebase
     if not os.path.lexists(path):
         return MISSING_KEY
@@ -107,6 +116,7 @@ def color_key_for_path(path, color_codes, is_link_target=True):
 
 
 def color_code_for_path(path, color_codes):
+    """Get the color of a file."""
     def get_extension(basename, color_codes):
         parts = basename.split(".")
         if len(parts) == 2:

vigil/terminal.py

@@ -3,6 +3,9 @@
 # Licensed under the Artistic License 2.0.
 
 
+"""Terminal codes used to control common terminals."""
+
+
 import contextlib
 import sys
 
@@ -23,19 +26,23 @@ restore = ESC + "8"
 
 
 def color(color_number, is_foreground):
+    """Set the color of text."""
     return f"\x1b[{'38' if is_foreground else '48'};5;{color_number:d}m"
 
 
 def rgb_color(rgb, is_foreground):
+    """Set the color of text using an rgb tuple."""
     return f"\x1b[{'38' if is_foreground else '48'};2;" + "%i;%i;%im" % rgb
 
 
 def move(x, y):
+    """Move the cursor to column x, row y."""
     return f"\x1b[{y + 1:d};{x + 1:d}H"
 
 
 @contextlib.contextmanager
 def fullscreen():
+    """Enter fullscreen mode."""
     sys.stdout.write(enter_fullscreen)
     try:
         yield
@@ -45,6 +52,7 @@ def fullscreen():
 
 @contextlib.contextmanager
 def hidden_cursor():
+    """Hide the cursor."""
     sys.stdout.write(hide_cursor)
     try:
         yield
@@ -53,7 +61,8 @@ def hidden_cursor():
 
 
 @contextlib.contextmanager
-def console_title(title):
+def terminal_title(title):
+    """Set the title of the terminal window."""
     sys.stdout.write(save)
     sys.stdout.write(f"\033]0;{title}\007")
     try:

vigil/termstr.py

@@ -2,6 +2,10 @@
 # Copyright (C) 2015-2018 Andrew Hamilton. All rights reserved.
 # Licensed under the Artistic License 2.0.
 
+
+"""Termstr strings contain characters that have color and style."""
+
+
 import collections
 import functools
 import html
@@ -20,6 +24,7 @@ xterm_colormap = vigil.ColorMap.XTermColorMap()
 
 @functools.lru_cache()
 def xterm_color_to_rgb(color_index):
+    """Return the rgb color of an xterm color."""
     return vigil.ColorMap._rgb(xterm_colormap.colors[color_index])
 
 
@@ -34,6 +39,7 @@ def _cache_first_result(user_function):
 
 
 class Color:
+    """A list of common colors."""
 
     # https://en.wikipedia.org/wiki/Natural_Color_System
     black = (0, 0, 0)
@@ -54,6 +60,10 @@ class Color:
 
 
 class CharStyle:
+    """Characters have a foreground and background color, and styles.
+
+    The styles are bold, italic or underlined.
+    """
 
     _POOL = weakref.WeakValueDictionary()
     _TERMINAL256_FORMATTER = \
@@ -128,8 +138,8 @@ class CharStyle:
                     else xterm_color_to_rgb(self.fg_color))
         bg_color = (self.bg_color if type(self.bg_color) == tuple
                     else xterm_color_to_rgb(self.bg_color))
-        return (f"<style>.S{id(self)} {{font-size:80%%; color:rgb{fg_color!r}; "
-                f"background-color:rgb{bg_color!r}; "
+        return (f"<style>.S{id(self)} {{font-size:80%%; color:rgb{fg_color!r};"
+                f" background-color:rgb{bg_color!r}; "
                 f"{bold_code}{italic_code}{underline_code}}}</style>")