search

pyca / pynacl

Python binding to the Networking and Cryptography (NaCl) library
https://pynacl.readthedocs.io/
Apache License 2.0
1.07k stars 230 forks source link

Type annotations #660

Closed Dreamsorcerer closed 2 years ago

Dreamsorcerer commented 3 years ago

Would be nice to have type annotations to support static typing in projects using mypy.

reaperhulk commented 3 years ago

We'd love to see them!

Dreamsorcerer commented 3 years ago

I'm working on a dozen other repos at the moment. But, if anyone wants to make a start on this, I can review PRs and help answer any questions if you get stuck. Just tag me on a PR.

reaperhulk commented 2 years ago

As mentioned in #724 I'd definitely like to see us cover the tests. We'll need check untyped defs since I don't think there's much value in annotating the types on the pytest declarations themselves, but my experience with pyca/cryptography was that we found some bugs in our type decls when we added the test suite into the mix 😄

DMRobertson commented 2 years ago

Is there anything else we'd like to do here? I have some time spare over the Christmas break if anything springs to mind.

reaperhulk commented 2 years ago

I think we're set until we see some feedback after the 1.5.0 release. If there's anything else you want to see in 1.5.0 I'd suggest a PR in the next day or two though 😄

Dreamsorcerer commented 2 years ago

The only thing I see missing, which is perhaps not a small task, would be to factor out the examples from the documentation into separate .py files (and then include the files into the documentation dynamically). This would allow testing all those examples, which serves 2 purposes.

  1. Ensure the documentation is always up-to-date and likely to be working correctly.
  2. Find any errors in typing that are present to the end-user, but won't show when checking pynacl (e.g. when the output of one function is expected to be used as the input to another function, but the types are incompatible (like Mapping output and Dict input), the type error won't appear in pynacl as the functions are only used together by the end user).
reaperhulk commented 2 years ago

doctest can do this (with some limitations) if we're not already using it on this repository (we do on cryptography). I agree that having the examples run is highly desirable to prevent bit rot