Add pyright for static type checking (#17744)

Related to #17301

Summary of the issue:
NVDA has no type checking for python.
Python is a dynamically typed language meaning typing issues can occur at runtime.
Static analysers like `mypy` or `pyright` can be used to avoid typing errors.

Description of user facing changes
None

Description of development approach
`pyright` was chosen over `mypy` for performance reasons.
Additionally, pyright has better pre-commit integration, and is built-in to VS Code, which is used by most NVDA developers.

We are far from compliant with static type checking, so most rules are currently disabled.
The intention is to fix compliance and turn on rules over time.

Various trivial typing fixes have occurred, particularly:
- removing unnecessary casts
- fixing type hints
- adding relevant type ignore comments
- removing redundant type ignore comments
- adding type stubs for `gettext` builtins and `_buildVersion` generated build vars
- remove duplicate imports
- adding `__all__` to mark export for private classes
- adding missing `match` cases

Testing strategy:
- [x] Smoke test NVDA
- [x] pyright passing
- [x] Automated testing passes

Known issues with pull request:
We are far from compliant with static type checking, so most rules are currently disabled.
The intention is to fix compliance and turn on rules over time.

Author: seanbudd

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ ci:
   # https://stackoverflow.com/questions/70778806/pre-commit-not-using-virtual-environment .
   # Can't run licenseCheck as it relies on telemetry,
   # which CI blocks.
-  skip: [scons-source, checkPot, unitTest, licenseCheck]
+  skip: [scons-source, checkPot, unitTest, licenseCheck, pyrightLocal]
   autoupdate_schedule: monthly
   autoupdate_commit_msg: "Pre-commit auto-update"
   autofix_commit_msg: "Pre-commit auto-fix"
@@ -107,6 +107,23 @@ repos:
     - id: ruff-format
       name: format with ruff
 
+- repo: https://github.com/RobertCraigie/pyright-python
+  rev: v1.1.394
+  hooks:
+  - id: pyright
+    alias: pyrightLocal
+    name: Check types with pyright
+
+- repo: https://github.com/RobertCraigie/pyright-python
+  rev: v1.1.396
+  hooks:
+  - id: pyright
+    alias: pyrightCI
+    name: Check types with pyright
+    # use nodejs version of pyright and install requirements.txt for CI
+    additional_dependencies: ["-rrequirements.txt", "pyright[nodejs]"]
+    stages: [manual]  # Only run from CI manually
+
 - repo: local
   hooks:
     - id: scons-source

projectDocs/testing/automated.md

@@ -41,13 +41,15 @@ scons checkPot
 
 Our linting process involves running [Ruff](https://docs.astral.sh/ruff) to pick up Python linting issues and auto-apply fixes where possible.
 
+[pyright](https://microsoft.github.io/pyright/) is used for static type checking.
+
 To run the linter locally:
 
 ```cmd
 runlint.bat
 ```
 
-To be warned about linting errors faster, you may wish to integrate Ruff with your IDE or other development tools you are using.
+To be warned about linting errors faster, you may wish to integrate Ruff and pyright with your IDE or other development tools you are using.
 
 ### Unit Tests
 

pyproject.toml

@@ -51,6 +51,7 @@ exclude = [
 	".tox",
 	"build",
 	"output",
+	".venv",
 	# When excluding concrete paths relative to a directory,
 	# not matching multiple folders by name e.g. `__pycache__`,
 	# paths are relative to the configuration file.
@@ -59,6 +60,8 @@ exclude = [
 	"./source/louis",
 	# #10924: generated by third-party dependencies
 	"./source/comInterfaces/*",
+	# Code from add-ons
+	"./source/userConfig/addons/*",
 ]
 
 [tool.ruff.format]
@@ -115,3 +118,154 @@ ignore_packages = [
 	"wxPython",  # wxWindows Library License
 	"pillow",  # PIL Software License
 ]
+
+
+[tool.pyright]
+venvPath = ".venv"
+venv = "."
+pythonPlatform = "Windows"
+typeCheckingMode = "strict"
+
+include = [
+	"**/*.py",
+	"**/*.pyw",
+]
+
+exclude = [
+	"sconstruct",
+	"*sconscript",
+	".git",
+	"__pycache__",
+	".tox",
+	"build",
+	"output",
+	".venv",
+	# When excluding concrete paths relative to a directory,
+	# not matching multiple folders by name e.g. `__pycache__`,
+	# paths are relative to the configuration file.
+	"./include/*",
+	"./miscDeps",
+	"./source/louis",
+	# #10924: generated by third-party dependencies
+	"./source/comInterfaces/*",
+	# Code from add-ons
+	"./source/userConfig/addons/*",
+]
+
+# Tell pyright where to load python code from
+extraPaths = [
+	"./source",
+	# Used by system tests
+	"./tests/system/libraries",
+	# Used internally in NVDA
+	"./miscDeps/python",
+]
+
+# General config
+analyzeUnannotatedFunctions = true
+deprecateTypingAliases = true
+
+# Stricter typing
+strictParameterNoneValue = true
+strictListInference = true
+strictDictionaryInference = true
+strictSetInference = true
+
+# Compliant rules
+reportAssertAlwaysTrue = true
+reportAssertTypeFailure = true
+reportDuplicateImport = true
+reportIncompleteStub = true
+reportInconsistentOverload = true
+reportInconsistentConstructor = true
+reportInvalidStringEscapeSequence = true
+reportInvalidStubStatement = true
+reportInvalidTypeVarUse = true
+reportMatchNotExhaustive = true
+reportMissingModuleSource = true
+reportMissingImports = true
+reportNoOverloadImplementation = true
+reportOptionalContextManager = true
+reportOverlappingOverload = true
+reportPrivateImportUsage = true
+reportPropertyTypeMismatch = true
+reportSelfClsParameterName = true
+reportShadowedImports = true
+reportTypeCommentUsage = true
+reportTypedDictNotRequiredAccess = true
+reportUndefinedVariable = true
+reportUnusedExpression = true
+reportUnboundVariable = true
+reportUnhashable = true
+reportUnnecessaryCast = true
+reportUnnecessaryContains = true
+reportUnnecessaryTypeIgnoreComment = true
+reportUntypedClassDecorator = true
+reportUntypedFunctionDecorator = true
+reportUnusedClass = true
+reportUnusedCoroutine = true
+reportUnusedExcept = true
+
+# Should switch to true when possible
+reportDeprecated = false  # 1834 errors
+
+# Can be enabled by generating type stubs for modules via pyright CLI
+reportMissingTypeStubs = false
+
+# Bad rules
+# These are roughly sorted by compliance to make it easier for devs to focus on enabling them.
+# Errors were last checked Feb 2025.
+# 1-50 errors
+reportUnsupportedDunderAll = false  # 2 errors
+reportAbstractUsage = false  # 3 errors
+reportUntypedBaseClass = false  # 4 errors
+reportOptionalIterable = false  # 5 errors
+reportCallInDefaultInitializer = false  # 6 errors
+reportInvalidTypeArguments = false  # 7 errors
+reportUntypedNamedTuple = false  # 11 errors
+reportRedeclaration = false  # 12 errors
+reportOptionalCall = false  # 16 errors
+reportConstantRedefinition = false  # 18 errors
+reportWildcardImportFromLibrary = false  # 26 errors
+reportIncompatibleVariableOverride = false  # 28 errors
+reportInvalidTypeForm = false  # 38 errors
+
+
+# 50-100 errors
+reportGeneralTypeIssues = false  # 53 errors
+reportOptionalOperand = false  # 59 errors
+reportUnnecessaryComparison = false  # 67 errors
+reportFunctionMemberAccess = false  # 80 errors
+reportUnnecessaryIsInstance = false  # 88 errors
+reportUnusedFunction = false  # 97 errors
+reportImportCycles = false  # 99 errors
+reportUnusedImport = false  # 113 errors
+reportUnusedVariable = false  # 147 errors
+
+# 100-1000 errors
+reportOperatorIssue = false  # 102 errors
+reportAssignmentType = false  # 103 errors
+reportReturnType = false  # 104 errors
+reportPossiblyUnboundVariable = false  # 126 errors
+reportMissingSuperCall = false  # 159 errors
+reportUninitializedInstanceVariable = false  # 179 errors
+reportUnknownLambdaType = false  # 196 errors
+reportMissingTypeArgument = false  # 204 errors
+reportImplicitStringConcatenation = false  # 300+ errors
+reportIncompatibleMethodOverride = false  # 300+ errors
+reportPrivateUsage = false  # 900+ errors
+
+# 1000+ errors
+reportUnusedCallResult = false  # 1000+ errors
+reportOptionalSubscript = false  # 1000+ errors, mostly failing to recognize config setter/getter
+reportCallIssue = false  # 1000+ errors, mostly failing to recognize config setter/getter
+reportOptionalMemberAccess = false  # 1683 errors
+reportImplicitOverride = false  # 2000+ errors
+reportIndexIssue = false  # 2000+ errors, mostly failing to recognize config setter/getter
+reportAttributeAccessIssue = false  # 2000+ errors
+reportArgumentType = false  # 2000+ errors
+reportUnknownParameterType = false  # 4000+ errors
+reportMissingParameterType = false  # 4000+ errors
+reportUnknownVariableType = false  # 6000+ errors
+reportUnknownArgumentType = false  # 6000+ errors
+reportUnknownMemberType = false  # 20000+ errors

requirements.txt

@@ -45,6 +45,7 @@ sphinx_rtd_theme==3.0.1
 # Requirements for automated linting
 ruff==0.8.1
 pre-commit==4.0.1
+pyright==1.1.396
 
 # Running automated license checks
 licensecheck==2024.3

runlint.bat

@@ -14,3 +14,5 @@ call "%scriptsDir%\venvCmd.bat" ruff check --fix %ruffCheckArgs%
 if ERRORLEVEL 1 exit /b %ERRORLEVEL%
 call "%scriptsDir%\venvCmd.bat" ruff format %ruffFormatArgs%
 if ERRORLEVEL 1 exit /b %ERRORLEVEL%
+call "%scriptsDir%\venvCmd.bat" pyright --threads --level warning
+if ERRORLEVEL 1 exit /b %ERRORLEVEL%

source/NVDAObjects/IAccessible/__init__.py

@@ -1890,8 +1890,6 @@ def _getIA2RelationFirstTarget(
 			else:
 				raise TypeError(f"Bad type for 'relationType' arg, got: {type(relationType)}")
 
-		relationType = typing.cast(IAccessibleHandler.RelationType, relationType)
-
 		try:
 			# rather than fetch all the relations and querying the type, do that in process for performance reasons
 			targetsGen = self._getIA2TargetsForRelationsOfType(relationType, maxRelations=1)
@@ -1935,8 +1933,6 @@ def _getIA2RelationTargetsOfType(
 			else:
 				raise TypeError(f"Bad type for 'relationType' arg, got: {type(relationType)}")
 
-		relationType = typing.cast(IAccessibleHandler.RelationType, relationType)
-
 		try:
 			# rather than fetch all the relations and querying the type, do that in process for performance reasons
 			# Bug in Chrome, Chrome does not respect maxRelations param.

source/NVDAObjects/IAccessible/adobeAcrobat.py

@@ -13,7 +13,7 @@
 from NVDAObjects import NVDAObjectTextInfo
 from NVDAObjects.behaviors import EditableText
 from comtypes import GUID, COMError, IServiceProvider
-from comtypes.gen.AcrobatAccessLib import IAccID, IGetPDDomNode, IPDDomElement
+from comtypes.gen.AcrobatAccessLib import IAccID, IGetPDDomNode, IPDDomElement  # type: ignore[reportMissingImports]
 from logHandler import log
 
 SID_AccID = GUID("{449D454B-1F46-497e-B2B6-3357AED9912B}")

source/NVDAObjects/IAccessible/ia2Web.py

@@ -330,7 +330,7 @@ class EditorChunk(Ia2Web):
 
 class Math(Ia2Web):
 	def _get_mathMl(self):
-		from comtypes.gen.ISimpleDOM import ISimpleDOMNode
+		from comtypes.gen.ISimpleDOM import ISimpleDOMNode  # type: ignore[reportMissingImports]
 
 		try:
 			node = self.IAccessibleObject.QueryInterface(ISimpleDOMNode)

source/NVDAObjects/UIA/winConsoleUIA.py

@@ -27,6 +27,17 @@
 from ..window import Window
 
 
+__all__ = [
+	"ConsoleUIATextInfo",
+	"ConsoleUIATextInfoWorkaroundEndInclusive",
+	"WinConsoleUIA",
+	"consoleUIAWindow",
+	"findExtraOverlayClasses",
+	"_DiffBasedWinTerminalUIA",
+	"_NotificationsBasedWinTerminalUIA",
+]
+
+
 class ConsoleUIATextInfo(UIATextInfo):
 	"A TextInfo implementation for consoles with an IMPROVED, but not FORMATTED, API level."
 

source/UIAHandler/_remoteOps/instructions/_base.py

@@ -9,6 +9,8 @@
 	InstructionBase,
 )
 
+__all__ = ["_TypedInstruction"]
+
 
 class _TypedInstruction(InstructionBase):
 	@property