Introduce NonCons type and use Python ABCs to register classes

Author: brandonwillard

README.md

@@ -19,12 +19,11 @@ The `cons` package attempts to emulate the semantics of Lisp/Scheme's `cons` as
 
 >>> cons(1, [2, 3])
 [1, 2, 3]
-
->>> cons(1, "a string")
-ConsPair(1 'a string')
 ```
 
-According to `cons`, `None` corresponds to the empty built-in `list`:
+In general, `cons` is designed to work with `collections.abc.Sequence` types.
+
+According to the `cons` package, `None` corresponds to the empty built-in `list`, as `nil` does in some Lisps:
 ```python
 >>> cons(1, None)
 [1]
@@ -44,17 +43,26 @@ ConsError: Not a cons pair
 
 ```
 
+By default, `str` types are not considered cons-pairs, although they are sequences:
+```python
+>>> cons("a", "string")
+ConsPair('a' 'a string')
+```
+
+This setting can be overridden and other types can be similarly excluded from consideration by registering classes with the `abc`-based classes `MaybeCons` and `NonCons`.
+
+
 Features
 ===========
 
-* Support for the standard Python ordered collection types: i.e. `list`, `tuple`, `Iterator`, `OrderedDict`.
+* Built-in support for the standard Python ordered sequence types: i.e. `list`, `tuple`, `Iterator`, `OrderedDict`.
 ```python
 >>> from collections import OrderedDict
 >>> cons(('a', 1), OrderedDict())
 OrderedDict([('a', 1)])
 
 ```
-* Existing `cons` behavior is easy to change and new collections are straightforward to add through [`multipledispatch`][md].
+* Existing `cons` behavior can be changed and support for new collections can be added through the generic functions `cons.core._car` and `cons.core._cdr`.
 * Built-in support for [`unification`][un].
 ```python
 >>> from unification import unify, reify, var
@@ -78,5 +86,4 @@ pip install cons
 
 
 [cons]: https://en.wikipedia.org/wiki/Cons
-[md]: https://github.com/mrocklin/multipledispatch
 [un]: https://github.com/mrocklin/unification

cons/core.py

@@ -1,8 +1,9 @@
+from abc import ABCMeta, ABC, abstractmethod
 from functools import reduce
 from operator import length_hint
-from collections import OrderedDict
+from collections import OrderedDict, UserString
 from itertools import chain, islice
-from collections.abc import Iterator, Sequence, ItemsView
+from collections.abc import Iterator, Sequence, ItemsView, ByteString
 
 from multipledispatch import dispatch
 
@@ -23,15 +24,15 @@ class ConsError(ValueError):
     pass
 
 
-class ConsType(type):
+class ConsType(ABCMeta):
     def __instancecheck__(self, o):
         return (
             issubclass(type(o), (ConsPair, MaybeCons))
             and length_hint(o, 0) > 0
         )
 
 
-class ConsNullType(type):
+class ConsNullType(ABCMeta):
     def __instancecheck__(self, o):
         if o is None:
             return True
@@ -63,7 +64,9 @@ class ConsNull(metaclass=ConsNullType):
     is returned, and it signifies the uncertainty of the negative assertion.
     """
 
-    pass
+    @abstractmethod
+    def __init__(self):
+        pass
 
 
 class ConsPair(metaclass=ConsType):
@@ -137,7 +140,7 @@ def __eq__(self, other):
         )
 
     def __repr__(self):
-        return "{}({} {})".format(
+        return "{}({}, {})".format(
             self.__class__.__name__, repr(self.car), repr(self.cdr)
         )
 
@@ -148,15 +151,15 @@ def __str__(self):
 cons = ConsPair
 
 
-class MaybeConsType(type):
-    _ignored_types = (object, type(None), ConsPair, str)
-
+class MaybeConsType(ABCMeta):
     def __subclasscheck__(self, o):
-        return o not in self._ignored_types and any(
-            issubclass(o, d)
-            for d in cdr.funcs.keys()
-            if d not in self._ignored_types
-        )
+
+        if issubclass(o, tuple(_cdr.funcs.keys())) and not issubclass(
+            o, NonCons
+        ):
+            return True
+
+        return False
 
 
 class MaybeCons(metaclass=MaybeConsType):
@@ -172,21 +175,47 @@ class MaybeCons(metaclass=MaybeConsType):
     functions.
     """
 
-    pass
+    @abstractmethod
+    def __init__(self):
+        pass
+
+
+class NonCons(ABC):
+    """A class (and its subclasses) that is *not* considered a cons.
+
+    This type/class can be used as a means of excluding certain types from
+    consideration as a cons pair (i.e. via `NotCons.register`).
+    """
+
+    @abstractmethod
+    def __init__(self):
+        pass
+
+
+for t in (type(None), str, set, UserString, ByteString):
+    NonCons.register(t)
 
 
-@dispatch((type(None), str))
 def car(z):
-    raise ConsError("Not a cons pair")
+    if issubclass(type(z), ConsPair):
+        return z.car
+
+    try:
+        return _car(z)
+    except NotImplementedError:
+        raise ConsError("Not a cons pair")
 
 
-@car.register(ConsPair)
-def car_ConsPair(z):
-    return z.car
+@dispatch(Sequence)
+def _car(z):
+    try:
+        return first(z)
+    except StopIteration:
+        raise ConsError("Not a cons pair")
 
 
-@car.register(Iterator)
-def car_Iterator(z):
+@_car.register(Iterator)
+def _car_Iterator(z):
     """Return the first element in the given iterator.
 
     Warning: `car` necessarily draws from the iterator, and we can't do
@@ -201,48 +230,40 @@ def car_Iterator(z):
         raise ConsError("Not a cons pair")
 
 
-@car.register(Sequence)
-def car_Sequence(z):
-    try:
-        return first(z)
-    except StopIteration:
-        raise ConsError("Not a cons pair")
-
-
-@car.register(OrderedDict)
-def car_OrderedDict(z):
+@_car.register(OrderedDict)
+def _car_OrderedDict(z):
     if len(z) == 0:
         raise ConsError("Not a cons pair")
 
     return first(z.items())
 
 
-@dispatch((type(None), str))
 def cdr(z):
-    raise ConsError("Not a cons pair")
-
-
-@cdr.register(ConsPair)
-def cdr_ConsPair(z):
-    return z.cdr
+    if issubclass(type(z), ConsPair):
+        return z.cdr
 
-
-@cdr.register(Iterator)
-def cdr_Iterator(z):
-    if length_hint(z, 1) == 0:
+    try:
+        return _cdr(z)
+    except NotImplementedError:
         raise ConsError("Not a cons pair")
-    return rest(z)
 
 
-@cdr.register(Sequence)
-def cdr_Sequence(z):
+@dispatch(Sequence)
+def _cdr(z):
     if len(z) == 0:
         raise ConsError("Not a cons pair")
     return type(z)(rest(z))
 
 
-@cdr.register(OrderedDict)
-def cdr_OrderedDict(z):
+@_cdr.register(Iterator)
+def _cdr_Iterator(z):
+    if length_hint(z, 1) == 0:
+        raise ConsError("Not a cons pair")
+    return rest(z)
+
+
+@_cdr.register(OrderedDict)
+def _cdr_OrderedDict(z):
     if len(z) == 0:
         raise ConsError("Not a cons pair")
     return cdr(list(z.items()))

setup.cfg

@@ -1,3 +1,5 @@
 [tool:pytest]
+filterwarnings =
+    ignore:Using or importing the ABCs from 'collections':DeprecationWarning:unification.core
 python_files=test*.py
 testpaths=tests

setup.py

@@ -4,10 +4,9 @@
 
 setup(
     name="cons",
-    version="0.1.2",
+    version="0.1.3",
     install_requires=[
         'toolz',
-        'multipledispatch',
         'unification'
     ],
     packages=find_packages(exclude=['tests']),

tests/test_cons.py

@@ -8,7 +8,7 @@
 from unification import unify, reify, var
 
 from cons import cons, car, cdr
-from cons.core import ConsPair, MaybeCons, ConsNull, rest, ConsError
+from cons.core import ConsPair, MaybeCons, ConsNull, rest, ConsError, NonCons
 
 
 def assert_all_equal(*tests):
@@ -19,12 +19,33 @@ def _equal(x, y):
     reduce(_equal, tests)
 
 
+def test_noncons_type():
+
+    with pytest.raises(TypeError):
+        NonCons()
+
+    class MyStr(object):
+        pass
+
+    NonCons.register(MyStr)
+
+    assert issubclass(MyStr, NonCons)
+    assert not isinstance(MyStr, NonCons)
+    assert not issubclass(MyStr, MaybeCons)
+    assert not issubclass(ConsPair, NonCons)
+
+
 def test_cons_type():
+    with pytest.raises(TypeError):
+        MaybeCons()
+
     assert isinstance(cons(1, "hi"), ConsPair)
     assert isinstance((1, 2), ConsPair)
     assert isinstance([1, 2], ConsPair)
-    assert isinstance(OrderedDict({(1): 2}), ConsPair)
+    assert isinstance(OrderedDict({1: 2}), ConsPair)
     assert isinstance(iter([1]), ConsPair)
+
+    assert not isinstance({1: 2}, MaybeCons)
     assert not isinstance(cons(1, "hi"), MaybeCons)
     assert not isinstance({}, ConsPair)
     assert not isinstance(set(), ConsPair)
@@ -40,6 +61,10 @@ def test_cons_type():
 
 
 def test_cons_null():
+
+    with pytest.raises(TypeError):
+        ConsNull()
+
     assert isinstance(None, ConsNull)
     assert isinstance([], ConsNull)
     assert isinstance(tuple(), ConsNull)
@@ -91,8 +116,8 @@ def test_cons_join():
     assert cons("a", cons("b", "c")).cdr == cons("b", "c")
 
 
-def test_cons_tr():
-    assert repr(cons(1, 2)) == "ConsPair(1 2)"
+def test_cons_str():
+    assert repr(cons(1, 2)) == "ConsPair(1, 2)"
     assert str(cons(1, 2, 3)) == "(1 . (2 . 3))"
 
 
@@ -128,7 +153,11 @@ def test_car_cdr():
     with pytest.raises(ConsError):
         cdr(OrderedDict())
 
+    assert car([1, 2]) == 1
+    assert cdr([1, 2]) == [2]
+
     assert car(cons("a", "b")) == "a"
+
     z = car(cons(iter([]), 1))
     expected = iter([])
     assert type(z) == type(expected)