Create mentoring.md for Say

tracks/python/exercises/say/mentoring.md

@@ -0,0 +1,127 @@
+# Mentoring
+
+## Problems and Challenges
+This problem requires the student to transform an integer (0 <= n < 1,000,000,000,000) into its full English equivalent, and raise an exception for values outside that range.
+Take note of the tests - the use of 'and' as a separator is not required, and adding it will cause the tests to fail, but it is suggested as an extension exercise. 
+
+## Reasonable Solution
+```
+digits = [""] + "one two three four five six seven eight nine".split()
+teens = "ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen".split()
+tens = ["", ""] + "twenty thirty forty fifty sixty seventy eighty ninety".split()
+denominations = (9, "billion"), (6, "million"), (3, "thousand"), (2, "hundred")
+
+def say(number):
+    if 0 > number or number > 999999999999:
+        raise ValueError("input out of range")
+    if number < 20 and number >= 10:
+        return teens[number % 10]
+    if number < 100:
+        if number // 10 and number % 10:
+            return "-".join([tens[number // 10], digits[number % 10]])
+        else:
+            return tens[number // 10] or digits[number % 10] or "zero"
+    for k, denomination in denominations:
+        if number > 10**k - 1:
+            result = [say(number // 10**k), denomination]
+            if number % 10 ** k:
+                result.append(say(number % 10**k))
+            return " ".join(result)
+```
+Or without using recursion:
+```
+def say3(number):
+    hundreds_col, tens_col, ones_col = number // 100, number // 10 % 10, number % 10
+    result = [str(digits[hundreds_col]) + " hundred"] if hundreds_col else []
+    if tens_col == 1:
+        result.append(teens[ones_col])
+    elif tens_col and ones_col:
+        result.append("-".join([tens[tens_col], digits[ones_col]]))
+    else:
+        result.append(tens[tens_col] or digits[ones_col])
+    return result
+
+def say(number):
+    if 0 > number or number > 999999999999:
+        raise ValueError("input out of range")
+    result = []
+    for k, denomination in denominations:
+        if number > 10**k - 1:
+            result += say3(number // 10**k)
+            result += [denomination]
+            number %= 10**k
+    return " ".join(e for e in result if e) or "zero"
+```
+
+## Common Suggestions
+
+### Defining the literals
+Typically this problem will begin with defining the literals needed. 
+These can be done as either lists or dicts, but most students will fine dicts easier to work with for this problem. 
+Encourage the student to define these at the start rather than embedding them in their code.
+
+### Values below 1000
+Next, the instructions suggest begining by creating a function which works for values of up to three digits.
+The return value of this function will typically be a string, but it can also be a list of strings for later assembly.
+Whether in this function or for the final return, encourage them to use a list and combine the elements using `str.join`.
+
+The main challenges are ensuring that the 'hundred' denominator is conditionally included and that the tens and ones columns are joined with a hyphen if they are both present.
+Simple `if` checks for each of these conditions are the most straightforward approach.
+
+Another valid approach is to only handle values below 100, and instead handle the hundreds alongside the other denominators.
+This approach typically requires the use of recursion. 
+
+### Larger numbers
+Encourage the student to use the first function they wrote for each set of three digits rather than duplicating code.
+Each set of three can be checked individually and conditionally added along with the appropriate denominator, or alternatively the denominators can be stored in a list and iterated over.
+
+### Zero or invalid input
+Finally, the student must add a guard that returns a `ValueError` if the input is out of range. 
+A guard is also the easiest way to handle the zero case, but this can also be handled through short circuit evaluation.
+
+### Parsing the number
+The number needs to be broken up into groups of three. 
+This can be handled either with numeric operators or by casting to a string.
+Generally a student will find it easier to work with the number as a string for this problem, but both approaches are valid.
+
+## Talking points
+The student should be familiar with comprehensions - if they aren't, introduce the concept as they are very useful here.
+
+There are a wide variety of valid approaches to this problem, which gives students a lot of opportunity to experiment and encounter new ways of manipulating data.
+Some useful techniques that students might not have encountered are listed below.
+Students will not need or want to use all of these, but mentors should look for opportunities in the student's code to introduce one or more of them.
+* Casting between numeric types and strings
+* String indexing, iteration, formatting, or concatenation
+* String methods such as `zfill`, `isnumeric`, `split`, or `join`
+* List concatenation using the `+` operator
+* List methods such as `append` or `extend`
+* Iterator functions such as `zip`, `enumerate`, or `filter`
+* Assignment operators
+* Unpacking operator
+* Short circuit evaluation and the use of `or`/`and` for control flow
+* Ternery if-else
+* Integer division and modulo operators, and the divmod function
+* Recusion
+
+Students who wish to extend the exercise can rewrite the function to include 'and' as a seperator as well as handle negative or larger numbers.
+This will require rewriting the tests, which might also serve as a learning opportunity for the student.
+
+This problem is a good opportunity to practice writing concise code and balancing readability. 
+It is also a good chance to code verbosely while the problem is solved, and then iterate on the solution to reduce length and complexity, so don't require the student to write concise code on every iteration. 
+A terse solution which demonstrates some techniques:
+```
+digits = [""] + "one two three four five six seven eight nine".split()
+teens = "ten eleven twelve thir four fif six seven eigh nine".split()
+tens = ["", ""] + "twenty thirty forty fifty sixty seventy eighty ninety".split()
+denominations = (9, 'billion'), (6, 'million'), (3, 'thousand'), (2, 'hundred')
+
+def say(n):
+    if 0 > n or n > 999999999999:
+        raise ValueError("input out of range")
+    if n < 20 and n >= 10:
+        return teens[n % 10] + "teen" if n % 10 > 2 else ""
+    if n < 100:
+        return '-'.join(filter(bool, [tens[n // 10], digits[n % 10]])) or 'zero'
+    k, d = [t for t in denominations if n > 10**t[0] - 1][0]
+    return " ".join([say(n // 10**k), d] + ([say(n % 10**k)] if n % 10**k else []))
+```