Add type hints in python codebase

[hoefling]

trafficstars

🚀 Feature Proposal

Type hints in Python are specified by PEP 484 and are of a great help when developing, thus proposing to add them to Python codebase. Would this be an option if I volunteer to (gradually) add them, assuming the types are validated in the CI by a checker tool like mypy so the types are validated on each pull request?

I have noticed rudimentary type hints already exist here and there, for example

https://github.com/SeleniumHQ/selenium/blob/e9c738de8a587dc6bc86b55949c57b8574ec68bb/py/selenium/webdriver/remote/webdriver.py#L263

indicates that WebDriver().name is a string. This offers better code completions in IDEs.

I have searched for similar issues, but it seems like this wasn't discussed yet (at least not on Github). As far as I can see, the only issue mentioning type hints is #1917; however, type stubs were removed since then.

Another alternative would be maintaining a third-party stub package (as specified in PEP 561). However, I don't want to start a third-party package if you are willing to keep the type hints along with the code (which is a much better option), or planning to add them already.

Motivation

Better code completion in IDEs is surely something the end users will appreciate. Another advantage is that type hints often intercept bugs, thus making the code more robust.

[AutomatedTester]

I am all for this! Feel free to start adding PRs and then tagging me for review.

[Akuli]

When are you going to add a py.typed file to tell type checkers to rely on what's in selenium itself, instead of using typeshed's selenium 3.x stubs?

For context, I am a maintainer of typeshed, and I'm wondering if we should upgrade our selenium 3.x stubs to selenium 4.x, or just wait until someone adds a py.typed file to selenium 4.x.

[AutomatedTester]

I haven't got round to adding a py.typed. If someone fancies putting a PR up I will review and get it landed as quickly as I can.

[GergelyKalmar]

I don't think this worked, the py.typed file is still missing from the latest release (4.1.1). Could we get a patch release which fixes that? It would be awesome.

[Akuli]

Can someone who does the releases tell me what commit the latest pypi release 4.1.1 is based on? There's no tag in the repo (which makes sense, because the x of 4.1.x seems to be Python-specific). Looking at https://github.com/SeleniumHQ/selenium/commits/trunk/py I can see that it does include #10273, but the other two PRs after that don't modify any files that are included in the releases (if my py.typed PR doesn't work, that is).

[AutomatedTester]

The issue is I forgot to update bazel to pick up the file when building the wheel. I will do that

[AutomatedTester]

landed in e8e9389f6b793a51e9cf5989eab7b55982ccbf6d

[AutomatedTester]

4.1.2 has been pushed to pypi with this change. I checked the wheel had the file. Let me know if it doesn't work as expected.

[Akuli]

It works! Thanks!

[bersbersbers]

Is there a recommended course of action to follow while this issue is open? For example, WebDriverWait is not typed yet, and I am getting many errors such as

Call to untyped function "WebDriverWait" in typed context [no-untyped-call]

with mypy --disallow-untyped-calls. This does not happen with types-selenium installed, but then I am hitting https://github.com/python/typeshed/issues/7379. Any recommendations?

[Akuli]

I recommend disabling --disallow-untyped-calls. It's not helpful and it only generates noisy warnings. It's meant to be used in projects that want every function call type checked, which isn't yet possible if you use selenium.

Don't use types-selenium if you use selenium 4. It is meant to be used only with selenium 3.

You can also make pull requests that add the missing types :)

[Akuli]

And I might as well mention how to disable the warning in mypy.ini:

[mypy]
strict = True
show_error_codes = True
disable_error_code = no-untyped-call

[diemol]

@symonk @AutomatedTester do we need to keep this open, or can we open more specific issues so people can report punctual things they find along the way?

[AutomatedTester]

Let's get specific bugs. @symonk has done a great job of getting this a lot further forward. Other issues should be raised as specific items

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.