Let's learn about Python generator functions and expressions!

Generators

Generator functions return an iterator object that contains traversable values. To retrieve the next value from a generator object, we can use the Python built-in function `next()` which will cause the generator function to resume its execution until the next `yield` expression is found. After the next `yield` expression is found, the function will pause execution again.

If no additional `yield` expressions are found in a generator function, that means the code has finished and a StopIteration is raised.

Generator functions are not limited to just single `yield` statements. They can also include loops where the `yield` occurs.

To see this in action, imagine we have a dictionary of students and their student ID numbers. We want to hold a raffle where every student whose student ID is a multiple of 3 wins prize A and every student whose ID is a multiple of 5 wins prize B. Any student whose ID is both a multiple of 3 and 5 wins prize C.

Here is what it might look like: 
```py
def prize_generator():
  student_info = {
    "Joan Stark": 355,
    "Billy Mars": 45,
    "Tori Rivers": 18,
    "Kyle Newman": 25
  }

  for student in student_info:
    name = student
    id = student_info[name]
    if id % 3 == 0 and id % 5 == 0:
      yield student + " gets prize C"
    elif id % 3 == 0:
      yield student + " gets prize A"
    elif id % 5 == 0:
      yield student + " gets prize B"
```

Since this is a generator function, the local variable dictionary, `student_info` is preserved while the function executes with each `next()` call. We can see this by creating a variable `prizes` that calls the `prize_generator()` function and then calling `next()` on it. Let's have a look:

```py
prizes = prize_generator()
print(next(prizes))
print(next(prizes))
print(next(prizes))
print(next(prizes))
```

Running this code will produce the following output:
```bash
Joan Stark gets prize B
Billy Mars gets prize C
Tori Rivers gets prize A
Kyle Newman gets prize B
```

If we were to call `next()` one additional time, we would see a `StopIteration` exception raised since the `student_info` dictionary will have been exhausted:

```py
print(next(prizes))
```

Running this code will produce the following output:
```bash
StopIteration
```

Now, let's practice retrieving values from a generator object!

next() and StopIteration

Congratulations! You have completed the Generators lesson!

In this lesson, you learned how to:

* Create generator functions using `yield`
* Implement generator expressions
* Use built-in generator methods like `.send()`, `.throw()`, and `.close()`
* Connect generators into single generators
* Use nested or pipelined generators

Let’s review these topics one final time.



Review

Generator functions are similar to regular functions except that they must return an iterator. But instead of using a `return` statement, generator functions use an expression called `yield`.

So how does `yield` differ from a `return` statement? Well, any code that is written after a `yield` expression will execute on the next iteration of the iterator. Code written after a `return` statement will not execute.

The following example shows how the `yield` expression is used within a generator function:

```py
def course_generator():
  yield 'Computer Science'
  yield 'Art'
  yield 'Business'
```

This function will return an iterator that contains the string values 'Computer Science', 'Art', and 'Business'. On each iteration of the iterator, each yield will return its corresponding course value.

```py
courses = course_generator()
for course in courses:
    print(course)
```

Would print out:
```bash
Computer Science
Art
Business
```

Another key difference between `yield` and `return` is that the `yield` expression will suspend the execution of the function and preserve any local variables that exist within the function. The `return` statement will terminate the function immediately and return the result(s) to the caller.

Like all objects, the iterator object returned by a generator function can be stored in a variable to be used later. It can then be iterated through as needed.

Let's utilize the `yield` keyword to write our own generator function!

yield vs return

There are some cases where it is useful to connect multiple generators into one. This allows us to delegate the operations of one generator to another sub-generator. Connecting generators is similar to using the itertools `chain()` function to combine iterators into a single iterator.

In order to connect generators, we use the `yield from` statement. An example of how it is used is below:

```py
def cs_courses():
    yield 'Computer Science'
    yield 'Artificial Intelligence'

def art_courses():
    yield 'Intro to Art'
    yield 'Selecting Mediums'


def all_courses():
    yield from cs_courses()
    yield from art_courses()

combined_generator = all_courses()
```

Let’s break down this example: 

- We have a generator function called `cs_courses()` that yields two results, `'Computer Science'` and `'Artificial Intelligence'`. 
- We have another generator function called `art_courses()` that will yield two separate results, `'Intro to Art'` and `'Selecting Mediums'`.
- Our `all_courses()` generator function will yield results from both `cs_courses()` and `art_courses()` to create one combined generator with all four string values representing the courses.

If we iterate through each value within `combined_generator` using `print()` and `next()`, we can see that `yield from` retrieves each individual yield item at a time in the order that the yields are called within the generator functions.

```py
print(next(combined_generator))
print(next(combined_generator))
print(next(combined_generator))
print(next(combined_generator))
```

Our printouts will look like the following:
```bash
Computer Science
Artificial Intelligence
Intro to Art
Selecting Mediums
```

Let's practice more examples of how to connect generators.

Connecting Generators

Python provides a few special methods to manipulate generators! 

The `.send()` method allows us to send a value to a generator using the `yield` expression. If you assign `yield` to a variable the argument passed to the `.send()` method will be assigned to that variable. Calling `.send()` will also cause the generator to perform an iteration. 

Look at the following example to see the behavior of the `.send()` method:
```py
def count_generator():
  while True:
    n = yield
    print(n)

my_generator = count_generator()
next(my_generator) # 1st Iteration Output: 
next(my_generator) # 2nd Iteration Output: None
my_generator.send(3) # 3rd Iteration Output: 3
next(my_generator) # 4th Iteration Output: None
```
In the code example above, the generator definition contains the line `n = yield`. This assigns the value in `yield` to `n` which will be `None` unless a value is passed using `.send()`.

The last 4 lines in the code are 4 iterations, 3 using `next()` and one using the `.send()` method: 
- The 1st iteration creates no output since the execution stops at `n = yield` which is before `print(n)`.
- The 2nd iteration assigns `None` to `n` through the `n = yield` expression. `None` is printed.
- The 3rd iteration is caused by `my_generator.send(3)`. The value `3` is passed through `yield` and assigned to `n`. `3` is printed.
- The last, and 4th, iteration, assigns `None` to `n`. `None` is printed.

The `.send()` method can control the value of the generator when a second variable is introduced. One variable holds the iteration value and the other holds the value passed through `yield`.
```py
def generator():
  count = 0
  while True:
    n = yield count
    if n is not None:
      count = n
    count += 1

my_generator = generator()
print(next(my_generator)) # Output: 0
print(next(my_generator)) # Output: 1
print(my_generator.send(3)) # Output: 4
print(next(my_generator)) # Output: 5
```
In the above example, the generator function defines `count = 0` as the iteration value. `n` is used to hold the value provided by `yield`. Just like `next()`, the `.send()` method returns the value of the recent iteration. In this example, the return values are printed using `print()`.

The updated line, `n = yield count`, has 2 behaviors:
- At the start of each iteration the value provided by `yield` is assigned to `n`. This value will be `None` when `next()` causes an iteration or it will be equal to the value passed using `.send()`
- At the end of each iteration, the value stored in `count` is returned by the generator.

If `n is not None` the value stored in `n` can be assigned to the iterator variable, `count`. This allows the iterator to only change the value of `count` when the `.send()` method is called.


Generator Methods: send()

The generator method `throw()` provides the ability to throw an exception inside the generator from the caller point. This can be useful if we need to end the generator once it reaches a certain value or meets a particular condition.

Using the `throw()` method looks like the following:

```py
def generator():
  i = 0
  while True:
    yield i
    i += 1

my_generator = generator()
for item in my_generator:
    if item == 3:
        my_generator.throw(ValueError, "Bad value given")
```

To see how the `throw()` method can be used in a real-world scenario, let's practice using it some more.

Generator Methods: throw()

In Python, a _generator_ allows for the creation of iterators without having to implement `__iter__()` and `__next__()` methods. Generators improve code readability, save memory by allowing for iterative access of elements, and allow for the traversal of infinite streams of data.

There are two types of generators in Python: 

1. Generator functions 

2. Generator Expressions

Both of these return a generator object that can be looped over similar to a list, but unlike a list, the contents of the generator object are not stored in memory, allowing for complex and even infinite iteration of data.

Defining a generator function will resemble how we already define regular functions, except for a few key components that we will dive into in the following exercises.

Introduction to Generators

Generator expressions allow for a clean, single-line definition and creation of an iterator. By using a generator expression, there is no need to define a full generator function as we covered in the previous exercises.

Generator expressions resemble the syntax of list comprehensions. However, they do differ in the following ways:

| Generator Expressions | List Comprehensions |
| :-- | :-- |
| Returns a newly defined iterator | Returns a new list |
| Uses parentheses | Uses brackets |

<br>

Let’s look at an example of how the two compare:


```py
# List comprehension
a_list = [i*i for i in range(4)]

# Generator comprehension
a_generator = (i*i for i in range(4))
```

In this code above, `a_list` will be a list object containing the values [0, 1, 4, 9]. The object `a_generator` will be a generator object that cannot be accessed directly like `a_list`. It will need to be traversed to retrieve the values it contains. To show this further, we can print out `a_list` and `a_generator` and see what is returned:

```py
print(a_list)
print(a_generator)
```

Running this code will produce the following output:
```bash
[0, 1, 4, 9]
<generator object <genexpr> at 0x7f82e0e4d4c0>
```

Since our generator expression returns an iterator object, we can loop through to obtain the values within it:
```py
for i in a_generator:
    print(i)
```

Which produces the following output:
```bash
0
1
4
9
```

We can practice more with generator expressions by using them to create some new college courses!

Generator Expressions

_Generator pipelines_ allow us to use multiple generators to perform a series of operations all within one expression.  We can break down complex operations into smaller, more manageable parts where they can then be pipelined together to achieve the desired output.

To pipeline generators, the output of one generator function can be the input of another generator function. That resulting generator can then be used as input for another generator function, and so on. 

Pipeline generators are also often referred to as _nested generators_. We can use a pipelined generator like in the following example:

```py
def number_generator():
  i = 0
  while True:
    yield i
    i += 1
    
def even_number_generator(numbers):
  for n in numbers:
    if n % 2 == 0:
      yield n

even_numbers = even_number_generator(number_generator())

for e in even_numbers:
  print(e)
  if e == 100:
    break
```
The above example contains:
- The infinite generator `number_generator()` that yields numbers incrementing by `1`
- The infinite generator `even_number_generator()` which takes a generator as a parameter, iterates through that generator and only yields even numbers.
- The `even_numbers` variable which holds an `even_number_generator()` object with `number_generator()` as its argument.

When we iterate over `even_numbers` only even numbers are output. The `even_number_generator()` iterates over all numbers using `number_generator()`. When an even number occurs, that number is returned by `even_number_generator()`.

Let's practice more with generator pipelines!

Generator Pipelines

The generator method `.close()` is used to terminate a generator early. Once the `.close()` method is called the generator is finished just like the end of a `for loop`. Any further iteration attempts will raise a `StopIteration` exception. 
```py
def generator():
  i = 0
  while True:
    yield i
    i += 1

my_generator = generator()
next(my_generator)
next(my_generator)
my_generator.close()
next(my_generator) # raises StopGenerator exception
```
In the above example, `my_generator()` holds an an infinite generator object. After a couple `next(my_generator)` calls,  `my_generator.close()` is called. When we attempt to call `next(my_generator)` again, a `StopIteration` exception is raised. 


The `.close()` method works by raising a `GeneratorExit` exception inside the generator function. The exception is generally ignored but can be handled using `try` and `except`. 
```py
def generator():
  i = 0
  while True:
    try:
      yield i
    except GeneratorExit:
      print("Early exit, BYE!")
      break
    i += 1

my_generator = generator()
for item in my_generator:
  print(item)
  if item == 1:
    my_generator.close()
```

```bash
0
1
Early exit, BYE!
```
Putting the `yield` expression in a `try` block we can handle the `GeneratorExit` exception. In this case, we simply print out a message. Because we interrupted the automatic behavior of the `.close()` method, we must also use a `break` to exit the loop or else a `RuntimeError` will occur.

To practice this further, we can attempt to use the `.close()` method on our student generator.