TreeItemData doc suggestions

[raf]

Hi,

I was using (classic) TreeCtrl.SetPyData() with the data being a lambda function.
I received a deprecation warning:

app.py:2010: wxPyDeprecationWarning: Call to deprecated item. Use SetItemData instead.
self.tree.SetPyData(tree_item, callable)

Looking it up at:

https://wxpython.org/Phoenix/docs/html/wx.TreeCtrl.html#wx.TreeCtrl.SetItemData

I see this signature:

SetItemData(self, item: TreeItemId, data: TreeItemData)

But the TreeItemData isn't a hyperlink. Similarly, at:

https://wxpython.org/Phoenix/docs/html/wx.TreeCtrl.html

There is a See Also list containing TreeItemData but it's the only
item in the list that isn't a hyperlink.

So I looked at:

https://wxpython.org/Phoenix/docs/html/treectrl_overview.html

And saw that the data parameter to SetItemData needs to be an
object of a class derived from TreeItemData which only needs
the GetId() method that returns the item's id [even though the
tree item itself has a GetID method - inconsistent but OK].

So I tried:

class TID(wx.TreeItemData):
def __init__(self, item, data):
self.item = item
self.data = data
def GetId(self):
return self.item.GetID()

and:

self.tree.SetItemData(tree_item, TID(tree_item, callable))

But then I got this error:

Traceback (most recent call last):
File "app.py", line 1277, in <module>
class TID(TreeItemData):
TypeError: function() argument 'code' must be code, not str

I'm really starting to suspect that TreeItemData isn't a class,
so I print it out its representation and see:

TreeItemData <function deprecated.<locals>.deprecated_func at 0x1322e1300>

Since it looks like TreeItemData is a function rather than a class,
I tried to execute it:

Python 3.12.9 (main, Feb 8 2025, 11:05:42) [Clang 10.0.1 (clang-1001.0.46.4)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import wx
>>> wx.TreeItemData()
<stdin>:1: wxPyDeprecationWarning: Call to deprecated item. The TreeItemData class no longer exists, just pass your object directly to the tree instead.
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/opt/local/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/wx/core.py", line 82, in deprecated_func
return item(*args)
^^^^^^^^^^^
TypeError: TreeItemData() missing 1 required positional argument: 'data'
>>> wx.TreeItemData('data')
'data'

So it looks like it's a function that takes 1 parameter and returns it.
But it gives a deprecation warning only when no arguments are supplied.
And it gives a wierd error when used as a base class, which is the documented
way to use it. So I don't think the deprecation message happens when
it's used as documented.

It look a lot of fiddling to get the deprecation warning, which, once seen,
is very helpful. But it would be great if the documentation could be updated
to stop mentioning TreeItemData altogether.

Or possibly better, maybe something could be done to make the deprecation warning
happen when TreeItemData is used as a base class (as documented).

Or maybe the TreeItemData page could be put back stating that it's deprecated.

Basically, whatever the easiest way to make the helpful deprecation message
appear sooner without so much digging would be great.

cheers,
raf