rspec/rules/S2876/python/rule.adoc

This rule raises an issue when the object returned by ``++__iter__++`` is not a valid iterator.

== Why is this an issue?

An https://docs.python.org/3/glossary.html#term-iterable[iterable] object is an object capable of returning its members one at a time. To do so, it must define an ``++__iter__++`` method that returns an iterator.

The https://docs.python.org/3/library/stdtypes.html#iterator-types[iterator protocol] specifies that, in order to be a valid iterator, an object must define a ``++__next__++`` and an ``++__iter__++`` method (because iterators are also iterable).

Defining an ``++__iter__++`` method that returns anything else than an iterator will raise a ``++TypeError++`` as soon as the iteration begins.


Note that https://docs.python.org/3/tutorial/classes.html#generators[generators] and https://docs.python.org/3/tutorial/classes.html#generator-expressions[generator expressions] have both ``++__next__++`` and ``++__iter__++`` methods generated automatically.

== How to fix it

Make sure that the ``++__iter__++`` method returns a valid iterator.

== Code examples 

=== Noncompliant code example

[source,python,diff-id=1,diff-type=noncompliant]
----
class MyIterable:
    def __init__(self, values):
        self._values = values

    def __iter__(self):
        return None  # Noncompliant: Not a valid iterator
----


=== Compliant solution

[source,python,diff-id=1,diff-type=compliant]
----
class MyIterable:
    def __init__(self, values):
        self._values = values

    def __iter__(self):
        return MyIterator(self._values)

class MyIterator:
    def __init__(self, values):
        self._values = values
        self._index = 0

    def __next__(self):
        if self._index >= len(self._values):
            raise StopIteration()
        value = self._values[self._index]
        self._index += 1
        return value

    def __iter__(self):
        return self
----


== Resources

=== Documentation

* Python Documentation -  https://docs.python.org/3/library/stdtypes.html#iterator-types[Iterator Types]
* PEP 234 - https://www.python.org/dev/peps/pep-0234/#python-api-specification[Iterators]


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

* Return an object complying with iterator protocol.


'''
== Comments And Links
(visible only on this page)

=== is related to: S5625

endif::env-github,rspecator-view[]