It would be helpful to have Python type annotations as a way to catch bugs (in wfdb itself and in applications) and as a way to more rigorously document the API.

A couple of issues would need to be resolved:

1. Decide on a style for writing annotations.

You could import typing and then write def foo(x: typing.Sequence[int]) -> typing.Union[None, typing.List], but that's very noisy.

You could instead write from typing import (List, Sequence, Union) and then write def foo(x: Sequence[int]) -> Union[None, List], which is a little less ugly, but requires maintaining a list of imports at the top of the file.

It's also, honestly, a bit confusing (hard to remember which names refer to concrete classes in the standard library, and which are abstract classes that are only useful for typing. Quick, without looking it up, tell me the difference between BinaryIO and BytesIO.)

2. Find a way to actually type-check the package.

Annotations are useless if we can't check that they are correct or at least syntactically valid.

mypy will give an error if there are any binary modules in use that don't have a corresponding "stub" file. If there's a way to suppress this error, I haven't found it. That makes it very difficult to do any automated checking.

Of the modules used by wfdb, requests, pandas, matplotlib, and scipy are currently lacking these stubs. (numpy has its own.)

It's possible to use third-party stub files, with all the caveats that implies. mypy itself suggests using the third-party types-requests package for requests. For pandas and matplotlib there is the third-party data-science-types package, which is apparently abandoned. I don't know about scipy.

Fixing bugs in wfdb is one thing, but this issue seems to be largely out of our control.