Decorator to make an iterator returned by a method yield each result only
    once.

    >>> @yield_once
    ... def generate_list(foo):
    ...     return foo
    >>> list(generate_list([1, 2, 1]))
    [1, 2]

    :param iterator: Any method that returns an iterator
    :return:         An method returning an iterator
                     that yields every result only once at most.

def yield_once(iterator):
    """
    Decorator to make an iterator returned by a method yield each result only
    once.

    >>> @yield_once
    ... def generate_list(foo):
    ...     return foo
    >>> list(generate_list([1, 2, 1]))
    [1, 2]

    :param iterator: Any method that returns an iterator
    :return:         An method returning an iterator
                     that yields every result only once at most.
    """
    @wraps(iterator)
    def yield_once_generator(*args, **kwargs):
        yielded = set()
        for item in iterator(*args, **kwargs):
            if item not in yielded:
                yielded.add(item)
                yield item

    return yield_once_generator