Update doc for equalsNotEquals

Author: joefarebrother

python/ql/src/Classes/Comparisons/EqualsOrNotEquals.qhelp

@@ -4,33 +4,47 @@
 <qhelp>
 
 <overview>
-<p>In order to conform to the object model, classes should define either no equality methods, or both 
-an equality and an inequality method. If only one of <code>__eq__</code> or <code>__ne__</code> is 
-defined then the method from the super class is used. This is unlikely to result in the expected 
-behavior.</p>
+<p>In order to ensure the <code>==</code> and <code>!=</code> operators behave consistently as expected (i.e. they should be negations of each other), care should be taken when implementing the 
+<code>__eq__</code> and <code>__ne__</code> special methods.</p>
+
+<p>In Python 3, if the <code>__eq__</code> method is defined in a class while the <code>__ne__</code> is not, 
+then the <code>!=</code> operator will automatically delegate to the <code>__eq__</code> method in the expected way. 
+ </p>
+
+ <p>However, if the <code>__ne__</code> method is defined without a corresponding <code>__eq__</code> method, 
+ the <code>==</code> operator will still default to object identity (equivalent to the <code>is</code> operator), while the <code>!=</code>
+ operator will use the <code>__ne__</code> method, which may be inconsistent.
+
+<p>Additionally, if the <code>__ne__</code> method is defined on a superclass, and the subclass defines its own <cde>__eq__</code> method without overriding
+the superclass <code>__ne__</code> method, the <code>!=</code> operator will use this superclass <code>__ne__</code> method, rather than automatically delegating
+to <code>__eq__</code>, which may be incorrect.
 
 </overview>
 <recommendation>
 
-<p>When you define an equality or an inequality method for a class, remember to implement both an 
-<code>__eq__</code> method and an <code>__ne__</code> method.</p>
+<p>Ensure that when an <code>__ne__</code> method is defined, the <code>__eq__</code> method is also defined, and their results are consistent.
+In most cases, the <code>__ne__</code> method does not need to be defined at all, as the default behavior is to delegate to <code>__eq__</code> and negate the result. </p>
 
 </recommendation>
 <example>
-<p>In the following example the <code>PointOriginal</code> class defines an equality method but 
-no inequality method. If this class is tested for inequality then a type error will be raised. The 
-<code>PointUpdated</code> class is better as it defines both an equality and an inequality method. To
-comply fully with the object model this class should also define a hash method (identified by
-a separate rule).</p>
+<p>In the following example, <code>A</code> defines a <code>__ne__</code> method, but not an <code>__eq__</code> method.
+This leads to inconsistent results between equality and inequality operators. 
+</p>
+
+<sample src="examples/EqualsOrNotEquals1.py" />
+
+<p>In the following example, <code>C</code> defines an <code>__eq__</code> method, but its <code>__ne__</code> implementation is inherited from <code>B</code>, 
+which is not consistent with the equality operation.
+</p>
 
-<sample src="EqualsOrNotEquals.py" />
+<sample src="examples/EqualsOrNotEquals2.py" />
 
 </example>
 <references>
 
 
-<li>Python Language Reference: <a href="http://docs.python.org/2/reference/datamodel.html#object.__ne__">object.__ne__</a>, 
-<a href="http://docs.python.org/2/reference/expressions.html#comparisons">Comparisons</a>.</li>
+<li>Python Language Reference: <a href="http://docs.python.org/3/reference/datamodel.html#object.__ne__">object.__ne__</a>, 
+<a href="http://docs.python.org/3/reference/expressions.html#comparisons">Comparisons</a>.</li>
 
 
 </references>

python/ql/src/Classes/Comparisons/IncompleteOrdering.qhelp

@@ -17,7 +17,8 @@ If the ordering is not consistent with default equality, then <code>__eq__</code
   </p>
 
 <p>
-The <code>functools.total_ordering</code> class decorator can be used to automatically implement all four comparison methods from a single one,
+The <code>functools.total_ordering</code> class decorator can be used to automatically implement all four comparison methods from a 
+single one,
 which is typically the cleanest way to ensure all necessary comparison methods are implemented consistently.</p>
 
 </recommendation>

python/ql/src/Classes/Comparisons/examples/EqualsOrNotEquals.py

@@ -0,0 +1,15 @@
+class A:
+    def __init__(self, a):
+        self.a = a 
+
+    # BAD: ne is defined, but not eq.
+    def __ne__(self, other):
+        if not isinstance(other, A):
+            return NotImplemented 
+        return self.a != other.a
+
+x = A(1)
+y = A(1)
+
+print(x == y) # Prints False (potentially unexpected - object identity is used)
+print(x != y) # Prints False

python/ql/src/Classes/Comparisons/examples/EqualsOrNotEquals1.py

@@ -0,0 +1,21 @@
+class B:
+    def __init__(self, b):
+        self.b = b 
+    
+    def __eq__(self, other):
+        return self.b == other.b 
+    
+    def __ne__(self, other):
+        return self.b != other.b 
+    
+class C(B):
+    def __init__(self, b, c):
+        super().init(b)
+        self.c = c 
+
+    # BAD: eq is defined, but != will use superclass ne method, which is not consistent
+    def __eq__(self, other):
+        return self.b == other.b and self.c == other.c 
+    
+print(C(1,2) == C(1,3)) # Prints False 
+print(C(1,2) != C(1,3)) # Prints False (potentially unexpected)