Add type hints and docstrings

add_links/match.py

@@ -11,7 +11,7 @@ re_link_in_text = re.compile(r"\[\[[^]]+?\]\]", re.I | re.S)
 
 
 class LinkReplace(Exception):
-    pass
+    """Replaces and existing link."""
 
 
 en_dash = "\u2013"
@@ -54,7 +54,7 @@ patterns = [
 
 
 class NoMatch(Exception):
-    pass
+    """No match."""
 
 
 re_cite = re.compile(
@@ -98,7 +98,7 @@ def section_iter(text: str) -> typing.Iterator[tuple[str | None, str]]:
 
 
 def get_subsections(text: str, section_num: int) -> str:
-    "retrieve the text of subsections for a given section number within an article"
+    """Retrieve the text of subsections for a given section number within an article."""
     found = ""
     collection_level = None
     for num, (heading, body) in enumerate(section_iter(text)):
@@ -120,7 +120,7 @@ def get_subsections(text: str, section_num: int) -> str:
     return found
 
 
-def match_found(m, q, linkto):
+def match_found(m: re.Match[str], q: str, linkto: str | None) -> str:
     if q[1:] == m.group(0)[1:]:
         replacement = m.group(1) + q[1:]
     elif any(c.isupper() for c in q[1:]) or m.group(0) == m.group(0).upper():
@@ -159,14 +159,16 @@ def parse_links(text: str) -> typing.Iterator[tuple[str, str]]:
         yield ("text", text[prev:])
 
 
-def mk_link_matcher(q):
+def mk_link_matcher(q: str) -> typing.Callable[[str], re.Match[str] | None]:
+    """Make link matcher."""
     re_links = [p(q) for p in patterns]
 
-    def search_for_link(text):
+    def search_for_link(text: str) -> re.Match[str] | None:
         for re_link in re_links:
             m = re_link.search(text)
             if m and m.group(0).count("[[") < 4:
                 return m
+        return None
 
     return search_for_link
 
@@ -175,7 +177,10 @@ def add_link(m, replacement, text):
     return m.re.sub(lambda m: "[[%s]]" % replacement, text, count=1)
 
 
-def find_link_in_chunk(q, content, linkto=None):
+def find_link_in_chunk(
+    q: str, content: str, linkto: str | None = None
+) -> tuple[str, str | None, str | None]:
+    """Find link in chunk."""
     search_for_link = mk_link_matcher(q)
     new_content = ""
     replacement = None
@@ -245,7 +250,7 @@ def find_link_in_chunk(q, content, linkto=None):
     return (new_content, replacement, found_text_to_link)
 
 
-def find_link_in_text(q, content):
+def find_link_in_text(q: str, content: str) -> tuple[str, str]:
     (new_content, replacement) = find_link_in_chunk(q, content)
     if replacement:
         return (new_content, replacement)
@@ -280,7 +285,7 @@ def find_link_in_content(q, content, linkto=None):
     raise LinkReplace if link_replace else NoMatch
 
 
-def find_link_and_section(q, content, linkto=None):
+def find_link_and_section(q: str, content: str, linkto: str | None = None):
     if linkto:
         try:
             return find_link_and_section(linkto, content)