Fix remaining documentation; enable Pylint

Make Pylint fail if there are any warnings or suggestions.

Author: enzet

.githooks/pre-commit

@@ -15,6 +15,7 @@ times=()
 
 for i in "${!tools[@]}"; do
     SECONDS=0
+    echo "Checking with ${tools[i]}..."
     tool_name="${tools[i]}"
     command="${commands[i]}"
     if ! eval "$command"; then

emmio/graph.py

@@ -1,3 +1,5 @@
+"""Visualization utilities."""
+
 import random
 from collections import defaultdict
 from collections.abc import Callable, Iterator
@@ -23,16 +25,24 @@
 
 
 class Visualizer:
+    """Graph visualizer."""
+
+    interactive: bool
+    """Whether to show the graph interactively."""
+
     def __init__(self, interactive: bool = True):
         self.interactive: bool = interactive
 
     def plot(self):
+        """Plot the graph."""
         if self.interactive:
             plt.show()
         else:
             plt.savefig("out/graph.svg")
 
     def actions(self, records: list[tuple[LearningRecord, Learning]]):
+        """Show the graph of learning actions."""
+
         x: list[datetime] = []
         y: list[int] = []
         count_learning: int = 0
@@ -52,12 +62,13 @@ def cumulative_actions(
         width: float,
         by_language: bool = False,
     ) -> None:
+        """Show the graph of cumulative learning actions."""
 
         data: dict[str | int, dict[datetime, int]]
         size: int
 
         if by_language:
-            learnings = {x[1] for x in records}
+            learnings: set[Learning] = {x[1] for x in records}
             data = {
                 x.learning_language.get_code(): defaultdict(int)
                 for x in learnings
@@ -158,9 +169,11 @@ def cumulative_actions_moving(
         self,
         records: list[tuple[LearningRecord, Learning]],
         days: int,
-    ):
-        day_min = day_start(min(x[0].time for x in records))
-        day_max = day_start(max(x[0].time for x in records))
+    ) -> None:
+        """Show the graph of cumulative learning actions with moving average."""
+
+        day_min: datetime = day_start(min(x[0].time for x in records))
+        day_max: datetime = day_start(max(x[0].time for x in records))
 
         data: list[int] = [0] * ((day_max - day_min).days + 1)
 
@@ -176,7 +189,9 @@ def cumulative_actions_moving(
 
         self.plot()
 
-    def knowing(self, learnings: list[Learning]):
+    def knowing(self, learnings: list[Learning]) -> None:
+        """Show the graph of knowing words."""
+
         records: list[tuple[str, LearningRecord]] = []
 
         for learning in learnings:
@@ -324,6 +339,8 @@ def knowing(self, learnings: list[Learning]):
     def history(
         self, learnings: Iterator[Learning], marker_size: float = 0.5
     ) -> None:
+        """Show the graph of learning history."""
+
         data: dict[datetime, int] = {}
         index: int = 0
         indices: dict[str, int] = {}
@@ -346,7 +363,9 @@ def history(
         )
         self.plot()
 
-    def next_question_time(self, learnings: Iterator[Learning]):
+    def next_question_time(self, learnings: Iterator[Learning]) -> None:
+        """Show the graph of next question time."""
+
         data: dict[datetime, float] = {}
         for learning in learnings:
             for word in learning.knowledge:
@@ -365,6 +384,8 @@ def next_question_time(self, learnings: Iterator[Learning]):
         self.plot()
 
     def graph_mistakes(self, learnings: Iterator[Learning]) -> None:
+        """Show the graph of mistakes."""
+
         for learning in learnings:
             records: list[tuple[str, LearningRecord]] = []
             for record in learning.process.records:
@@ -406,8 +427,7 @@ def response_time(
         steps: int = 5,
         max_: int = 60,
     ) -> None:
-        """
-        Draw user response time histogram.
+        """Draw user response time histogram.
 
         :param records: user response records
         :param steps: number of histogram steps per second

emmio/learn/teacher.py

@@ -115,6 +115,7 @@ def __init__(
         self.max_for_day: int = self.learning.config.max_for_day
 
     async def get_new_question(self) -> str | None:
+        """Get new question to learn."""
 
         for question_id, list_, index in self.question_ids[
             self.question_index :
@@ -129,8 +130,13 @@ async def get_new_question(self) -> str | None:
         return None
 
     async def check_question_id(self, question_id) -> bool:
-        # Check whether the learning process already has the word: whether
-        # it was initially known or it is learning.
+        """Check whether the learning process already has the word.
+
+        Whether it was initially known or it is learning.
+
+        :param question_id: question identifier
+        :return: whether the word is known
+        """
         if self.learning.has(question_id):
             if self.learning.is_initially_known(question_id):
                 logging.info("Was initially known")
@@ -154,6 +160,10 @@ async def check_question_id(self, question_id) -> bool:
         return await self.check2(question_id)
 
     async def check2(self, question_id: str) -> bool:
+        """Check whether the word should be asked.
+
+        :param question_id: question identifier
+        """
         # TODO: rename.
         # Check user lexicon. Skip the word if it was mark as known by user
         # while checking lexicon. This should be done after checking
@@ -199,6 +209,10 @@ async def check2(self, question_id: str) -> bool:
         return True
 
     async def check_common(self, question_id: str) -> bool:
+        """Check whether the word is common.
+
+        :param question_id: question identifier
+        """
         # Request word definition in the dictionary.
         items: list[DictionaryItem] = (
             await self.dictionaries_to_check.get_items(
@@ -217,8 +231,7 @@ async def check_common(self, question_id: str) -> bool:
                 question_id, self.learning.learning_language, follow_links=False
             )
         )
-
-        not_common = False
+        not_common: bool = False
         for item in items_no_links:
             for language in self.learning.base_languages:
                 if item.has_definitions() and item.is_not_common(language):
@@ -231,6 +244,11 @@ async def check_common(self, question_id: str) -> bool:
         return True
 
     async def repeat(self, max_actions: int | None = None) -> bool:
+        """Start repeating process.
+
+        :param max_actions: maximum number of actions
+        :return: whether to continue
+        """
         actions: int = 0
         to_continue: bool
         session: LearningSession = LearningSession(
@@ -265,6 +283,11 @@ async def repeat(self, max_actions: int | None = None) -> bool:
         return to_continue
 
     async def learn_new(self, max_actions: int | None = None) -> bool:
+        """Start learning new words.
+
+        :param max_actions: maximum number of actions
+        :return: whether to continue
+        """
         actions: int = 0
         to_continue: bool
         session: LearningSession = LearningSession(
@@ -300,6 +323,11 @@ async def learn_new(self, max_actions: int | None = None) -> bool:
     async def repeat_and_learn_new(
         self, max_actions: int | None = None
     ) -> bool:
+        """Start repeating and learning new words.
+
+        :param max_actions: maximum number of actions
+        :return: whether to continue
+        """
         actions: int = 0
         to_continue: bool
         session: LearningSession = LearningSession(
@@ -349,7 +377,11 @@ async def repeat_and_learn_new(
 
         return to_continue
 
-    def play(self, word: str):
+    def play(self, word: str) -> None:
+        """Play the audio pronunciation of the word.
+
+        :param word: word to play
+        """
         self.audio.play(word)
 
     def print_sentence(
@@ -404,7 +436,11 @@ def print_sentence(
         self.interface.print("\n".join(translations))
 
     async def learn(self, word: str, knowledge: Knowledge | None) -> str:
+        """Start learning the word.
 
+        :param word: word to learn
+        :param knowledge: knowledge of the word
+        """
         ids_to_skip: set[int] = set()
         # if word in self.data.exclude_sentences:
         #     ids_to_skip = set(self.data.exclude_sentences[word])
@@ -598,8 +634,15 @@ async def learn(self, word: str, knowledge: Knowledge | None) -> str:
                 elif index == len(rated_sentences):
                     self.interface.print("No more sentences.")
 
-    async def process_command(self, command: str, word: str, sentence_id: int):
+    async def process_command(
+        self, command: str, word: str, sentence_id: int
+    ) -> None:
+        """Process the command.
 
+        :param command: user command
+        :param word: current learning word
+        :param sentence_id: sentence identifier
+        """
         if command in ["s", "/skip"]:
             self.learning.register(Response.SKIP, sentence_id, word)
             print(f'Word "{word}" is no longer in the learning process.')

emmio/learn/visualizer.py

@@ -1,4 +1,5 @@
 # type: ignore
+"""Learning visualizer."""
 
 from collections import defaultdict
 from dataclasses import dataclass
@@ -26,6 +27,13 @@
 
 
 def get_depth(interval: timedelta) -> int:
+    """Get depth of the word learning.
+
+    The bigger the interval, the deeper the learning.
+
+    :param interval: interval of the learning process
+    :return: depth of the learning process
+    """
     if not (seconds := interval.total_seconds()):
         return 0
 
@@ -34,6 +42,8 @@ def get_depth(interval: timedelta) -> int:
 
 @dataclass
 class LearningVisualizer:
+    """Learning process visualizer."""
+
     # User responses.
     records: list[tuple[LearningRecord, Learning]]
 

emmio/plot.py

@@ -1,3 +1,5 @@
+"""Plotting utilities."""
+
 import logging
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -39,6 +41,8 @@ def map_(value, current_min, current_max, target_min, target_max):
 
 
 def map_array(value, current_min, current_max, target_min, target_max):
+    """Remap array of values from current bounds to target bounds."""
+
     result = [None, None]
     for index in 0, 1:
         result[index] = map_(
@@ -108,7 +112,9 @@ def map_(self, point):
             self.canvas.workspace[1],
         )
 
-    def draw_background(self, svg) -> None:
+    def draw_background(self, svg: Drawing) -> None:
+        """Draw background as a rectangle."""
+
         svg.add(
             svg.rect(
                 insert=(0, 0),
@@ -119,7 +125,9 @@ def draw_background(self, svg) -> None:
             )
         )
 
-    def plot(self, svg: Drawing, data) -> None:
+    def plot(self, svg: Drawing, data: list) -> None:
+        """Plot data."""
+
         recolor: str | None = None
 
         if isinstance(self.color, list):
@@ -179,6 +187,8 @@ def plot(self, svg: Drawing, data) -> None:
                 last_text_y = text_y
 
     def to_points(self, xs: list, ys: list) -> list:
+        """Convert data to points on the canvas."""
+
         xs_second: list[float] = [(x - self.min_x).total_seconds() for x in xs]
         points: list = []
 
@@ -195,8 +205,17 @@ def to_points(self, xs: list, ys: list) -> list:
         return points
 
     def fill_between(
-        self, svg: Drawing, xs, ys_1, ys_2, color=None, label=None, opacity=None
+        self,
+        svg: Drawing,
+        xs: list,
+        ys_1: list,
+        ys_2: list,
+        color: Color | str | None = None,
+        label: str | None = None,
+        opacity: float | None = None,
     ) -> None:
+        """Fill between two lines."""
+
         recolor: str | None = None
 
         if isinstance(self.color, list):
@@ -240,13 +259,17 @@ def fill_between(
             self.text(svg, (points[-1][0] + 15, text_y), label, color)
             self.last_text_y = text_y
 
-    def write(self, svg):
+    def write(self, svg: Drawing) -> None:
+        """Write the graph to a file."""
+
         with Path(svg.filename).open("w+", encoding="utf-8") as output_file:
             svg.write(output_file)
 
         logging.info("Graph was saved to `%s`.", Path(svg.filename).absolute())
 
     def draw_grid(self, svg: Drawing) -> None:
+        """Draw grid."""
+
         group: Group = Group(opacity=0.25)
         for index in range(self.min_y, self.max_y + 1):
             mapped_1: np.ndarray = self.map_((0, index))

pyproject.toml

@@ -61,7 +61,6 @@ disable_error_code = ["import-untyped"]
 
 [tool.pylint]
 py-version = "3.12"
-fail-under = 9.0
 disable = [
     "E0401",  # Import error (Pylint usually fails to track imports correctly).
     "W0511",  # `TODO`/`FIXME` comments warning.