Type annotate the public API

[pradyunsg]

Closes #90

[layday]

Should have py.typed marker file inside the pyproject_hooks package.

[takluyver]

Thanks @pradyunsg - it looks like @layday has already done a detailed review of the annotations, so I'll skip doing that.

My inclination is to be fairly conservative with Python version support, since this is meant to be a boring piece of low-level infrastructure that doesn't change often. I see pip hasn't dropped 3.7 support yet, so I'd suggest we don't here either. But I'm not going to argue about this if you really want to.

[layday]

I've type-checked this branch against the main branch of build; there was only one error, which looks like something that should be fixed on build's side:

src/build/__init__.py:180: error: Argument "runner" to "BuildBackendHookCaller" has incompatible type "Callable[[Sequence[str], Optional[str], Optional[Mapping[str, str]]], None]"; expected "Optional[SubprocessRunner]"  [arg-type]

(This is presumably because the protocol has default arguments.)

[layday]

pypa/build#601

[pradyunsg]

The latest commit makes it possible to do...

if TYPE_CHECKING:
    from pyproject_hooks import SubprocessRunner

And then annotate subprocess runners using that type.

[pradyunsg]

Instead of leaving that as a comment, I've gone ahead and documented that.

[henryiii]

Wouldn’t it make sense to allow SubprocessRunner at runtime on Python 3.8+? So this interface oddity will go away once 3.7 is dropped? Another idea (if it’s not runtime checkable) is to just make it a dummy object at runtime, so downstream code isn’t forced into extra TYPE_CHECKING checks.

[layday]

That's what we do with the IsolatedEnv in build, it's a simple ABC at runtime on Python 3.7.

[pradyunsg]

On the basis of "this is better than status quo", I'm gonna go ahead and merge this.

There's a couple of potential follow ups to improve this further:

• Using the newer typing syntax and more granular "semantic" types, that @gotmax23 has suggested.
• Making the protocol available on Python 3.8+ at runtime (with an object on 3.7), as @henryiii suggested.

[pradyunsg]

(I'll fix the documentation build separately)