More type annotations (#697)

* Add comprehensive type annotations

- mypy.ini: expanded configuration with module-specific settings
- hookspecs.py: type annotations for hook functions
- plugins.py: typed get_plugins() return value
- recipes.py: full type annotations for parsedate, parsedatetime, jsonsplit
- utils.py: extensive type annotations including Row type alias,
  TypeTracker, ValueTracker, and all utility functions
- db.py: type annotations for Database methods (__exit__,
  ensure_autocommit_off, tracer, register_function, etc.) and
  Queryable class methods
- tests/test_docs.py: updated to match new signature display format

* Fix type errors caught by ty check

- Add type: ignore comments for external library type stub limitations
  (csv.reader, click.progressbar, IOBase.name, Callable.__name__)
- Change Iterable to Sequence for SQL where_args parameters
- Use db.table() instead of db[name] for proper Table return type
- Fix rebuild_fts return type from None to Table
- Update test_tracer to expect fewer queries (optimization side effect)

* Fix mypy type errors

- Add type: ignore comments for runtime-valid patterns mypy can't verify
- Fix new_column_types annotation to Dict[str, Set[type]]
- Add type: ignore for Default sentinel values passed to create_table

* mypy skip tests directory

* Fix CI: exclude typing imports from recipe docs, skip mypy on tests

- Add Callable and Optional to exclusion list in _generate_convert_help()
- Regenerate docs/cli-reference.rst with cog
- Add [mypy-tests.*] ignore_errors = True to skip test type errors

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: simonw

docs/cli-reference.rst

@@ -615,11 +615,13 @@ See :ref:`cli_convert`.
 
       The following common operations are available as recipe functions:
 
-      r.jsonsplit(value, delimiter=',', type=<class 'str'>)
+      r.jsonsplit(value: 'str', delimiter: 'str' = ',', type: 'Callable[[str],
+      object]' = <class 'str'>) -> 'str'
 
       Convert a string like a,b,c into a JSON array ["a", "b", "c"]
 
-      r.parsedate(value, dayfirst=False, yearfirst=False, errors=None)
+      r.parsedate(value: 'str', dayfirst: 'bool' = False, yearfirst: 'bool' = False,
+      errors: 'Optional[object]' = None) -> 'Optional[str]'
 
       Parse a date and convert it to ISO date format: yyyy-mm-dd
   
@@ -628,7 +630,8 @@ See :ref:`cli_convert`.
       - errors=r.IGNORE to ignore values that cannot be parsed
       - errors=r.SET_NULL to set values that cannot be parsed to null
 
-      r.parsedatetime(value, dayfirst=False, yearfirst=False, errors=None)
+      r.parsedatetime(value: 'str', dayfirst: 'bool' = False, yearfirst: 'bool' =
+      False, errors: 'Optional[object]' = None) -> 'Optional[str]'
 
       Parse a datetime and convert it to ISO datetime format: yyyy-mm-ddTHH:MM:SS
   

mypy.ini

@@ -1,4 +1,35 @@
 [mypy]
+python_version = 3.10
+warn_return_any = False
+warn_unused_configs = True
+warn_redundant_casts = False
+warn_unused_ignores = False
+check_untyped_defs = True
+disallow_untyped_defs = False
+disallow_incomplete_defs = False
+no_implicit_optional = True
+strict_equality = True
 
-[mypy-pysqlite3,sqlean,sqlite_dump]
-ignore_missing_imports = True
+[mypy-sqlite_utils.cli]
+ignore_errors = True
+
+[mypy-pysqlite3.*]
+ignore_missing_imports = True
+
+[mypy-sqlean.*]
+ignore_missing_imports = True
+
+[mypy-sqlite_dump.*]
+ignore_missing_imports = True
+
+[mypy-sqlite_fts4.*]
+ignore_missing_imports = True
+
+[mypy-pandas.*]
+ignore_missing_imports = True
+
+[mypy-numpy.*]
+ignore_missing_imports = True
+
+[mypy-tests.*]
+ignore_errors = True

sqlite_utils/cli.py

@@ -1051,7 +1051,7 @@ def insert_upsert_implementation(
                 csv_reader_args["delimiter"] = delimiter
             if quotechar:
                 csv_reader_args["quotechar"] = quotechar
-            reader = csv_std.reader(decoded, **csv_reader_args)
+            reader = csv_std.reader(decoded, **csv_reader_args)  # type: ignore
             first_row = next(reader)
             if no_headers:
                 headers = ["untitled_{}".format(i + 1) for i in range(len(first_row))]
@@ -2988,7 +2988,7 @@ def _generate_convert_help():
         n
         for n in dir(recipes)
         if not n.startswith("_")
-        and n not in ("json", "parser")
+        and n not in ("json", "parser", "Callable", "Optional")
         and callable(getattr(recipes, n))
     ]
     for name in recipe_names: