new concept exercise - bools

Introduces the bools concept, see design and .docs for more details.

Co-authored-by: Corey McCandless <[email protected]>
Co-authored-by: Erik Schierboom <[email protected]>

Author: 3 people

exercises/concept/bools/.docs/after.md

@@ -0,0 +1,69 @@
+Python represents True and False values with the [boolean][boolean] type. There are only two [boolean][boolean] values: _True_ and _False_. These values can be assigned to a variable and combined with [boolean operators][boolean-operators] (`and`, `or`, `not`):
+
+```python
+true_variable = True and True
+false_variable = True and False
+
+true_variable = False or True
+false_variable = False or False
+
+true_variable = not False
+false_variable = not True
+```
+
+[Boolean operators][boolean-operators] use _short-circuit evaluation_, which means that expression on the right-hand side of the operator is only evaluated if needed.
+
+Each of the operators has a different precedence, where `not` is evaluated before `and` and `or`. Brackets can be used to evaluate one part of the expression before the others:
+
+```python
+not True and True # => False
+not (True and False) # => True
+```
+
+## Type Coercion and Truthiness
+
+The [`bool` function][bool-function] converts any type to a Boolean value. By default all values return `True` unless defined to return `False`.
+
+Some built-ins already defined to be considered `False`:
+
+- constants like `None` and `False`
+- zero of any _numeric type_
+- empty _sequences_ and _collections_
+
+```python
+bool(1) # => True
+bool(0) # => False
+```
+
+When a value is used in a boolean context, it is used as a _truthy_ or _falsey_ value by transparently using the `bool` function.
+
+```python
+a = "is this true?"
+if a:
+  print("True")
+# => This will print "True", as a non-empty string is a truthy value
+```
+
+Classes may define how they are evaluated in truthy situations if they override and implement a `__bool__` method.
+
+## How Booleans work under the hood
+
+The Boolean type is a _sub-type_ of the _int_ type. `True` is numerically equal to `1`. `False` is numerically equal to `0`. This is observable when comparing them:
+
+```python
+1 == True # => True
+0 == False # => True
+```
+
+However, they are still different as noted when checking for a Boolean identity:
+
+```python
+1 is True # => False
+0 is False # => False
+```
+
+> Note: in python >= 3.8, using a literal value on the left side of `is` will raise a warning.
+
+[bool-function]: https://docs.python.org/3/library/functions.html#bool
+[boolean]: https://docs.python.org/3/library/stdtypes.html#truth
+[boolean-operators]: https://docs.python.org/3/library/stdtypes.html#boolean-operations-and-or-not

exercises/concept/bools/.docs/hints.md

@@ -0,0 +1,22 @@
+## General
+
+- Don't worry about how the arguments are derived, just focus on combining the arguments to return the intended result.
+
+## 1. Define if Pac-Man can eat a ghost
+
+- You can use the [boolean][boolean] [operators][boolean-operators] to combine the arguments for a result.
+
+## 2. Define if Pac-Man scores
+
+- You can use the [boolean][boolean] [operator][boolean-operators] to combine the arguments for a result.
+
+## 3. Define if Pac-Man loses
+
+- You can use the [boolean][boolean] [operator][boolean-operators] to combine the arguments for a result.
+
+## 4. Define if Pac-Man wins
+
+- You can use the [boolean][boolean] [operator][boolean-operators] to combine the arguments for a result.
+
+[boolean]: https://docs.python.org/3/library/stdtypes.html#truth
+[boolean-operators]: https://docs.python.org/3/library/stdtypes.html#boolean-operations-and-or-not

exercises/concept/bools/.docs/instructions.md

@@ -0,0 +1,41 @@
+In this exercise, you need to implement some rules from [Pac-Man, the classic arcade-game](https://en.wikipedia.org/wiki/Pac-Man).
+
+You have four rules to implement, all related to the game states.
+
+> Don't worry about how the arguments are derived, just focus on combining the arguments to return the intended result.
+
+## 1. Define if Pac-Man eats a ghost
+
+Define the `eat_ghost()` function that takes two parameters (_if Pac-Man has a power pellet active_ and _if Pac-Man is touching a ghost_) and returns a boolean value if Pac-Man is able to eat the ghost. The function should return `True` only if Pac-Man has a power pellet active and is touching a ghost.
+
+```python
+eat_ghost(False, True)
+# => False
+```
+
+## 2. Define if Pac-Man scores
+
+Define the `score()` function that takes two parameters (_if Pac-Man is touching a power pellet_ and _if Pac-Man is touching a dot_) and returns a boolean value if Pac-Man scored. The function should return `True` if Pac-Man is touching a power pellet or a dot.
+
+```python
+score(True, True)
+# => True
+```
+
+## 3. Define if Pac-Man loses
+
+Define the `lose()` function that takes two parameters (_if Pac-Man has a power pellet active_ and _if Pac-Man is touching a ghost_) and returns a boolean value if Pac-Man loses. The function should return `True` if Pac-Man is touching a ghost and does not have a power pellet active.
+
+```python
+lose(False, True)
+# => True
+```
+
+## 4. Define if Pac-Man wins
+
+Define the `win()` function that takes three parameters (_if Pac-Man has eaten all of the dots_, _if Pac-Man has a power pellet active_, and _if Pac-Man is touching a ghost_) and returns a boolean value if Pac-Man wins. The function should return `True` if Pac-Man has eaten all of the dots and has not lost based on the parameters defined in part 3.
+
+```python
+win(False, True, False)
+# => False
+```

exercises/concept/bools/.docs/introduction.md

@@ -0,0 +1,19 @@
+Python represents true and false values with the boolean type. There are only two values: `True` and `False`. These values can be bound to a variable:
+
+```python
+true_variable = True
+false_variable = False
+```
+
+We can evaluate boolean expressions using the `and`, `or`, and `not` operators.
+
+```python
+true_variable = True and True
+false_variable = True and False
+
+true_variable = False or True
+false_variable = False or False
+
+true_variable = not False
+false_variable = not True
+```

exercises/concept/bools/.meta/config.json

@@ -0,0 +1,16 @@
+{
+  "authors": [
+    {
+      "github_username": "neenjaw",
+      "exercism_username": "neenjaw"
+    }
+  ],
+  "contributors": [
+    {
+      "github_username": "cmccandless",
+      "exercism_username": "cmccandless"
+    }
+  ],
+  "forked_from": ["elixir/booleans"],
+  "language_versions": ">=3.5"
+}

exercises/concept/bools/.meta/design.md

@@ -0,0 +1,35 @@
+## Goal
+
+The goal of this exercise is to teach the student how [`bool`](https://github.com/exercism/v3/blob/master/languages/python/reference/concepts/builtin_types/bool.md) is implemented and used in Python. We will teach the `bool` type by showing the student how to use it.
+
+## Learning objectives
+
+- create a `bool` object via literal declaration
+- obtain a `bool` object from using [logical operators](https://docs.python.org/3/reference/expressions.html#boolean-operations) (`and`, `or`, `not`)
+
+## Out of scope
+
+- obtain a `bool` object from [comparison operators](https://docs.python.org/3/reference/expressions.html#value-comparisons) (`>`, `<`, `==`)
+- obtain a `bool` object from [membership operators](https://docs.python.org/3/reference/expressions.html#membership-test-operations) (`in`, `not in`)
+- obtain a `bool` object from [identity operators](https://docs.python.org/3/reference/expressions.html#is-not) (`is`, `is not`)
+- 'truthyness' and 'falsyness'
+  - create a `bool` object from other objects (`collections`, `integers`, `strings`) with the the `bool()` constructor.
+- catching/raising Exceptions
+- covering that `bool` is a subtype of `int`
+- bitwise logical operators
+- orders of evaluation
+
+## Concepts
+
+- **booleans:** know of the existence of the bool type and its two values; know about boolean operators and how to build logical expressions with them; know of the boolean operator precedence rules.
+
+## Prerequisites
+
+- `builtin-types`
+- `comparison-operators`
+
+## Resources
+
+- [Boolean Operations — and, or, not](https://docs.python.org/3/library/stdtypes.html#boolean-operations-and-or-not)
+- [Built-in Functions - bool](https://docs.python.org/3/library/functions.html#bool)
+- [Truth Value Testing](https://docs.python.org/3/library/stdtypes.html#truth)

exercises/concept/bools/.meta/example.py

@@ -0,0 +1,14 @@
+def eat_ghost(power_pellet_active, touching_ghost):
+    return power_pellet_active and touching_ghost
+
+
+def score(touching_power_pellet, touching_dot):
+    return touching_power_pellet or touching_dot
+
+
+def lose(power_pellet_active, touching_ghost):
+    return not power_pellet_active and touching_ghost
+
+
+def win(has_eaten_all_dots, power_pellet_active, touching_ghost):
+    return has_eaten_all_dots and not lose(power_pellet_active, touching_ghost)

exercises/concept/bools/arcade_game.py

@@ -0,0 +1,11 @@
+def eat_ghost(power_pellet_active, touching_ghost):
+    pass
+
+def score(touching_power_pellet, touching_dot):
+    pass
+
+def lose(power_pellet_active, touching_ghost):
+    pass
+
+def win(has_eaten_all_dots, power_pellet_active, touching_ghost):
+    pass

exercises/concept/bools/arcade_game_test.py

@@ -0,0 +1,89 @@
+import unittest
+from arcade_game import eat_ghost, score, lose, win
+
+
+class TestArcadeGame(unittest.TestCase):
+
+    def test_ghost_gets_eaten(self):
+        self.assertIs(
+            eat_ghost(True, True),
+            True,
+            msg="ghost should get eaten"
+        )
+
+    def test_ghost_does_not_get_eaten_because_no_power_pellet_active(self):
+        self.assertIs(
+            eat_ghost(False, True),
+            False,
+            msg="ghost does not get eaten because no power pellet active"
+        )
+
+    def test_ghost_does_not_get_eaten_because_not_touching_ghost(self):
+        self.assertIs(
+            eat_ghost(True, False),
+            False,
+            msg="ghost does not get eaten because not touching ghost"
+        )
+
+    def test_score_when_eating_dot(self):
+        self.assertIs(
+          score(False, True),
+          True,
+          msg="score when eating dot"
+        )
+
+    def test_score_when_eating_power_pellet(self):
+        self.assertIs(
+            score(True, False),
+            True,
+            msg="score when eating power pellet"
+        )
+
+    def test_no_score_when_nothing_eaten(self):
+        self.assertIs(
+            score(False, False),
+            False,
+            msg="no score when nothing eaten"
+        )
+
+    def test_lose_if_touching_a_ghost_without_a_power_pellet_active(self):
+        self.assertIs(
+            lose(False, True),
+            True,
+            msg="lose if touching a ghost without a power pellet active"
+        )
+
+    def test_dont_lose_if_touching_a_ghost_with_a_power_pellet_active(self):
+        self.assertIs(
+            lose(True, True),
+            False,
+            msg="don't lose if touching a ghost with a power pellet active"
+        )
+
+    def test_dont_lose_if_not_touching_a_ghost(self):
+        self.assertIs(
+            lose(True, False),
+            False,
+            msg="don't lose if not touching a ghost"
+        )
+
+    def test_win_if_all_dots_eaten(self):
+        self.assertIs(
+            win(True, False, False),
+            True,
+            msg="win if all dots eaten"
+        )
+
+    def test_dont_win_if_all_dots_eaten_but_touching_a_ghost(self):
+        self.assertIs(
+            win(True, False, True),
+            False,
+            msg="don't win if all dots eaten, but touching a ghost"
+        )
+
+    def test_win_if_all_dots_eaten_and_touching_a_ghost_with_a_power_pellet_active(self):
+        self.assertIs(
+            win(True, True, True),
+            True,
+            msg="win if all dots eaten and touching a ghost with a power pellet active"
+        )