.. getthecode:: generators.py
    :language: python3
    :hidden:

============
 Generators
============

This page contains a memo on generators.

For a complete reference documentation, look at
https://docs.python.org/3/reference/expressions.html#generator-expressions


.. code-block:: py3

    from Tools import *
    
    import asyncio
    
List Comprehensions
-------------------


.. code-block:: py3

    a_list = [x for x in range(10)]
    print(a_list)

.. code-block:: none

    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    

.. code-block:: py3

    a_set = {x % 10 for x in range(100)}
    print(a_set)

.. code-block:: none

    {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
    

.. code-block:: py3

    a_dict = {x:x for x in range(5)}
    print(a_dict)

.. code-block:: none

    {0: 0, 1: 1, 2: 2, 3: 3, 4: 4}
    
Nested List Comprehensions
~~~~~~~~~~~~~~~~~~~~~~~~~~


.. code-block:: py3

    a_list_of_list = [[x, y]
                      for x in range(2)
                      for y in range(4)]
    print(a_list_of_list)

.. code-block:: none

    [[0, 0], [0, 1], [0, 2], [0, 3], [1, 0], [1, 1], [1, 2], [1, 3]]
    
Filtered List Comprehensions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. code-block:: py3

    a_list = [x for x in range(10)
              if 2 <= x <= 6]
    print(a_list)

.. code-block:: none

    [2, 3, 4, 5, 6]
    

.. code-block:: py3

    a_list_of_list = [[x, y]
                      for x in range(10)
                      for y in range(10)
                      if 2 <= x <= 3 and 5 <= y <= 6]
    print(a_list_of_list)

.. code-block:: none

    [[2, 5], [2, 6], [3, 5], [3, 6]]
    
Generator expressions
---------------------


.. code-block:: py3

    N = 4
    multiplication_table = (x*y for x in range(1, N+1) for y in range(1, N+1))
    
    print(list(multiplication_table))

.. code-block:: none

    [1, 2, 3, 4, 2, 4, 6, 8, 3, 6, 9, 12, 4, 8, 12, 16]
    
Yield expressions
-----------------


.. code-block:: py3

    def simplist_generator():
        yield 1
    
    print(list(simplist_generator()))

.. code-block:: none

    [1]
    

.. code-block:: py3

    def range_clone(N):
        for i in range(N):
            yield i
    
    print(list(range_clone(10)))

.. code-block:: none

    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    
A generator exit when :code:`StopIteration` is raised:


.. code-block:: py3

    def generator(N, M):
        value = N
        while True:
            yield value
            value += 1
            if M <= value:
                raise StopIteration
    
    print(list(generator(10, 20)))

.. code-block:: none

    [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
        /home/opt/python-virtual-env/py36/lib/python3.6/site-packages/ipykernel_launcher.py:9: DeprecationWarning: generator 'generator' raised StopIteration
      if __name__ == '__main__':
    
We can yield from a generator instead of a value:


.. code-block:: py3

    def generator(N):
        yield from range_clone(N)
    
    print(list(generator(10)))

.. code-block:: none

    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    
Generator-iterator Methods
--------------------------


.. code-block:: py3

    def echo(value=None):
        print("echo is running")
        try:
            while True:
                try:
                    value = (yield value)
                except Exception as exception:
                    print('exception:', exception)
                    value = exception
        finally:
            # cleanup code
            print("reached finally")
    
    generator = echo(1)

.. code-block:: none


Starts the execution of a generator function or resumes it at the last executed yield expression.


.. code-block:: py3

    print(next(generator))

.. code-block:: none

    echo is running
    1
    

.. code-block:: py3

    print(next(generator))

.. code-block:: none

    None
    
Resumes the execution and “sends” a value into the generator function.


.. code-block:: py3

    print(generator.send(2))

.. code-block:: none

    2
    
Raises an exception of type type at the point where the generator was paused.


.. code-block:: py3

    # generator.throw(type[, value[, traceback]])
    generator.throw(TypeError, "spam")

.. code-block:: none

    exception: spam
    
Raises a :code:`GeneratorExit` at the point where the generator function was paused.


.. code-block:: py3

    generator.close()

.. code-block:: none

    reached finally
    
Asynchronous Generator Functions
--------------------------------
**To be completed**

For further information see `PEP 525 -- Asynchronous Generators <https://www.python.org/dev/peps/pep-0525>`_


.. code-block:: py3

    async def ticker(delay, to):
        """Yield numbers from 0 to `to` every `delay` seconds."""
        for i in range(to):
            yield i
            await asyncio.sleep(delay)
    
Asynchronous Generator-Iterator Methods
---------------------------------------
**To be completed**