How to gradually type a library

[aucampia]

I'm trying to add type hints to RDFLib, but it's a big library and I don't think everything from it will be typed soon. My current approach has been to add rdflib/py.typed and to add type hints where I can.

If we do this however, users who were using RDFLib with import rdflib # type: ignore[import] now have a problem which is that they have to add # type: ignore[no-untyped-call] every time they use some untyped function/class from RDFLib if they run mypy with disallow_untyped_calls=True.

What is the right approach here?

• Should the users of RDFLib just not use disallow_untyped_calls?
  The downside here is maybe that they want to only enforce this for some libraries, but setting this per library as follows does not work:

  ; in mypy.ini
  [mypy-rdflib]
  ; THIS DOES NOT HELP, because this only affects the consumer side, not the provider side.
  disallow_untyped_calls = False

  If there was some other way to say that don't warn about untyped calls for rdflib only, it would be great, but I find no such option.
• Should we not add py.typed to RDFLib until it is fully typed?
  The downside here is that users of RDFLib will get no benefit from type hints we add until we are done, which may be very long.
• Something else?
  Are there other options I'm missing here?

The specific issue I'm trying to solve is RDFLib/rdflib#1447 and further context for us adding py.typed can be seen in RDFLib/rdflib#1407

[hmc-cs-mdrissi]

https://www.python.org/dev/peps/pep-0561/#partial-stub-packages I think is best option. But I think that also requires you use .pyi stubs. If you use .pyi stubs you can mark a package as partially typed and any files that have .pyi will use that, otherwise they will be treated as untyped.

Alternative option I consider 80/20 rule of most tasks. What are most commonly used public API's? Type hint those and only those in line. Accept the rest lacking types and fill them in over time. Most libraries the commonly used functions is much smaller subset than the full api.

disallow_untyped_calls is a pretty strict setting that I don't really expect to work with much of the python ecosystem today although this depends on what libraries you need. Some parts of ecosystem have better coverage then others.

[hauntsaninja]

Yeah, agreed. Given that you're adding inline types (i.e. not using pyi files), my recommendation is to not add py.typed marker until you've added types to your most commonly used APIs. I'd hold off till, say, the median user can use your library without having to use untyped bits.

Specific to mypy, once you've added py.typed, users with strict settings who are annoyed by the amount of untyped code should be able to use something like the following to ignore your types and replace everything in rdflib with Any.

[mypy]
[mypy-rdflib.*]
follow_imports = skip

Seems like disallow_untyped_calls being per-module configurable could be a useful feature in mypy though.