refactor(codegen/docs): add type hints

[wpbonelli]

Sketching #2298, and possibly moving the templating in flopy/mf6/utils/createpackages.py to Jinja

Aiming to minimally/faithfully reproduce component source files, adding type hints in __init__ and the docstrings.

Type mapping

Not sure the mapping is right, but so far

list -> Iterable
keystring -> Union 
record -> Tuple (possibly variadic)
file record -> Tuple[Union[str, PathLike]]
array -> Iterable if of str, otherwise NDArray (ArrayLike in fn signatures)
double precision -> float
integer -> int
keyword -> bool (unless in a record, in which case Literal["..."])
string -> str (unless valid options specified, in which case Literal of options)

Array variables

I think while variables can be specified as NDArray with a type parameter, method/function implementations are lenient and NDArray can be switched to ArrayLike for type hinting. Conversely we might be able to use ndarray[Shape, T] where Shape = Tuple[str, ...] in a specification to defer shape checking until dimensions can be looked up from other parameters — this possible because numpy leaves the shape parameter wide open (it need not be a tuple of int)

Tagged records in keystrings

For records whose last item repeats, I considered doing:

• Tuple[Any, ...]
• Tuple[Union[Literal, T], ...]
• Tuple[Literal, Tuple[T, ...]]

Ended up going with the latter.

Checking correctness

The correctness of this could be checked with tests or maybe mypy? Not sure about checking completeness — i.e. do the type hints truly cover all accepted types. For instance I think single-value records can be provided directly, without a wrapping tuple.

Todo

• simulation
• models
• exchanges
• subpackages
• named tuples
  • I could see a case for or against these, as they make the type hint less explicit, but more concise
• allow unwrapped 1-item tuples
• accept NDArray as ArrayLike
• description rendering
  • common variable substitutions
  • math symbols
  • citations
• structural parity (AST checking)
• functional parity, passing test suite
• check correctness of type hints — mypy?

Motivation

This is a first step toward refactoring mfstructure.py and determining what is really necessary to represent an input data model. In the meantime this grows the codebase instead of shrinking it, but I am thinking of it a bit like scaffolding before renovation. Some complexity in the implementation is ascribable to the current framework and could simplify eventually.