Use xfail instead of silently passing tests

This makes it more clear when certain features are not supported by an
algebra.

To be able to use xfail, this adds a mechanism to declare what sidedness
values are supported by specfic algebra operations. This mechanism is
a decorator which adds an attribute with the allowed sidedness values to
the method object.

Closes #281.

CHANGES.rst

@@ -33,6 +33,11 @@ Release History
   vector generators.
   (`#284 <https://github.com/nengo/nengo_spa/issues/284>`__,
   `#285 <https://github.com/nengo/nengo_spa/pull/285>`__)
+- ``supports_sidedness`` decorator that can be used in algebras to define what
+  ``ElementSidedness`` values are allowed for an operation. This information can
+  then be retrieved from the respective methods.
+  (`#281 <https://github.com/nengo/nengo_spa/issues/281>`__,
+  `#291 <https://github.com/nengo/nengo_spa/pull/291>`__)
 
 **Removed**
 

docs/modules/nengo_spa.algebras.rst

@@ -10,6 +10,7 @@ The following items are re-exported by :mod:`nengo_spa.algebras`:
    base.AbstractAlgebra
    base.CommonProperties
    base.ElementSidedness
+   base.supports_sidedness
    hrr_algebra.HrrAlgebra
    hrr_algebra.HrrProperties
    vtb_algebra.VtbAlgebra

nengo_spa/algebras/base.py

@@ -11,6 +11,50 @@ class ElementSidedness(Enum):
     TWO_SIDED = "two-sided"
 
 
+def supports_sidedness(sidedness):
+    """Declare supported sidedness values on an operation.
+
+    This decorator can be used with methods in an algebra that take a
+    *sidedness* parameter. It declares which values of *sidedness* are
+    supported by the algebra. The valid values are added as a *frozenset* as
+    a *supported_sidedness* attribute on the method.
+
+    When checking for supported sidedness, it must first be checked whether
+    the *supported_sidedness* attribute exists (for backwards compatibility).
+    If it does not exist, it should be assumed that all values for *sidedness*
+    are supported.
+
+    Parameters
+    ----------
+    sidedness: Iterable[ElementSidedness]
+        The sidedness values that are supported by the annotated method.
+
+    Returns
+    -------
+    function
+        The method itself with the *supported_sidedness* attribute added.
+
+    Examples
+    -------
+
+    >>> class MyAlgebra(AbstractAlgebra):
+    >>>     @supports_sidedness({ElementSidedness.LEFT})
+    >>>     def invert(self, v, sidedness):
+    >>>         # ...
+    >>>
+    >>>     # ...
+    >>>
+    >>> print(MyAlgebra.invert.supported_sidedness)
+    frozenset({<ElementSidedness.LEFT: 'left'>})
+    """
+
+    def decorator(fn):
+        setattr(fn, "supported_sidedness", frozenset(sidedness))
+        return fn
+
+    return decorator
+
+
 class _DuckTypedABCMeta(ABCMeta):
     def __instancecheck__(cls, instance):
         if super().__instancecheck__(instance):