Added some more documentation

Author: edomora97

python/args.py

@@ -4,35 +4,49 @@
 from enum import Enum
 
 try:
+    # this files comes from the build system
     from task_maker.version import TASK_MAKER_VERSION
 except ImportError:
     TASK_MAKER_VERSION = "unknown"
 
 
 class CacheMode(Enum):
-    ALL = 0
-    REEVALUATE = 1
-    NOTHING = 2
+    """
+    The mode on how the cache should be used
+    """
+    ALL = 0  # cache everything
+    REEVALUATE = 1  # do not cache the evaluations
+    NOTHING = 2  # do not cache anything
 
 
 class UIS(Enum):
-    CURSES = 0
-    PRINT = 1
-    SILENT = 2
+    """
+    Kind of UI to use
+    """
+    CURSES = 0  # animated terminal curses interface
+    PRINT = 1  # print to stdout the information as soon as they arrive
+    SILENT = 2  # do not print
 
 
 class TaskFormat(Enum):
-    IOI = 0
-    TERRY = 1
-    TM = 2
+    """
+    Format of the task
+    """
+    IOI = 0  # IOI-like task
+    TERRY = 1  # Terry-like task
+    TM = 2  # Task-maker format
 
 
 class Arch(Enum):
-    DEFAULT = 0
-    X86_64 = 1
-    I686 = 2
+    """
+    Architecture to target the executables
+    """
+    DEFAULT = 0  # use the default one
+    X86_64 = 1  # force x86-64 64-bit executables
+    I686 = 2  # force i686 32-bit executables
 
 
+# patch the classes for argparse
 for cls in [UIS, CacheMode, TaskFormat, Arch]:
 
     def from_string(cls, name: str):

python/config.py

@@ -99,13 +99,19 @@ def __init__(self):
         self.bulk_total = None  # type: Optional[int]
 
     def apply_args(self, args):
+        """
+        Apply all the options from Config.OPTIONS using the argparse's result
+        """
         for group, options in Config.OPTIONS.items():
             for arg in options:
                 self._apply_arg(arg, args)
         self._get_host_port()
         self._resolve_dir()
 
     def apply_file(self):
+        """
+        Apply the configuration from the ~/.task-maker.toml file
+        """
         path = os.path.join(os.path.expanduser("~"), ".task-maker.toml")
         try:
             with open(path, "r") as f:

python/contest_maker.py

@@ -1,17 +1,20 @@
 #!/usr/bin/env python3
 
-import ruamel.yaml
-from typing import List
-import os
 import sys
 
-from task_maker.uis.bulk_finish_ui import BulkFinishUI
+import os
+import ruamel.yaml
 from task_maker.args import get_parser, UIS
 from task_maker.config import Config
 from task_maker.task_maker import setup, run
+from task_maker.uis.bulk_finish_ui import BulkFinishUI
+from typing import List
 
 
 def get_task_paths(config: Config) -> List[str]:
+    """
+    Get the paths of the tasks that have to be executed
+    """
     if config.contest_yaml:
         yaml_dir = os.path.dirname(config.contest_yaml)
         with open(config.contest_yaml) as f:
@@ -21,6 +24,9 @@ def get_task_paths(config: Config) -> List[str]:
 
 
 def bulk_run(config: Config) -> int:
+    """
+    Run all the tasks using task-maker, will return the exit code to use
+    """
     tasks = get_task_paths(config)
     if not tasks:
         raise ValueError("No tasks found")

python/detect_exe.py

@@ -25,6 +25,10 @@
 
 
 def get_exeflags(filepath: str) -> int:
+    """
+    Detect if a file is an executable, EXEFLAG_NONE if not a recognized
+    executable, something else if an executable is detected.
+    """
     with open(filepath, "rb") as file:
         buf = b""
         buf_len = 0

python/detect_format.py

@@ -2,9 +2,15 @@
 
 from os.path import join, isdir, dirname, exists
 from task_maker.args import TaskFormat
+from typing import Tuple, Optional
 
 
-def find_task_dir(task_dir: str, max_depth: int, hint: TaskFormat):
+def find_task_dir(task_dir: str, max_depth: int,
+                  hint: TaskFormat) -> Tuple[str, Optional[TaskFormat]]:
+    """
+    Find the root directory of the task which should be a parent folder of
+    task_dir. It must be at most max_depth directories above the current one.
+    """
     if task_dir.endswith("/"):
         task_dir = task_dir[:-1]
     current_format = detect_format(task_dir, hint)
@@ -13,7 +19,11 @@ def find_task_dir(task_dir: str, max_depth: int, hint: TaskFormat):
     return find_task_dir(dirname(task_dir), max_depth - 1, hint)
 
 
-def detect_format(task_dir: str, hint: TaskFormat):
+def detect_format(task_dir: str, hint: TaskFormat) -> Optional[TaskFormat]:
+    """
+    Detect the format of the task in task_dir, using hint if it matches the
+    format of the task.
+    """
     valid_formats = []
     if is_tm_format(task_dir):
         valid_formats.append(TaskFormat.TM)
@@ -33,11 +43,17 @@ def detect_format(task_dir: str, hint: TaskFormat):
     return None
 
 
-def is_tm_format(task_dir: str):
+def is_tm_format(task_dir: str) -> bool:
+    """
+    Check if the format could be task-maker
+    """
     return exists(join(task_dir, "gen", "cases.gen"))
 
 
 def is_ioi_format(task_dir: str):
+    """
+    Check if the format could be IOI-like
+    """
     if isdir(join(task_dir, "gen")):
         if exists(join(task_dir, "gen", "GEN")) and \
                 not exists(join(task_dir, "gen", "cases.gen")):
@@ -50,6 +66,9 @@ def is_ioi_format(task_dir: str):
 
 
 def is_terry_format(task_dir: str):
+    """
+    Check if the format could be Terry-like
+    """
     if isdir(join(task_dir, "managers")):
         return True
     return False

python/manager.py

@@ -13,12 +13,18 @@
 
 
 def get_task_maker_path():
+    """
+    Get the path of the cpp executable
+    """
     task_maker = os.path.dirname(__file__)
     task_maker = os.path.join(task_maker, "bin", "task-maker")
     return os.path.abspath(task_maker)
 
 
 def spawn_backend(type: str, args: List[str], daemonize: bool):
+    """
+    Spawn a backend service, eventually daemonizing it
+    """
     task_maker = get_task_maker_path()
     if daemonize:
         args.append("--daemon")
@@ -33,6 +39,9 @@ def spawn_backend(type: str, args: List[str], daemonize: bool):
 
 
 def spawn_server(config: Config):
+    """
+    Spawn the server, passing its arguments from the config
+    """
     args = []
     if config.server_logfile is not None:
         args += ["--logfile", config.server_logfile]
@@ -54,6 +63,9 @@ def spawn_server(config: Config):
 
 
 def spawn_worker(config: Config):
+    """
+    Spawn the worker, passing its arguments from the config
+    """
     args = []
     if config.worker_logfile is not None:
         args += ["--logfile", config.worker_logfile]
@@ -83,6 +95,10 @@ def spawn_worker(config: Config):
 
 
 def get_frontend(config: Config) -> Frontend:
+    """
+    Run the frontend module connecting to the server and eventually spawning it
+    if needed.
+    """
     try:
         return Frontend(config.host, config.port)
     except:

python/printer.py

@@ -3,26 +3,58 @@
 
 
 class Printer:
+    """
+    Utility class to print to various types of terminals. This class won't
+    print anything, to print use one of the subclasses.
+    """
+
     def text(self, what: str) -> None:
+        """
+        Normal, unformatted string, the newline won't be added automatically
+        """
         pass
 
     def red(self, what: str, bold: bool = True) -> None:
+        """
+        Print some text in red, optionally also in bold, the newline won't be
+        added automatically.
+        """
         pass
 
     def green(self, what: str, bold: bool = True) -> None:
+        """
+        Print some text in green, optionally also in bold, the newline won't be
+        added automatically.
+        """
         pass
 
     def blue(self, what: str, bold: bool = True) -> None:
+        """
+        Print some text in blue, optionally also in bold, the newline won't be
+        added automatically.
+        """
         pass
 
     def yellow(self, what: str, bold: bool = True) -> None:
+        """
+        Print some text in yellow, optionally also in bold, the newline won't be
+        added automatically.
+        """
         pass
 
     def bold(self, what: str, bold: bool = True) -> None:
+        """
+        Print some text in bold, the newline won't be added automatically.
+        """
         pass
 
 
 class StdoutPrinter(Printer):
+    """
+    Printer that will print to stdout using the escape sequences to make the
+    colors and so on.
+    """
+
     def __init__(self) -> None:
         self.bold_fmt = "\033[1m"
         self.green_fmt = "\033[32m"
@@ -43,40 +75,47 @@ def text(self, what: str) -> None:
 
     def red(self, what: str, bold: bool = True) -> None:
         print(
-            self.red_fmt + (self.bold_fmt
-                            if bold else "") + what + self.reset_fmt,
+            self.red_fmt + (self.bold_fmt if bold else "") + what +
+            self.reset_fmt,
             end="")
 
     def green(self, what: str, bold: bool = True) -> None:
         print(
-            self.green_fmt + (self.bold_fmt
-                              if bold else "") + what + self.reset_fmt,
+            self.green_fmt + (self.bold_fmt if bold else "") + what +
+            self.reset_fmt,
             end="")
 
     def blue(self, what: str, bold: bool = True) -> None:
         print(
-            self.blue_fmt + (self.bold_fmt
-                             if bold else "") + what + self.reset_fmt,
+            self.blue_fmt + (self.bold_fmt if bold else "") + what +
+            self.reset_fmt,
             end="")
 
     def yellow(self, what: str, bold: bool = True) -> None:
         print(
-            self.yellow_fmt + (self.bold_fmt
-                               if bold else "") + what + self.reset_fmt,
+            self.yellow_fmt + (self.bold_fmt if bold else "") + what +
+            self.reset_fmt,
             end="")
 
     def bold(self, what: str, bold: bool = True) -> None:
         print(self.bold_fmt + what + self.reset_fmt, end="")
 
     def right(self, what: str) -> None:
+        """
+        Print the text aligned to the right of the screen
+        """
         print(self.right_fmt + self.left_fmt(len(what) - 1) + what)
 
 
 class CursesPrinter(Printer):
+    """
+    Printer that will use the curses API in a curses Window.
+    """
+
     def __init__(self, stdscr: 'curses._CursesWindow') -> None:
         self.stdscr = stdscr
         self.bold_fmt = curses.A_BOLD
-        if curses.COLORS >= 256:
+        if hasattr(curses, "COLORS") and curses.COLORS >= 256:
             self.green_fmt = curses.color_pair(82)
         else:
             self.green_fmt = curses.color_pair(curses.COLOR_GREEN)
@@ -91,16 +130,16 @@ def red(self, what: str, bold: bool = True) -> None:
         self.stdscr.addstr(what, self.red_fmt | (self.bold_fmt if bold else 0))
 
     def green(self, what: str, bold: bool = True) -> None:
-        self.stdscr.addstr(what, self.green_fmt | (self.bold_fmt
-                                                   if bold else 0))
+        self.stdscr.addstr(what,
+                           self.green_fmt | (self.bold_fmt if bold else 0))
 
     def blue(self, what: str, bold: bool = True) -> None:
-        self.stdscr.addstr(what, self.blue_fmt | (self.bold_fmt
-                                                  if bold else 0))
+        self.stdscr.addstr(what,
+                           self.blue_fmt | (self.bold_fmt if bold else 0))
 
     def yellow(self, what: str, bold: bool = True) -> None:
-        self.stdscr.addstr(what, self.yellow_fmt | (self.bold_fmt
-                                                    if bold else 0))
+        self.stdscr.addstr(what,
+                           self.yellow_fmt | (self.bold_fmt if bold else 0))
 
     def bold(self, what: str, bold: bool = True) -> None:
         self.stdscr.addstr(what, self.bold_fmt)