UIA handler reorganization: gather UIA modules into a public "UIAHandler" package by josephsl · Pull Request #13089 · nvaccess/nvda

josephsl · 2021-11-24T04:30:16Z

Link to issue number:

Summary of the issue:

The bulk of UIA support code resides in a private UIA handler module (_UIAHandler.py). It was done that way to support Windows releases without usable UIA implementations such as Windows XP. Also, other UIA support modules such as custom annotations were added to support specific UIA scenarios.

Description of how this pull request fixes the issue:

Reorganized UIA handler as follows:

UIA handler and other support modules is now part of a UIAHandler package, similar to IAccessibleHandler reorganization that took place recently.
The public ane private UIA handler modules were combined under one module (UIAHandler/init.py).
Additional uIA modules such as UIC custom annotations and properties, constatns, browse mode, and UIA utils are now part of UIAHandler package.
NVDA source code that referred to old file locations were edited to point to UIAHandler package modules.
Linted UIAHandler.UIAHandler.getNearestWindowHandle method.

Testing strategy:

Manual, unit, and system tests:

Performed unit tests whenever commits were made.
Performed system tests whenever commits were made.
Ran linter to make sure it passed before commiting changes.
Ran UIA scenarios manually such as console support, Windows apps, UIA+Excel, among other things to make sure functionality remained the same.

Known issues with pull request:

None (haven't found add-ons that use the old modules)

Change log entries:

Changes for developers:

UIA handler module and other UIA support modules are now part of UIAHandler package. (#10916

Then mention the renamed files:

UIAHandler.py and _UIAHandler.py -> UIAHandler/init.py (you don't have to mention this if you want)
UIAUtils.py -> UIAHandler/utils.py
UIABrowseMode.py -> UIAHandler/browseMode.py
_UIAConstants.py -> UIAHandler/constants.py
_UIACustomProps.py -> UIAHandler/customPropts.py
_UIACustomAnnotations.py -> UIAHandler/customAnnotations.py

Code Review Checklist:

Pull Request description:
- description is up to date
- change log entries
Testing:
- Unit tests
- System (end to end) tests
- Manual testing
API is compatible with existing add-ons.
Documentation:
- User Documentation
- Developer / Technical Documentation
- Context sensitive help for GUI changes
UX of all users considered:
- Speech
- Braille
- Low Vision
- Different web browsers
- Localization in other languages / culture than English

… public module. Re nvaccess#10916. When UIA handler first appeared in 2008, it was housed in UIAHandler.py, the public-facing module. In 2011, a private _UIAHandler.py module was created to handle lack of usable UIA implementation in Windows XP, Server 2003, and older releases of Windows Vista and Server 2008. Since NVDA 2017.4, Windows 7 SP1 and Server 2008 R2 SP1 are required, meaning a usable UIA implementation is available. For backward compatibility, the private/public split was kept. Recognizing maintenance issues with private/public module, a reorganization effort was proposed in 2020, with the work taking place in 2021. This effort aims to combine private and public UIA handler modules under one file, as well as bring UIA support modules under a package, similar to IAccessible handler reorganization in 2021. As a first step, contents of private UIA handler module is now part of public UIA handler, with other NVDA modules importing the private module to be edited to use the public module (later commit). Module header is based on a combination of both public and private modules. Combined module contents: 1. Module header 2. Public module contents (UIA handler object definition, init/terminate methods) placed between bulk of private module content and UIA debug check function

With the contents of the private module moved to public UIA handler module, there is no need to keep the private module around anymore. Therefore remove the private module.

…. Re nvaccess#10916. Reorganization: convert UIA handler from a module to a package (source/UIAHandler/__init__.py). The new UIA handler package will be home of various UIA related modules such as UIA custom properties and annotations support.

…m props, and custom annotations modules. Re nvaccess#10916

Import changes: * _UIAConstants -> UIAHandler.constants * _UIACustomAnnotations -> UIAHandler.customAnnocations * _UIACustomProps -> UIAHandler.customProps

…ndler. Re nvaccess#10916. Transfer UIA utils module to UIA handler package, along with editing UIA constants module import to be relative import.

…and custom props modules as contents were transferred to UIA handler package and renamed. Re nvaccess#10916

…IA handler and was renamed to utils. Re nvaccess#10916

… rename it to browseMode.py. Re nvaccess#10916

…s#10916

… to UIA handler package and renamed. Re nvaccess#10916

In addition to resolving lint issues (Flake8), linted UIAHandler.handler.getNearistWindowHandle method.

…omRange import from UIAHandler.browseMode module as it is not used. Re nvaccess#10916. According to Flake8, UIAHandler.utils.getUIATextAttributeValueFromRange is imported but unused in UIAHandler.browseMode.py, therefore remove this import.

seanbudd

This generally looks good to me.

I would also consider moving all/most of the constants at the top of source/UIAHandler/__init__.py into separate files within the module.
This could be done in a follow up PR to make reviewing this PR easier.

Additionally, merging this PR will require reviews and feedback from other developers.

seanbudd · 2021-11-24T04:39:28Z

 		return False


+handler: Optional[UIAHandler] = None


This, and the initialization code, might be better suited to the top of file

I agree it would be nicer. The only problem you may encounter would be a Linter complain about UIAHandler not being defined yet. This can be easily worked around either by:

placing UIAHandler in quotes or

moving UIAHandler to a separate file, though this should happen in a follow up.

josephsl · 2021-11-24T04:48:15Z

Hi, I think it would be best if someone takes care of splitting constants, event definitions, and related things to a separate file after creating an issue/PR pair discussing it. As for init code, it is at the bottom because Python wants class definitions to come before code that instantiates it (at least in my experience as well as looking at other modules with initialize/terminate functions defined). Thanks.

lukaszgo1 · 2021-11-24T10:03:12Z

 		return False


+handler: Optional[UIAHandler] = None


I agree it would be nicer. The only problem you may encounter would be a Linter complain about UIAHandler not being defined yet. This can be easily worked around either by:

placing UIAHandler in quotes or

moving UIAHandler to a separate file, though this should happen in a follow up.

josephsl · 2021-11-24T23:37:13Z

Hi,

As for a follow-up issue/PR pair, I guess it will discuss splitting UIA handler main module into two or more files. While we are at it, I think a long-term proposal would be to provide similar interfaces/modules between IAccessible and UIA handlers (and perhaps add JAB handler to the mix later), perhaps in 2023 cycle.

Thanks.

…ttribute from that module is used. Re nvaccess#10916. Comment from Lukasz Golonka: since word document module (UIA) imports UIAHandler.utils but no attribute is used, remove the import altogether.

josephsl · 2021-11-26T03:03:29Z

Hi,

As for putting initialize/terminate/handler class at the top of the UIA handler main module, I think it would be best to do it as part of a follow-up pull request that splits the main UIA module into two or more files. That way not only we can take care of this, but also lets us lint changes.

Thanks.

feerrenrut

Looks good to me.

Let's get this merged in and monitor for issues. Good work @josephsl

josephsl added 17 commits November 22, 2021 18:02

NVDAObjects/UIA/Excel: _UIAHandler -> UIAHandler. Re nvaccess#10916

78359de

UIA handler: remove private module. Re nvaccess#10916.

3dbc0a0

With the contents of the private module moved to public UIA handler module, there is no need to keep the private module around anymore. Therefore remove the private module.

UIA handler package: create a package version of UIA constants, custo…

2a4da6a

…m props, and custom annotations modules. Re nvaccess#10916

UIA handler reorg: change imports. Re nvaccess#10916.

a81e7f9

Import changes: * _UIAConstants -> UIAHandler.constants * _UIACustomAnnotations -> UIAHandler.customAnnocations * _UIACustomProps -> UIAHandler.customProps

UIA handler reorg: transfer and edit UIA utilities module into UIA ha…

dcb87a5

…ndler. Re nvaccess#10916. Transfer UIA utils module to UIA handler package, along with editing UIA constants module import to be relative import.

UIA handler reorg: remove private UIA constants, custom annotations, …

47921b4

…and custom props modules as contents were transferred to UIA handler package and renamed. Re nvaccess#10916

UIA handler reorg: UIAUtils -> UIAHandler.utils. Re nvaccess#10916

b3b931e

UIA handler reorg: remove UIA utilities module as it is now part of U…

4e7f2b5

…IA handler and was renamed to utils. Re nvaccess#10916

UIA handler reorg: transfer UIA browse mode module to UIA handler and…

4f91435

… rename it to browseMode.py. Re nvaccess#10916

UIA handler reorg: UIABrowseMode -> UIAHandler.browseMode. Re nvacces…

42e0cc2

…s#10916

UIA handler reorg: remove UIA browse mode module as it is transferred…

35ced41

… to UIA handler package and renamed. Re nvaccess#10916

UIA handler reorg: fix attribute names. Re nvaccess#10916

9ed4c09

Merge branch 'master' into UIAHandlerReorg

c81a721

UIA handler reorg: lint. Re nvaccess#10916.

b07348d

In addition to resolving lint issues (Flake8), linted UIAHandler.handler.getNearistWindowHandle method.

josephsl requested a review from a team as a code owner November 24, 2021 04:30

josephsl requested a review from seanbudd November 24, 2021 04:30

seanbudd reviewed Nov 24, 2021

View reviewed changes

seanbudd requested a review from feerrenrut November 24, 2021 05:15

seanbudd approved these changes Nov 24, 2021

View reviewed changes

lukaszgo1 reviewed Nov 24, 2021

View reviewed changes

josephsl added 2 commits November 25, 2021 18:40

Merge branch 'master' into UIAHandlerReorg

50188fc

NVDAObjects/UIA/word document: remove UIAHandler.utils import as no a…

7383080

…ttribute from that module is used. Re nvaccess#10916. Comment from Lukasz Golonka: since word document module (UIA) imports UIAHandler.utils but no attribute is used, remove the import altogether.

feerrenrut approved these changes Nov 26, 2021

View reviewed changes

update changes

853ed75

seanbudd merged commit d025cd1 into nvaccess:master Nov 29, 2021

nvaccessAuto added this to the 2022.1 milestone Nov 29, 2021

Brian1Gaff mentioned this pull request Nov 29, 2021

UIA handler (backward compatibility): unify public and private modules under a package #10916

Closed

josephsl deleted the UIAHandlerReorg branch December 27, 2021 23:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

UIA handler reorganization: gather UIA modules into a public "UIAHandler" package#13089

UIA handler reorganization: gather UIA modules into a public "UIAHandler" package#13089
seanbudd merged 20 commits into
nvaccess:masterfrom
josephsl:UIAHandlerReorg

josephsl commented Nov 24, 2021

Uh oh!

seanbudd left a comment

Uh oh!

seanbudd Nov 24, 2021

Uh oh!

lukaszgo1 Nov 24, 2021

Uh oh!

josephsl commented Nov 24, 2021 via email

Uh oh!

Uh oh!

lukaszgo1 Nov 24, 2021

Uh oh!

josephsl commented Nov 24, 2021

Uh oh!

josephsl commented Nov 26, 2021

Uh oh!

feerrenrut left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

josephsl commented Nov 24, 2021

Link to issue number:

Summary of the issue:

Description of how this pull request fixes the issue:

Testing strategy:

Known issues with pull request:

Change log entries:

Code Review Checklist:

Uh oh!

seanbudd left a comment

Choose a reason for hiding this comment

Uh oh!

seanbudd Nov 24, 2021

Choose a reason for hiding this comment

Uh oh!

lukaszgo1 Nov 24, 2021

Choose a reason for hiding this comment

Uh oh!

josephsl commented Nov 24, 2021 via email

Uh oh!

Uh oh!

lukaszgo1 Nov 24, 2021

Choose a reason for hiding this comment

Uh oh!

josephsl commented Nov 24, 2021

Uh oh!

josephsl commented Nov 26, 2021

Uh oh!

feerrenrut left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants