[New Concept Exercise] : Generators (Plane Tickets)

.github/workflows/configlet.yml

@@ -1,16 +1,15 @@
-name: Configlet CI
+name: Configlet
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
   configlet:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v3
-
-    - name: Fetch configlet
-      uses: exercism/github-actions/configlet-ci@main
-
-    - name: Configlet Linter
-      run: configlet lint
+    uses: exercism/github-actions/.github/workflows/configlet.yml@main

.github/workflows/sync-labels.yml

@@ -2,20 +2,18 @@ name: Tools
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
     paths:
       - .github/labels.yml
       - .github/workflows/sync-labels.yml
-  schedule:
-    - cron: 0 0 1 * *
   workflow_dispatch:
+  schedule:
+    - cron: 0 0 1 * * # First day of each month
+
+permissions:
+  issues: write
 
 jobs:
   sync-labels:
-    name: Sync labels
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: micnncim/action-label-syncer@3abd5ab72fda571e69fffd97bd4e0033dd5f495c
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    uses: exercism/github-actions/.github/workflows/labels.yml@main

concepts/generators/.meta/config.json

@@ -1,5 +1,5 @@
 {
-  "blurb": "TODO: add blurb for this concept",
-  "authors": ["bethanyg", "cmccandless"],
+  "blurb": "Learn about generators by assigning seats to passengers.",
+  "authors": ["J08K"],
   "contributors": []
 }

concepts/generators/about.md

@@ -1,2 +1,132 @@
-#TODO: Add about for this concept.
+# About
 
+## Constructing a generator
+
+Generators are constructed much like other looping or recursive functions, but require a [`yield` expression](#the-yield-expression), which we will explore in depth a bit later.
+
+
+An example is a function that returns the _squares_ from a given list of numbers.  
+As currently written, all input must be processed before any values can be returned:  
+
+
+```python
+>>> def squares(list_of_numbers):
+>>>     squares = []
+>>>     for number in list_of_numbers:
+>>>         squares.append(number ** 2)
+>>>     return squares
+```
+
+You can convert that function into a generator like this:
+
+```python
+def squares(list_of_numbers):
+    for number in list_of_number:
+        yield number ** 2
+```
+
+The rationale behind this is that you use a generator when you do not need all the values _at once_.
+
+This saves memory and processing power, since only the value you are _currently working on_ is calculated.
+
+
+## Using a generator
+
+Generators may be used in place of most `iterables` in Python. This includes  _functions_ or _objects_ that require an `iterable`/`iterator` as an argument.
+
+To use the `squares()` generator:
+
+```python
+>>> squared_numbers = squares([1, 2, 3, 4])
+
+>>> for square in squared_numbers:
+>>>     print(square)
+1
+4
+9
+16
+```
+
+Values within a generator can also be produced/accessed via the `next()` function. 
+`next()` calls the `__next__()` method of a generator object, "advancing" or evaluating the generator code up to its `yield` expression, which then "yields" or returns the value.
+
+```python
+square_generator = squares([1, 2])
+
+>>> next(square_generator)
+1
+>>> next(square_generator)
+4
+```
+
+When a `generator` is fully consumed and has no more values to return, it throws a `StopIteration` error.
+
+```python
+>>> next(square_generator)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+StopIteration
+```
+
+### Difference between iterables and generators
+
+Generators are a special sub-set of _iterators_.
+`Iterators` are the mechanism/protocol that enables looping over _iterables_.
+Generators and and the iterators returned by common Python (`iterables`)[https://wiki.python.org/moin/Iterator] act very similarly, but there are some important differences to note:
+
+
+- Generators are _one-way_; there is no "backing up" to a previous value.
+
+- Iterating over generators consume the returned values; no resetting.
+- Generators (_being lazily evaluated_) are not sortable and can not be reversed.
+
+- Generators do _not_ have `indexes`, so you can't reference a previous or future value using addition or subtraction.
+
+- Generators cannot be used with the `len()` function.
+
+- Generators can be _finite_ or _infinite_, be careful when collecting all values from an _infinite_ generator.
+
+## The yield expression
+
+The [yield expression](https://docs.python.org/3.8/reference/expressions.html#yield-expressions) is very similar to the `return` expression.
+
+_Unlike_ the `return` expression, `yield` gives up values to the caller at a _specific point_, suspending evaluation/return of any additional values until they are requested.
+
+When `yield` is evaluated, it pauses the execution of the enclosing function and returns any values of the function _at that point in time_.
+
+The function then _stays in scope_, and when `__next__()` is called, execution resumes until `yield` is encountered again.
+
+Note: _Using `yield` expressions is prohibited outside of functions._
+
+```python
+>>> def infinite_sequence():
+>>>     current_number = 0
+>>>     while True:
+>>>         yield current_number
+>>>         current_number += 1
+
+>>> lets_try = infinite_sequence()
+>>> lets_try.__next__()
+0
+>>> lets_try.__next__()
+1
+```
+
+## Why generators?
+
+Generators are useful in a lot of applications.
+
+When working with a large collection, you might not want to put all of its values into `memory`.
+A generator can be used to work on larger data piece-by-piece, saving memory and improving performance.
+
+Generators are also very helpful when a process or calculation is _complex_, _expensive_, or _infinite_:
+
+```python
+>>> def infinite_sequence():
+>>>     current_number = 0
+>>>     while True:
+>>>         yield current_number
+>>>         current_number += 1
+```
+
+Now whenever `__next__()` is called on the `infinite_sequence` object, it will return the _previous number_ + 1.

concepts/generators/introduction.md

@@ -1,2 +1,5 @@
-#TODO: Add introduction for this concept.
+# Introduction
 
+A generator in Python is a _callable function_ that returns a [lazy iterator](https://en.wikipedia.org/wiki/Lazy_evaluation).
+
+_Lazy iterators_ are similar to `lists`, and other `iterators`, but with one key difference: They do not store their `values` in memory, but _generate_ their values when needed.

concepts/generators/links.json

@@ -1,18 +1,10 @@
 [
   {
-    "url": "http://example.com/",
-    "description": "TODO:  add new link (above) and write a short description here of the resource."
+    "url": "https://docs.python.org/3.8/reference/expressions.html#yield-expressions",
+    "description": "Official Python 3.8 docs for the yield expression."
   },
   {
-    "url": "http://example.com/",
-    "description": "TODO:  add new link (above) and write a short description here of the resource."
-  },
-  {
-    "url": "http://example.com/",
-    "description": "TODO:  add new link (above) and write a short description here of the resource."
-  },
-  {
-    "url": "http://example.com/",
-    "description": "TODO:  add new link (above) and write a short description here of the resource."
+    "url": "https://en.wikipedia.org/wiki/Lazy_evaluation",
+    "description": "Wikipedia page about lazy evaluation"
   }
 ]

config.json

@@ -176,12 +176,37 @@
         "prerequisites": ["basics", "dicts", "lists", "loops", "tuples"],
         "status": "beta"
       },
+      {
+        "slug": "plane-tickets",
+        "name": "Plane Tickets",
+        "uuid": "3ba3fc89-3e1b-48a5-aff0-5aeaba8c8810",
+        "concepts": [
+          "generators"
+        ],
+        "prerequisites": [
+          "conditionals",
+          "dicts",
+          "lists",
+          "loops"
+        ],
+        "status": "wip"
+      },
       {
         "slug": "ellens-alien-game",
         "name": "Ellen's Alien Game",
         "uuid": "3550ec07-f6c6-48bd-b2b4-086e75faf9e7",
         "concepts": ["classes"],
-        "prerequisites": ["basics", "bools", "comparisons", "loops", "dicts", "lists", "numbers", "sets", "strings", "tuples"],
+        "prerequisites": ["basics",
+          "bools",
+          "comparisons",
+          "loops",
+          "dicts",
+          "lists",
+          "numbers",
+          "sets",
+          "strings",
+          "tuples"
+        ],
         "status": "beta"
       }
     ],

docs/TOOLS.md

@@ -37,7 +37,6 @@ To create a virtual environment, `cd` to the directory you want to store your en
 ```bash
 $ python3 -m venv {name_of_virtualenv}
 created virtual environment ... in 8568ms
-```
 
 #### Activating your virtual environment
 
@@ -181,7 +180,7 @@ Sublime Text comes with a lot of tools already, but some of these tools could ma
 
 ### JupyterLab
 
-[Jupyter lab](https://jupyter.org/install) is an in-browser code editor that runs on your machine, combining the ability to write Markdown along side executable code and data. Jupyter supports multiple programming languages via `kernels` and can display graphs and tables as well as code and text.  
+[Jupyter lab](https://jupyter.org/install) is an in-browser code editor that runs on your machine, combining the ability to write Markdown along side executable code and data. Jupyter supports multiple programming languages via `kernels` and can display graphs and tables as well as code and text.
 
 Jupyter comes pre-packaged with Anaconda.  You can also install it in a **virtual environment** using `pip` or `conda`.  Jupyter will use that environment and its Python version. Jupyter is most well-known for its code "notebooks". It is commonly used among data-scientists.
 

exercises/concept/plane-tickets/.docs/hints.md

@@ -0,0 +1,11 @@
+# Hints
+
+## 1. Generate an amount of seats
+
+- The returned value should be of _type_ `generator`.
+- Row `13` should be skipped, so go from `12` to `14`.
+- Keep in mind that the returned values should be ordered from low to high. `1A, 1B, 2A, ...`
+
+## 2. Assign seats to passengers
+
+- Make sure your seat numbers do not have any space in them.

exercises/concept/plane-tickets/.docs/instructions.md

@@ -0,0 +1,73 @@
+# Instructions
+
+Conda airlines is the programming-world's biggest airline, with over 10.000 flights a day!
+
+They are currently assigning all seats to passengers by hand, this will need to automated.
+
+They have asked _you_ to create software to automate the assigning of seats to passengers. They require your software to be memory efficient and performant.
+
+Conda's airplanes have up to _4 seats_ in each row, and each airplane has many rows.
+
+While the rows are defined using numbers, seats in each row are defined using letters from the alphabet, with `seat A` being the first _seat_ in the row.
+
+You can use this table as a guide:
+
+| x             | 1         | 2     |
+| :----:        | :----:    | :----:|
+| Row           | 5         | 21    |
+| Seat letter   | A         | D     |
+| Result        | 5A        | 21D   |
+
+## 1. Generate an amount of seats
+
+Implement the `generate_seats()` function that returns an _iterable_ of seats given the following variable:
+
+`amount`: The amount of seats to be generated.
+
+Many airlines do not have _row_ number 13 on their flights, due to superstition amongst passengers.
+Conda Airlines also follows this convention, so make sure you _don't_ generate seats for _row_ number 13.
+
+_Note: The returned seats should be ordered, like: 1A 1B 1C._
+
+```python
+>>> seats = generate_seats(10)
+>>> next(seats)
+"1A"
+>>> next(seats)
+"1B"
+```
+
+## 2. Assign seats to passengers
+
+Implement the `assign_seats()` function that returns a _dictionary_ of `passenger` as _key_, and `seat_number` as _value_. Given is the following _list_:
+
+`passengers`: A list containing passenger names.
+
+```python
+>>> passengers = ['Jerimiah', 'Eric', 'Bethaney', 'Byte', 'SqueekyBoots', 'Bob']
+
+>>> assign_seats(passengers)
+{'Jerimiah': '1A', 'Eric': '1B', 'Bethaney': '1C', 'Byte': '1D', 'SqueekyBoots': '2A', 'Bob': '2B'}
+```
+
+## 3. Ticket codes
+
+Each ticket has a _12_ character long string code for identification.
+
+This code begins with the `assigned_seat` followed by the `flight_id`. The rest of the code is appended by `0s`.
+
+Implement a `generator` that yields a `ticket_number` given the following arguments:
+
+`seat_numbers`: A _list_ of *seat_numbers*.
+`flight_id`: A string containing the flight identification.
+
+```python
+>>> seat_numbers = ['1A', '17D']
+>>> flight_id = 'CO1234'
+>>> ticket_ids = generate_codes(seat_numbers, flight_id)
+
+>>> next(ticket_ids)
+'1ACO12340000'
+>>> next(ticket_ids)
+'17DCO1234000'
+```

exercises/concept/plane-tickets/.docs/introduction.md

@@ -0,0 +1,5 @@
+# Introduction
+
+A generator in Python is a _callable function_ that returns a [lazy iterator](https://en.wikipedia.org/wiki/Lazy_evaluation).
+
+_Lazy iterators_ are similar to iterables such as `lists`, and other types of `iterators` in Python -- but with one key difference: `generators` do not store their `values` in memory, but _generate_ their values as needed or when called.

exercises/concept/plane-tickets/.meta/config.json

@@ -0,0 +1,11 @@
+{
+  "blurb": "Learn about generators by assigning seats to passengers.",
+  "authors": ["J08K"],
+  "icon": "poker",
+  "contributors": ["BethanyG"],
+  "files": {
+    "solution": ["plane_tickets.py"],
+    "test": ["plane_tickets_test.py"],
+    "exemplar": [".meta/exemplar.py"]
+  }
+}