Remove cons_merge generic function and implement cons types

This also fixes some broken cons semantics (e.g. `cons("a", cons("b", "c"))` is
*not* `cons(["a", "b"], "c")`) and introduces a `ConsError` exception.

Author: brandonwillard

README.md

@@ -35,12 +35,12 @@ The `cons` package follows Scheme-like semantics for empty sequences:
 >>> car([])
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
-TypeError: Not a cons pair
+ConsError: Not a cons pair
 
 >>> cdr([])
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
-TypeError: Not a cons pair
+ConsError: Not a cons pair
 
 ```
 

cons/core.py

@@ -1,18 +1,69 @@
 from functools import reduce
-from itertools import chain
 from operator import length_hint
 from collections import OrderedDict
-from collections.abc import Iterator
+from itertools import chain, islice
+from collections.abc import Iterator, Sequence, ItemsView
 
 from multipledispatch import dispatch
 
 from toolz import last, first
-from toolz.itertoolz import rest
+
+# We can't use this because `islice` drops __length_hint__ info.
+# from toolz.itertoolz import rest
+
+
+def rest(seq):
+    if isinstance(seq, Iterator) and length_hint(seq, 2) <= 1:
+        return iter([])
+    else:
+        return islice(seq, 1, None)
+
+
+class ConsError(ValueError):
+    pass
 
 
 class ConsType(type):
     def __instancecheck__(self, o):
-        return is_cons(o)
+        return (
+            issubclass(type(o), (ConsPair, MaybeCons))
+            and length_hint(o, 0) > 0
+        )
+
+
+class ConsNullType(type):
+    def __instancecheck__(self, o):
+        if o is None:
+            return True
+        elif issubclass(type(o), MaybeCons):
+            lhint = length_hint(o, -1)
+            if lhint == 0:
+                return True
+            elif lhint > 0:
+                return False
+            else:
+                return None
+        else:
+            return False
+
+
+class ConsNull(metaclass=ConsNullType):
+    """A class used to indicate a Lisp/cons-like null.
+
+    A "Lisp-like" null object is one that can be used as a `cdr` to produce a
+    non-`ConsPair` collection (e.g. `None`, `[]`, `()`, `OrderedDict`, etc.)
+
+    It's important that this function be used when considering an arbitrary
+    object as the terminating `cdr` for a given collection (e.g. when unifying
+    `cons` objects); otherwise, fixed choices for the terminating `cdr`, such
+    as `None` or `[]`, will severely limit the applicability of the
+    decomposition.
+
+    Also, for relevant collections with no concrete length information, `None`
+    is returned, and it signifies the uncertainty of the negative assertion.
+    """
+
+    pass
 
 
 class ConsPair(metaclass=ConsType):
@@ -41,18 +92,40 @@ def __new__(cls, *parts):
         elif len(parts) == 2:
             car_part = first(parts)
             cdr_part = last(parts)
-            try:
-                res = cons_merge(car_part, cdr_part)
-            except NotImplementedError:
+
+            if cdr_part is None:
+                cdr_part = []
+
+            if isinstance(
+                cdr_part, (ConsNull, ConsPair, Iterator)
+            ) and not issubclass(type(cdr_part), ConsPair):
+                res = cls.cons_merge(car_part, cdr_part)
+            else:
                 instance = super(ConsPair, cls).__new__(cls)
                 instance.car = car_part
                 instance.cdr = cdr_part
                 res = instance
+
         else:
             raise ValueError("Number of arguments must be greater than 2.")
 
         return res
 
+    @classmethod
+    def cons_merge(cls, car_part, cdr_part):
+
+        if isinstance(cdr_part, OrderedDict):
+            cdr_part = cdr_part.items()
+
+        res = chain((car_part,), cdr_part)
+
+        if isinstance(cdr_part, ItemsView):
+            res = OrderedDict(res)
+        elif not isinstance(cdr_part, Iterator):
+            res = type(cdr_part)(res)
+
+        return res
+
     def __hash__(self):
         return hash([self.car, self.cdr])
 
@@ -75,74 +148,78 @@ def __str__(self):
 cons = ConsPair
 
 
-@dispatch(object, type(None))
-def cons_merge(car_part, cdr_part):
-    """Merge a generic car and cdr.
-
-    This is the base/`nil` case with `cdr` `None`; it produces a standard list.
-    """
-    return [car_part]
-
-
-@cons_merge.register(object, ConsPair)
-def cons_merge_ConsPair(car_part, cdr_part):
-    """Merge a car and a `ConsPair` cdr."""
-    return ConsPair([car_part, car(cdr_part)], cdr(cdr_part))
+class MaybeConsType(type):
+    _ignored_types = (object, type(None), ConsPair, str)
 
+    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
+        )
 
-@cons_merge.register(object, Iterator)
-def cons_merge_Iterator(car_part, cdr_part):
-    """Merge a car and an `Iterator` cdr."""
-    return chain([car_part], cdr_part)
 
+class MaybeCons(metaclass=MaybeConsType):
+    """A class used to dynamically determine potential cons types from
+    non-ConsPairs.
 
-@cons_merge.register(object, (list, tuple))
-def cons_merge_list_tuple(car_part, cdr_part):
-    """Merge a car with a list or tuple cdr."""
-    return type(cdr_part)([car_part]) + cdr_part
+    For example,
 
+        issubclass(tuple, MaybeCons) is True
+        issubclass(ConsPair, MaybeCons) is False
 
-@cons_merge.register((list, tuple), OrderedDict)
-def cons_merge_OrderedDict(car_part, cdr_part):
-    """Merge a list/tuple car with a dict cdr."""
-    if hasattr(cdr_part, "move_to_end"):
-        cdr_part.update([car_part])
-        cdr_part.move_to_end(first(car_part), last=False)
-    else:
-        cdr_part = OrderedDict([car_part] + list(cdr_part.items()))
+    The potential cons types are drawn from the implemented `cdr` dispatch
+    functions.
+    """
 
-    return cdr_part
+    pass
 
 
-@dispatch(type(None))
+@dispatch((type(None), str))
 def car(z):
-    raise TypeError("Not a cons pair")
+    raise ConsError("Not a cons pair")
 
 
 @car.register(ConsPair)
 def car_ConsPair(z):
     return z.car
 
 
-@car.register((list, tuple, Iterator))
+@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
+    much--within this function--to make copies (e.g. with `tee`) that will
+    appropriately replace the original iterator.
+    Callers must handle this themselves.
+    """
     try:
+        # z, _ = tee(z)
         return first(z)
     except StopIteration:
-        raise TypeError("Not a cons pair")
+        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):
     if len(z) == 0:
-        raise TypeError("Not a cons pair")
+        raise ConsError("Not a cons pair")
 
     return first(z.items())
 
 
-@dispatch(type(None))
+@dispatch((type(None), str))
 def cdr(z):
-    raise TypeError("Not a cons pair")
+    raise ConsError("Not a cons pair")
 
 
 @cdr.register(ConsPair)
@@ -153,69 +230,19 @@ def cdr_ConsPair(z):
 @cdr.register(Iterator)
 def cdr_Iterator(z):
     if length_hint(z, 1) == 0:
-        raise TypeError("Not a cons pair")
+        raise ConsError("Not a cons pair")
     return rest(z)
 
 
-@cdr.register((list, tuple))
-def cdr_list_tuple(z):
+@cdr.register(Sequence)
+def cdr_Sequence(z):
     if len(z) == 0:
-        raise TypeError("Not a cons pair")
-    return type(z)(list(rest(z)))
+        raise ConsError("Not a cons pair")
+    return type(z)(rest(z))
 
 
 @cdr.register(OrderedDict)
 def cdr_OrderedDict(z):
     if len(z) == 0:
-        raise TypeError("Not a cons pair")
+        raise ConsError("Not a cons pair")
     return cdr(list(z.items()))
-
-
-def is_cons(a):
-    """Determine if an object is the result of a `cons`.
-
-    This is automatically determined by the accepted `cdr` types for each
-    `cons_merge` implementation, since any such implementation implies that
-    `cons` can construct that type.
-    """
-    return issubclass(type(a), ConsPair) or (
-        any(
-            isinstance(a, d)
-            for _, d in cons_merge.funcs.keys()
-            if d not in (object, ConsPair)
-        )
-        and length_hint(a, 0) > 0
-    )
-
-
-def is_null(a):
-    """Check if an object is a "Lisp-like" null.
-
-    A "Lisp-like" null object is one that can be used as a `cdr` to produce a
-    non-`ConsPair` collection (e.g. `None`, `[]`, `()`, `OrderedDict`, etc.)
-
-    It's important that this function be used when considering an arbitrary
-    object as the terminating `cdr` for a given collection (e.g. when unifying
-    `cons` objects); otherwise, fixed choices for the terminating `cdr`, such
-    as `None` or `[]`, will severely limit the applicability of the
-    decomposition.
-
-    Also, for relevant collections with no concrete length information, `None`
-    is returned, and it signifies the uncertainty of the negative assertion.
-    """
-    if a is None:
-        return True
-    elif any(
-        isinstance(a, d)
-        for d, in cdr.funcs.keys()
-        if not issubclass(d, (ConsPair, type(None)))
-    ):
-        lhint = length_hint(a, -1)
-        if lhint == 0:
-            return True
-        elif lhint > 0:
-            return False
-        else:
-            return None
-    else:
-        return False

cons/unify.py

@@ -1,33 +1,35 @@
-from collections import OrderedDict
-from collections.abc import Iterator
+from itertools import tee
+from collections import OrderedDict, Iterator
 
 from unification.core import unify, _unify, reify, _reify
 
-from .core import is_cons, car, cdr, ConsPair, cons
+from .core import car, cdr, ConsPair, cons, MaybeCons, ConsError
 
 
-# Unfortunately, `multipledispatch` doesn't use `isinstance` on the arguments,
-# so it won't use our fancy setup for `isinstance(x, ConsPair)` and we have to
-# specify--and check--each `cons`-amenable type explicitly.
 def _cons_unify(lcons, rcons, s):
 
-    if not is_cons(lcons) or not is_cons(rcons):
-        # One of the arguments is necessarily a `ConsPair` object,
-        # but the other could be an empty iterable, which isn't a
-        # `cons`-derivable object.
-        return False
+    lcons_ = lcons
+    rcons_ = rcons
+
+    if isinstance(lcons, Iterator):
+        lcons, lcons_ = tee(lcons)
+
+    if isinstance(rcons, Iterator):
+        rcons, rcons_ = tee(rcons)
+
+    try:
+        s = unify(car(lcons), car(rcons), s)
+
+        if s is not False:
+            return unify(cdr(lcons_), cdr(rcons_), s)
+    except ConsError:
+        pass
 
-    s = unify(car(lcons), car(rcons), s)
-    if s is not False:
-        return unify(cdr(lcons), cdr(rcons), s)
     return False
 
 
-_unify.add(
-    (ConsPair, (ConsPair, list, tuple, Iterator, OrderedDict), dict),
-    _cons_unify,
-)
-_unify.add(((list, tuple, Iterator, OrderedDict), ConsPair, dict), _cons_unify)
+_unify.add((ConsPair, (ConsPair, MaybeCons), dict), _cons_unify)
+_unify.add((MaybeCons, ConsPair, dict), _cons_unify)
 
 
 @_reify.register(OrderedDict, dict)