[Python] Deprecate TObject __eq__ pythonization

The TObject `__eq__` pythonization calls `TObject::Equals()`, which by
default does a pointer comparison. That can be very confusing for Python
users.

Author: guitargeek

README/ReleaseNotes/v638/index.md

@@ -144,6 +144,14 @@ If you want to keep using `TList*` return values, you can write a small adapter
 
 ROOT dropped support for Python 3.8, meaning ROOT now requires at least Python 3.9.
 
+### Deprecation of the `TObject` equalily pythonization
+
+`TObject.__eq__` is deprecated and will be removed in ROOT 6.40.
+
+It forwards to `TObject::Equals()`, which uses pointer comparison if not overridden in derived classes.
+This may be confusing, because people expect value comparisons.
+Use Pythons `is` for pointer comparison, or request an implementation of `operator==` on the C++ side if you need value-based equality checks for a given class.
+
 ### Deprecate the attribute pythonization of `TDirectory` in favor of item-getting syntax
 
 Since ROOT 6.32, the recommended way to get objects from a `TFile` or any `TDirectory` in general is via `__getitem__`:

bindings/pyroot/pythonizations/python/ROOT/_pythonization/_tobject.py

@@ -13,6 +13,7 @@
 
 # Searching
 
+
 def _contains(self, o):
     # Relies on TObject::FindObject
     # Parameters:
@@ -22,26 +23,47 @@ def _contains(self, o):
     # - True if self contains o
     return bool(self.FindObject(o))
 
+
 # Comparison operators
 
+
+def _eq(self, o):
+    import warnings
+
+    warnings.warn(
+        "\nTObject.__eq__ is deprecated and will be removed in ROOT 6.40."
+        "\n\nIt forwards to TObject::Equals(), which uses pointer comparison if"
+        " not overridden in derived classes."
+        "\nThis may be confusing, because people expect value comparisons."
+        "\nUse Pythons `is` for pointer comparison, or request/implement"
+        " `operator==` on the C++ side if you need value-based equality checks.",
+        FutureWarning,
+        stacklevel=2,
+    )
+    return self._cpp_eq(o)
+
+
 def _lt(self, o):
     if isinstance(o, cppyy.gbl.TObject):
         return self.Compare(o) == -1
     else:
         return NotImplemented
 
+
 def _le(self, o):
     if isinstance(o, cppyy.gbl.TObject):
         return self.Compare(o) <= 0
     else:
         return NotImplemented
 
+
 def _gt(self, o):
     if isinstance(o, cppyy.gbl.TObject):
         return self.Compare(o) == 1
     else:
         return NotImplemented
 
+
 def _ge(self, o):
     if isinstance(o, cppyy.gbl.TObject):
         return self.Compare(o) >= 0
@@ -57,11 +79,14 @@ def pythonize_tobject():
 
     # Inject comparison operators
     AddTObjectEqNePyz(klass)
+    klass._cpp_eq = klass.__eq__
+    klass.__eq__ = _eq
     klass.__lt__ = _lt
     klass.__le__ = _le
     klass.__gt__ = _gt
     klass.__ge__ = _ge
 
+
 # Instant pythonization (executed at `import ROOT` time), no need of a
 # decorator. This is a core class that is instantiated before cppyy's
 # pythonization machinery is in place.