Classes and objects, part 2

Make a day17 folder for today’s files, open it in your editor, and run each script from its terminal, as on earlier days. Several of today’s programs import Day 16’s BankAccount class, so save the file bank.py below into day17 first; the scripts that import it sit beside it, exactly like the modules you split up on Day 13.

"""The BankAccount class from Day 16, ready to import."""


class BankAccount:
    """An account with an owner and a balance that cannot go negative."""

    def __init__(self, owner, balance=0):
        if balance < 0:
            raise ValueError(f"opening balance cannot be negative, not {balance}")
        self.owner = owner
        self.balance = balance

    def deposit(self, amount):
        if amount <= 0:
            raise ValueError(f"deposit must be more than 0, not {amount}")
        self.balance += amount

    def withdraw(self, amount):
        if amount <= 0:
            raise ValueError(f"withdrawal must be more than 0, not {amount}")
        if amount > self.balance:
            raise ValueError(f"only {self.balance:.2f} available, not {amount:.2f}")
        self.balance -= amount

    def __str__(self):
        return f"{self.owner}'s account: {self.balance:.2f}"

Yesterday you wrote classes from scratch. Today you learn the tools that make classes fit together and fit into Python. You will build a new class on top of an existing one instead of copying it, teach your objects to answer ==, <, and len(), make attributes that work themselves out when you read them, and let Python write the routine parts of a class for you. The day ends with a question that matters as much as any syntax: when is a class worth writing at all?

The bank wants a savings account. A savings account is a bank account in every way (it has an owner and a balance, and it takes deposits and withdrawals with the same rules), plus one extra ability: it can add interest. With only Day 16’s tools, you would copy the whole BankAccount class, rename it SavingsAccount, and add one method. Now there are two copies of the deposit and withdrawal rules. If you later find a bug in withdraw, you have to fix it twice, and sooner or later someone fixes only one copy.

You have actually done the better thing already. On Day 15 you wrote class TaskNumberError(Exception): and got a working exception type in two lines, without writing any of the code that lets an exception be raised, caught, and printed. The (Exception) part told Python: “make this new class a kind of Exception, and give it everything an Exception already has.” That idea has a name.

Inheritance means defining a new class as an extended version of an existing one. The new class automatically has every method and class attribute of the existing class, and you add only what is different. The existing class is called the parent class (also the base class or superclass), and the new one is the child class (also the subclass). The child inherits from the parent.

class SavingsAccount(BankAccount):
    def add_interest(self, rate):
        self.deposit(round(self.balance * rate, 2))

• class SavingsAccount starts a class definition as on Day 16.
• (BankAccount) in parentheses names the parent. Leave it out and you get an ordinary class with no deposit, withdraw, or anything else.
• The body holds only what is new: one method. __init__, deposit, withdraw, and __str__ all come from BankAccount.

from bank import BankAccount


class SavingsAccount(BankAccount):
    def add_interest(self, rate):
        self.deposit(round(self.balance * rate, 2))


savings = SavingsAccount("Ana", 200)
savings.deposit(50)
savings.add_interest(0.02)
print(savings)
print(savings.owner, savings.balance)

plain = BankAccount("Ben", 40)
print(isinstance(savings, SavingsAccount), isinstance(savings, BankAccount))
print(isinstance(plain, SavingsAccount), isinstance(plain, object))

Ana's account: 255.00
Ana 255.0
True True
False True

Lines 15 to 17 introduce a built-in function you need with inheritance. isinstance(obj, SomeClass) returns True if obj is an instance of SomeClass or of any child of it. A child object counts as an instance of its parent, because a savings account really is a bank account. The reverse is not true: plain, an ordinary BankAccount, is not a SavingsAccount. That is why inheritance is often described as an “is-a” relationship: a SavingsAccount is a BankAccount, and a TaskNumberError is an Exception.

The last True on line 17 shows that even BankAccount has a parent. Every class you write without parentheses quietly inherits from a built-in class called object. That is where Day 16’s defaults came from: the <__main__.Player object at 0x...> text and the “same object” meaning of == are methods that every class inherits from object until it defines its own.

Because a child is also an instance of its parent, code written for the parent keeps working for the child. Here is the same idea with the exception classes you already know. AmountError inherits from the built-in ValueError, so an except ValueError clause catches it too:

class AmountError(ValueError):
    pass


def check_amount(amount):
    if amount <= 0:
        raise AmountError(f"amount must be more than 0, not {amount}")
    return amount


for text in ["25", "-5", "ten"]:
    try:
        print(check_amount(int(text)))
    except ValueError as error:
        print(f"Refused {text}: {error}")

25
Refused -5: amount must be more than 0, not -5
Refused ten: invalid literal for int() with base 10: 'ten'

-5 raises an AmountError, which is a kind of ValueError, so except ValueError catches it. "ten" makes int() raise a plain ValueError, which the same clause catches. An except clause catches the type it names and every child of that type.

from bank import BankAccount


class SavingsAccount(BankAccount):
    def add_interest(self, rate):
        self.deposit(round(self.balance * rate, 2))


accounts = [SavingsAccount("Ana", 200), BankAccount("Ben", 40)]
for account in accounts:
    account.add_interest(0.02)
    print(account)

Ana's account: 204.00
Traceback (most recent call last):
  File ".../day17/one_way.py", line 11, in <module>
    account.add_interest(0.02)
    ^^^^^^^^^^^^^^^^^^^^
AttributeError: 'BankAccount' object has no attribute 'add_interest'

from bank import BankAccount


class SavingsAccount(BankAccount):
    def add_interest(self, rate):
        self.deposit(round(self.balance * rate, 2))


accounts = [SavingsAccount("Ana", 200), BankAccount("Ben", 40)]
for account in accounts:
    if isinstance(account, SavingsAccount):
        account.add_interest(0.02)
    print(account)

Ana's account: 204.00
Ben's account: 40.00

class Ticket:
    def __init__(self, seat, price):
        self.seat = seat
        self.price = price

    def describe(self):
        return f"Seat {self.seat}: {self.price}"


class VipTicket(Ticket):
    def lounge(self):
        return f"Seat {self.seat} may use the lounge"


regular = Ticket("B4", 12)
vip = VipTicket("A1", 30)
print(vip.describe())
print(vip.lounge())
print(isinstance(vip, Ticket), isinstance(regular, VipTicket))

Seat A1: 30
Seat A1 may use the lounge
True False

The savings account from 17.1 takes the interest rate as an argument every time. A real savings account has its own rate, agreed when it is opened, so the rate belongs in an instance attribute set in __init__. That means SavingsAccount needs an __init__ of its own, with a rate parameter.

There is a catch. Defining a method in the child with the same name as one in the parent replaces it for the child: the name lookup from 17.1 finds the child’s version first and stops. So the child’s __init__ runs instead of BankAccount.__init__, and the parent’s work (checking the opening balance, storing the owner and balance) would not happen. You do not want to copy that work into the child, which is the duplication inheritance was supposed to remove. You want the child’s __init__ to say “first do everything the parent’s __init__ does, then add the rate.”

The built-in super() gives you exactly that. Inside a method, super() means “the parent class, working on this same object”. super().__init__(owner, balance) calls the parent’s __init__ on the object being set up, with those arguments.

from bank import BankAccount


class SavingsAccount(BankAccount):
    def __init__(self, owner, balance=0, rate=0.02):
        super().__init__(owner, balance)
        self.rate = rate

    def add_interest(self):
        self.deposit(round(self.balance * self.rate, 2))


savings = SavingsAccount("Ana", 200, rate=0.05)
savings.add_interest()
print(savings, savings.rate)
try:
    SavingsAccount("Cy", -10)
except ValueError as error:
    print(f"Refused: {error}")

Ana's account: 210.00 0.05
Refused: opening balance cannot be negative, not -10

The second half of the program shows why calling the parent matters. SavingsAccount("Cy", -10) runs the child’s __init__, which calls the parent’s, and the parent’s check on line 8 of bank.py refuses the negative balance. The rule “an opening balance cannot be negative” is written once, in BankAccount, and every kind of account obeys it.

You may also see the parent named directly, BankAccount.__init__(self, owner, balance), which is Day 16’s long form of a method call (and there you do pass self). It works, but super() is the usual choice: it does not repeat the parent’s name, so the line stays correct if the parent class is ever renamed.

from bank import BankAccount


class SavingsAccount(BankAccount):
    def __init__(self, owner, balance=0, rate=0.02):
        self.rate = rate

    def add_interest(self):
        self.deposit(round(self.balance * self.rate, 2))


savings = SavingsAccount("Ana", 200)
print(savings.rate)
savings.add_interest()

0.02
Traceback (most recent call last):
  File ".../day17/forgot_super.py", line 14, in <module>
    savings.add_interest()
    ~~~~~~~~~~~~~~~~~~~~^^
  File ".../day17/forgot_super.py", line 9, in add_interest
    self.deposit(round(self.balance * self.rate, 2))
                       ^^^^^^^^^^^^
AttributeError: 'SavingsAccount' object has no attribute 'balance'

class Employee:
    def __init__(self, name, hourly):
        self.name = name
        self.hourly = hourly

    def pay(self, hours):
        return self.hourly * hours


class Manager(Employee):
    def __init__(self, name, hourly, team):
        super().__init__(name, hourly + 5)
        self.team = team


lead = Manager("Ana", 20, ["Ben", "Cy"])
print(lead.name, lead.hourly, len(lead.team))
print(lead.pay(10))

Ana 25 2
250

class Pet:
    def __init__(self, name):
        self.name = name.title()


class Dog(Pet):
    def __init__(self, name, breed):
        self.breed = breed


rex = Dog("rex", "beagle")
print(rex.breed)
print(f"{rex.name} the {rex.breed}")

AttributeError: 'Dog' object has no attribute 'name'

class Pet:
    def __init__(self, name):
        self.name = name.title()


class Dog(Pet):
    def __init__(self, name, breed):
        super().__init__(name)
        self.breed = breed


rex = Dog("rex", "beagle")
print(rex.breed)
print(f"{rex.name} the {rex.breed}")

beagle
Rex the beagle

Some accounts charge a fee: every withdrawal costs an extra 1.50. A fee account is still a bank account, so inheritance fits, but its withdrawal works differently. 17.2 showed that a child method with the same name as a parent method replaces it. Doing this on purpose, to change how a child behaves, is called overriding the method. The child’s version is the override.

An override does not have to start from nothing. Inside it, super().withdraw(...) still reaches the parent’s version, so the child can do its own part and hand the rest to the parent.

from bank import BankAccount


class FeeAccount(BankAccount):
    fee = 1.5

    def withdraw(self, amount):
        super().withdraw(amount + self.fee)

    def __str__(self):
        return f"{super().__str__()} (fee {self.fee:.2f} per withdrawal)"


accounts = [BankAccount("Ana", 50), FeeAccount("Ben", 50)]
for account in accounts:
    account.withdraw(10)
    print(account)

Ana's account: 40.00
Ben's account: 38.50 (fee 1.50 per withdrawal)

One line of code, account.withdraw(10), ran two different methods, chosen by each object’s class at the moment of the call. This is polymorphism (Greek for “many forms”): the same method call works on objects of different classes, and each object answers in its own way. You have relied on it since Day 1 without knowing: print works on ints, strings, lists, and your own objects, because each type has its own __str__, and print just asks.

Polymorphism lets you write a loop or a function once and use it with kinds of objects that did not exist when you wrote it. To plan for that, a parent class can define a method that only its children are meant to fill in. The parent’s version raises NotImplementedError, a built-in exception that means “this has to be provided by a child class”:

class Notifier:
    def send(self, text):
        raise NotImplementedError("each kind of notifier must define send()")


class EmailNotifier(Notifier):
    def __init__(self, address):
        self.address = address

    def send(self, text):
        return f"Email to {self.address}: {text}"


class TextNotifier(Notifier):
    def __init__(self, phone):
        self.phone = phone

    def send(self, text):
        return f"Text to {self.phone}: {text[:20]}"


class Banner:
    def send(self, text):
        return f"Banner: {text.upper()}"


notifiers = [EmailNotifier("ana@example.com"), TextNotifier("555-0142"), Banner()]
for notifier in notifiers:
    print(notifier.send("Your library book is due tomorrow"))

Email to ana@example.com: Your library book is due tomorrow
Text to 555-0142: Your library book is
Banner: YOUR LIBRARY BOOK IS DUE TOMORROW

• Notifier (lines 1 to 3) is a parent that only says what every notifier can do: send(text). Its own send refuses to run.
• EmailNotifier and TextNotifier each override send. A text message is short, so TextNotifier keeps only the first 20 characters with a slice (Day 3).
• Banner (lines 22 to 24) does not inherit from Notifier at all, yet the loop works with it too. Python never checks an object’s class before calling a method; it only looks the name up. Any object that has a send method works in this loop. This style, caring about what an object can do rather than what class it is, is called duck typing, from the saying “if it walks like a duck and quacks like a duck, it is a duck.”

Inheritance is still useful here: the parent documents what every notifier must provide, and its NotImplementedError catches a notifier that forgot.

class Notifier:
    def send(self, text):
        raise NotImplementedError("each kind of notifier must define send()")


class PopupNotifier(Notifier):
    def sned(self, text):
        return f"Popup: {text}"


popup = PopupNotifier()
print(popup.send("Practice starts at 4"))

Traceback (most recent call last):
  File ".../day17/override_typo.py", line 12, in <module>
    print(popup.send("Practice starts at 4"))
          ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../day17/override_typo.py", line 3, in send
    raise NotImplementedError("each kind of notifier must define send()")
NotImplementedError: each kind of notifier must define send()

class Price:
    def __init__(self, amount):
        self.amount = amount

    def final(self):
        return self.amount

    def label(self):
        return f"{self.final():.2f}"


class Sale(Price):
    def final(self):
        return self.amount * 0.8


class Clearance(Sale):
    def final(self):
        return super().final() - 1


for price in [Price(10), Sale(10), Clearance(10)]:
    print(price.label())

10.00
8.00
7.00

Inheritance is not the only way to build a class out of other classes. Think about a bank branch. It holds many accounts, but a branch is not an account; you would never deposit money “into the branch” the way you deposit into an account. The branch has accounts. When one object keeps other objects as its attributes and uses them to do its job, that is composition, a “has-a” relationship. You have already done it: Day 16’s Cart kept a dictionary of prices, and its library kept lists of Book objects.

from bank import BankAccount


class Branch:
    def __init__(self, city):
        self.city = city
        self.accounts = []

    def open_account(self, owner, deposit):
        account = BankAccount(owner, deposit)
        self.accounts.append(account)
        return account

    def total(self):
        return sum(account.balance for account in self.accounts)


branch = Branch("Springfield")
ana = branch.open_account("Ana", 50)
branch.open_account("Ben", 20)
ana.deposit(30)
print(f"{branch.city}: {len(branch.accounts)} accounts, {branch.total():.2f} in total")
print(ana)

Springfield: 2 accounts, 100.00 in total
Ana's account: 80.00

Why not always inherit, since it saves typing? Because a child gets everything the parent has, wanted or not. Here is a playlist that must never hold the same song twice. Inheriting from the built-in list class looks convenient (Python’s built-in types are classes, so you can inherit from them):

class Playlist(list):
    def add(self, song):
        if song in self:
            raise ValueError(f"{song} is already on the playlist")
        self.append(song)


road_trip = Playlist()
road_trip.add("Holiday")
road_trip.add("Sunrise")
road_trip.append("Holiday")
road_trip.insert(0, 42)
print(road_trip)

[42, 'Holiday', 'Sunrise', 'Holiday']

add refuses duplicates, but a Playlist is a list, so it also has append, insert, extend, and every other list method. Line 11 adds a duplicate with append, and line 12 even puts a number in front with insert. The rule lives in one method, and a dozen other methods walk around it. Composition gives the playlist a list instead, and offers only the operations that keep the rule:

class Playlist:
    def __init__(self, name):
        self.name = name
        self.songs = []

    def add(self, song):
        if song in self.songs:
            raise ValueError(f"{song} is already on {self.name}")
        self.songs.append(song)

    def __str__(self):
        return f"{self.name}: {', '.join(self.songs)}"


road_trip = Playlist("Road trip")
road_trip.add("Holiday")
road_trip.add("Sunrise")
try:
    road_trip.add("Holiday")
except ValueError as error:
    print(f"Not added: {error}")
print(road_trip)
try:
    road_trip.append("Holiday")
except AttributeError as error:
    print(error)

Not added: Holiday is already on Road trip
Road trip: Holiday, Sunrise
'Playlist' object has no attribute 'append'

Now add is the only way in (line 6), so the rule always holds, and append simply does not exist on a playlist (line 24). The list is still there doing the storing, in self.songs; the playlist decides what the outside world may do with it.

Two questions help you choose:

Inheritance needs both of the first two answers to be yes. When you are unsure, choose composition. It is the safer default: it keeps the classes separate, so changing one does not quietly change the other, and the outer class shows only the methods you chose.

Day 16 ended with a puzzle: two Player objects with the same name and score were not ==, because for your own classes == starts out meaning “same object”. You now know where that meaning comes from: == is a method that every class inherits from object. And 17.3 showed that a child can override any inherited method. So you can override equality.

When Python works out a == b, it calls a.__eq__(b) and uses what the method returns. __eq__ is another dunder method (Day 16): you write it, and Python calls it for you whenever == is used. It takes self and one more parameter, by convention named other, for the object on the right of ==. It returns True or False.

You decide what “equal” means. For points on a game board, two points are equal when they are at the same place: same x and same y.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return self.x == other.x and self.y == other.y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"


start = Point(2, 3)
same_spot = Point(2, 3)
print(start == same_spot, start is same_spot)
print(start != Point(3, 2))
visited = [Point(0, 0), Point(2, 3), Point(5, 1)]
print(Point(2, 3) in visited, visited.index(Point(5, 1)))
visited.remove(Point(0, 0))
print(visited)

True False
True
True 2
[Point(2, 3), Point(5, 1)]

Equality does not have to use every attribute. A library may own two copies of the same book, one new and one worn. For the catalog, they are the same book, because they have the same catalog code. So __eq__ compares only the code. This version also handles a question the first one ignored: what if the other value is not a Book at all? Look at what the first Point does when compared with a tuple:

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return self.x == other.x and self.y == other.y


print(Point(2, 3) == Point(2, 3))
print(Point(2, 3) == (2, 3))

True
Traceback (most recent call last):
  File ".../day17/point_tuple.py", line 11, in <module>
    print(Point(2, 3) == (2, 3))
          ^^^^^^^^^^^^^^^^^^^^^
  File ".../day17/point_tuple.py", line 7, in __eq__
    return self.x == other.x and self.y == other.y
                     ^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'tuple' object has no attribute 'x'

Asking “is this point equal to that tuple?” should simply be False, not a crash. The careful pattern checks the other value’s type first:

class Book:
    def __init__(self, title, code, condition):
        self.title = title
        self.code = code
        self.condition = condition

    def __eq__(self, other):
        if not isinstance(other, Book):
            return NotImplemented
        return self.code == other.code


copy_1 = Book("Holes", "B-04", "new")
copy_2 = Book("Holes", "B-04", "worn")
wonder = Book("Wonder", "B-17", "new")
print(copy_1 == copy_2, copy_1 == wonder)
print(copy_1 == "Holes", copy_1 != (2, 3))

True False
False True

• Lines 8 and 9: if other is not a Book, the method returns NotImplemented, a special built-in value that means “I do not know how to compare with that.” It is not an error. Python then gives the other value a chance to compare itself, and if neither side knows, == falls back to identity, which is False for two different objects.
• Line 16: the two copies of Holes have different conditions but the same code, so they are equal. Wonder has a different code.
• Line 17: comparing a book with a string or a tuple now gives False for == and True for !=, with no crash.

NotImplemented (a value you return) is not the same thing as NotImplementedError from 17.3 (an exception you raise). Only __eq__ and its relatives return NotImplemented.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return self.x == other.x and self.y == other.y


visited = [Point(0, 0), Point(2, 3)]
print(len(visited))
seen = {Point(0, 0), Point(2, 3)}

2
Traceback (most recent call last):
  File ".../day17/point_set.py", line 12, in <module>
    seen = {Point(0, 0), Point(2, 3)}
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: cannot use 'Point' as a set element (unhashable type: 'Point')

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return self.x == other.x and self.y == other.y


visited = [Point(0, 0), Point(2, 3), Point(0, 0)]
seen = {(point.x, point.y) for point in visited}
print(len(seen), (0, 0) in seen)

2 True

class Coin:
    def __init__(self, value, year):
        self.value = value
        self.year = year

    def __eq__(self, other):
        if not isinstance(other, Coin):
            return NotImplemented
        return self.value == other.value


purse = [Coin(25, 2019), Coin(10, 2020), Coin(25, 2024)]
print(Coin(25, 1999) in purse)
print(purse.count(Coin(25, 2000)), purse.index(Coin(10, 1990)))
print(purse[0] == purse[2], purse[0] is purse[2], purse[0] == 25)

True
2 1
True False False

class Card:
    def __init__(self, rank, suit):
        self.rank = rank
        self.suit = suit

    def __eq__(self, other):
        self.rank == other.rank and self.suit == other.suit


print(Card("Q", "hearts") == Card("Q", "hearts"))

class Card:
    def __init__(self, rank, suit):
        self.rank = rank
        self.suit = suit

    def __eq__(self, other):
        return self.rank == other.rank and self.suit == other.suit


print(Card("Q", "hearts") == Card("Q", "hearts"))

True

Ask Python to sort a list of your objects, and it does not know how:

class Runner:
    def __init__(self, name, time):
        self.name = name
        self.time = time


runners = [Runner("Ana", 31), Runner("Ben", 28), Runner("Cy", 35)]
print(sorted(runners))

Traceback (most recent call last):
  File ".../day17/runners_no_lt.py", line 8, in <module>
    print(sorted(runners))
          ~~~~~~^^^^^^^^^
TypeError: '<' not supported between instances of 'Runner' and 'Runner'

The message gives away how sorting works: sorted compares items two at a time with <. Day 10 worked around this with key=, telling sorted to compare a value taken from each item. That is still the right tool for a one-off order. But if your objects have one natural order (runners by finishing time, versions by number), you can teach the class itself what < means. a < b calls a.__lt__(b) (“lt” is short for “less than”), and __lt__ returns True if self should come before other.

class Runner:
    def __init__(self, name, time):
        self.name = name
        self.time = time

    def __lt__(self, other):
        return self.time < other.time

    def __repr__(self):
        return f"Runner({self.name!r}, {self.time})"


runners = [Runner("Ana", 31), Runner("Ben", 28), Runner("Cy", 35)]
print(sorted(runners))
print(min(runners), max(runners))
print(runners[0] < runners[1], runners[0] > runners[1])
runners.sort(reverse=True)
print(runners)

[Runner('Ben', 28), Runner('Ana', 31), Runner('Cy', 35)]
Runner('Ben', 28) Runner('Cy', 35)
False True
[Runner('Cy', 35), Runner('Ana', 31), Runner('Ben', 28)]

__lt__ gives you < and >, but not <= or >=. Those are separate methods (__le__ and __ge__), and this class does not define them:

class Runner:
    def __init__(self, name, time):
        self.name = name
        self.time = time

    def __lt__(self, other):
        return self.time < other.time


ana = Runner("Ana", 31)
ben = Runner("Ben", 28)
print(ben < ana)
print(ben <= ana)

True
Traceback (most recent call last):
  File ".../day17/runner_le.py", line 13, in <module>
    print(ben <= ana)
          ^^^^^^^^^^
TypeError: '<=' not supported between instances of 'Runner' and 'Runner'

For sorting, min, and max, __lt__ is all you need. 17.8 shows a way to get all four comparisons at once.

The other special method today answers “how big is it?” len(obj) calls obj.__len__(), and __len__ must return a whole number of 0 or more. It makes sense for objects that hold a collection of things, like the playlist from 17.4:

class Playlist:
    def __init__(self, name):
        self.name = name
        self.songs = []

    def add(self, song):
        self.songs.append(song)

    def __len__(self):
        return len(self.songs)


road_trip = Playlist("Road trip")
print(len(road_trip), bool(road_trip))
if not road_trip:
    print("Road trip is empty")
road_trip.add("Holiday")
road_trip.add("Sunrise")
print(len(road_trip), bool(road_trip))

0 False
Road trip is empty
2 True

__len__ delegates to the list inside (composition again): the playlist’s length is the number of songs. Defining __len__ has a second effect. Day 4 taught that an empty string or list counts as False in an if. Python decides that for your objects too, using __len__: an object whose length is 0 is falsy. So bool(road_trip) is False while the playlist is empty, and if not road_trip: reads like English. After two songs it is truthy.

Here are the special methods so far, and what triggers each:

class Playlist:
    def __init__(self, name):
        self.name = name
        self.seconds = []

    def add(self, seconds):
        self.seconds.append(seconds)

    def __len__(self):
        return sum(self.seconds) / 60


road_trip = Playlist("Road trip")
road_trip.add(200)
road_trip.add(250)
print(len(road_trip))

Traceback (most recent call last):
  File ".../day17/len_float.py", line 16, in <module>
    print(len(road_trip))
          ~~~^^^^^^^^^^^
TypeError: 'float' object cannot be interpreted as an integer

class Box:
    def __init__(self, label, weight):
        self.label = label
        self.weight = weight

    def __lt__(self, other):
        return self.weight < other.weight

    def __len__(self):
        return len(self.label)

    def __repr__(self):
        return self.label


boxes = [Box("books", 12), Box("lamp", 4), Box("kettle", 9)]
print(sorted(boxes))
print(max(boxes), len(boxes), len(boxes[0]))
print(sorted(boxes, key=len))

[lamp, kettle, books]
books 3 5
[lamp, books, kettle]

A rectangle’s area depends on its width and height. A natural first try stores it in __init__, next to them:

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height
        self.area = width * height


room = Rectangle(4, 3)
print(room.area)
room.width = 5
print(room.width, room.area)

12
5 12

The width changed to 5, but the area still says 12, which is now wrong (5 × 3 is 15). self.area was worked out once, when the object was made, and nothing updates it. A value copied from other attributes goes stale as soon as they change.

A method fixes that, because it works the area out each time: room.area(). But the area feels like a fact about the rectangle, like its width, not like an action. Python lets you have both: a method that is read like an attribute. Put the line @property directly above the method’s def:

    @property
    def area(self):
        return self.width * self.height

A line that starts with @ and sits right above a def is a decorator: it changes what the def makes. Day 18 shows how decorators work and how to write your own. Today you only use two that come with Python. @property turns the method into a property: an attribute whose value is computed by running the method each time the attribute is read. You read it with no parentheses, room.area, and Python calls the method for you, the same way it calls __str__ for print.

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height

    @property
    def area(self):
        return self.width * self.height

    @property
    def is_square(self):
        return self.width == self.height


room = Rectangle(4, 3)
print(room.area, room.is_square)
room.width = 3
print(room.area, room.is_square)
try:
    room.area = 100
except AttributeError as error:
    print(error)

12 False
9 True
property 'area' of 'Rectangle' object has no setter

Being read-only solves a problem from Day 16. The bank account’s rules hold only if every change goes through deposit and withdraw, but any code could still write account.balance = -5. With a property, outside code can read the balance but not assign it:

class BankAccount:
    def __init__(self, owner, balance=0):
        if balance < 0:
            raise ValueError(f"opening balance cannot be negative, not {balance}")
        self.owner = owner
        self._balance = balance

    @property
    def balance(self):
        return self._balance

    def deposit(self, amount):
        if amount <= 0:
            raise ValueError(f"deposit must be more than 0, not {amount}")
        self._balance += amount


account = BankAccount("Ana", 50)
account.deposit(25)
print(account.balance)
try:
    account.balance = -5
except AttributeError as error:
    print(f"Refused: {error}")
print(account.balance)

75
Refused: property 'balance' of 'BankAccount' object has no setter
75

• Line 6 stores the real number in an attribute named _balance. A name that starts with one underscore is a convention, not a rule: it tells other programmers “this is internal; use it only inside the class.” Python does not stop anyone from reading or changing _balance, but anyone who does has been warned.
• Lines 8 to 10 make balance a property that just returns _balance. Outside code reads account.balance exactly as before.
• Line 15: the methods change _balance, the internal attribute.
• Line 22: assigning account.balance is refused, so the balance can change only through the methods, where the checks are.

When should something be a property rather than a method? Use a property for a value that describes the object, takes no arguments, is quick to work out, and changes nothing (area, is_square, a full name built from first and last names). Use a method for an action (deposit), for anything that needs arguments (withdraw(amount)), or for slow work, because a reader expects reading an attribute to be instant.

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height

    @property
    def area(self):
        return self.width * self.height


room = Rectangle(4, 3)
print(room.area())

Traceback (most recent call last):
  File ".../day17/property_call.py", line 12, in <module>
    print(room.area())
          ~~~~~~~~~^^
TypeError: 'int' object is not callable

class Thermometer:
    def __init__(self, celsius):
        self.celsius = celsius

    @property
    def fahrenheit(self):
        return self.celsius * 9 / 5 + 32

    @property
    def is_freezing(self):
        return self.celsius <= 0


reading = Thermometer(25)
print(reading.fahrenheit, reading.is_freezing)
reading.celsius = -10
print(reading.fahrenheit, reading.is_freezing)

77.0 False
14.0 True

Many classes mostly hold data. A point, a song, a task, a grade: each has a few attributes and not much behavior. Yet a well-behaved data-holding class needs the same routine methods every time. Here is a point written by hand with __init__, a __repr__ in the Day 16 style, and a careful __eq__ from 17.5:

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __repr__(self):
        return f"Point(x={self.x!r}, y={self.y!r})"

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return self.x == other.x and self.y == other.y


print(Point(2, 3), Point(2, 3) == Point(2, 3))

Point(x=2, y=3) True

Twelve lines for two attributes, and x and y each appear six times. Add a field and you must update three methods; forget one and the class is quietly wrong. Python can write these methods for you. The module dataclasses in the standard library provides a decorator, @dataclass, that goes above a class line:

from dataclasses import dataclass


@dataclass
class Point:
    x: int
    y: int


start = Point(2, 3)
print(start)
print(start == Point(2, 3), start.x + start.y)
print(Point(y=1, x=4))
print(Point("two", "three"))

Point(x=2, y=3)
True 5
Point(x=4, y=1)
Point(x='two', y='three')

A data class is still a class. You can give fields default values, and add methods and properties exactly as before:

from dataclasses import asdict, dataclass


@dataclass
class Song:
    title: str
    artist: str
    seconds: int = 180

    @property
    def minutes(self):
        return round(self.seconds / 60, 1)


hit = Song("Sunrise", "The Larks", 210)
demo = Song("Untitled", "The Larks")
print(hit)
print(demo.seconds, hit.minutes)
print(hit == Song("Sunrise", "The Larks", 210))
print(asdict(demo))

Song(title='Sunrise', artist='The Larks', seconds=210)
180 3.5
True
{'title': 'Untitled', 'artist': 'The Larks', 'seconds': 180}

• Line 8 gives seconds a default, so Song("Untitled", "The Larks") on line 16 gets 180, like a default parameter value (Day 10).
• Lines 10 to 12 are a property from 17.7: 210 / 60 = 3.5 minutes.
• Line 20: the dataclasses module also has a function asdict(), which turns a data class object into a dictionary of its fields. That is exactly what json.dump needs (Day 14).

Fields with defaults must come after fields without them, for the same reason as in a def line: the generated __init__ lists the fields in order, and a parameter without a default cannot follow one with a default.

from dataclasses import dataclass


@dataclass
class Song:
    title: str
    seconds: int = 180
    artist: str

Traceback (most recent call last):
  File ".../day17/dataclass_order.py", line 4, in <module>
    @dataclass
     ^^^^^^^^^
  ...
TypeError: non-default argument 'artist' follows default argument 'seconds'

The ... stands for several lines from inside the dataclasses module; the first and last lines are the ones that matter. Notice that the error comes when the class is defined, before any object is made. Move artist above seconds.

Finally, @dataclass(order=True) also writes __lt__, __le__, __gt__, and __ge__. They compare two objects like tuples of their fields (Day 10): first fields first, and the next field only to break a tie.

from dataclasses import dataclass


@dataclass(order=True)
class Grade:
    score: int
    name: str


grades = [Grade(88, "Ben"), Grade(95, "Ana"), Grade(88, "Ali")]
print(sorted(grades))
print(max(grades).name)

[Grade(score=88, name='Ali'), Grade(score=88, name='Ben'), Grade(score=95, name='Ana')]
Ana

The two 88s tie on score, so name decides: 'Ali' comes before 'Ben'. Put the fields in the order you want them compared.

from dataclasses import dataclass


@dataclass
class Recipe:
    name: str
    ingredients: list = []


soup = Recipe("Tomato soup")

Traceback (most recent call last):
  File ".../day17/list_default.py", line 4, in <module>
    @dataclass
     ^^^^^^^^^
  ...
ValueError: mutable default <class 'list'> for field ingredients is not allowed: use default_factory

from dataclasses import dataclass, field


@dataclass
class Recipe:
    name: str
    ingredients: list = field(default_factory=list)


soup = Recipe("Tomato soup")
salad = Recipe("Green salad")
soup.ingredients.append("tomatoes")
print(soup)
print(salad)

Recipe(name='Tomato soup', ingredients=['tomatoes'])
Recipe(name='Green salad', ingredients=[])

from dataclasses import dataclass


@dataclass
class Order:
    item: str
    quantity: int = 1
    price: float = 2.5

    def total(self):
        return self.quantity * self.price


first = Order("bagel", 3)
second = Order("bagel", price=3.0)
print(first)
print(first.total(), second.total())
print(first == Order("bagel", 3, 2.5), first == second)

Order(item='bagel', quantity=3, price=2.5)
7.5 3.0
True False

from dataclasses import dataclass


class Pet:
    name: str
    age: int = 1


rex = Pet("Rex", 3)
print(rex)

TypeError: Pet() takes no arguments

from dataclasses import dataclass


@dataclass
class Pet:
    name: str
    age: int = 1


rex = Pet("Rex", 3)
print(rex)

Pet(name='Rex', age=3)

You now have a lot of tools: plain functions, dictionaries, classes, inheritance, data classes. Having them does not mean using all of them every time. More structure is not better in itself; the best code is the simplest code that keeps the program correct and easy to change. So, before writing a class, ask what it would buy you.

Some jobs need nothing more than a function and a dictionary. Counting words takes some text and gives back counts. No data has to be kept between calls, and there are no rules to protect:

def count_words(text):
    counts = {}
    for word in text.lower().split():
        counts[word] = counts.get(word, 0) + 1
    return counts


print(count_words("The cat saw the dog"))

{'the': 2, 'cat': 1, 'saw': 1, 'dog': 1}

A WordCounter class here would add a name, an __init__, and a method call, and do nothing a function cannot. On the other hand, the bank account earned its class: it keeps data between operations, it has rules that must always hold (the balance cannot go negative), several operations work on the same data, and the program makes many accounts of the same shape. Day 16 started from exactly this kind of signal: several functions that all took the same dictionary, with nothing stopping a misspelled key.

The table is a guide, not a law. A program often starts with a function and a dictionary and grows into a class when a second and third function appear that all work on the same data. That is a good moment to switch, not a failure to plan.

class TipCalculator:
    def __init__(self, bill, percent):
        self.bill = bill
        self.percent = percent

    def calculate(self):
        return round(self.bill * self.percent / 100, 2)


print(TipCalculator(40, 15).calculate())

6.0

def tip(bill, percent):
    return round(bill * percent / 100, 2)


print(tip(40, 15))

6.0

A school library lends books and films. Films go out for less time and cost double in late fines. Each loan remembers what was borrowed and for how many days, and each member’s loan card can work out the total fine. The program below uses every idea from today.

from dataclasses import dataclass


class Item:
    kind = "item"
    loan_days = 21
    daily_fine = 0.25

    def __init__(self, title, code):
        self.title = title
        self.code = code

    def fine(self, days_late):
        return days_late * self.daily_fine

    def __eq__(self, other):
        if not isinstance(other, Item):
            return NotImplemented
        return self.code == other.code

    def __lt__(self, other):
        return self.title < other.title

    def __str__(self):
        return f"{self.title} ({self.kind})"


class Book(Item):
    kind = "book"

    def __init__(self, title, code, pages):
        super().__init__(title, code)
        self.pages = pages


class Film(Item):
    kind = "film"
    loan_days = 7

    def fine(self, days_late):
        return super().fine(days_late) * 2


@dataclass
class Loan:
    item: Item
    days_out: int

    @property
    def days_late(self):
        return max(0, self.days_out - self.item.loan_days)

    @property
    def fine(self):
        return self.item.fine(self.days_late)


class LoanCard:
    def __init__(self, owner):
        self.owner = owner
        self.loans = []

    def borrow(self, item, days_out):
        if item in [loan.item for loan in self.loans]:
            raise ValueError(f"{self.owner} already has {item}")
        self.loans.append(Loan(item, days_out))

    def __len__(self):
        return len(self.loans)

    @property
    def total_fine(self):
        return sum(loan.fine for loan in self.loans)


card = LoanCard("Ana")
card.borrow(Book("Wonder", "B-17", 310), 25)
card.borrow(Film("Up", "F-02"), 10)
card.borrow(Book("Holes", "B-04", 233), 3)
try:
    card.borrow(Book("Wonder", "B-17", 310), 1)
except ValueError as error:
    print(f"Refused: {error}")

for loan in sorted(card.loans, key=lambda loan: loan.item):
    print(f"{loan.item}: {loan.days_late} days late, fine {loan.fine:.2f}")
print(f"{card.owner} has {len(card)} loans; total fine {card.total_fine:.2f}")

Refused: Ana already has Wonder (book)
Holes (book): 0 days late, fine 0.00
Up (film): 3 days late, fine 1.50
Wonder (book): 4 days late, fine 1.00
Ana has 3 loans; total fine 2.50

Work through the fines. Wonder was out 25 days and a book may go out for 21, so it is 4 days late: 4 × 0.25 = 1.00. Up was out 10 days and a film may go out for 7, so 3 days late; Film.fine doubles the parent’s 3 × 0.25 = 0.75 to 1.50. Holes was out 3 days, and max(0, 3 - 21) is 0, so no fine. The total is 2.50.

Look at what each tool bought. Adding a third kind of item, say a magazine with a 14-day loan, is a three-line child class; the loan card, the loans, and the fine total all work with it unchanged, through polymorphism. And Loan, which only holds two values and works things out from them, took five lines as a data class.

Many of today’s mistakes show up as error messages that point at the line where the problem appears, not where it was made. Use this table to go from a message to its usual cause.

Older versions of Python may word some of these messages a little differently.

• Inheritance (class Child(Parent):) gives a child every method and class attribute of its parent, so you write only what is new. A child object is a parent object: isinstance says so, and except Parent catches it. Every class inherits from object in the end.
• A child method with a parent’s name overrides it. super() reaches the parent’s version, so a child’s __init__ calls super().__init__(...) and an override can build on the parent. Polymorphism means one call runs each object’s own version.
• Composition (“has-a”) keeps other objects as attributes and delegates to them. Prefer it unless the new class truly is a kind of the old one and every inherited method makes sense for it.
• Special methods plug your objects into Python: __eq__ for == (return NotImplemented for other types), __lt__ for < and sorting, and __len__ for len() and truthiness.
• @property makes a computed, read-only attribute that is never stale. @dataclass writes __init__, __repr__, and __eq__ from the fields of a class that mostly holds data.
• A class is worth writing when data, its rules, and several operations belong together; otherwise a function, a dictionary, or a data class is often enough.

Do these in your day17 folder. Type each program yourself, run it, and only then open the answer.

import math


class Shape:
    name = "shape"

    def area(self):
        raise NotImplementedError("each kind of shape must define area()")

    def __str__(self):
        return f"{self.name} with area {self.area():.2f}"


class Circle(Shape):
    name = "circle"

    def __init__(self, radius):
        self.radius = radius

    def area(self):
        return math.pi * self.radius**2


class Rectangle(Shape):
    name = "rectangle"

    def __init__(self, width, height):
        self.width = width
        self.height = height

    def area(self):
        return self.width * self.height


class Square(Rectangle):
    name = "square"

    def __init__(self, side):
        super().__init__(side, side)


shapes = [Circle(1), Rectangle(4, 2.5), Square(3)]
for shape in shapes:
    print(shape)
print(f"Total area: {sum(shape.area() for shape in shapes):.2f}")

circle with area 3.14
rectangle with area 10.00
square with area 9.00
Total area: 22.14

"""The Task class for the to-do manager, written as a data class."""

from dataclasses import asdict, dataclass


@dataclass
class Task:
    """One thing to do: a title, and whether it is done yet."""

    title: str
    done: bool = False

    def complete(self):
        """Mark this task as done."""
        self.done = True

    def to_dict(self):
        """Return this task as a dictionary, ready to save as JSON."""
        return asdict(self)

    def __str__(self):
        mark = "x" if self.done else " "
        return f"[{mark}] {self.title}"


if __name__ == "__main__":
    task = Task("Test the class")
    print(repr(task))
    task.complete()
    print(task)
    print(task.to_dict())
    print(task == Task("Test the class", True))

Task(title='Test the class', done=False)
[x] Test the class
{'title': 'Test the class', 'done': True}
True

"""Task functions for the to-do manager. main.py imports them."""

import json

from task import Task


def show_menu():
    """Print the menu of choices."""
    print()
    print("1) Add  2) List  3) Complete  4) Delete  5) Quit")


def add_task(tasks, title):
    """Add a new, unfinished Task to the end of tasks."""
    tasks.append(Task(title))


def list_tasks(tasks):
    """Print every task with its number, using Task.__str__."""
    if not tasks:
        print("No tasks yet.")
        return
    for number, task in enumerate(tasks, 1):
        print(f"{number}. {task}")


def complete_task(tasks, number):
    """Mark task number (counting from 1) as done.

    Return the Task, or None if no task has that number.
    """
    if not 1 <= number <= len(tasks):
        return None
    task = tasks[number - 1]
    task.complete()
    return task


def delete_task(tasks, number):
    """Remove task number (counting from 1) from tasks.

    Return the removed Task, or None if no task has that number.
    """
    if not 1 <= number <= len(tasks):
        return None
    return tasks.pop(number - 1)


def save_tasks(tasks, path):
    """Write tasks to the JSON file at path, replacing what was there."""
    data = [task.to_dict() for task in tasks]
    with path.open("w", encoding="utf-8") as file:
        json.dump(data, file, indent=2)


def load_tasks(path):
    """Return the Tasks saved at path, or [] if there are none to load.

    A missing file means this is the first run. A file that is not valid
    JSON gets a warning, and the program starts with no tasks.
    """
    try:
        with path.open(encoding="utf-8") as file:
            data = json.load(file)
    except FileNotFoundError:
        return []
    except json.JSONDecodeError:
        print(f"Warning: {path.name} is not valid JSON, so no tasks loaded.")
        return []
    return [Task(**item) for item in data]


if __name__ == "__main__":
    test_tasks = []
    add_task(test_tasks, "Test the module")
    print(complete_task(test_tasks, 1).done)
    print(complete_task(test_tasks, 2))
    list_tasks(test_tasks)