From: Christian Heller <c.heller@plomlompom.de>
Date: Thu, 18 Jul 2024 02:50:05 +0000 (+0200)
Subject: Slightly improve code readability with comment and renaming.
X-Git-Url: https://plomlompom.com/repos/%22https:/validator.w3.org/%7B%7Bdb.prefix%7D%7D/todos?a=commitdiff_plain;h=65fd23a57f9aadd75c03bdf47c277ac8602d7d6b;p=plomtask

Slightly improve code readability with comment and renaming.
---

diff --git a/plomtask/http.py b/plomtask/http.py
index c7678a7..3d8508c 100644
--- a/plomtask/http.py
+++ b/plomtask/http.py
@@ -16,7 +16,7 @@ from plomtask.exceptions import (HandledException, BadFormatException,
 from plomtask.db import DatabaseConnection, DatabaseFile, BaseModel
 from plomtask.processes import Process, ProcessStep, ProcessStepsNode
 from plomtask.conditions import Condition
-from plomtask.todos import Todo, TodoStepsNode, DictableNode
+from plomtask.todos import Todo, TodoOrProcStepNode, DictableNode
 
 TEMPLATES_DIR = 'templates'
 
@@ -378,11 +378,11 @@ class TaskHandler(BaseHTTPRequestHandler):
 
         def walk_process_steps(node_id: int,
                                process_step_nodes: list[ProcessStepsNode],
-                               steps_nodes: list[TodoStepsNode]) -> int:
+                               steps_nodes: list[TodoOrProcStepNode]) -> int:
             for process_step_node in process_step_nodes:
                 node_id += 1
-                node = TodoStepsNode(node_id, None, process_step_node.process,
-                                     [])
+                node = TodoOrProcStepNode(node_id, None,
+                                          process_step_node.process, [])
                 steps_nodes += [node]
                 node_id = walk_process_steps(
                         node_id, list(process_step_node.steps.values()),
@@ -390,7 +390,7 @@ class TaskHandler(BaseHTTPRequestHandler):
             return node_id
 
         def walk_todo_steps(node_id: int, todos: list[Todo],
-                            steps_nodes: list[TodoStepsNode]) -> int:
+                            steps_nodes: list[TodoOrProcStepNode]) -> int:
             for todo in todos:
                 matched = False
                 for match in [item for item in steps_nodes
@@ -404,14 +404,14 @@ class TaskHandler(BaseHTTPRequestHandler):
                             node_id, todo.children, match.children)
                 if not matched:
                     node_id += 1
-                    node = TodoStepsNode(node_id, todo, None, [])
+                    node = TodoOrProcStepNode(node_id, todo, None, [])
                     steps_nodes += [node]
                     node_id = walk_todo_steps(
                             node_id, todo.children, node.children)
             return node_id
 
         def collect_adoptables_keys(
-                steps_nodes: list[TodoStepsNode]) -> set[int]:
+                steps_nodes: list[TodoOrProcStepNode]) -> set[int]:
             ids = set()
             for node in steps_nodes:
                 if not node.todo:
@@ -423,7 +423,7 @@ class TaskHandler(BaseHTTPRequestHandler):
 
         todo_steps = [step.todo for step in todo.get_step_tree(set()).children]
         process_tree = todo.process.get_steps(self.conn, None)
-        steps_todo_to_process: list[TodoStepsNode] = []
+        steps_todo_to_process: list[TodoOrProcStepNode] = []
         last_node_id = walk_process_steps(
                 0, list(process_tree.values()), steps_todo_to_process)
         for steps_node in steps_todo_to_process:
diff --git a/plomtask/todos.py b/plomtask/todos.py
index 4138abc..cb72640 100644
--- a/plomtask/todos.py
+++ b/plomtask/todos.py
@@ -12,7 +12,7 @@ from plomtask.dating import valid_date
 
 
 class DictableNode:
-    """Template for TodoNode, TodoStepsNode providing .as_dict_and_refs."""
+    """Template for TodoNode, TodoOrStepsNode providing .as_dict_and_refs."""
     # pylint: disable=too-few-public-methods
     _to_dict: list[str] = []
 
@@ -51,13 +51,13 @@ class TodoNode(DictableNode):
     _to_dict = ['todo', 'seen', 'children']
 
 
-class TodoStepsNode(DictableNode):
-    """Collect what's useful for Todo steps tree display."""
+class TodoOrProcStepNode(DictableNode):
+    """Collect what's useful for Todo-or-ProcessStep tree display."""
     # pylint: disable=too-few-public-methods
     node_id: int
     todo: Todo | None
     process: Process | None
-    children: list[TodoStepsNode]  # pylint: disable=undefined-variable
+    children: list[TodoOrProcStepNode]  # pylint: disable=undefined-variable
     fillable: bool = False
     _to_dict = ['node_id', 'todo', 'process', 'children', 'fillable']
 
@@ -120,7 +120,13 @@ class Todo(BaseModel[int], ConditionsRelations):
     @classmethod
     def create_with_children(cls, db_conn: DatabaseConnection,
                              process_id: int, date: str) -> Todo:
-        """Create Todo of process for date, ensure children."""
+        """Create Todo of process for date, ensure children demanded by chain.
+
+        At minimum creates Todo of process_id, but checks the respective
+        Process for its step tree, and walks down that to provide the initial
+        Todo with all descendants defined there, either adopting existing
+        Todos, or creating them where necessary.
+        """
 
         def key_order_func(n: ProcessStepsNode) -> int:
             assert isinstance(n.process.id_, int)