PyoIterable

@runtime_checkable
class PyoIterable[T](Checkable, Fluent, Protocol):
    """Base ABC for all pyochain `Iterables`.

    It's the common API surface shared by:

    - eager `Collections`: `Seq`, `Vec`, `Set`, `SetMut`, `Dict`
    - lazy `Iterator`: `Iter`

    It extends the standard `Iterable[T]` protocol, as well as `Fluent` and `Checkable`.

    All concrete subclasses must implement `__iter__()`.

    Note:
        The difference between an `Iterable` and an `Iterator` is often misunderstood, but it's actually quite simple.

        An `Iterable` is any object that can **create** an `Iterator`.

        It's sole responsbility is to provide an `__iter__` method.

        This method must return an object that have a `__next__` method, which is the actual `Iterator`.

        An `Iterator` is an object that can produce elements one at a time, and can be exhausted.

        When you do a `for x in my_iterable`, Python implicitly calls `my_iterable.__iter__(), and then repeatedly calls `next()` on the resulting `Iterator` to get the elements.

        More concretely, a `list`, for example, is an `Iterable`.

        You can't call `next()` on a `list`, because it don't know how to produce elements by itself, it's primary responsibility being to **store** them.

        However, as soon as you call `map(my_list)`, `[x for x in my_list]`, (*my_list), or any other operation that needs to visit elements, an `Iterator` is created (implicitly or explicitly) from the `list`.

        It's also why `abc::Iterator::__iter__` returns `Self` by convention.

    Example:
        Since it's very straightforward to implement, it can very easily be integrated into business logic classes to provide them with a rich set of methods for free.

        ```python
        from pyochain.abc import PyoIterable
        from dataclasses import dataclass

        @dataclass(slots=True)
        class ClientRegistry(PyoIterable[str]):
            clients: list[str]

            def __iter__(self):
                return iter(self.clients)

        registry = ClientRegistry(["Alice", "Bob", "Charlie"])

        assert not registry.iter().all(lambda name: name.startswith("A"))
        assert registry.iter().join(", ") == "Alice, Bob, Charlie"
        assert registry.iter().map(str.lower).join(", ") == "alice, bob, charlie"

        x = (
            registry
            .ok_or("Registry is empty")
            .map(lambda s: s.iter().join(", "))
            .unwrap()
        )
        assert x == ("Alice, Bob, Charlie")
        ```
    """
    @abstractmethod
    def __iter__(self) -> Iterator[T]: ...
    def iter[I](self: PyoIterable[I]) -> PyoIterator[I]:
        """Returns a `PyoIterator` object over the `Iterable`.

        By default, this returns an `Iter`, but can be overriden by concrete subclasses.

        This method is the pyochain equivalent of the `__iter__` dunder method.

        Returns:
            PyoIterator[I]: An `Iterator` over the `Iterable`.

        Example:
            ```python
            from pyochain import Seq

            seq = Seq(1, 2, 3)
            iterator = seq.iter()

            assert iterator.collect(Seq) == Seq(1, 2, 3)

            # iterator is now empty
            assert iterator.collect(Seq).is_empty()
            assert iterator.next().is_none()
            ```
        """