As I've started to work with modern Sopel in the context of plugins that want to do their own type-checking (e.g. sopel-iplookup), I've also built up an opinion that we should really give ourselves a concrete target for officially declaring sopel as supporting type-checks, i.e. adding the py.typed file that it needs to silence mypy's missing-imports warning.
I propose that the target be "every piece of Sopel's public API has complete type hints". We can go above and beyond that with type hints for internal functions or plugin callables, but anything that we expect a plugin developer to import or touch (including the types passed through the bot and trigger args and all of the things they contain) should be fully hinted.
To help us find shortcomings, the following mypy options are available:
--disallow-incomplete-defs: raises an error for function definitions where some, but not all, parameters are typed
--disallow-untyped-decorators: errors when a type-hinted function is decorated by an untyped decorator
(not sure how useful this one is for us, but it's around)
--disallow-untyped-defs: superset of --disallow-incomplete-defs; anydef without type hints is an error
This would be our final endgame, once EVERYTHING is typed, even the internals and built-in plugins.
For 8.0.1 we should definitely do a pass with --disallow-incomplete-defs and fix those as a first step. The goal—or at least, my goal—is to do the rest of the typing work along the road to 9.0 and ship py.typed with --disallow-untyped-defs enforcement by then.
(In case you're wondering who to blame for this "make more work" issue, in my own defense, it was @SnoopJ who said "probably a good thing to start tracking for 9.0.0 milestone tho" in our IRC channel when I mentioned --disallow-incomplete-defs. 😜)
As I've started to work with modern Sopel in the context of plugins that want to do their own type-checking (e.g. sopel-iplookup), I've also built up an opinion that we should really give ourselves a concrete target for officially declaring
sopelas supporting type-checks, i.e. adding thepy.typedfile that it needs to silence mypy'smissing-importswarning.I propose that the target be "every piece of Sopel's public API has complete type hints". We can go above and beyond that with type hints for internal functions or plugin callables, but anything that we expect a plugin developer to import or touch (including the types passed through the
botandtriggerargs and all of the things they contain) should be fully hinted.To help us find shortcomings, the following
mypyoptions are available:--disallow-incomplete-defs: raises an error for function definitions where some, but not all, parameters are typed--disallow-untyped-decorators: errors when a type-hinted function is decorated by an untyped decorator (not sure how useful this one is for us, but it's around)--disallow-untyped-defs: superset of--disallow-incomplete-defs; anydefwithout type hints is an error This would be our final endgame, once EVERYTHING is typed, even the internals and built-in plugins.For 8.0.1 we should definitely do a pass with
--disallow-incomplete-defsand fix those as a first step. The goal—or at least, my goal—is to do the rest of the typing work along the road to 9.0 and shippy.typedwith--disallow-untyped-defsenforcement by then.(In case you're wondering who to blame for this "make more work" issue, in my own defense, it was @SnoopJ who said "probably a good thing to start tracking for 9.0.0 milestone tho" in our IRC channel when I mentioned
--disallow-incomplete-defs. 😜)