We listened, re-introducing controlTypes aliases.


Reef Turner
 

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


Tony Malykh
 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony


On 4/7/2022 10:15 PM, Reef Turner wrote:
Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


 

Hi,

I think the key thing to keep in mind is that, due to the nature of enumerations and addition/removal/change of roles, it is not really a good idea to store internal values in configurations. The integer values are kept for compatibility, but we never know when they might be gone.

My own plan is to use the new enumeration throughout. But with changes to how deprecations and removals are communicated from documentation and compatibility policy and costs, I may need to change some things such as when I drop compatibility with older releases. However the bigger issue remains: if NV Access keeps annual compatibility API flag policy, then the problem of NVDA not flagging add-ons as “compatible” will surface again around this time next year. As demonstrated in a discussion on add-on files pull requests and who can submit them (or at least implied), we have authors who do not have the time and luxury to sit down in front of their computers working on add-ons all day, and sometimes it takes a while for folks to understand the impact of deprecations and removals; my hope is that the new documentation and compatibility cost considerations would serve as a way to improve communication between NV Access and add-ons community.

P.S. While I love giving previews of what’s coming in future API releases, I realize that I need to do a better job with it such as providing examples, as well as find a way to train you to do what I do: documentation strategies. One way to improve documentation is strategic source code commenting where you comment your add-on source code in places where you realize that first-time readers may not understand the magic behind what you wrote. I’ve been pushing this idea for years and will do so again because source code comments are extremely beneficial for beginners and experts alike. I know I’m digressing, but the key takeaway from my musings is the importance of communication.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Friday, April 8, 2022 10:25 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony

 

On 4/7/2022 10:15 PM, Reef Turner wrote:

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


Tony Malykh
 

Joseph, your message is pretty confusing
> My own plan is to use the new enumeration throughout.
I never mentioned anything regarding new enumeration vs old constants.
> it is not really a good idea to store internal values in configurations
Who said this? I've been working in many IT companies in IT industry and this appears to be standard practice.
> The integer values are kept for compatibility, but we never know when they might be gone.
Well with all the conversion to enums we don't know when variables might be gone either. So even if I decide to store roles as strings, but then the strings might be gone due to some kind of refactoring. So I am really struggling to understand what point are you trying to make. Do you imply I shouldn't store roles at all? Because in the absense of better option it seems like so.

I guess my main point is I wanted NVAccess to know that some people depend on integer constants and ask them not to change their values without a good reason. Again I come from IT industry and it appears to be standard practice there in many big companies. ThatThat's how protobufs and thrift structures are designed. In any case I don't think I am asking for too much and since Reef mentioned that they care about add-on authors' opinion, I wanted to provide my two cents.

--Tony

it can be said equivalently that we shouldn't store string values of roles either, since they can be renamed in the future versions breaking compatibility. I read your email twice and it feels that you are suggesting that we shouldn't store any NVDA enums (like roles) in the configuration.t

On 4/8/2022 3:42 PM, Joseph Lee wrote:

Hi,

I think the key thing to keep in mind is that, due to the nature of enumerations and addition/removal/change of roles, it is not really a good idea to store internal values in configurations. The integer values are kept for compatibility, but we never know when they might be gone.

My own plan is to use the new enumeration throughout. But with changes to how deprecations and removals are communicated from documentation and compatibility policy and costs, I may need to change some things such as when I drop compatibility with older releases. However the bigger issue remains: if NV Access keeps annual compatibility API flag policy, then the problem of NVDA not flagging add-ons as “compatible” will surface again around this time next year. As demonstrated in a discussion on add-on files pull requests and who can submit them (or at least implied), we have authors who do not have the time and luxury to sit down in front of their computers working on add-ons all day, and sometimes it takes a while for folks to understand the impact of deprecations and removals; my hope is that the new documentation and compatibility cost considerations would serve as a way to improve communication between NV Access and add-ons community.

P.S. While I love giving previews of what’s coming in future API releases, I realize that I need to do a better job with it such as providing examples, as well as find a way to train you to do what I do: documentation strategies. One way to improve documentation is strategic source code commenting where you comment your add-on source code in places where you realize that first-time readers may not understand the magic behind what you wrote. I’ve been pushing this idea for years and will do so again because source code comments are extremely beneficial for beginners and experts alike. I know I’m digressing, but the key takeaway from my musings is the importance of communication.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Friday, April 8, 2022 10:25 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony

 

On 4/7/2022 10:15 PM, Reef Turner wrote:

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


 

Hi,

Regarding enumerations, what I’m getting at is that, given the old (integer) versus new (enumerations) ways of defining and using roles and states, my add-ons will use the new enumerations.

As for storing integers in config files, while I understand that this is the practice employed in the industry, integer constants for roles and states are really meant as internal representations and code should do its best to use the attribute names provided by control types module/package. At least the aliases are back, which will keep the affected code going. But at some point we need to come up with a way to think about data conversion if the goal is to support widest set of NVDA releases as possible, or in some cases, handle multiple implementations/releases. This is why I advised this community a few months ago to try using hasattr method to detect changes and act accordingly – at least for now this doesn’t apply for control types, but there are other API changes that will require use of hasattr.

Hope this clarifies things – do let me know if further clarifications are needed.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 10:04 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Joseph, your message is pretty confusing
> My own plan is to use the new enumeration throughout.
I never mentioned anything regarding new enumeration vs old constants.
> it is not really a good idea to store internal values in configurations
Who said this? I've been working in many IT companies in IT industry and this appears to be standard practice.
> The integer values are kept for compatibility, but we never know when they might be gone.
Well with all the conversion to enums we don't know when variables might be gone either. So even if I decide to store roles as strings, but then the strings might be gone due to some kind of refactoring. So I am really struggling to understand what point are you trying to make. Do you imply I shouldn't store roles at all? Because in the absense of better option it seems like so.

I guess my main point is I wanted NVAccess to know that some people depend on integer constants and ask them not to change their values without a good reason. Again I come from IT industry and it appears to be standard practice there in many big companies. ThatThat's how protobufs and thrift structures are designed. In any case I don't think I am asking for too much and since Reef mentioned that they care about add-on authors' opinion, I wanted to provide my two cents.

--Tony

it can be said equivalently that we shouldn't store string values of roles either, since they can be renamed in the future versions breaking compatibility. I read your email twice and it feels that you are suggesting that we shouldn't store any NVDA enums (like roles) in the configuration.t

On 4/8/2022 3:42 PM, Joseph Lee wrote:

Hi,

I think the key thing to keep in mind is that, due to the nature of enumerations and addition/removal/change of roles, it is not really a good idea to store internal values in configurations. The integer values are kept for compatibility, but we never know when they might be gone.

My own plan is to use the new enumeration throughout. But with changes to how deprecations and removals are communicated from documentation and compatibility policy and costs, I may need to change some things such as when I drop compatibility with older releases. However the bigger issue remains: if NV Access keeps annual compatibility API flag policy, then the problem of NVDA not flagging add-ons as “compatible” will surface again around this time next year. As demonstrated in a discussion on add-on files pull requests and who can submit them (or at least implied), we have authors who do not have the time and luxury to sit down in front of their computers working on add-ons all day, and sometimes it takes a while for folks to understand the impact of deprecations and removals; my hope is that the new documentation and compatibility cost considerations would serve as a way to improve communication between NV Access and add-ons community.

P.S. While I love giving previews of what’s coming in future API releases, I realize that I need to do a better job with it such as providing examples, as well as find a way to train you to do what I do: documentation strategies. One way to improve documentation is strategic source code commenting where you comment your add-on source code in places where you realize that first-time readers may not understand the magic behind what you wrote. I’ve been pushing this idea for years and will do so again because source code comments are extremely beneficial for beginners and experts alike. I know I’m digressing, but the key takeaway from my musings is the importance of communication.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Friday, April 8, 2022 10:25 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony

 

On 4/7/2022 10:15 PM, Reef Turner wrote:

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


Tony Malykh
 

I think you still didn't understand my point.

I am not talking about code. Of course in the code I would use Role.BUTTON and so forth. It would be insanity to use hardcoded role_id = 46 in an add-on.

I am talking about configuration file. That is the file stored on the disk in my case in json format in NVDA configuration directory. And when I say role = Role.BUTTON to store it in json it would naturally store its value, e.g. 46. But v2022 breaks this by reshuffling those values (unnecesarily I believe).

And as a result, now I need to figure out:

1. How to convert role = Role.BUTTON into a string, that hopefully is not going to change until NVDA 2035.1. That means I would need to defien a separate function to convert role into string, and then string back into role. I like simple solutions when possible, you know.

2. And how to Migrate existing numbers using v2021 versioning into string values.

All of these are headaches for add-on authors, so I just wanted to communicate this to nvaccess.

I hope now I clarified that my concern is not about writing code, we are all clear that enums are a better way. My concern was about storing roles in a config file. So your points regarding using hasattr and regarding using enums vs constans are irrelevant since they apply to working with roles in code and not storing them in config file.


On 4/9/2022 10:25 AM, Joseph Lee wrote:

Hi,

Regarding enumerations, what I’m getting at is that, given the old (integer) versus new (enumerations) ways of defining and using roles and states, my add-ons will use the new enumerations.

As for storing integers in config files, while I understand that this is the practice employed in the industry, integer constants for roles and states are really meant as internal representations and code should do its best to use the attribute names provided by control types module/package. At least the aliases are back, which will keep the affected code going. But at some point we need to come up with a way to think about data conversion if the goal is to support widest set of NVDA releases as possible, or in some cases, handle multiple implementations/releases. This is why I advised this community a few months ago to try using hasattr method to detect changes and act accordingly – at least for now this doesn’t apply for control types, but there are other API changes that will require use of hasattr.

Hope this clarifies things – do let me know if further clarifications are needed.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 10:04 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Joseph, your message is pretty confusing
> My own plan is to use the new enumeration throughout.
I never mentioned anything regarding new enumeration vs old constants.
> it is not really a good idea to store internal values in configurations
Who said this? I've been working in many IT companies in IT industry and this appears to be standard practice.
> The integer values are kept for compatibility, but we never know when they might be gone.
Well with all the conversion to enums we don't know when variables might be gone either. So even if I decide to store roles as strings, but then the strings might be gone due to some kind of refactoring. So I am really struggling to understand what point are you trying to make. Do you imply I shouldn't store roles at all? Because in the absense of better option it seems like so.

I guess my main point is I wanted NVAccess to know that some people depend on integer constants and ask them not to change their values without a good reason. Again I come from IT industry and it appears to be standard practice there in many big companies. ThatThat's how protobufs and thrift structures are designed. In any case I don't think I am asking for too much and since Reef mentioned that they care about add-on authors' opinion, I wanted to provide my two cents.

--Tony

it can be said equivalently that we shouldn't store string values of roles either, since they can be renamed in the future versions breaking compatibility. I read your email twice and it feels that you are suggesting that we shouldn't store any NVDA enums (like roles) in the configuration.t

On 4/8/2022 3:42 PM, Joseph Lee wrote:

Hi,

I think the key thing to keep in mind is that, due to the nature of enumerations and addition/removal/change of roles, it is not really a good idea to store internal values in configurations. The integer values are kept for compatibility, but we never know when they might be gone.

My own plan is to use the new enumeration throughout. But with changes to how deprecations and removals are communicated from documentation and compatibility policy and costs, I may need to change some things such as when I drop compatibility with older releases. However the bigger issue remains: if NV Access keeps annual compatibility API flag policy, then the problem of NVDA not flagging add-ons as “compatible” will surface again around this time next year. As demonstrated in a discussion on add-on files pull requests and who can submit them (or at least implied), we have authors who do not have the time and luxury to sit down in front of their computers working on add-ons all day, and sometimes it takes a while for folks to understand the impact of deprecations and removals; my hope is that the new documentation and compatibility cost considerations would serve as a way to improve communication between NV Access and add-ons community.

P.S. While I love giving previews of what’s coming in future API releases, I realize that I need to do a better job with it such as providing examples, as well as find a way to train you to do what I do: documentation strategies. One way to improve documentation is strategic source code commenting where you comment your add-on source code in places where you realize that first-time readers may not understand the magic behind what you wrote. I’ve been pushing this idea for years and will do so again because source code comments are extremely beneficial for beginners and experts alike. I know I’m digressing, but the key takeaway from my musings is the importance of communication.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Friday, April 8, 2022 10:25 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony

 

On 4/7/2022 10:15 PM, Reef Turner wrote:

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


 

Hi,

Yep, I stand corrected (perhaps I should have slept before responding…).

One possible workaround, although may not be as convenient as we might like, is checking the instance of obj.role and retrieve the raw role integer or enum.value like so:

role = obj.role

# Then either:

if not isinstance(role, int):

role = role.value

# or:

if isinstance(role, controlTypes.Role):

  role = role.value

 

The idea is to hold the correct “value” while doing config operations.

Again my apologies for my earlier post.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 1:57 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

I think you still didn't understand my point.

I am not talking about code. Of course in the code I would use Role.BUTTON and so forth. It would be insanity to use hardcoded role_id = 46 in an add-on.

I am talking about configuration file. That is the file stored on the disk in my case in json format in NVDA configuration directory. And when I say role = Role.BUTTON to store it in json it would naturally store its value, e.g. 46. But v2022 breaks this by reshuffling those values (unnecesarily I believe).

And as a result, now I need to figure out:

1. How to convert role = Role.BUTTON into a string, that hopefully is not going to change until NVDA 2035.1. That means I would need to defien a separate function to convert role into string, and then string back into role. I like simple solutions when possible, you know.

2. And how to Migrate existing numbers using v2021 versioning into string values.

All of these are headaches for add-on authors, so I just wanted to communicate this to nvaccess.

I hope now I clarified that my concern is not about writing code, we are all clear that enums are a better way. My concern was about storing roles in a config file. So your points regarding using hasattr and regarding using enums vs constans are irrelevant since they apply to working with roles in code and not storing them in config file.

 

On 4/9/2022 10:25 AM, Joseph Lee wrote:

Hi,

Regarding enumerations, what I’m getting at is that, given the old (integer) versus new (enumerations) ways of defining and using roles and states, my add-ons will use the new enumerations.

As for storing integers in config files, while I understand that this is the practice employed in the industry, integer constants for roles and states are really meant as internal representations and code should do its best to use the attribute names provided by control types module/package. At least the aliases are back, which will keep the affected code going. But at some point we need to come up with a way to think about data conversion if the goal is to support widest set of NVDA releases as possible, or in some cases, handle multiple implementations/releases. This is why I advised this community a few months ago to try using hasattr method to detect changes and act accordingly – at least for now this doesn’t apply for control types, but there are other API changes that will require use of hasattr.

Hope this clarifies things – do let me know if further clarifications are needed.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 10:04 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Joseph, your message is pretty confusing
> My own plan is to use the new enumeration throughout.
I never mentioned anything regarding new enumeration vs old constants.
> it is not really a good idea to store internal values in configurations
Who said this? I've been working in many IT companies in IT industry and this appears to be standard practice.
> The integer values are kept for compatibility, but we never know when they might be gone.
Well with all the conversion to enums we don't know when variables might be gone either. So even if I decide to store roles as strings, but then the strings might be gone due to some kind of refactoring. So I am really struggling to understand what point are you trying to make. Do you imply I shouldn't store roles at all? Because in the absense of better option it seems like so.

I guess my main point is I wanted NVAccess to know that some people depend on integer constants and ask them not to change their values without a good reason. Again I come from IT industry and it appears to be standard practice there in many big companies. ThatThat's how protobufs and thrift structures are designed. In any case I don't think I am asking for too much and since Reef mentioned that they care about add-on authors' opinion, I wanted to provide my two cents.

--Tony

it can be said equivalently that we shouldn't store string values of roles either, since they can be renamed in the future versions breaking compatibility. I read your email twice and it feels that you are suggesting that we shouldn't store any NVDA enums (like roles) in the configuration.t

On 4/8/2022 3:42 PM, Joseph Lee wrote:

Hi,

I think the key thing to keep in mind is that, due to the nature of enumerations and addition/removal/change of roles, it is not really a good idea to store internal values in configurations. The integer values are kept for compatibility, but we never know when they might be gone.

My own plan is to use the new enumeration throughout. But with changes to how deprecations and removals are communicated from documentation and compatibility policy and costs, I may need to change some things such as when I drop compatibility with older releases. However the bigger issue remains: if NV Access keeps annual compatibility API flag policy, then the problem of NVDA not flagging add-ons as “compatible” will surface again around this time next year. As demonstrated in a discussion on add-on files pull requests and who can submit them (or at least implied), we have authors who do not have the time and luxury to sit down in front of their computers working on add-ons all day, and sometimes it takes a while for folks to understand the impact of deprecations and removals; my hope is that the new documentation and compatibility cost considerations would serve as a way to improve communication between NV Access and add-ons community.

P.S. While I love giving previews of what’s coming in future API releases, I realize that I need to do a better job with it such as providing examples, as well as find a way to train you to do what I do: documentation strategies. One way to improve documentation is strategic source code commenting where you comment your add-on source code in places where you realize that first-time readers may not understand the magic behind what you wrote. I’ve been pushing this idea for years and will do so again because source code comments are extremely beneficial for beginners and experts alike. I know I’m digressing, but the key takeaway from my musings is the importance of communication.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Friday, April 8, 2022 10:25 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony

 

On 4/7/2022 10:15 PM, Reef Turner wrote:

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


Alberto Buffolino
 

Joseph Lee, il 09/04/2022 23.17, ha scritto:
One possible workaround, although may not be as convenient as we might like, is checking the instance of obj.role and retrieve the raw role integer or enum.value like so:
Alberto:
Hi Joseph,
I think Tony is saying from the opposite side, particularly because (cite):
"But v2022 breaks this by reshuffling those values (unnecesarily I believe)."
So, i.e.: add-on config has stored 46 under 2021.1, but now you run 2022.1, and you ask: what this was role associated to?
Maybe the simplest solution could be to re-distribute an old (partial) copy of controlTypes module, and, verified that the add-on is in the new situation, use this copy for get the old role and convert in string for a new configuration.
Alberto


 

Hi,
Yep, that's part of the reason for restoring aliases. Of course we can include a mapping module that maps old versus new control types role/state values. The value shuffling problem is partly caused by the fact that we had gaps in control types role/state integer values in the past, and it was somewhat addressed (or not) with role/state enumerations (the overall idea of enumerations is to resolve shuffling problems at the cost of doing extra work to access raw values as they stand now).
This is one of those instances where we should have done a better job communicating our needs with folks, especially NV Access people, and in some cases, sleep before answering or attempting to answer questions (the debacle I have exhibited in answering Tony's questions is strictly my fault).
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Alberto Buffolino
Sent: Saturday, April 9, 2022 2:36 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

Joseph Lee, il 09/04/2022 23.17, ha scritto:
One possible workaround, although may not be as convenient as we might
like, is checking the instance of obj.role and retrieve the raw role
integer or enum.value like so:
Alberto:
Hi Joseph,
I think Tony is saying from the opposite side, particularly because (cite):
"But v2022 breaks this by reshuffling those values (unnecesarily I believe)."
So, i.e.: add-on config has stored 46 under 2021.1, but now you run 2022.1, and you ask: what this was role associated to?
Maybe the simplest solution could be to re-distribute an old (partial) copy of controlTypes module, and, verified that the add-on is in the new situation, use this copy for get the old role and convert in string for a new configuration.
Alberto


Tony Malykh
 

Joseph,

Apparently you still didn't get my problem. I don't know if I can explain it in any better way. I don't want to appear offensive, but all your replies just miss my main point.
> role = obj.role
> role = role.value
This still returns an integer value that was changed in v2022, so this would still not work for me. In fact this is exactly how storing roles is currently implemented in BrowserNav and the reason why I was complaining that I would have to switch to storing strings.
No need for you to send me code snippets of how to convert roles into strings, I can figure that out by myself. Again, I just wanted to communicate this inconenience to NVAccess.

On 4/9/2022 2:17 PM, Joseph Lee wrote:

Hi,

Yep, I stand corrected (perhaps I should have slept before responding…).

One possible workaround, although may not be as convenient as we might like, is checking the instance of obj.role and retrieve the raw role integer or enum.value like so:

role = obj.role

# Then either:

if not isinstance(role, int):

role = role.value

# or:

if isinstance(role, controlTypes.Role):

  role = role.value

 

The idea is to hold the correct “value” while doing config operations.

Again my apologies for my earlier post.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 1:57 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

I think you still didn't understand my point.

I am not talking about code. Of course in the code I would use Role.BUTTON and so forth. It would be insanity to use hardcoded role_id = 46 in an add-on.

I am talking about configuration file. That is the file stored on the disk in my case in json format in NVDA configuration directory. And when I say role = Role.BUTTON to store it in json it would naturally store its value, e.g. 46. But v2022 breaks this by reshuffling those values (unnecesarily I believe).

And as a result, now I need to figure out:

1. How to convert role = Role.BUTTON into a string, that hopefully is not going to change until NVDA 2035.1. That means I would need to defien a separate function to convert role into string, and then string back into role. I like simple solutions when possible, you know.

2. And how to Migrate existing numbers using v2021 versioning into string values.

All of these are headaches for add-on authors, so I just wanted to communicate this to nvaccess.

I hope now I clarified that my concern is not about writing code, we are all clear that enums are a better way. My concern was about storing roles in a config file. So your points regarding using hasattr and regarding using enums vs constans are irrelevant since they apply to working with roles in code and not storing them in config file.

 

On 4/9/2022 10:25 AM, Joseph Lee wrote:

Hi,

Regarding enumerations, what I’m getting at is that, given the old (integer) versus new (enumerations) ways of defining and using roles and states, my add-ons will use the new enumerations.

As for storing integers in config files, while I understand that this is the practice employed in the industry, integer constants for roles and states are really meant as internal representations and code should do its best to use the attribute names provided by control types module/package. At least the aliases are back, which will keep the affected code going. But at some point we need to come up with a way to think about data conversion if the goal is to support widest set of NVDA releases as possible, or in some cases, handle multiple implementations/releases. This is why I advised this community a few months ago to try using hasattr method to detect changes and act accordingly – at least for now this doesn’t apply for control types, but there are other API changes that will require use of hasattr.

Hope this clarifies things – do let me know if further clarifications are needed.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 10:04 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Joseph, your message is pretty confusing
> My own plan is to use the new enumeration throughout.
I never mentioned anything regarding new enumeration vs old constants.
> it is not really a good idea to store internal values in configurations
Who said this? I've been working in many IT companies in IT industry and this appears to be standard practice.
> The integer values are kept for compatibility, but we never know when they might be gone.
Well with all the conversion to enums we don't know when variables might be gone either. So even if I decide to store roles as strings, but then the strings might be gone due to some kind of refactoring. So I am really struggling to understand what point are you trying to make. Do you imply I shouldn't store roles at all? Because in the absense of better option it seems like so.

I guess my main point is I wanted NVAccess to know that some people depend on integer constants and ask them not to change their values without a good reason. Again I come from IT industry and it appears to be standard practice there in many big companies. ThatThat's how protobufs and thrift structures are designed. In any case I don't think I am asking for too much and since Reef mentioned that they care about add-on authors' opinion, I wanted to provide my two cents.

--Tony

it can be said equivalently that we shouldn't store string values of roles either, since they can be renamed in the future versions breaking compatibility. I read your email twice and it feels that you are suggesting that we shouldn't store any NVDA enums (like roles) in the configuration.t

On 4/8/2022 3:42 PM, Joseph Lee wrote:

Hi,

I think the key thing to keep in mind is that, due to the nature of enumerations and addition/removal/change of roles, it is not really a good idea to store internal values in configurations. The integer values are kept for compatibility, but we never know when they might be gone.

My own plan is to use the new enumeration throughout. But with changes to how deprecations and removals are communicated from documentation and compatibility policy and costs, I may need to change some things such as when I drop compatibility with older releases. However the bigger issue remains: if NV Access keeps annual compatibility API flag policy, then the problem of NVDA not flagging add-ons as “compatible” will surface again around this time next year. As demonstrated in a discussion on add-on files pull requests and who can submit them (or at least implied), we have authors who do not have the time and luxury to sit down in front of their computers working on add-ons all day, and sometimes it takes a while for folks to understand the impact of deprecations and removals; my hope is that the new documentation and compatibility cost considerations would serve as a way to improve communication between NV Access and add-ons community.

P.S. While I love giving previews of what’s coming in future API releases, I realize that I need to do a better job with it such as providing examples, as well as find a way to train you to do what I do: documentation strategies. One way to improve documentation is strategic source code commenting where you comment your add-on source code in places where you realize that first-time readers may not understand the magic behind what you wrote. I’ve been pushing this idea for years and will do so again because source code comments are extremely beneficial for beginners and experts alike. I know I’m digressing, but the key takeaway from my musings is the importance of communication.

Cheers,

Joseph

 

From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Friday, April 8, 2022 10:25 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

 

Hey Reef, as an add-on author I definitely support nvAccess to leave old definitions for backward compatibility.
One piece of feedback from me is that it would be great to keep role values constant. I saw that you recently changed them in commit d4586a5d907dd4dec761d3234147fa5fd6186b37.
For me this breaks compatibility of BrowserNav add-on, as I was storing some user-configurable roels in my configuration file and I was storing them as integer ID values. But after that commit all the roles were messed up. Now I would have to implement some code to perform mirgration to the new values. But since you listen to add-on authors' feedback, I hope that in the future enum constants won't change from one version to another to make life easier for some add-on authors!
Sincerely
--Tony

 

On 4/7/2022 10:15 PM, Reef Turner wrote:

Hi add-on developers, and core-developers,

NV Access has had feedback during the beta period that add-on authors are finding it onerous to replace the removed controlTypes aliases. After assessing the maintenance cost of this, we determined that we could reintroduce them in the 2022.1 release. Although this is a late change, and theoretically post-finalization of the add-on API, we believe it is low risk, and an overall benefit to add-on developers (lower cost upgrade) and end users (more add-ons available).

We still recommend that add-on authors migrate towards the new names for these Enum values. Consistency with the nvda-core code will benefit current and future developers reading code within your add-on.

This feedback only became clear to us very late in the development cycle, far past when we want to be making changes. We'll be investigating what prevents community developers from knowing about API changes, and providing feedback on the impact to them. We wish to streamline this process so we can reduce the likelihood of this situation in the future.

Additionally, we'll be changing our process to opt to preserve backwards compatibility if the maintenance cost is considered low.

The Pull Request to restore the controlTypes aliases can be found here: https://github.com/nvaccess/nvda/pull/13588

Thanks,
Reef (NV Access)


Tony Malykh
 

we had gaps in control types role/state integer values in the past
What exactly is the problem with gaps? If there is a real technical issue caused by these gaps I might understand reshuffling. But if it was done for the abstract concept of code beauty, then I just wanted to shed some light on the other side of this tradeoff.


I am perhaps repeating myself, but my complain is not about switching to enums. It is not about restoring the old aliases. It is about reshuffling the values. But I guess I've reach max number of attempts to repeat myself at this point.

On 4/9/2022 2:48 PM, Joseph Lee wrote:
Hi,
Yep, that's part of the reason for restoring aliases. Of course we can include a mapping module that maps old versus new control types role/state values. The value shuffling problem is partly caused by the fact that we had gaps in control types role/state integer values in the past, and it was somewhat addressed (or not) with role/state enumerations (the overall idea of enumerations is to resolve shuffling problems at the cost of doing extra work to access raw values as they stand now).
This is one of those instances where we should have done a better job communicating our needs with folks, especially NV Access people, and in some cases, sleep before answering or attempting to answer questions (the debacle I have exhibited in answering Tony's questions is strictly my fault).
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Alberto Buffolino
Sent: Saturday, April 9, 2022 2:36 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

Joseph Lee, il 09/04/2022 23.17, ha scritto:
One possible workaround, although may not be as convenient as we might
like, is checking the instance of obj.role and retrieve the raw role
integer or enum.value like so:
Alberto:
Hi Joseph,
I think Tony is saying from the opposite side, particularly because (cite):
"But v2022 breaks this by reshuffling those values (unnecesarily I believe)."
So, i.e.: add-on config has stored 46 under 2021.1, but now you run 2022.1, and you ask: what this was role associated to?
Maybe the simplest solution could be to re-distribute an old (partial) copy of controlTypes module, and, verified that the add-on is in the new situation, use this copy for get the old role and convert in string for a new configuration.
Alberto









 

Hi,
Ah, I see what's up... Even with restored aliases, you will still need to perform shifts - values were not shuffled, but rather shifted by 1 or 2 - this is because Role.UNKNOWN starts at 1, not 0 (but of course we can say values were shuffled). What's not helping is the fact that, in older NVDA release, there were gaps in integer values: 68 and 81 are missing, and 114 (alert) was removed recently.
To elaborate my understanding of the frustration expressed here, we have a situation where role integer values are stored inside configuration files and are used from an add-on. In NVDA 2021.x and earlier, both NVDA and config file was in sync about what integer values meant as far as roles were concerned. But with introduction of role/state enumerations, and especially with these enumerations tagged with unique decorator in 2022.1, integer values have changed. For example, we had controlTypes.ROLE_UNKNOWN having a value of 0 in NVDA 2021.x whereas it is 1 in 2022.x and in restored aliases. Now suppose an add-on code sees that a role value in config file is 0, which maps to ROLE_UNKNOWN in older NVDA releases but nothing in 2022.x.
In answer to another post: I know that we went around in circles to get to this point. I think what could have made this trip easier was an example or two of changed role values that demonstrates what is happening. Now I have a better picture, I should be able to focus on possible solutions and reflecting and critiquing my earlier responses, which I think was disastrous (wasn't clearly thinking when I wrote those replies, didn't look into NVDA Core code differences to notice it earlier).
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 4:08 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

> we had gaps in control types role/state integer values in the past

What exactly is the problem with gaps? If there is a real technical issue caused by these gaps I might understand reshuffling. But if it was done for the abstract concept of code beauty, then I just wanted to shed some light on the other side of this tradeoff.


I am perhaps repeating myself, but my complain is not about switching to enums. It is not about restoring the old aliases. It is about reshuffling the values. But I guess I've reach max number of attempts to repeat myself at this point.

On 4/9/2022 2:48 PM, Joseph Lee wrote:
Hi,
Yep, that's part of the reason for restoring aliases. Of course we can include a mapping module that maps old versus new control types role/state values. The value shuffling problem is partly caused by the fact that we had gaps in control types role/state integer values in the past, and it was somewhat addressed (or not) with role/state enumerations (the overall idea of enumerations is to resolve shuffling problems at the cost of doing extra work to access raw values as they stand now).
This is one of those instances where we should have done a better job communicating our needs with folks, especially NV Access people, and in some cases, sleep before answering or attempting to answer questions (the debacle I have exhibited in answering Tony's questions is strictly my fault).
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io
<nvda-addons@nvda-addons.groups.io> On Behalf Of Alberto Buffolino
Sent: Saturday, April 9, 2022 2:36 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

Joseph Lee, il 09/04/2022 23.17, ha scritto:
One possible workaround, although may not be as convenient as we
might like, is checking the instance of obj.role and retrieve the raw
role integer or enum.value like so:
Alberto:
Hi Joseph,
I think Tony is saying from the opposite side, particularly because (cite):
"But v2022 breaks this by reshuffling those values (unnecesarily I believe)."
So, i.e.: add-on config has stored 46 under 2021.1, but now you run 2022.1, and you ask: what this was role associated to?
Maybe the simplest solution could be to re-distribute an old (partial) copy of controlTypes module, and, verified that the add-on is in the new situation, use this copy for get the old role and convert in string for a new configuration.
Alberto










Karl-Otto Rosenqvist
 

Hi!
One solution would be to move from storing integers to strings first with a NVDA 2021.x or earlier with an updated add on before upgrading to NVDA 2022.1. the problem with this is that you can't be sure that it happens in the correct order.

Perhaps the configurations have to include what version of NVDA it was stored with so one could detect if there's need for an upgrade before use.
This mechanism should be implemented in NVDA and the configuration system so when configurations are loaded that needs an upgrade is pushed through a config upgrade method that you need to override.

I understand that this is very late to the game but perhaps it's better to standardize with a slight delay than getting wild west?

The mentioned version control of configurations can be done by each add on author regardless of if there's built in support for it in NVDA.

1. Load configuration.
2. Check version.
2.1. Upgrade values if needed.
2.2 Save configuration.
3. Do your work as an add on.


Regards

Karl-Otto



Karl-Otto Rosenqvist
MAWINGU
Orgnr: 750804-3937
0701- 75 98 56
karl-otto@...
https://mawingu.se

Den 2022-04-10 kl. 03:44, skrev Joseph Lee:

Hi,
Ah, I see what's up... Even with restored aliases, you will still need to perform shifts - values were not shuffled, but rather shifted by 1 or 2 - this is because Role.UNKNOWN starts at 1, not 0 (but of course we can say values were shuffled). What's not helping is the fact that, in older NVDA release, there were gaps in integer values: 68 and 81 are missing, and 114 (alert) was removed recently.
To elaborate my understanding of the frustration expressed here, we have a situation where role integer values are stored inside configuration files and are used from an add-on. In NVDA 2021.x and earlier, both NVDA and config file was in sync about what integer values meant as far as roles were concerned. But with introduction of role/state enumerations, and especially with these enumerations tagged with unique decorator in 2022.1, integer values have changed. For example, we had controlTypes.ROLE_UNKNOWN having a value of 0 in NVDA 2021.x whereas it is 1 in 2022.x and in restored aliases. Now suppose an add-on code sees that a role value in config file is 0, which maps to ROLE_UNKNOWN in older NVDA releases but nothing in 2022.x.
In answer to another post: I know that we went around in circles to get to this point. I think what could have made this trip easier was an example or two of changed role values that demonstrates what is happening. Now I have a better picture, I should be able to focus on possible solutions and reflecting and critiquing my earlier responses, which I think was disastrous (wasn't clearly thinking when I wrote those replies, didn't look into NVDA Core code differences to notice it earlier).
Cheers,
Joseph
-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Tony Malykh
Sent: Saturday, April 9, 2022 4:08 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

> we had gaps in control types role/state integer values in the past
What exactly is the problem with gaps? If there is a real technical issue caused by these gaps I might understand reshuffling. But if it was done for the abstract concept of code beauty, then I just wanted to shed some light on the other side of this tradeoff.
I am perhaps repeating myself, but my complain is not about switching to enums. It is not about restoring the old aliases. It is about reshuffling the values. But I guess I've reach max number of attempts to repeat myself at this point.
On 4/9/2022 2:48 PM, Joseph Lee wrote:
Hi,
Yep, that's part of the reason for restoring aliases. Of course we can include a mapping module that maps old versus new control types role/state values. The value shuffling problem is partly caused by the fact that we had gaps in control types role/state integer values in the past, and it was somewhat addressed (or not) with role/state enumerations (the overall idea of enumerations is to resolve shuffling problems at the cost of doing extra work to access raw values as they stand now).
This is one of those instances where we should have done a better job communicating our needs with folks, especially NV Access people, and in some cases, sleep before answering or attempting to answer questions (the debacle I have exhibited in answering Tony's questions is strictly my fault).
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io
<nvda-addons@nvda-addons.groups.io> On Behalf Of Alberto Buffolino
Sent: Saturday, April 9, 2022 2:36 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] We listened, re-introducing controlTypes aliases.

Joseph Lee, il 09/04/2022 23.17, ha scritto:
One possible workaround, although may not be as convenient as we
might like, is checking the instance of obj.role and retrieve the raw
role integer or enum.value like so:
Alberto:
Hi Joseph,
I think Tony is saying from the opposite side, particularly because (cite):
"But v2022 breaks this by reshuffling those values (unnecesarily I believe)."
So, i.e.: add-on config has stored 46 under 2021.1, but now you run 2022.1, and you ask: what this was role associated to?
Maybe the simplest solution could be to re-distribute an old (partial) copy of controlTypes module, and, verified that the add-on is in the new situation, use this copy for get the old role and convert in string for a new configuration.
Alberto










Reef Turner
 

Hi Tony,

Thanks for the feedback. The use-case you describe was not considered when making this change. Generally, I wouldn't recommend storing the values of enums in config, they are too prone to change. Essentially this is depending on an implementation detail. The config spec is then highly coupled to the implementation of the enum. Of course, you likely made this decision when these were stand-alone constants, not enums, and options were limited.
 
I'd recommend migrating towards either keeping an internal mapping to translate between API values and config values, or using the enum name to save and restore: 'role.name', 'controlTypes.Role[nameFromConfig]'.
There are different trade-offs with these approaches, which approach you choose really depends on your comfort level with having to cater to future change.
 
In the meantime, I'll be re-introducing the explicit values for Roles and States. But be aware that the implementations for these enums may change in the future.
 
I hope that add-on developers can appreciate that the breadth and depth of the API provided by NVDA is large. Often highly coupled with internals. This can result in difficulty making changes (sometimes prohibiting fixing bugs, or implementing features). We offer a 'best-effort' attempt not to create problems for add-ons, while pushing the core forwards. To help this process we really do need feedback from add-on authors where some change will cause them excessive difficulty to manage.
 
On the longer term, I think a suite of add-on API's that are decoupled from core will need to be introduced. These would be able to provide much greater stability, but likely with reduced breadth and depth.

Regards, Reef (NV Access)


Reef Turner