[py] PEP 484 type hints for common.exceptions and webdriver.support.color

[hoefling]

Description

This is the initial PR that adds type hints to Python codebase. Typed modules:

• selenium.common.exceptions,
• webdriver.support.color.
  I have selected those two for the initial typing since they do not depend on any other modules and can be typed in isolation.

Motivation and Context

The goal of this PR is to configure and add initial integration for the mypy tool (checks the type hints validity). It can be run via

$ tox -e mypy

or

$ TOXENV=mypy tox

Right now it emits 1248 errors, mainly due to missing type hints; the goal is to gradually reduce it to zero. No errors are emitted in modules typed in this PR.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have read the contributing document.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[CLAassistant]

All committers have signed the CLA.

[hoefling]

@AutomatedTester gentle ping (no rush though!). Please advise:

1. Is the PR too big for a review? I will split it if necessary and create smaller PRs in the future.
2. I would like to add a new job that runs mypy checks, but it will fail until all the codebase is typed and unfortunately GH actions syntax doesn't allow to ignore failing jobs. I can filter out untyped modules in mypy config (so no errors are reported) and loosen the filter gradually with each typed module, like suggested in mypy docs:

   # mypy config
   [mypy]
   ...
   [mypy-selenium.webdriver.*]
   ignore_errors = True
   
   [mypy-selenium.webdriver.support.event_firing_webdriver]
   ignore_errors = True
   
   # etc

   However, maybe you have a better idea for me?

[AutomatedTester]

@AutomatedTester gentle ping (no rush though!). Please advise:

1. Is the PR too big for a review? I will split it if necessary and create smaller PRs in the future.

No, this is fine. Don't go much bigger than this though.

2. I would like to add a new job that runs `mypy` checks, but it will fail until all the codebase is typed and unfortunately GH actions syntax doesn't allow to ignore failing jobs. I can filter out untyped modules in `mypy` config (so no errors are reported) and loosen the filter gradually with each typed module, like suggested in [mypy docs](https://mypy.readthedocs.io/en/stable/existing_code.html):
   ```ini
   # mypy config
   [mypy]
   ...
   [mypy-selenium.webdriver.*]
   ignore_errors = True
   
   [mypy-selenium.webdriver.support.event_firing_webdriver]
   ignore_errors = True
   
   # etc
   ```

I've not used mypy in anger so I might need your help here. Is there a way that we can do a pass over and have file that holds the current output so we can't regress and then fix the others? A little similar to how Rubocop works for Ruby. If your suggestion above does that then do it and we can then clean it up as we go. Let's try not boil the ocean.

[AutomatedTester]

These are always going to be str or `None

[AutomatedTester]

The types here are str or None.

[hoefling]

@AutomatedTester I guess except stacktrace? Looking at this right now:

selenium/py/selenium/webdriver/remote/errorhandler.py

Lines 208 to 236 in c138008

	stacktrace = None
	st_value = value.get('stackTrace') or value.get('stacktrace')
	if st_value:
	if isinstance(st_value, str):
	stacktrace = st_value.split('\n')
	else:
	stacktrace = []
	try:
	for frame in st_value:
	line = self._value_or_default(frame, 'lineNumber', '')
	file = self._value_or_default(frame, 'fileName', '<anonymous>')
	if line:
	file = "%s:%s" % (file, line)
	meth = self._value_or_default(frame, 'methodName', '<anonymous>')
	if 'className' in frame:
	meth = "%s.%s" % (frame['className'], meth)
	msg = " at %s (%s)"
	msg = msg % (meth, file)
	stacktrace.append(msg)
	except TypeError:
	pass
	if exception_class == UnexpectedAlertPresentException:
	alert_text = None
	if 'data' in value:
	alert_text = value['data'].get('text')
	elif 'alert' in value:
	alert_text = value['alert'].get('text')
	raise exception_class(message, screen, stacktrace, alert_text)
	raise exception_class(message, screen, stacktrace)

[hoefling]

I've not used mypy in anger so I might need your help here. Is there a way that we can do a pass over and have file that holds the current output so we can't regress and then fix the others? A little similar to how Rubocop works for Ruby. If your suggestion above does that then do it and we can then clean it up as we go. Let's try not boil the ocean.

I see what you mean - unfortunately, my suggestion doesn't do that, it's merely "hide modules with errors until those are fixed, and don't forget to uncover them back once fixed". However, mypy can produce JUnit and Cobertura reports. Let me play with them - I think the report file can be cached on main branch and compared against the report in the PR. Maybe we can even integrate that in a service like codecov.io and get an automatic regression reports in PRs. However, I wouldn't bloat this PR up anymore and introduce the CI job in another PR.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information