NVDA code base: employ structural pattern matching to make the code more readable

[josephsl]

Hi,

Now that Python 3.11 powers NVDA, it would be great to modernize NVDA source code, and one such possibility is below. Note that an issue is not used as this should serve as a starting point with issues to cover individual or hard cases.

Introduction

Python 3.10 introduced structural pattern matching (match/case). This allows Python code to use a more declarative syntax when handling conditions and other scenarios.

A typical structural pattern matching syntax is:

subject = someExpression/function()
match subject:
case case1:
doSomething
case case2:
doSomethingElse()
case "case3A" | "case3B":
performSomethingThatTakesOneOrBothMatches()
case ["case4", someValue]:
complicatedProcedureInvolvingMatchAndSomeValue()
case ["case5A", "case5B"] as something:
quiteAComplicatedProcedure()
case _:
everythingElse

For example, if NVDA wants to insert specific overlay class based on window class name:

windowClassName = obj.windowClassName
match windowClassName: # (or you can write match obj.windowClassName but this one can get verbose)
case "class1":
clsList.insert(0, OverlayClass1)
case "class2":
clsList.insert(0, OverlayClass2)
case "class3A" | "class3B":
clsList.remove(UnwantedOverlayClass)

Here, "case _:" is omitted.

You can also do something similar to the following (example: event_NVDAObject_init):

match obj.role:
case controlTypes.Role.CHECKBOX:
obj.name = aMoreUsefulName
case controlTypes.Role.STATICTEXT | controlTypes.Role.PANE:
if obj.windowClassName.endswith("form"):
obj.description = ""

Structural pattern matching and NVDA source code

The following places in NVDA source code may see improved readability when structural pattern matching is employed:

• Overlay class finders and choosers in app modules, NVDA objects, and add-ons (remember that match/case only works on single subject, so one cannot use combination of window class/role/state at once but can be used once a pattern matches, see above)
• Commands for changing NVDA settings on the fly such as NVDA+U to step through progress bar announcement (match/case replaces if/elif/else statements)

Places where structural pattern maching is not useful:

• Overlay class choosers where multiple subjects are checked at once (see a possible workaround above)
• Windows API availability checks where hasattr is more effective

NVDA and other tools

Flake8 4.0.1 supports structural pattern matching so we can use match/case statements right away.

Impact on add-ons

Add-ons wishing to employ structural pattern matching must do one of the following:

• Version aware code: have separate code paths for Python 3.7 and 3.11, likely two different functions to cover different Python versions and syntax differences
• Target NVDA 2024.1 from the start i.e. drop NVDA 2023.3 or earlier version compatibility

Positions

Reasons to adopt structural pattern matching:

• Modernizes NVDA source code
• Makes code more readable

Drawbacks:

• The new syntax is optimized for single subjects, not a combination of subjects unless conditions are checked inside case code path
• Existing if/elif/else statements are adequate
• Need to compare performance of if/elif/else versus match/case statements (match/case works best if common and/or specific cases are handled early).

If structural pattern matching is adopted

If we say "yes" to structural pattern matching:

1. Decide on when to adopt the new syntax (I propose 2024.1 or 2024.2).
2. Compare performances between if/elif/else and match/case.
3. Survey NVDA source code, marking places where structural pattern matching makes code more readable.
4. Test with a limited set of source code files, then compare user experiences.
5. If structural pattern matching is working and beneficial, update NVDA source gradually over at least one or two releases.

Thanks.

[seanbudd]

Thanks Joseph for investigating this. I don't think there is a need for this level of planning here. Like other modern python features, we can adopt this as new code is written or existing code is modified. I don't think it is a good use of time to compare performances, survey code or perform extensive testing.
We should continue to update code to use the latest language features when appropriate, like we have for Enums, dataclasses, and typing annotations.