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/__init__.py

@@ -1,6 +1,11 @@
 """Algebras define the specific superposition and (un)binding operations."""
 
-from .base import AbstractAlgebra, CommonProperties, ElementSidedness
+from .base import (
+    AbstractAlgebra,
+    CommonProperties,
+    ElementSidedness,
+    supports_sidedness,
+)
 from .hrr_algebra import HrrAlgebra, HrrProperties
 from .tvtb_algebra import TvtbAlgebra, TvtbProperties
 from .vtb_algebra import VtbAlgebra, VtbProperties

nengo_spa/algebras/base.py

@@ -11,6 +11,54 @@ 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
+    -------
+
+    >>> from nengo_spa.algebras import (
+    ...     AbstractAlgebra, ElementSidedness, supports_sidedness
+    ... )
+    >>> class MyAlgebra(AbstractAlgebra):
+    ...     @supports_sidedness({ElementSidedness.LEFT})
+    ...     def invert(self, v, sidedness):
+    ...         # ...
+    ...         pass
+    ...
+    ...     # ...
+    ...
+    >>> 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):