[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` equality 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/_tfile.py

@@ -90,7 +90,7 @@ def _TFileOpen(klass, *args):
     # klass: TFile class
     # *args: arguments passed to the constructor
     f = klass._OriginalOpen(*args)
-    if f == ROOT.bind_object(0, klass):
+    if not f:
         # args[0] can be either a string or a TFileOpenHandle
         raise OSError('Failed to open file {}'.format(str(args[0])))
     return f

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.

main/python/cmdLineUtils.py

@@ -195,11 +195,9 @@ def isDirectoryKey(key):
     """
     Return True if the object, corresponding to the key, inherits from TDirectory
     """
-    import cppyy
-
     classname = key.GetClassName()
     cl = ROOT.gROOT.GetClass(classname)
-    if cl == cppyy.nullptr:
+    if not cl:
         logging.warning("Unknown class to ROOT: " + classname)
         return False
     return cl.InheritsFrom(ROOT.TDirectory.Class())
@@ -209,11 +207,9 @@ def isTreeKey(key):
     """
     Return True if the object, corresponding to the key, inherits from TTree
     """
-    import cppyy
-
     classname = key.GetClassName()
     cl = ROOT.gROOT.GetClass(classname)
-    if cl == cppyy.nullptr:
+    if not cl:
         logging.warning("Unknown class to ROOT: " + classname)
         return False
     return cl.InheritsFrom(ROOT.TTree.Class())
@@ -223,11 +219,9 @@ def isTHnSparseKey(key):
     """
     Return True if the object, corresponding to the key, inherits from THnSparse
     """
-    import cppyy
-
     classname = key.GetClassName()
     cl = ROOT.gROOT.GetClass(classname)
-    if cl == cppyy.nullptr:
+    if not cl:
         logging.warning("Unknown class to ROOT: " + classname)
         return False
     return cl.InheritsFrom(ROOT.THnSparse.Class())