add more OOP stuff and get rid of boring bank example

Author: krother

classes/abc.rst

@@ -34,10 +34,9 @@ properties:
        def is_alive(self):
            return True
 
---------------
 
-Exercise
---------
+Exercise 1: Abstract Animals
+----------------------------
 
 Implement the Dog class so that the code below runs.
 
@@ -52,3 +51,31 @@ Implement the Dog class so that the code below runs.
    print(rex.is_alive())
    rex.make_noise()
    print(rex.species())
+
+Exercise 2: Descriptors
+------------------------
+
+The example in :download:`descriptors.py` uses the **descriptor protocol**, a mechanism to control the getting and setting of attributes using object composition. 
+
+Create both valid and invalid instances of the defined class.
+
+
+Exercise 3: Game Objects
+------------------------
+
+Create a superclass `GameObject` for the classes in your game.
+Use the following example code:
+
+.. code:: python3
+
+    from abc import ABC, abstractmethod
+
+    class Command(ABC):
+    
+        def __init__(self, name):
+            self.name = name
+
+        @abstractmethod
+        def executed(self):
+            pass
+

classes/class_dataclass.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Level:
+    name: str
+    level: str
+    level_matrix: list[list[str]] = field(init=False, repr=False)
+
+    def __post_init__(self):
+        self.level_matrix = [list(row) for row in self.level.strip().split()]
+
+    def __repr__(self) -> str:
+        return "\n".join(["".join(row) for row in self.level_matrix])
+
+
+level_one = Level(
+    name="empty level",
+    level="""
+#############
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#############""",
+)
+
+print(level_one)

classes/class_pydantic.py

@@ -0,0 +1,37 @@
+from typing import Annotated
+from pydantic import BaseModel, BeforeValidator, ValidationError
+
+
+def parse_level(level: str) -> list[list[str]]:
+    return [list(row) for row in level.strip().split()]
+
+
+class Level(BaseModel):
+    name: str
+    level: Annotated[list[list[str]], BeforeValidator(parse_level)]
+
+    def __str__(self) -> str:
+        return "\n".join("".join(row) for row in self.level)
+
+    class Config:
+        extra = "forbid"  # Disallow unknown fields
+
+
+level_one = Level(
+    name="empty level",
+    level="""
+#############
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#############""", # type: ignore
+)
+
+print(level_one)

classes/class_typedict.py

@@ -0,0 +1,36 @@
+from typing import TypedDict, List
+
+
+class Level(TypedDict):
+    name: str
+    level: List[List[str]]
+
+
+def create_level(name: str, level: str) -> Level:
+    level_matrix = [list(row) for row in level.strip().split()]
+    return Level(name=name, level=level_matrix)
+
+
+def print_level(level: Level) -> None:
+    print("\n".join("".join(row) for row in level["level"]))
+
+
+level_one = create_level(
+    name="empty level",
+    level="""
+#############
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#############""",
+)
+print(level_one["name"])
+print_level(level_one)
+print(type(level_one))

classes/class_vanilla.py

@@ -0,0 +1,27 @@
+class Level:
+
+    def __init__(self, name: str, level: str):
+        self.name = name
+        self.level = [list(row) for row in level.strip().split()]
+
+    def __repr__(self) -> str:
+        return "\n".join(["".join(row) for row in self.level])
+
+
+level_one = Level(
+    name="empty level",
+    level="""
+#############
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#...........#
+#############""",
+)
+print(level_one)

classes/classes.png

@@ -4,6 +4,8 @@ Classes
 What are classes?
 -----------------
 
+.. figure:: classes.png
+
 Classes are a tool to manage complexity in a program. They group two
 things in a single structural unit: **attributes (data)** and **methods
 (behavior)**.
@@ -13,8 +15,7 @@ so that your main program becomes simple. In my opinion, this way of
 structuring code should be the main motivation to using classes in
 Python.
 
-In this article, you find an example how to use a class to structure
-your code.
+In this chapter, you find an example how to use a class to structure your code.
 
 --------------
 
@@ -27,116 +28,83 @@ To define a class, you need to define three things:
 -  define attributes (variables that belong to the class)
 -  define methods (functions that belong to the class)
 
-In the code below, a class for a bank account is defined:
-
-.. code:: python3
-
-   class Account:
-       """
-       Account of a bank client.
-       """
-       def __init__(self, owner, start_balance=0):
-           self.name = owner
-           self.balance = start_balance
-
-       def deposit(self, amt):
-           self.balance += amt
+In the code below, a class for a **Planet** is defined:
 
-       def withdraw(self, amt):
-           self.balance -= amt
+.. literalinclude:: planet.py
 
-The class ``Account`` contains two attributes (``name`` and ``balance``)
-and two methods (``deposit`` and ``withdraw``).
+The class ``Planet`` contains three attributes
+and two methods.
 
 Note that you need to add the word ``self`` every time you refer to an
 attribute. You also must use ``self`` as the first parameter in every
 method of a class.
 
---------------
-
 Creating Objects
 ----------------
 
 To use a class, you need to create an object from it first. Objects are
 *“live versions”* of a class, the class being an idealized abstration
 (in the sense of `Platos Theory of Forms <https://en.wikipedia.org/wiki/Theory_of_forms>`__).
-If you think of **BankAccount** as a class, the actual accounts of **Ada Lovelace** and **Mahatma Gandi**
+If you think of **Planet** as a class, the actual planets **Earth** and **Pandalor**
 would be the objects of that class.
 
 You can create multiple objects from a class, and each objects has its
-own, independent attributes (e.g. if **BankAccount** has an attribute **balance**,
-then **Ada** and **Mahatma** could have a different amount of money).
-
-Syntactically, you can think of a class as a function that returns
+own, independent attributes. Syntactically, you can think of a class as a function that returns
 objects. (This is a gross oversimplification to what textbooks on
 classes say, but in Python it is more or less what happens).
 
-To create ``Account`` objects, you need to call the class. Creating an
+To create ``Planet`` objects, you need to call the class. Creating an
 object will automatically call the constructor ``__init__(self)`` with
 the parameters supplied.
 
 .. code:: python3
 
-   a = Account('Ada Lovelace', 1234)
-   m = Account('Mahatma Gandhi', 10)
+   earth = Planet(name="Earth", description="the blue planet")
+   pandalor = Planet(name="Pandalor", description="home of the space pandas")
+   arcturus = Planet(name="Arcturus", description="an icy planet, home of penguins")
+
 
 Then you can access the attributes like any variable using the dot (``.``) syntax:
 
 .. code:: python3
 
-   print(a.name)
-   print(m.balance)
+   print(earth.name)
+   print(earth.balance)
+
+Exercise: Methods
+-----------------
 
 And you can call methods in a similar way:
 
 .. code:: python3
 
-   a.deposit(100)
-   a.withdraw(10)
-   print(a.balance)
+   earth.add_connection(pandalor)
+   earth.add_connection(arcturus)
 
-Note that these methods modify the state of *Adas* account object, but
-not *Mahatmas*.
+   earth.show_connections()
 
---------------
-
-Making classes printable
-------------------------
-
-One disadvantage of classes is that when you print an object, you will
-see something like this:
-
-::
-
-   <__main__.Account at 0x7f64519d8438>
+Note that these methods modify the state of the planet *Earth*, but not the other two.
 
-A good workaround is to add a special method, ``__repr__(self)`` to the
-class that returns a string. This method will be called every time a
-string representation is needed: when printing and object, when an
-object appears inside a list or in error messages.
+Implement the `show_connections()` method using the code from the program `space_game.py`.
 
-Typically, you would build a short string in ``__repr__(self)`` that
-describes the object:
+Exercise: Refactor using classes
+--------------------------------
 
-.. code:: python3
-
-       def __repr__(self):
-           return f"<Account of '{self.name}' with {self.balance} galactic credits>"
-
-With this method defined, the instruction
-
-.. code:: python3
+Simplify `space_game.py` using the `Planet` class.
 
-   print(a)
 
-would result in the output
+Four Ways to create classes
+---------------------------
 
-::
+Python knows multiple flavors of defining and using classes.
+These are recent developments (~2018+), strongly relying on the availability of **Type Hints**.
 
-   <Account of 'Ada Lovelace' with 1324 galactic credits>"
+Execute and examine the following code examples, defining a level for a point-eating game:
 
-It is a good idea to implement ``__repr__(self)`` as the first method in
-a new class.
+- :download:`class_vanilla.py`
+- :download:`class_typedict.py`
+- :download:`class_dataclass.py`
+- :download:`class_pydantic.py`
 
 --------------
 
@@ -151,9 +119,9 @@ the same purpose equally well.
 
 Another motivation for using classes you find in textbooks is
 **encapsulation**, isolating parts of your program from the rest.
-Encapsulation does not exist in Python (e.g. you cannot declare parts of
+Encapsulation does not exist in Python (e.g. you cannot declare parts of
 a class as ``private`` in a way that cannot be circumvented). If you
-depend on your code being strictly isolated from other parts (e.g. in a
+depend on your code being strictly isolated from other parts (e.g. in a
 security-critical application or when organizing a very large program),
 **consider other programming languages than Python.**