search

h2non / pook

HTTP traffic mocking and testing made easy in Python
http://pook.rtfd.io
MIT License
342 stars 38 forks source link

Type definitions #138

Open silverwind opened 2 months ago

silverwind commented 2 months ago

Could/Does this module provide type definitions?. It looks like type checkers like pyright can not find any types:

image
sarayourfriend commented 2 months ago

Pook does not export types, but I'd welcome PRs to that end :heart:

sarayourfriend commented 1 month ago

@silverwind in case you are interested, I've added the baseline stuff for type annotations/checking pook itself in #143. My plan to get pook exporting types is to have the library itself pass type checks, as I'm not interested in maintaining separate stub files if it can possibly be avoided. To get there, I'd like to focus on small PRs that add annotations and checking to a contained section of the code each time (through judicious use of # type: ignore to draw boundaries on imports). I'll spend a little time later coming up with a list of the individual sections for each PR, but if you have any input or feel up to getting a few of those done, let me know. I'll share the list in this issue once I've written it out.

silverwind commented 1 month ago

I don't think I can be of much help as I'm just starting to get into typed python. I do have quite a bit of typescript experience though, and in many senses, these type systems look similar, though python's system seems less fledged out, with things like the type statement only being recently added in 3.12.

sarayourfriend commented 1 month ago

There are some similarities, mostly in that they are both additions over top an otherwise highly dynamic language. TS is structurally typed though, and Python is nominally typed, with structural typing only possible when explicitly using Protocol added in 3.8. For the simplest cases you don't need to worry about these differences. Pook has some areas that should be simpler to contribute types too, I'll let you know if I identify any that might better suited for you, if you're interested.

The biggest thing I've found missing in Python's type system coming from a broader TypeScript background are conditional and mapped types, and that mypy will not auto-cast strings to Literal sometimes.

For what it's worth, the type statement in Python has a very narrow use case, and typically isn't necessary for most code, we get by fine without them, and wouldn't be able to use them in pook anyway, as pook supports all maintained Python versions (so >=3.9 since this week 3.8 went EOL).

The main difficulty with pook will be working around somewhat tedious optional attributes/properties, where things can technically be None, but in practice never will be outside of specific, almost never relevant windows. Also some places where the types seem to indicate the code might be totally wrong (and where I'm not confident the code is actually right anyway!). It will be interesting to see if adding types to pook can be accomplished without introducing too many runtime changes.