Add missing type hints

[Pennycook]

Feature/behavior summary

Several legacy functions are missing type hints.

Although we've made good progress in adding missing type hints as we've developed new features, we still have a backlog of functionality that we haven't touched in some time.

Request attributes

• Would this be a refactor of existing code?
• Does this proposal require new package dependencies?
• Would this change break backwards compatibility?

Related issues

No response

Solution description

We need to add type hints to the functions in the following files:

• codebasin/init.py
• codebasin/config.py
• codebasin/file_parser.py
• codebasin/file_source.py
• codebasin/finder.py
• codebasin/language.py
• codebasin/platform.py
• codebasin/preprocessor.py
• codebasin/report.py
• codebasin/tree.py
• Type hints to util.py #191

...and/or refactor the code to replace the functionality in these files.

Additional notes

Applying the following patch enables flake8 to identify all the functions with missing type hints:

--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -51,6 +51,7 @@ repos:
           [
             flake8-debugger,
             flake8-use-fstring,
+            flake8-annotations,
           ]
         args:
           [

At the time of writing, there are 573 instances of missing type hints. I'd like to enable this as part of the CI, but it probably makes sense to wait until we've addressed some of these.

[laserkelvin]

As a form of devtooling, ty is does static type checking amazingly well; running it in the codebasein directory using uv:

uvx ty check .
...
error: lint:invalid-parameter-default: Default value of type `None` is not assignable to annotated parameter type `int`
   --> report.py:743:40
    |
741 |         return lines
742 |
743 |     def write_to(self, stream: TextIO, levels: int = None):
    |                                        ^^^^^^^^^^^^^^^^^^
744 |         """
745 |         Write the FileTree to the specified stream.
    |
info: `lint:invalid-parameter-default` is enabled by default

error: lint:invalid-parameter-default: Default value of type `None` is not assignable to annotated parameter type `int`
   --> report.py:769:5
    |
767 |     stream: TextIO = sys.stdout,
768 |     prune: bool = False,
769 |     levels: int = None,
    |     ^^^^^^^^^^^^^^^^^^
770 | ):
771 |     """
    |
info: `lint:invalid-parameter-default` is enabled by default

...detects ~77 instances of "errors". This should be pretty useful to check against when adding the type hinting, although some of them could be ignored. For some reason, this error also came up:

error: lint:unresolved-import: Cannot resolve imported module `tomllib`
  --> util.py:14:8
   |
12 | import os
13 | import pkgutil
14 | import tomllib
   |        ^^^^^^^
15 | import typing
16 | from collections.abc import Iterable
   |
info: `lint:unresolved-import` is enabled by default

Even though tomllib should be part of the stdlib?

[Pennycook]

This should be pretty useful to check against when adding the type hinting, although some of them could be ignored. For some reason, this error also came up:

error: lint:unresolved-import: Cannot resolve imported module tomllib
--> util.py:14:8
|
12 | import os
13 | import pkgutil
14 | import tomllib
| ^^^^^^^
15 | import typing
16 | from collections.abc import Iterable
|
info: lint:unresolved-import is enabled by default
Even though tomllib should be part of the stdlib?

This could be related to me not having updated the pyproject.toml yet. It currently says we only need Python 3.9, but TOML support was added in Python 3.10, and we actually now require 3.12. Since you're using uv to install, it might be picking up the wrong Python version.

[laserkelvin]

No I've got Python 3.12 - ty is very alpha so there are a lot of false positives.

[Pennycook]

info: lint:invalid-parameter-default is enabled by default
...detects ~77 instances of "errors". This should be pretty useful to check against when adding the type hinting, although some of them could be ignored. For some reason, this error also came up:

mypy found a lot of similar errors, which I have all fixed in #196. I opted to use mypy instead because it's blessed by the official Python folks; I'd be open to exploring alternatives, but using mypy to try and fix things up initially seems like a good idea.