Iteration-utilities

^^^^^^^^^^^^^^^^^^^^^^^^^^

- fixed major mistake that made 0.5.0 unusable. (``%R`` formatter isn't allowed
in ``PyErr_Format``).

^^^^^^^^^^^^^^^^^^^^^^^^^^

- minor speedup for ``next(merge)``.

- removed **unused** ``key`` parameter from ``combinations_from_relations``.

- replaced ``Iterable.as_string`` parameter ``seperaror`` (sic!) by
``seperator``.

- included signature for ``__reduce__``, ``__setstate__`` and
``__length_hint__`` methods.

- fixed ``Seen.contains_add`` method signature.

- fixed potential segfault in ``ItemIdxKey.__repr__``.

- removed unnecessary ``__setstate__`` method for ``ItemIdxKey``.

- various ``__setstate__`` and ``__reduce__`` methods were changed so they
can't used to cause segmentation faults, ``SystemError`` or blatantly wrong
behaviour. However, serializing or copying such an instance can significantly
slower as a result of this change. Unpickling these instances from previous
versions could be impossible and ``copy.copy`` is **not** supported (and
probably won't be ever because ``itertools.tee`` interacts with ``__copy__``
methods). Affected iterators: ``chained``, ``deepflatten``, ``duplicates``,
``grouper``, ``intersperse``, ``merge``, ``roundrobin``, ``sideeffects``,
``split``, ``successive``, ``unique_everseen``, ``unique_justseen``.

- added ``__repr__`` method for ``chained``, ``complement``, ``constant``,
``flip``, ``nth`` and ``packed``.

- fixed a bug with ``partial`` when the function kept the arguments and a call
only provided exactly the number of arguments as there are placeholders in
the partial.

- Applying ``flip`` on another ``flip`` instance now simply returns the
original function.

- ``chained`` now unwraps (if possible) other ``chained`` instances when
creating a new instance. This is only done if this **won't** change the
current behaviour.

^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``Seen`` and ``ItemIdxKey`` can detect recursive objects in their ``repr``.

- The representation for ``Seen`` and ``ItemIdxKey`` now uses the classname
even for subclasses.

- added ``partial`` callback class, which is essentially ``functools.partial``
but also allows positional placeholders.

- several functions now interpret ``None`` as if that argument for the function
wasn't given:

- ``key`` argument for ``minmax``, ``merge``, ``argmin`` and ``argmax``.
- ``reduce`` argument for ``groupedby``.
- all arguments for ``Seen.__new__``.

^^^^^^^^^^^^^^^^^^^^^^^^^^

- implemented ``__length_hint__`` method for ``clamp``. However sensible
results (!= 0) are only possible if ``remove=False`` or both ``low`` and
``high`` were not set.

- fixed ``SystemError`` in several functions when accessing the next item of
the iterable resulted in an Exception different from ``StopIteration``.

- added ``starfilter`` iterator.

- added ``packed`` callback class.

- fixed a segfault in ``complement.__call__`` method when the function raised
an Exception.

- fixed a segfault in ``partition`` when ``bool(item)`` raised an Exception.

- included a missing ``ValueError`` in ``split`` when two of the ``keep*``
parameters are True. The case where all three were given already raised the
correct exception.

- ``clamp`` now interprets ``low=None`` or ``high=None`` as if the
corresponding value wasn't given. Before it tried to compare the items with
``None``.

^^^^^^^^^^^^^^^^^^^^^^^^^^

- fixed segfault in ``nth`` when ``retpred=True``.

^^^^^^^^^^^^^^^^^^^^^^^^^^

- added ``remove`` parameter to ``clamp``.

- made ``deepflatten`` string-aware. For other recursive-iterable classes a
``RecursionException`` (or ``RuntimeException`` on python < 3.5) is raised
instead of freezing.