Backwards compatible control types refactor

[seanbudd]

Link to issue number:

Closes #10732

Summary of the issue:

controlTypes.py is a large file with many constants. To maintain backwards compatibility, the file length would increase to 1000+ LOC. It would be an improvement to split this code up, and group the constants into enums. As 2021.2 is not a compatibility breaking release, all changes must be backwards compatible.

Description of how this pull request fixes the issue:

This is a large refactor. The changes are split into individual commits for reviewers.

The first commit can be reviewed using the following tool

for file in $(ls source/controlTypes/*.py)
do
git diff master:source/controlTypes.py 8642581:$file > $file-controlTypes.diff
done

The second commit is generated using the following sed commands.

sed -i'' -bre "s/ROLE_([A-z0-9_]+) ?= ?/\t\1 = /g" source/controlTypes.py
sed -i'' -bre "s/ROLE_([A-z0-9_]+) ?:([^ ])/Role.\1: \2/g" source/controlTypes.py
sed -i'' -bre "s/ROLE_([A-z0-9_]+)/Role.\1/g" source/controlTypes.py

sed -i'' -bre "s/STATE_([A-z0-9_]+) ?= ?/\t\1 = /g" source/controlTypes.py
sed -i'' -bre "s/STATE_([A-z0-9_]+) ?:([^ ])/State.\1: \2/g" source/controlTypes.py
sed -i'' -bre "s/STATE_([A-z0-9_]+)/State.\1/g" source/controlTypes.py

The mixin strategy follows what is outlined for python 3.7 here. Mixins with Enums are fragile, and this code will have to be changed when updating (or downgrading python) Python.

Testing strategy:

Manual testing.

There is unit testing for the controlTypes module which should help ensure that compatibility doesn't break.

This module is fairly widely utilised, so any breaking changes are likely to be picked up quickly.

Known issues with pull request:

Changes can't be tracked backwards using git blame to controlTypes.py due to how the files are split up. As such, I've linted these files.

I haven't implemented the enums in the wider NVDA codebase. When we break the backwards compatibility, by updating to 2022.1, we will need to update the rest of the NVDA code beforehand (see #12549).

Change log entries:

For developers:

• controlTypes has been split up into various submodules. ROLE_* and STATE_* constants should be replaced to their equivalent Role.* and State.* before 2022.1. (Backwards compatible control types refactor #12510)
• roleLabels, stateLabels and negativeStateLabels have been deprecated, usages such as roleLabels[ROLE_*] should be replace to their equivalent Role.*.displayString or State.*.negativeDisplayString before 2022.1. (Backwards compatible control types refactor #12510)

Code Review Checklist:

• Pull Request description is up to date.
• Unit tests.
• System (end to end) tests.
• Manual testing.
• User Documentation.
• Change log entry.
• Context sensitive help for GUI changes.
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers

[LeonarddeR]

This is an awesome change!

Could you consider the following while at it?

1. Create an abstract class that defines the displayString property e.g. EnumWithTranslatableDisplayString
2. Base the following classes on this abstract class: IsCurrent, Role and State
3. Role and State's displayString should return the role/state label, respectively
4. Instead of letting code use the role and state label dictionaries, use the displayString property instead.

[AppVeyorBot]

• FAIL: System tests. See test results for more information.
• Build (for testing PR)
• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.

See test results for failed build of commit aad9fadbb0

[feerrenrut]

For now I'll assume your self review has ensured that the movement of code hasn't introduced changes. I'll first focus on the layout and introduced code.

As usual, with moved code, we'll merge rather than squash merge. Can you confirm that the commits are logical for that please. I can recommend using the the "autosquash" feature in git. It makes it easier to keep track of what while be the final commits while making updates to them, addressing review actions etc.

[feerrenrut]

This is good, it's really close to being ready.

I have confirm there are only minor differences since the old HEAD 6ee01a53e
I have confirmed that the moved code still matches the old code from master, except for now using Enums and other minor changes. The code seems logically equivalent

I haven't yet confirmed everything previously exposed from controlTypes.py is exposed from controlTypes package.

[feerrenrut]

I have confirmed (by comparing the files with git difftool origin/master:source/controlTypes.py HEAD:source/controlTypes/__init__.py ) that what is exposed from control types hasn't changed.

Another way to verify this may be to load use the NVDA python console:

• Import control types
• pprint(dir(controlTypes)).
• Save this output for both before and after this change and compare with a diff tool.

[seanbudd]

I've updated the deprecations.md file to reflect your verification step, and changes.t2t

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests. See test results for more information.
• Build (for testing PR)

See test results for failed build of commit 721241b832