Type stub improvements

[lojack5]

Follow up to #2468 , addressing issues brought up in #2665 and #2666 . (I finally figured out my problem with running etg without --nodoc, so now I can finally test the doc building warnings).

Issues addressed:

• sphinx generator "SEVERE" warnings during signature validation:
  • Over-aggressive C++ syntax removal (ex: constraint -> raint) no longer happens.
  • Special case handle parameters named _from, _is, and _def (Python reserved keywords)
  • Most other warnings are handled by correctly factoring in (and removing) that the type-hints are present in the args string.
• __bool__ returning int: Special case handling done in the writing of the method. I'm not sure why we can't just change the definition in the sip file, but sip complains that it must return an int.
• None allowed for parent argument on TopLevelWindow subclasses.
• Marks values coming from #define directives which are boolean as bool.
• Properties declared using the variable = property(<getter>, <setter>) syntax not being seen as the applicable type. This is a typeshed issue (and not one easily solve). Addressed by using decorator syntax when a getter and type-hints are present on the getter and/or setter (setter-only properties still have to use the variable = property(fset=<setter>) syntax.
• sphinx generator warning for SetAssertMode. The clean-name code was inappropriately removing applying the "remove wx prefix" code to argument names:

==> Function/Method signature from `extractors`: SetAssertMode(AppAssertMode : AppAssertMode)
==> Parameter list from wxWidgets XML items:     ['wxAppAssertMode']

• wx.DateTime accepts datetime.datetime and datetime.date objects in its constructor. Similarly, wx.Point, wx.Size, and other similar automated conversions are handled.

Things I'd like extra eyes on:

• None for parent argument: Are any of the changed type-stubs incorrect in allowing None there? Are there any missing?
• Help with potentially addressing the wx.DateTime typing.

Closes #2665
Closes #2666

[swt2c]

Thanks a lot @lojack5 this looks good.

As far as the wx.DateTime issue goes, I think it's basically anywhere where a wx.DateTime can be passed as a parameter to the C++ side, a datetime.datetime or datetime.date can also be passed. Does that help with figuring out a place to do it?

[lojack5]

Maybe.

Does the conversion added happen anywhere a wx.DateTime is accepted as an input to any method, or only wx.DateTime method? For example does the conversion happen on wx.adv.CalendarCtrl.__init__'s date parameter? If so I might be able to do something with that. If not, then it's a lot more special casing that it might be pretty hard to get right.

If so, I could probably do something like:

DateTimeT: TypeAlias = Union[wx.DateTime, datetime.datetime, datetime.date]

Then wx.DateTime -> DateTimeT for input argument annotations only (ie, be careful not to do this replacement on return type annotations, etc).

Follow on, should something similar be done for wx.Point, wx.Size, and wx.Colour?. Like:

PointT: TypeAlias = Union[wx.Point, tuple[int, int]]
SizeT: TypeAlias = Union[wx.Size, tuple[int, int]]
ColourT: TypeAlias = Union[wx.Colour, tuple[int, int, int], tuple[int, int, int, int], str]

[echoix]

Note that typealias should come from typing_extensions for Python 3.9 (minimum supported version here), as it was only introduced in 3.10.

It's possible to use type aliases on Python 3.9, just without using the semicolon and TypeAlias, and directly using equal the thing it is aliasing.

[lojack5]

And yes, typing_extensions is already required for < Python 3.10.

[echoix]

What started my interest in improving wxPython typing a couple weeks ago was specifically because of the typing for Point and Size. So I'm interested in any improvement for that.

I remember trying hard to find where the conversion from class to tuple happens, but it wasn't clear yet.
This is close to the behaviour I was looking for

Phoenix/src/wxpy_api.sip

Line 487 in c3092be

// can be created from a sequence of numbers, such as wx.Point, wx.Colour,

Phoenix/etg/gdicmn.py

Lines 243 to 252 in c3092be

	# Because of our add-ons that make wx.Point and wx.Size act like 2-element
	# sequences, and also the typecheck code that allows 2-element sequences, then
	# we end up with a bit of confusion about the (Point,Point) and the
	# (Point,Size) overloads of the wx.Rect constructor. The confusion can be
	# dealt with by using keyword args, but I think that the (Point,Size) version
	# will be used more, so reorder the overloads so it is found first.
	m = module.find('wxRect.wxRect')
	mo = m.findOverload('topLeft')
	del m.overloads[m.overloads.index(mo)]
	m.overloads.append(mo)

[lojack5]

They're in the sip generating files as far as I can tell:

• Colour:

  Phoenix/etg/colour.py

  Line 195 in c3092be

  c.convertFromPyObject = """\

• Position:

  Phoenix/etg/position.py

  Line 37 in c3092be

  c.convertFromPyObject = tools.convertTwoIntegersTemplate('wxPosition')

• Point:

  Phoenix/etg/gdicmn.py

  Line 104 in c3092be

  c.convertFromPyObject = tools.convertTwoIntegersTemplate('wxPoint')

• Size:

  Phoenix/etg/gdicmn.py

  Line 181 in c3092be

  c.convertFromPyObject = tools.convertTwoIntegersTemplate('wxSize')

• Rect:

  Phoenix/etg/gdicmn.py

  Line 262 in c3092be

  c.convertFromPyObject = tools.convertFourIntegersTemplate('wxRect')

• RealPoint:

  Phoenix/etg/gdicmn.py

  Line 325 in c3092be

  c.convertFromPyObject = tools.convertTwoDoublesTemplate('wxRealPoint')

So I guess adding things for all of these is on the table. I'll see if there's a more general way to do this, instead of hard-coding all of them.

[swt2c]

Maybe.

Does the conversion added happen anywhere a wx.DateTime is accepted as an input to any method, or only wx.DateTime method? For example does the conversion happen on wx.adv.CalendarCtrl.__init__'s date parameter? If so I might be able to do something with that. If not, then it's a lot more special casing that it might be pretty hard to get right.

Yes, it does. Passing datetime.date to wx.adv.CalendarCtrl works.

[lojack5]

Gotcha, I'll start working on a solution that should encompass all types with a .convertFromPyObject attribute. I did a quick glance through and it doesn't seem anything uses the similar-but-reversed .convertToPyObject.

[lojack5]

Ok, I'm ready for review of this. In particular if @timrid can find anymore edge cases to fixup, now would be a great time to find them :). Otherwise, I'm pretty sure this handles most cases correctly now. There are still some edge cases I found that aren't exactly easy to fix, but from what I can tell they are on rarely used interfaces.

Still would like a yes/no on the None for parent changes, just a look though to make sure classes that have parent marked as Optional[...] do in fact accept a None for that argument.

[lojack5]

Oh, actually there were two points I was unsure about:
wx.InputStream and wx.OutputStream both have a .convertFromPyObject set on them, although the comments in the cpp code there ask if this is only a type-check. I couldn't find precise documentation on exactly what python type would be deemed acceptable as an automated conversion here. Is it a specific python type? Or is it a more general "file-like" object - ie: supports a specific interface, like "must have read, tell, and seek? Possibly something that I could solve with a typing.Protocol type-hint there.

[timrid]

I downloaded the wxPython-wheel-win64-py3.13-x64 wheel from https://github.com/wxWidgets/Phoenix/actions/runs/12824937831 and tested it in my codebase. My findings:

1. wx.Yield(), wx.MessageBox(...) and many more should have no self parameter.
   

2. In wx.Menu() the Method DestroyItem is missing. It was renamed to Destroy, but the comment is still correct:
   

3. In wx.ComboBox() there is a similar problem with GetTextSelection that is renamed to GetSelection:
   

4. Missing GetClientData() in wx.Choice(), wx.ListBox(), ... because it is missing in wx.ItemContainer()
   

5. I could not see any problem with parent set to None any more :)

[lojack5]

Thanks, I know what's happening with the functions (vs methods) - I can fix that quickly. The others, not so sure why they're getting renamed, so I'll have to look into that.

[lojack5]

Ok, those should be sorted now if you want to take another whirl at it (once the CI jobs complete).

The only one I couldn't reproduce was 3):
type-stub for ListBox:

and for ItemContainer:

[lojack5]

Also - I take back everything else working as intended - types that are automatically converted are only partially covered, because each generating file is fired up in a separate Python instance, meaning for example the wx.Point -> wx.Point | tuple[int, int] conversion only happens in the the generating file that defines wx.Point itself. This one might be tricky, because I need the scripts to remember these conversions between instances of it running.

[lojack5]

Sorry for the delay on this was having some computer issues (frequent BSOD) that I had to fix. Should get back into finishing this up.