chore: Type hinting fixes and update

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
     "Topic :: Utilities",
 ]
 
-requires-python = ">=3.8"
+requires-python = ">=3.12"
 dependencies = [
     "Sphinx >= 4",
     "langid",

src/sphinxnotes/snippet/cache.py

@@ -1,12 +1,12 @@
-"""sphinxnotes.snippet.cache
+"""
+sphinxnotes.snippet.cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :copyright: Copyright 2021 Shengyu Zhang
 :license: BSD, see LICENSE for details.
 """
 
 from __future__ import annotations
-from typing import List, Tuple, Dict, Optional
 from dataclasses import dataclass
 
 from .snippets import Snippet
@@ -18,25 +18,25 @@ class Item(object):
     """Item of snippet cache."""
 
     snippet: Snippet
-    tags: List[str]
+    tags: str
     excerpt: str
-    titlepath: List[str]
-    keywords: List[str]
+    titlepath: list[str]
+    keywords: list[str]
 
 
-DocID = Tuple[str, str]  # (project, docname)
+DocID = tuple[str, str]  # (project, docname)
 IndexID = str  # UUID
-Index = Tuple[str, str, List[str], List[str]]  # (tags, excerpt, titlepath, keywords)
+Index = tuple[str, str, list[str], list[str]]  # (tags, excerpt, titlepath, keywords)
 
 
-class Cache(PDict):
-    """A DocID -> List[Item] Cache."""
+class Cache(PDict[DocID, list[Item]]):
+    """A DocID -> list[Item] Cache."""
 
-    indexes: Dict[IndexID, Index]
-    index_id_to_doc_id: Dict[IndexID, Tuple[DocID, int]]
-    doc_id_to_index_ids: Dict[DocID, List[IndexID]]
-    num_snippets_by_project: Dict[str, int]
-    num_snippets_by_docid: Dict[DocID, int]
+    indexes: dict[IndexID, Index]
+    index_id_to_doc_id: dict[IndexID, tuple[DocID, int]]
+    doc_id_to_index_ids: dict[DocID, list[IndexID]]
+    num_snippets_by_project: dict[str, int]
+    num_snippets_by_docid: dict[DocID, int]
 
     def __init__(self, dirname: str) -> None:
         self.indexes = {}
@@ -46,7 +46,7 @@ def __init__(self, dirname: str) -> None:
         self.num_snippets_by_docid = {}
         super().__init__(dirname)
 
-    def post_dump(self, key: DocID, items: List[Item]) -> None:
+    def post_dump(self, key: DocID, value: list[Item]) -> None:
         """Overwrite PDict.post_dump."""
 
         # Remove old indexes and index IDs if exists
@@ -55,7 +55,7 @@ def post_dump(self, key: DocID, items: List[Item]) -> None:
             del self.indexes[old_index_id]
 
         # Add new index to every where
-        for i, item in enumerate(items):
+        for i, item in enumerate(value):
             index_id = self.gen_index_id()
             self.indexes[index_id] = (
                 item.tags,
@@ -69,12 +69,12 @@ def post_dump(self, key: DocID, items: List[Item]) -> None:
         # Update statistic
         if key[0] not in self.num_snippets_by_project:
             self.num_snippets_by_project[key[0]] = 0
-        self.num_snippets_by_project[key[0]] += len(items)
+        self.num_snippets_by_project[key[0]] += len(value)
         if key not in self.num_snippets_by_docid:
             self.num_snippets_by_docid[key] = 0
-        self.num_snippets_by_docid[key] += len(items)
+        self.num_snippets_by_docid[key] += len(value)
 
-    def post_purge(self, key: DocID, items: List[Item]) -> None:
+    def post_purge(self, key: DocID, value: list[Item]) -> None:
         """Overwrite PDict.post_purge."""
 
         # Purge indexes
@@ -83,17 +83,17 @@ def post_purge(self, key: DocID, items: List[Item]) -> None:
             del self.indexes[index_id]
 
         # Update statistic
-        self.num_snippets_by_project[key[0]] -= len(items)
+        self.num_snippets_by_project[key[0]] -= len(value)
         if self.num_snippets_by_project[key[0]] == 0:
             del self.num_snippets_by_project[key[0]]
-        self.num_snippets_by_docid[key] -= len(items)
+        self.num_snippets_by_docid[key] -= len(value)
         if self.num_snippets_by_docid[key] == 0:
             del self.num_snippets_by_docid[key]
 
-    def get_by_index_id(self, key: IndexID) -> Optional[Item]:
+    def get_by_index_id(self, key: IndexID) -> Item | None:
         """Like get(), but use IndexID as key."""
         doc_id, item_index = self.index_id_to_doc_id.get(key, (None, None))
-        if not doc_id:
+        if not doc_id or not item_index:
             return None
         return self[doc_id][item_index]
 
@@ -103,6 +103,6 @@ def gen_index_id(self) -> str:
 
         return uuid.uuid4().hex[:7]
 
-    def stringify(self, key: DocID, items: List[Item]) -> str:
+    def stringify(self, key: DocID, value: list[Item]) -> str:
         """Overwrite PDict.stringify."""
         return key[1]

src/sphinxnotes/snippet/cli.py

@@ -16,7 +16,7 @@
 import os
 from os import path
 import argparse
-from typing import List, Iterable, Tuple
+from typing import Iterable
 from textwrap import dedent
 from shutil import get_terminal_size
 import posixpath
@@ -51,7 +51,7 @@ def get_integration_file(fn: str) -> str:
     return path.join(prefix, 'integration', fn)
 
 
-def main(argv: List[str] = sys.argv[1:]):
+def main(argv: list[str] = sys.argv[1:]):
     """Command line entrypoint."""
 
     parser = argparse.ArgumentParser(
@@ -237,7 +237,7 @@ def _on_command_stat(args: argparse.Namespace):
 
 def _filter_list_items(
     cache: Cache, tags: str, docname_glob: str
-) -> Iterable[Tuple[IndexID, Index]]:
+) -> Iterable[tuple[IndexID, Index]]:
     # NOTE: Importing is slow, do it on demand.
     from sphinx.util.matching import patmatch
 

src/sphinxnotes/snippet/ext.py

@@ -9,7 +9,7 @@
 """
 
 from __future__ import annotations
-from typing import List, Set, TYPE_CHECKING, Dict
+from typing import TYPE_CHECKING
 import re
 from os import path
 import time
@@ -56,7 +56,7 @@ def extract_excerpt(s: Snippet) -> str:
     return ''
 
 
-def extract_keywords(s: Snippet) -> List[str]:
+def extract_keywords(s: Snippet) -> list[str]:
     keywords = [s.docname]
     # TODO: Deal with more snippet
     if isinstance(s, WithTitle) and s.title is not None:
@@ -65,8 +65,8 @@ def extract_keywords(s: Snippet) -> List[str]:
 
 
 def is_document_matched(
-    pats: Dict[str, List[str]], docname: str
-) -> Dict[str, List[str]]:
+    pats: dict[str, list[str]], docname: str
+) -> dict[str, list[str]]:
     """Whether the docname matched by given patterns pats"""
     new_pats = {}
     for tag, ps in pats.items():
@@ -76,7 +76,7 @@ def is_document_matched(
     return new_pats
 
 
-def is_snippet_matched(pats: Dict[str, List[str]], s: [Snippet], docname: str) -> bool:
+def is_snippet_matched(pats: dict[str, list[str]], s: [Snippet], docname: str) -> bool:
     """Whether the snippet's tags and docname matched by given patterns pats"""
     if '*' in pats:  # Wildcard
         for pat in pats['*']:
@@ -108,10 +108,10 @@ def on_config_inited(app: Sphinx, appcfg: SphinxConfig) -> None:
 def on_env_get_outdated(
     app: Sphinx,
     env: BuildEnvironment,
-    added: Set[str],
-    changed: Set[str],
-    removed: Set[str],
-) -> List[str]:
+    added: set[str],
+    changed: set[str],
+    removed: set[str],
+) -> list[str]:
     # Remove purged indexes and snippetes from db
     for docname in removed:
         del cache[(app.config.project, docname)]
@@ -150,6 +150,7 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N
         )
 
     cache_key = (app.config.project, docname)
+    assert cache is not None
     if len(doc) != 0:
         cache[cache_key] = doc
     elif cache_key in cache:

src/sphinxnotes/snippet/keyword.py

@@ -9,7 +9,6 @@
 """
 
 from __future__ import annotations
-from typing import List, Optional
 import string
 from collections import Counter
 
@@ -47,8 +46,8 @@ def __init__(self):
         )
 
     def extract(
-        self, text: str, top_n: Optional[int] = None, strip_stopwords: bool = True
-    ) -> List[str]:
+        self, text: str, top_n: int | None = None, strip_stopwords: bool = True
+    ) -> list[str]:
         """Return keywords of given text."""
         # TODO: zh -> en
         # Normalize
@@ -87,7 +86,7 @@ def normalize(self, text: str) -> str:
         text = text.replace('\n', ' ')
         return text
 
-    def tokenize(self, text: str) -> List[str]:
+    def tokenize(self, text: str) -> list[str]:
         # Get top most 5 langs
         langs = self._detect_langs(text)[:5]
         tokens = [text]
@@ -104,16 +103,16 @@ def tokenize(self, text: str) -> List[str]:
             new_tokens = []
         return tokens
 
-    def trans_to_pinyin(self, word: str) -> Optional[str]:
+    def trans_to_pinyin(self, word: str) -> str | None:
         return ' '.join(self._pinyin(word, errors='ignore'))
 
-    def strip_stopwords(self, words: List[str]) -> List[str]:
+    def strip_stopwords(self, words: list[str]) -> list[str]:
         stw = self._stopwords(['en', 'zh'])
         new_words = []
         for word in words:
             if word not in stw:
                 new_words.append(word)
         return new_words
 
-    def strip_invalid_token(self, tokens: List[str]) -> List[str]:
+    def strip_invalid_token(self, tokens: list[str]) -> list[str]:
         return [token for token in tokens if token != '']

src/sphinxnotes/snippet/picker.py

@@ -58,7 +58,7 @@ def pick(
 
 
 class SectionPicker(nodes.SparseNodeVisitor):
-    """Node visitor for picking code snippet from document."""
+    """Node visitor for picking snippets from document."""
 
     #: Constant list of unsupported languages (:class:`pygments.lexers.Lexer`)
     UNSUPPORTED_LANGUAGES: list[str] = ['default']

src/sphinxnotes/snippet/snippets.py

@@ -9,7 +9,7 @@
 """
 
 from __future__ import annotations
-from typing import List, Tuple, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING
 import itertools
 from os import path
 
@@ -36,16 +36,16 @@ class Snippet(object):
 
     #: Line number range of snippet, in the source file which is left closed
     #: and right opened.
-    lineno: Tuple[int, int]
+    lineno: tuple[int, int]
 
     #: The original reStructuredText of snippet
-    rst: List[str]
+    rst: list[str]
 
     #: The possible identifier key of snippet, which is picked from nodes'
     #: (or nodes' parent's) `ids attr`_.
     #:
     #: .. _ids attr: https://docutils.sourceforge.io/docs/ref/doctree.html#ids
-    refid: Optional[str]
+    refid: str | None
 
     def __init__(self, *nodes: nodes.Node) -> None:
         assert len(nodes) != 0
@@ -94,11 +94,11 @@ def __init__(self, node: nodes.Node) -> None:
         self.text = node.astext()
 
 
-class CodeBlock(Text):
+class Code(Text):
     #: Language of code block
     language: str
     #: Caption of code block
-    caption: Optional[str]
+    caption: str | None
 
     def __init__(self, node: nodes.literal_block) -> None:
         assert isinstance(node, nodes.literal_block)
@@ -107,23 +107,14 @@ def __init__(self, node: nodes.literal_block) -> None:
         self.caption = node.get('caption')
 
 
-class WithCodeBlock(object):
-    code_blocks: List[CodeBlock]
-
-    def __init__(self, nodes: nodes.Nodes) -> None:
-        self.code_blocks = []
-        for n in nodes.traverse(nodes.literal_block):
-            self.code_blocks.append(self.CodeBlock(n))
-
-
 class Title(Text):
     def __init__(self, node: nodes.title) -> None:
         assert isinstance(node, nodes.title)
         super().__init__(node)
 
 
 class WithTitle(object):
-    title: Optional[Title]
+    title: Title | None
 
     def __init__(self, node: nodes.Node) -> None:
         title_node = node.next_node(nodes.title)
@@ -178,7 +169,7 @@ def _line_of_start(node: nodes.Node) -> int:
     return node.line
 
 
-def _line_of_end(node: nodes.Node) -> Optional[int]:
+def _line_of_end(node: nodes.Node) -> int | None:
     next_node = node.next_node(descend=False, siblings=True, ascend=True)
     while next_node:
         if next_node.line:

src/sphinxnotes/snippet/table.py

@@ -7,7 +7,7 @@
 """
 
 from __future__ import annotations
-from typing import Iterable, Tuple
+from typing import Iterable
 
 from .cache import Index, IndexID
 from .utils import ellipsis
@@ -17,7 +17,7 @@
 COLUMN_DELIMITER = '  '
 
 
-def tablify(indexes: Iterable[Tuple[IndexID, Index]], width: int) -> Iterable[str]:
+def tablify(indexes: Iterable[tuple[IndexID, Index]], width: int) -> Iterable[str]:
     """Create a table from sequence of indices"""
 
     # Calcuate width

src/sphinxnotes/snippet/utils/ellipsis.py

@@ -9,12 +9,11 @@
 """
 
 from __future__ import annotations
-from typing import List
 from wcwidth import wcswidth
 
 
 def ellipsis(
-    text: str, width: int, ellipsis_sym: str = '..', blank_sym: str = None
+    text: str, width: int, ellipsis_sym: str = '..', blank_sym: str | None = None
 ) -> str:
     text_width = wcswidth(text)
     if text_width <= width:
@@ -34,7 +33,7 @@ def ellipsis(
 
 
 def join(
-    lst: List[str],
+    lst: list[str],
     total_width: int,
     title_width: int,
     separate_sym: str = '/',