shr: add ElementProxy.__eq__()

Steve Canny · Steve Canny · commit 71f4d031f80f · 2014-12-27T22:07:12.000-08:00
diff --git a/docx/shared.py b/docx/shared.py
@@ -164,6 +164,37 @@ def write_only_property(f):
     return property(fset=f, doc=docstring)
 
 
+class ElementProxy(object):
+    """
+    Base class for lxml element proxy classes. An element proxy class is one
+    whose primary responsibilities are fulfilled by manipulating the
+    attributes and child elements of an XML element. They are the most common
+    type of class in python-docx other than custom element (oxml) classes.
+    """
+
+    __slots__ = ('_element',)
+
+    def __init__(self, element):
+        self._element = element
+
+    def __eq__(self, other):
+        """
+        Return |True| if this proxy object refers to the same oxml element as
+        does *other*. ElementProxy objects are value objects and should
+        maintain no mutable local state. Equality for proxy objects is
+        defined as referring to the same XML element, whether or not they are
+        the same proxy object instance.
+        """
+        if not isinstance(other, ElementProxy):
+            return False
+        return self._element is other._element
+
+    def __ne__(self, other):
+        if not isinstance(other, ElementProxy):
+            return True
+        return self._element is not other._element
+
+
 class Parented(object):
     """
     Provides common services for document elements that occur below a part
diff --git a/tests/test_shared.py b/tests/test_shared.py
@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+"""
+Test suite for the docx.shared module
+"""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+import pytest
+
+from docx.shared import ElementProxy
+
+from .unitutil.cxml import element
+
+
+class DescribeElementProxy(object):
+
+    def it_knows_when_its_equal_to_another_proxy_object(self, eq_fixture):
+        proxy, proxy_2, proxy_3, not_a_proxy = eq_fixture
+
+        assert (proxy == proxy_2) is True
+        assert (proxy == proxy_3) is False
+        assert (proxy == not_a_proxy) is False
+
+        assert (proxy != proxy_2) is False
+        assert (proxy != proxy_3) is True
+        assert (proxy != not_a_proxy) is True
+
+    # fixture --------------------------------------------------------
+
+    @pytest.fixture
+    def eq_fixture(self):
+        p, q = element('w:p'), element('w:p')
+        proxy = ElementProxy(p)
+        proxy_2 = ElementProxy(p)
+        proxy_3 = ElementProxy(q)
+        not_a_proxy = 'Foobar'
+        return proxy, proxy_2, proxy_3, not_a_proxy
