Support `mypy --strict`

[mesozoic]

This branch adds type annotations to the entire library, along with a number of Airtable-specific types and TypedDicts. It is not compatible with Python 3.7 but it works on all later versions. As with some of the other big branches, it might be easier to review each commit individually.

• https://github.com/gtalarico/pyairtable/commit/821e435df80c4cf518116cb81032a7c73249ff68 introduces a number of types and TypedDicts in a new pyairtable.api.types module.

  • There are some aliases here (like RecordId and FieldName) that simply point to str. This is not strictly necessary, but without them there are so many places where we have things like List[str] or Dict[str, str], and this might make it a bit easier for developers to remember what goes where.
  • I'm open to adding more but I didn't want to go overboard on the first pass. (I'm not opposed to seeing str in type annotations as long as it's obvious what they represent.)

• https://github.com/gtalarico/pyairtable/commit/4aab9e077d3828bc5fd8c20de6ad49062f69a017 switches up how we call mypy to use strict mode and not silence any warnings.

• https://github.com/gtalarico/pyairtable/commit/5345b048cc1f56533b3bf73f039c737c037b3313 fills in most of the missing annotations on function/method signatures. It also removes the (deprecated) params.to_params_dict function and introduces Model._get_meta() as a helper for reading the Meta class.

• https://github.com/gtalarico/pyairtable/commit/8a28f3470988a0e758df0a1ca8bdc805bec6c054 does a few things:

• Turns pyairtable.orm.fields.Field into a generically-typed class, Field[T_API, T_ORM], whose subclasses need to define the API and ORM data types (which might not always match).

  • Provides the alias BasicField[T] for field classes which do not convert values between types.
  • Provides the alias AnyField for when a type annotation doesn't care what kind of field it gets.
  • Renames Field.value_if_missing to Field._missing_value() so it can be typed more flexibly.

• https://github.com/gtalarico/pyairtable/commit/b618b55409c2306e66fba26687a2d3fd86fdb5c2 uses typing.cast() on values returned by the Airtable API to conform them to the types introduced above; this assumes the API responses will conform to the data structures we expect. (See below.)

• https://github.com/gtalarico/pyairtable/commit/3d9be4731a51605ea1dd581f91ee0bdc0f76a5ca fixes some issues with forward references that caused sphinx_autodoc_typehints to crash.

• https://github.com/gtalarico/pyairtable/commit/ffa5c431223f9a0bcde22edaf61147c80eabbea6 introduces some basic types to pyairtable.metadata. I expect to deprecate this module soon, so I didn't spend too much time on it.

• https://github.com/gtalarico/pyairtable/commit/46b0950750a3dd9021cbc87e30816de5a40ada05 removes support (introduced in an earlier branch) for setting model.list_field = iterable_object, where iterable_object is a non-list (such as a set, tuple, or generator). Defining this correctly as a type annotation became problematic, and it seems reasonable to expect developers to convert those types to lists before setting field values on a model.

• https://github.com/gtalarico/pyairtable/commit/8364a4f916f33d077383851828152199c980ae58 adds a special test file, tests/test_typing.py, which makes a number of type assertions that mypy will validate on each run.

• https://github.com/gtalarico/pyairtable/commit/94a93cda63237d3220aae0a6a25a1443d17f87eb changes the approach used in b618b554 (above) to actively validate Airtable's API responses against our TypedDict definitions, instead of simply assuming they match what we expect. This introduces pydantic as a dependency, which we've already discussed using for metadata models in #258.

• 34eb19f updates the Sphinx configuration to include type annotations and default values in function signatures and parameter descriptions. It also adds a "Types" section.

• 9b5ecd0 fixes a bug that popped up when I pushed the previous commit, but which I hadn't run across before. I'm stumped why GitHub Actions didn't catch it when I pushed 94a93cda but :shrug: it was a quick fix.

This branch resolves #202.

[codecov[bot]]

Codecov Report

Merging #263 (2b6b8c0) into main (d9e5c94) will increase coverage by 1.24%. The diff coverage is 96.78%.

@@            Coverage Diff             @@
##             main     #263      +/-   ##
==========================================
+ Coverage   91.97%   93.22%   +1.24%     
==========================================
  Files          15       16       +1     
  Lines         773      826      +53     
==========================================
+ Hits          711      770      +59     
+ Misses         62       56       -6     

Impacted Files	Coverage Δ
pyairtable/metadata.py	29.41% <44.44%> (-6.31%)	:arrow_down:
pyairtable/api/abstract.py	98.69% <93.93%> (-1.31%)	:arrow_down:
pyairtable/orm/fields.py	94.11% <96.82%> (+1.99%)	:arrow_up:
pyairtable/__init__.py	100.00% <100.00%> (ø)
pyairtable/api/__init__.py	100.00% <100.00%> (ø)
pyairtable/api/api.py	77.50% <100.00%> (ø)
pyairtable/api/base.py	77.50% <100.00%> (+0.57%)	:arrow_up:
pyairtable/api/params.py	100.00% <100.00%> (+3.94%)	:arrow_up:
pyairtable/api/retrying.py	100.00% <100.00%> (ø)
pyairtable/api/table.py	100.00% <100.00%> (ø)
... and 6 more

[mesozoic]

Going to merge this now. Please feel free to open further issues for discussion if anything looks awry.