Cleanly break out of windows iteration

[CristiFati]

This is a (proposed) fix for #2163. If the user wants to stop iteration (by returning FALSE (or equivalent) from the callback) EnumWindows (&& friends) should not raise exception. It should only raise exception if callback:

• Raised one (already implemented)
• Sets last error (as suggested in [MS.Learn]: EnumWindows function (winuser.h) - Return value)

Notes:

• PyWin_SetAPIError: considering that 0 (SUCCESS) is Win's way of signaling non failure, I think that (logically) this should be the default behavior (if there's no error, don't raise any exception, especially since that message is not clear). But:

  • The function name clearly denotes an error
  • Most likely, lots of code (PyWin32 and 3^{rd</sup-party) depends on current behavior, I think it will trigger massive regressions}

  I only added this behavior as an option (disabled by default)

• IMPORTANT - do not merge until next question is answered:

  • As stated above, this applies to other functions from the same family (well except EnumChildWindows whose return value must be ignored). Since there are very little differences between behaviors, would it make sense to only have a function (with a couple of extra arguments) that does all the heavy lifting, and it's called by all the "visible" functions, instead of multiplicating the code in all of them?

[mhammond]

I quite like these semantics, but I'm not clear on the b/w compat story. Although you added this as an "option", each call site is what determines this option.

In other words, I'd like to understand how your tests change if you do not ever specify that new bool.

[CristiFati]

I think that design-wise the correct behavior would be to always return None when there is no error (like calling the function with the (extra) bool set to true). But I am afraid that there is code relying on the fact that an exception is raised even if GetLastError returns 0, so I took the safe side, and I just added support for this behavior, because I think that changing it altogether might break some (external) things. As code is right now, nothing changes in all places that call PyWin_SetAPIError. If you think that changing default behavior wouldn't be a problem I can change that bool's default value (or remove it altogether (keeping the new behavior)).

[CristiFati]

Closing, as it was replaced by the 2 linked PRs.