Chapter 10

Object-Oriented
Programming 10
Objectives
In this chapter, you’ll:
 Create custom classes and
objects of those classes.
 Understand the benefits of
crafting valuable classes.
 Control access to attributes.
 Appreciate the value of object
orientation.
 Use Python special methods
__repr__, __str__ and
__format__ to get an
object’s string representations.
 Use Python special methods
to overload (redefine)
operators to use them with
objects of new classes.
 Inherit methods, properties
and attributes from existing
classes into new classes, then
customize those classes.
 Understand the inheritance
notions of base classes
(superclasses) and derived
classes (subclasses).
 Understand duck typing and
polymorphism that enable
“programming in the general.”
 Understand class object
from which all classes inherit
fundamental capabilities.
 Compare composition and
inheritance.
 Build test cases into
docstrings and run these tests
with doctest,
 Understand namespaces and
how they affect scope.
404 Object-Oriented Programming
10.1 Introduction 10.8.3 Processing Commission-

Employees and Salaried-
10.2 Custom Class Account CommissionEmployees
10.2.1 Test-Driving Class Account Polymorphically
10.2.2 Account Class Definition 10.8.4 A Note About Object-Based and
10.2.3 Composition: Object References as Object-Oriented Programming
Members of Classes 10.9 Duck Typing and Polymorphism
10.3 Controlling Access to Attributes 10.10 Operator Overloading
10.4 Properties for Data Access 10.10.1 Test-Driving Class Complex
10.4.1 Test-Driving Class Time 10.10.2 Class Complex Definition
10.4.2 Class Time Definition 10.11 Exception Class Hierarchy and
10.4.3 Class Time Definition Design Notes
Custom Exceptions
10.5 Simulating “Private” Attributes
10.12 Named Tuples
10.6 Case Study: Card Shuffling and
10.13 A Brief Intro to Python 3.7’s New
Dealing Simulation
10.6.1 Test-Driving Classes Card and Data Classes
DeckOfCards 10.13.1 Creating a Card Data Class
10.6.2 Class Card—Introducing Class 10.13.2 Using the Card Data Class
Attributes 10.13.3 Data Class Advantages over Named
10.6.3 Class DeckOfCards Tuples
10.6.4 Displaying Card Images with 10.13.4 Data Class Advantages over
Matplotlib Traditional Classes
10.7 Inheritance: Base Classes and 10.14 Unit Testing with Docstrings and
Subclasses doctest
10.8 Building an Inheritance Hierarchy; 10.15 Namespaces and Scopes
Introducing Polymorphism 10.16 Intro to Data Science: Time Series
10.8.1 Base Class CommissionEmployee and Simple Linear Regression
10.8.2 Subclass
SalariedCommissionEmployee
10.17 Wrap-Up
Exercises
10.1 Introduction
Section 1.5 introduced the basic terminology and concepts of object-oriented program-
ming. Everything in Python is an object, so you’ve been using objects constantly through-
out this book. Just as houses are built from blueprints, objects are built from classes—one
of the core technologies of object-oriented programming. Building a new object from even
a large class is simple—you typically write one statement.
Crafting Valuable Classes
You’ve already used lots of classes created by other people. In this chapter you’ll learn how
to create your own custom classes. You’ll focus on “crafting valuable classes” that help you
meet the requirements of the applications you’ll build. You’ll use object-oriented pro-
gramming with its core technologies of classes, objects, inheritance and polymorphism.
Software applications are becoming larger and more richly functional. Object-oriented
programming makes it easier for you to design, implement, test, debug and update such
edge-of-the-practice applications. Read Sections 10.1 through 10.9 for a code-intensive
introduction to these technologies. Most people can skip Sections 10.10 through 10.15,
which provide additional perspectives on these technologies and present additional related
features.
10.1 Introduction 405
Class Libraries and Object-Based Programming

The vast majority of object-oriented programming you’ll do in Python is object-based
programming in which you primarily create and use objects of existing classes. You’ve been
doing this throughout the book with built-in types like int, float, str, list, tuple, dict
and set, with Python Standard Library types like Decimal, and with NumPy arrays, Mat-
plotlib Figures and Axes, and pandas Series and DataFrames.
To take maximum advantage of Python you must familiarize yourself with lots of pre-
existing classes. Over the years, the Python open-source community has crafted an enormous
number of valuable classes and packaged them into class libraries. This makes it easy for you
to reuse existing classes rather than “reinventing the wheel.” Widely used open-source library
classes are more likely to be thoroughly tested, bug free, performance tuned and portable
across a wide range of devices, operating systems and Python versions. You’ll find abundant
Python libraries on the Internet at sites like GitHub, BitBucket, SourceForge and more—
most easily installed with conda or pip. This is a key reason for Python’s popularity. The vast
majority of the classes you’ll need are likely to be freely available in open-source libraries.
Creating Your Own Custom Classes
Classes are new data types. Each Python Standard Library class and third-party library class
is a custom type built by someone else. In this chapter, you’ll develop application-specific
classes, like CommissionEmployee, Time, Card, DeckOfCards and more. The dozens of chap-
ter exercises challenge you to create additional classes for a wide variety of applications.
Most applications you’ll build for your own use will commonly use either no custom
classes or just a few. If you become part of a development team in industry, you may work
on applications that contain hundreds, or even thousands, of classes. You can contribute
your custom classes to the Python open-source community, but you are not obligated to
do so. Organizations often have policies and procedures related to open-sourcing code.
Inheritance
Perhaps most exciting is the notion that new classes can be formed through inheritance
and composition from classes in abundant class libraries. Eventually, software will be con-
structed predominantly from standardized, reusable components just as hardware is con-
structed from interchangeable parts today. This will help meet the challenges of
developing ever more powerful software.
When creating a new class, instead of writing all new code, you can designate that the
new class is to be formed initially by inheriting the attributes (variables) and methods (the
class version of functions) of a previously defined base class (also called a superclass). The
new class is called a derived class (or subclass). After inheriting, you then customize the
derived class to meet the specific needs of your application. To minimize the customiza-
tion effort, you should always try to inherit from the base class that’s closest to your needs.
To do that effectively, you should familiarize yourself with the class libraries that are
geared to the kinds of applications you’ll be building.
Polymorphism
We explain and demonstrate polymorphism, which enables you to conveniently program
“in the general” rather than “in the specific.” You simply send the same method call to
objects possibly of many different types. Each object responds by “doing the right thing.”
So the same method call takes on “many forms,” hence the term “poly-morphism.” We’ll
explain how to implement polymorphism through inheritance and a Python feature called
duck typing. We’ll explain both and show examples of each.
An Entertaining Case Study: Card-Shuffling-and-Dealing Simulation
You’ve already used a random-numbers-based die-rolling simulation and used those tech-
niques to implement the popular dice game craps. Here, we present a card-shuffling-and-
dealing simulation, which you can use to implement your favorite card games. You’ll use
Matplotlib with attractive public-domain card images to display the full deck of cards both
before and after the deck is shuffled. In the exercises, you can implement the popular card
games blackjack and solitaire, and evaluate a five-card poker hand.
Data Classes
Python 3.7’s new data classes help you build classes faster by using a more concise notation
and by autogenerating portions of the classes. The Python community’s early reaction to
data classes has been positive. As with any major new feature, it may take time before it’s
widely used. We present class development with both the older and newer technologies.
Other Concepts Introduced in This Chapter
Other concepts you’ll learn include:
• How to specify that certain identifiers should be used only inside a class and not
be accessible to clients of the class.
• Special methods for creating string representations of your classes’ objects and
specifying how objects of your classes work with Python’s built-in operators (a
process called operator overloading).
• An introduction to the Python exception class hierarchy and creating custom
exception classes.
• Testing code with the Python Standard Library’s doctest module.
• How Python uses namespaces to determine the scopes of identifiers.
10.2 Custom Class Account

Let’s begin with a bank Account class that holds an account holder’s name and balance.
An actual bank account class would likely include lots of other information, such as
address, birth date, telephone number, account number and more. The Account class
accepts deposits that increase the balance and withdrawals that decrease the balance.
10.2.1 Test-Driving Class Account

Each new class you create becomes a new data type that can be used to create objects. This
is one reason why Python is said to be an extensible language. Before we look at class
Account’s definition, let’s demonstrate its capabilities.
Importing Classes Account and Decimal

To use the new Account class, launch your IPython session from the ch10 examples folder,
then import class Account:
In [1]: from account import Account
10.2 Custom Class Account 407
Class Account maintains and manipulates the account balance as a Decimal, so we also
import class Decimal:
In [2]: from decimal import Decimal
Create an Account Object with a Constructor Expression

To create a Decimal object, we can write:
value = Decimal('12.34')
This is known as a constructor expression because it builds and initializes an object of the
class, similar to the way a house is constructed from a blueprint then painted with the
buyer’s preferred colors. Constructor expressions create new objects and initialize their
data using argument(s) specified in parentheses. The parentheses following the class name
are required, even if there are no arguments.
Let’s use a constructor expression to create an Account object and initialize it with an
account holder’s name (a string) and balance (a Decimal):
In [3]: account1 = Account('John Green', Decimal('50.00'))
Getting an Account’s Name and Balance

Let’s access the Account object’s name and balance attributes:
In [4]: account1.name
Out[4]: 'John Green'
In [5]: account1.balance
Out[5]: Decimal('50.00')
Depositing Money into an Account

An Account’s deposit method receives a positive dollar amount and adds it to the balance:
In [6]: account1.deposit(Decimal('25.53'))
Account Methods Perform Validation

Class Account’s methods validate their arguments. For example, if a deposit amount is
negative, deposit raises a ValueError:
In [8]: account1.deposit(Decimal('-123.45'))
-------------------------------------------------------------------------
ValueError Traceback (most recent call last)
<ipython-input-8-27dc468365a7> in <module>()
----> 1 account1.deposit(Decimal('-123.45'))
~/Documents/examples/ch10/account.py in deposit(self, amount)

21 # if amount is less than 0.00, raise an exception
22 if amount < Decimal('0.00'):
---> 23 raise ValueError('Deposit amount must be positive.')
24
25 self.balance += amount
ValueError: Deposit amount must be positive.

Self Check
1 (Fill-In) Each new class you create becomes a new data type that can be used to create
objects. This is one reason why Python is said to be a(n) language.
Answer: extensible.
2 (Fill-In) A(n) expression creates and initializes an object of a class.
Answer: constructor.
10.2.2 Account Class Definition

Now, let’s look at Account’s class definition, which is located in the file account.py.
Defining a Class
A class definition begins with the keyword class (line 5) followed by the class’s name and
a colon (:). This line is called the class header. The Style Guide for Python Code recom-
mends that you begin each word in a multi-word class name with an uppercase letter (for
example, CommissionEmployee). Every statement in a class’s suite is indented.
1 # account.py
2 """Account class definition."""
3 from decimal import Decimal
4
5 class Account:
6 """Account class for maintaining a bank account balance."""
7
Each class typically provides a descriptive docstring (line 6). When provided, it must
appear in the line or lines immediately following the class header. To view any class’s doc-
string in IPython, type the class name and a question mark, then press Enter:
In [9]: Account?
Init signature: Account(name, balance)
Docstring: Account class for maintaining a bank account balance.
Init docstring: Initialize an Account object.
File: ~/Documents/examples/ch10/account.py
Type: type
The identifier Account is both the class name and the name used in a constructor expres-
sion to create an Account object and invoke the class’s __init__ method. For this reason,
IPython’s help mechanism shows both the class’s docstring ("Docstring:") and the
__init__ method’s docstring ("Init docstring:").
Initializing Account Objects: Method __init__

The constructor expression in snippet [3] from the preceding section:
account1 = Account('John Green', Decimal('50.00'))
creates a new object, then initializes its data by calling the class’s __init__ method. Each
new class you create can provide an __init__ method that specifies how to initialize an
object’s data attributes. Returning a value other than None from __init__ results in a
TypeError. Recall that None is returned by any function or method that does not contain
a return statement. Class Account’s __init__ method (lines 8–16) initializes an Account
object’s name and balance attributes if the balance is valid:
10.2 Custom Class Account 409
8 def __init__(self, name, balance):

9 """Initialize an Account object."""
10
11 # if balance is less than 0.00, raise an exception
12 if balance < Decimal('0.00'):
13 raise ValueError('Initial balance must be >= to 0.00.')
14
15 self.name = name
16 self.balance = balance
17
When you call a method for a specific object, Python implicitly passes a reference to
that object as the method’s first argument. For this reason, all methods of a class must
specify at least one parameter. By convention most Python programmers call a method’s
first parameter self. A class’s methods must use that reference (self) to access the object’s
attributes and other methods. Class Account’s __init__ method also specifies parameters
for the name and balance.
The if statement validates the balance parameter. If balance is less than 0.00,
__init__ raises a ValueError, which terminates the __init__ method. Otherwise, the
method creates and initializes the new Account object’s name and balance attributes.
When an object of class Account is created, it does not yet have any attributes. They’re
added dynamically via assignments of the form:
self.attribute_name = value
Python classes may define many special methods, like __init__, each identified by
leading and trailing double-underscores (__) in the method name. Python class object,
which we’ll discuss later in this chapter, defines the special methods that are available for
all Python objects.
Method deposit
The Account class’s deposit method adds a positive amount to the account’s balance
attribute. If the amount argument is less than 0.00, the method raises a ValueError, indi-
cating that only positive deposit amounts are allowed. If the amount is valid, line 25 adds
it to the object’s balance attribute.
18 def deposit(self, amount):
19 """Deposit money to the account."""
20
23 raise ValueError('amount must be positive.')
24
10.2.3 Composition: Object References as Members of Classes

An Account has a name, and an Account has a balance. Recall that “everything in Python
is an object.” This means that an object’s attributes are references to objects of other
classes. For example, an Account object’s name attribute is a reference to a string object and
an Account object’s balance attribute is a reference to a Decimal object. Embedding ref-
erences to objects of other types is a form of software reusability known as composition
and is sometimes referred to as the “has a” relationship. An end-of-chapter exercise asks

you to implement composition with Circle and Point classes—a Circle “has a” Point
that represents the Circle’s center location. Later in this chapter, we’ll discuss inheritance,
which establishes “is a” relationships.
Self Check
1 (Fill-In) A class’s method is called by a constructor expression to initialize a
new object of the class.
Answer: __init__.
2 (True/False) A class’s __init__ method returns an object of the class.
Answer: False. A class’s __init__ method initializes an object of the class and implicitly
returns None.
3 (IPython Session) Add a withdraw method to class Account. If the withdrawal amount
is greater than the balance, raise a ValueError, indicating that the withdrawal amount
must be less than or equal to the balance. If the withdrawal amount is less than 0.00, raise
a ValueError indicating that the withdrawal amount must be positive. If the withdrawal
amount is valid, subtract it from the balance attribute. Create an Account object, then test
method withdraw first with a valid withdrawal amount, then with a withdrawal amount
greater than the balance and finally with a negative withdrawal amount.
Answer: The new method in class Account is:
def withdraw(self, amount):
"""Withdraw money from the account."""
# if amount is greater than balance, raise an exception

if amount > self.balance:
raise ValueError('amount must be <= to balance.')
elif amount < Decimal('0.00'):
raise ValueError('amount must be positive.')
self.balance -= amount
Testing method withdraw:

In [4]: account1.withdraw(Decimal('20.00'))
In [6]: account1.withdraw(Decimal('100.00'))
-------------------------------------------------------------------------
<ipython-input-6-61bb6aa89aa4> in <module>()
----> 1 account1.withdraw(Decimal('100.00'))
10.3 Controlling Access to Attributes 411
~/Documents/examples/ch10/snippets_py/account.py in withdraw(self,
amount)
30 # if amount is greater than balance, raise an exception
31 if amount > self.balance:
---> 32 raise ValueError('amount must be <= to balance.')
33 elif amount < Decimal('0.00'):
ValueError: amount must be <= to balance.
In [7]: account1.withdraw(Decimal('-10.00'))
-------------------------------------------------------------------------
<ipython-input-7-ab50927d9727> in <module>()
----> 1 account1.withdraw(Decimal('-10.00'))
~/Documents/examples/ch10/snippets_py/account.py in withdraw(self,
amount)
32 raise ValueError('amount must be <= to balance.')
33 elif amount < Decimal('0.00'):
---> 34 raise ValueError('amount must be positive.')
35
36 self.balance -= amount
ValueError: amount must be positive.
10.3 Controlling Access to Attributes

Class Account’s methods validate their arguments to ensure that the balance is always
valid—that is, always greater than or equal to 0.00. In the previous example, we used the
attributes name and balance only to get the values of those attributes. It turns out that we
also can use those attributes to modify their values. Consider the Account object in the fol-
lowing IPython session:
Initially, account1 contains a valid balance. Now, let’s set the balance attribute to an
invalid negative value, then display the balance:
In [5]: account1.balance = Decimal('-1000.00')
Out[6]: Decimal('-1000.00')
Snippet [6]’s output shows that account1’s balance is now negative. As you can see,
unlike methods, data attributes cannot validate the values you assign to them.
Encapsulation
A class’s client code is any code that uses objects of the class. Most object-oriented pro-
gramming languages enable you to encapsulate (or hide) an object’s data from the client
code. Such data in these languages is said to be private data.
Leading Underscore (_) Naming Convention
Python does not have private data. Instead, you use naming conventions to design classes
that encourage correct use. By convention, Python programmers know that any attribute
name beginning with an underscore (_) is for a class’s internal use only. Client code should
use the class’s methods and—as you’ll see in the next section—the class’s properties to
interact with each object’s internal-use data attributes. Attributes whose identifiers do not
begin with an underscore (_) are considered publicly accessible for use in client code. In the
next section, we’ll define a Time class and use these naming conventions. However, even
when we use these conventions, attributes are always accessible.
Self Check
1 (True/False) Like most object-oriented programming languages, Python provides
capabilities for encapsulating an object’s data attributes so client code cannot access the
data directly.
Answer: False. In Python, all data attributes are accessible. You use attribute naming con-
ventions to indicate that attributes should not be accessed directly from client code.
10.4 Properties for Data Access

Let’s develop a Time class that stores the time in 24-hour clock format with hours in the
range 0–23, and minutes and seconds each in the range 0–59. For this class, we’ll provide
properties, which look like data attributes to client-code programmers, but control the
manner in which they get and modify an object’s data. This assumes that other program-
mers follow Python conventions to correctly use objects of your class.
10.4.1 Test-Driving Class Time

Before we look at class Time’s definition, let’s demonstrate its capabilities. First, ensure that
you’re in the ch10 folder, then import class Time from timewithproperties.py:
In [1]: from timewithproperties import Time
Creating a Time Object

Next, let’s create a Time object. Class Time’s __init__ method has hour, minute and sec-
ond parameters, each with a default argument value of 0. Here, we specify the hour and
minute—second defaults to 0:
In [2]: wake_up = Time(hour=6, minute=30)
Displaying a Time Object

Class Time defines two methods that produce string representations of Time object. When
you evaluate a variable in IPython as in snippet [3], IPython calls the object’s __repr__
special method to produce a string representation of the object. Our __repr__ implemen-
tation creates a string in the following format:
10.4 Properties for Data Access 413
In [3]: wake_up
Out[3]: Time(hour=6, minute=30, second=0)
We’ll also provide the __str__ special method, which is called when an object is converted
to a string, such as when you output the object with print.1 Our __str__ implementation
creates a string in 12-hour clock format:
In [4]: print(wake_up)
6:30:00 AM
Getting an Attribute Via a Property

Class time provides hour, minute and second properties, which provide the convenience
of data attributes for getting and modifying an object’s data. However, as you’ll see, prop-
erties are implemented as methods, so they may contain additional logic, such as specify-
ing the format in which to return a data attribute’s value or validating a new value before
using it to modify a data attribute. Here, we get the wake_up object’s hour value:
In [5]: wake_up.hour
Out[5]: 6
Though this snippet appears to simply get an hour data attribute’s value, it’s actually a call
to an hour method that returns the value of a data attribute (which we named _hour, as
you’ll see in the next section).
Setting the Time
You can set a new time with the Time object’s set_time method. Like method __init__,
method set_time provides hour, minute and second parameters, each with a default of 0:
In [6]: wake_up.set_time(hour=7, minute=45)
In [7]: wake_up
Setting an Attribute via a Property

Class Time also supports setting the hour, minute and second values individually via its
properties. Let’s change the hour value to 6:
In [8]: wake_up.hour = 6
In [9]: wake_up
Though snippet [8] appears to simply assign a value to a data attribute, it’s actually a call
to an hour method that takes 6 as an argument. The method validates the value, then
assigns it to a corresponding data attribute (which we named _hour, as you’ll see in the
next section).
Attempting to Set an Invalid Value
To prove that class Time’s properties validate the values you assign to them, let’s try to
assign an invalid value to the hour property, which results in a ValueError:
1. If a class does not provide __str__ and an object of the class is converted to a string, the class’s
__repr__ method is called instead.
In [10]: wake_up.hour = 100

-------------------------------------------------------------------------
<ipython-input-10-1fce0716ef14> in <module>()
----> 1 wake_up.hour = 100
~/Documents/examples/ch10/timewithproperties.py in hour(self, hour)

20 """Set the hour."""
21 if not (0 <= hour < 24):
---> 22 raise ValueError(f'Hour ({hour}) must be 0-23')
23
24 self._hour = hour
ValueError: Hour (100) must be 0-23
Self Check
1 (Fill-In) The print function implicitly invokes special method .
Answer: __str__.
2 (Fill-In) IPython calls an object’s special method to produce a string repre-
sentation of the object
Answer: __repr__.
3 (True/False) Properties are used like methods.
Answer: False. Properties are used like data attributes, but (as we’ll see in the next section)
are implemented as methods.
10.4.2 Class Time Definition

Now that we’ve seen class Time in action, let’s look at its definition.
Class Time: __init__ Method with Default Parameter Values
Class Time’s __init__ method specifies hour, minute and second parameters, each with a
default argument of 0. Similar to class Account’s __init__ method, recall that the self
parameter is a reference to the Time object being initialized. The statements containing
self.hour, self.minute and self.second appear to create hour, minute and second
attributes for the new Time object (self). However, these statements actually call methods
that implement the class’s hour, minute and second properties (lines 13–50). Those meth-
ods then create attributes named _hour, _minute and _second that are meant for use only
inside the class:
1 # timewithproperties.py
2 """Class Time with read-write properties."""
3
4 class Time:
5 """Class Time with read-write properties."""
6
7 def __init__(self, hour=0, minute=0, second=0):
8 """Initialize each attribute."""
9 self.hour = hour # 0-23
10 self.minute = minute # 0-59
11 self.second = second # 0-59
12
Class Time: hour Read-Write Property

Lines 13–24 define a publicly accessible read-write property named hour that manipulates
a data attribute named _hour. The single-leading-underscore (_) naming convention indi-
cates that client code should not access _hour directly. As you saw in the previous section’s
snippets [5] and [8], properties look like data attributes to programmers working with
Time objects. However, notice that properties are implemented as methods. Each property
defines a getter method which gets (that is, returns) a data attribute’s value and can option-
ally define a setter method which sets a data attribute’s value:
13 @property
14 def hour(self):
15 """Return the hour."""
16 return self._hour
17
18 @hour.setter
19 def hour(self, hour):
20 """Set the hour."""
21 if not (0 <= hour < 24):
22 raise ValueError(f'Hour ({hour}) must be 0-23')
23
24 self._hour = hour
25
The @property decorator precedes the property’s getter method, which receives only
a self parameter. Behind the scenes, a decorator adds code to the decorated function—in
this case to make the hour function work with attribute syntax. The getter method’s name
is the property name. This getter method returns the _hour data attribute’s value. The fol-
lowing client-code expression invokes the getter method:
wake_up.hour
You also can use the getter method inside the class, as you’ll see shortly.
A decorator of the form @property_name.setter (in this case, @hour.setter) pre-
cedes the property’s setter method. The method receives two parameters—self and a
parameter (hour) representing the value being assigned to the property. If the hour param-
eter’s value is valid, this method assigns it to the self object’s _hour attribute; otherwise,
the method raises a ValueError. The following client-code expression invokes the setter by
assigning a value to the property:
wake_up.hour = 8
We also invoked this setter inside the class at line 9 of __init__:

self.hour = hour
Using the setter enabled us to validate __init__’s hour argument before creating and ini-
tializing the object’s _hour attribute, which occurs the first time the hour property’s setter
executes as a result of line 9. A read-write property has both a getter and a setter. A read-
only property has only a getter.
Class Time: minute and second Read-Write Properties
Lines 26–37 and 39–50 define read-write minute and second properties. Each property’s
setter ensures that its second argument is in the range 0–59 (the valid range of values for
minutes and seconds):
26 @property
27 def minute(self):
28 """Return the minute."""
29 return self._minute
30
31 @minute.setter
32 def minute(self, minute):
33 """Set the minute."""
34 if not (0 <= minute < 60):
35 raise ValueError(f'Minute ({minute}) must be 0-59')
36
37 self._minute = minute
38
39 @property
40 def second(self):
41 """Return the second."""
42 return self._second
43
44 @second.setter
45 def second(self, second):
46 """Set the second."""
47 if not (0 <= second < 60):
48 raise ValueError(f'Second ({second}) must be 0-59')
49
50 self._second = second
51
Class Time: Method set_time

We provide method set_time as a convenient way to change all three attributes with a sin-
gle method call. Lines 54–56 invoke the setters for the hour, minute and second properties:
52 def set_time(self, hour=0, minute=0, second=0):
53 """Set values of hour, minute, and second."""
54 self.hour = hour
55 self.minute = minute
56 self.second = second
57
Class Time: Special Method __repr__

When you pass an object to built-in function repr—which happens implicitly when you
evaluate a variable in an IPython session—the corresponding class’s __repr__ special
method is called to get a string representation of the object:
58 def __repr__(self):
59 """Return Time string for repr()."""
60 return (f'Time(hour={self.hour}, minute={self.minute}, ' +
61 f'second={self.second})')
62
The Python documentation indicates that __repr__ returns the “official” string represen-
tation of the object. Typically this string looks like a constructor expression that creates
and initializes the object,2 as in:
'Time(hour=6, minute=30, second=0)'
2. https://docs.python.org/3/reference/datamodel.html.
This is similar to the constructor expression in the previous section’s snippet [2]. Python
has a built-in function eval that could receive the preceding string as an argument and use
it to create and initialize a Time object containing values specified in the string.
Class Time: Special Method __str__
For our class Time we also define the __str__ special method. This method is called
implicitly when you convert an object to a string with the built-in function str, such as
when you print an object or call str explicitly. Our implementation of __str__ creates a
string in 12-hour clock format, such as '7:59:59 AM' or '12:30:45 PM':
63 def __str__(self):
64 """Print Time in 12-hour clock format."""
65 return (('12' if self.hour in (0, 12) else str(self.hour % 12)) +
66 f':{self.minute:0>2}:{self.second:0>2}' +
67 (' AM' if self.hour < 12 else ' PM'))
Self Check
1 (Fill-In) The print function implicitly invokes special method .
Answer: __str__.
2 (Fill-In) A(n) property has both a getter and setter. If only a getter is pro-
vided, the property is a(n) property, meaning that you only can get the property’s
value.
Answer: read-write, read-only.
3 (IPython Session) Add to class Time a read-write property time in which the getter
returns a tuple containing the values of the hour, minute and second properties, and the
setter receives a tuple containing hour, minute and second values and uses them to set the
time. Create a Time object and test the new property.
Answer: The new read-write property definition is shown below:
@property
def time(self):
"""Return hour, minute and second as a tuple."""
return (self.hour, self.minute, self.second)
@time.setter
def time(self, time_tuple):
"""Set time from a tuple containing hour, minute and second."""
self.set_time(time_tuple[0], time_tuple[1], time_tuple[2])
In [2]: t = Time()
In [3]: t
In [4]: t.time = (12, 30, 45)
In [5]: t
In [6]: t.time
Out[6]: (12, 30, 45)
Note that the self.set_time call in the time property’s setter method may be expressed
more concisely as
self.set_time(*time_tuple)
The expression *time_tuple uses the unary * operator to unpack the time_tuple’s values,
then passes them as individual arguments. In the preceding IPython session, the setter
would receive the tuple (12, 30, 45), then unpack the tuple and call self.set_time as
follows:
self.set_time(12, 30, 45)
10.4.3 Class Time Definition Design Notes

Let’s consider some class-design issues in the context of our Time class.
Interface of a Class
Class Time’s properties and methods define the class’s public interface—that is, the set of
properties and methods programmers should use to interact with objects of the class.
Attributes Are Always Accessible
Though we provided a well-defined interface, Python does not prevent you from directly
manipulating the data attributes _hour, _minute and _second, as in:
In [2]: wake_up = Time(hour=7, minute=45, second=30)
In [3]: wake_up._hour
Out[3]: 7
In [4]: wake_up._hour = 100
In [5]: wake_up
After snippet [4], the wake_up object contains invalid data. Unlike many other object-ori-
ented programming languages, such as C++, Java and C#, data attributes in Python cannot
be hidden from client code. The Python tutorial says, “nothing in Python makes it pos-
sible to enforce data hiding—it is all based upon convention.”3
Internal Data Representation
We chose to represent the time as three integer values for hours, minutes and seconds. It
would be perfectly reasonable to represent the time internally as the number of seconds
since midnight. Though we’d have to reimplement the properties hour, minute and sec-
ond, programmers could use the same interface and get the same results without being
aware of these changes. An exercise at the end of this chapter asks you to make this change
and show that client code using Time objects does not need to change.
Evolving a Class’s Implementation Details
When you design a class, carefully consider the class’s interface before making that class
available to other programmers. Ideally, you’ll design the interface such that existing code
3. https://docs.python.org/3/tutorial/classes.html#random-remarks.
10.5 Simulating “Private” Attributes 419
will not break if you update the class’s implementation details—that is, the internal data
representation or how its method bodies are implemented.
If Python programmers follow convention and do not access attributes that begin
with leading underscores, then class designers can evolve class implementation details
without breaking client code.
Properties
It may seem that providing properties with both setters and getters has no benefit over
accessing the data attributes directly, but there are subtle differences. A getter seems to
allow clients to read the data at will, but the getter can control the formatting of the data.
A setter can scrutinize attempts to modify the value of a data attribute to prevent the data
from being set to an invalid value.
Utility Methods
Not all methods need to serve as part of a class’s interface. Some serve as utility methods
used only inside the class and are not intended to be part of the class’s public interface used
by client code. Such methods should be named with a single leading underscore. In other
object-oriented languages like C++, Java and C#, such methods typically are implemented
as private methods.
Module datetime
In professional Python development, rather than building your own classes to represent
times and dates, you’ll typically use the Python Standard Library’s datetime module capa-
bilities. You can learn more about the datetime module at:
https://docs.python.org/3/library/datetime.html
An exercise at the end of the chapter has you manipulate dates and times with this module.
Self Check
1 (Fill-In) A class’s is the set of public properties and methods programmers
should use to interact with objects of the class.
Answer: interface.
2 (Fill-In) A class’s methods are used only inside the class and are not intended
to be used by client code.
Answer: utility.
10.5 Simulating “Private” Attributes

In programming languages such as C++, Java and C#, classes state explicitly which class
members are publicly accessible. Class members that may not be accessed outside a class
definition are private and visible only within the class that defines them. Python program-
mers often use “private” attributes for data or utility methods that are essential to a class’s
inner workings but are not part of the class’s public interface.
As you’ve seen, Python objects’ attributes are always accessible. However, Python has
a naming convention for “private” attributes. Suppose we want to create an object of class
Time and to prevent the following assignment statement:
wake_up._hour = 100
that would set the hour to an invalid value. Rather than _hour, we can name the attribute
__hour with two leading underscores. This convention indicates that __hour is “private” and
should not be accessible to the class’s clients. To help prevent clients from accessing “private”
attributes, Python renames them by preceding the attribute name with _ClassName, as in
_Time__hour. This is called name mangling. If you try assign to __hour, as in
wake_up.__hour = 100
Python raises an AttributeError, indicating that the class does not have an __hour attri-
bute. We’ll show this momentarily.
IPython Auto-Completion Shows Only “Public” Attributes
In addition, IPython does not show attributes with one or two leading underscores when
you try to auto-complete an expression like
wake_up.
by pressing Tab. Only attributes that are part of the wake_up object’s “public” interface are
displayed in the IPython auto-completion list.
Demonstrating “Private” Attributes
To demonstrate name mangling, consider class PrivateClass with one “public” data
attribute public_data and one “private” data attribute __private_data:
1 # private.py
2 """Class with public and private attributes."""
3
4 class PrivateClass:
5 """Class with public and private attributes."""
6
7 def __init__(self):
8 """Initialize the public and private attributes."""
9 self.public_data = "public" # public attribute
10 self.__private_data = "private" # private attribute
Let’s create an object of class PrivateData to demonstrate these data attributes:

In [1]: from private import PrivateClass
In [2]: my_object = PrivateClass()
Snippet [3] shows that we can access the public_data attribute directly:
In [3]: my_object.public_data
Out[3]: 'public'
However, when we attempt to access __private_data directly in snippet [4], we get an

AttributeError indicating that the class does not have an attribute by that name:
In [4]: my_object.__private_data
-------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-4-d896bfdf2053> in <module>()
----> 1 my_object.__private_data
AttributeError: 'PrivateClass' object has no attribute '__private_data'

10.6 Case Study: Card Shuffling and Dealing Simulation 421
This occurs because python changed the attribute’s name. Unfortunately, as you’ll see in
one of this section’s Self Check exercises, __private_data is still indirectly accessible.
Self Check
1 (Fill-In) Python mangles attribute names that begin with underscore(s).
Answer: two.
2 (True/False) An attribute that begins with a single underscore is a private attribute.
Answer: False. An attribute that begins with a single underscore simply conveys the con-
vention that a client of the class should not access the attribute directly, but it does allow
access. Again, “nothing in Python makes it possible to enforce data hiding—it is all
based upon convention.”4
3 (IPython Session) Even with double-underscore (__) naming, we can still access and
modify __private_data, because we know that Python renames attributes simply by pre-
fixing their names with '_ClassName'. Demonstrate this for class PrivateData’s data
attribute __private_data.
Answer:
In [5]: my_object._PrivateClass__private_data
Out[5]: 'private'
In [6]: my_object._PrivateClass__private_data = 'modified'
In [7]: my_object._PrivateClass__private_data
Out[7]: 'modified'
10.6 Case Study: Card Shuffling and Dealing Simulation

Our next example presents two custom classes that you can use to shuffle and deal a deck
of cards. Class Card represents a playing card that has a face ('Ace', '2', '3', …, 'Jack',
'Queen', 'King') and a suit ('Hearts', 'Diamonds', 'Clubs', 'Spades'). Class DeckOf-
Cards represents a deck of 52 playing cards as a list of Card objects. First, we’ll test-drive
these classes in an IPython session to demonstrate card shuffling and dealing capabilities
and displaying the cards as text. Then we’ll look at the class definitions. Finally, we’ll use
another IPython session to display the 52 cards as images using Matplotlib. We’ll show
you where to get nice-looking public-domain card images.
10.6.1 Test-Driving Classes Card and DeckOfCards

Before we look at classes Card and DeckOfCards, let’s use an IPython session to demon-
strate their capabilities.
Creating, Shuffling and Dealing the Cards
First, import class DeckOfCards from deck.py and create an object of the class:
In [1]: from deck import DeckOfCards
In [2]: deck_of_cards = DeckOfCards()
4. https://docs.python.org/3/tutorial/classes.html#random-remarks.
DeckOfCards method __init__ creates the 52 Card objects in order by suit and by face
within each suit. You can see this by printing the deck_of_cards object, which calls the
DeckOfCards class’s __str__ method to get the deck’s string representation. Read each
row left-to-right to confirm that all the cards are displayed in order from each suit (Hearts,
Diamonds, Clubs and Spades):
In [3]: print(deck_of_cards)
Ace of Hearts 2 of Hearts 3 of Hearts 4 of Hearts
5 of Hearts 6 of Hearts 7 of Hearts 8 of Hearts
9 of Hearts 10 of Hearts Jack of Hearts Queen of Hearts
King of Hearts Ace of Diamonds 2 of Diamonds 3 of Diamonds
4 of Diamonds 5 of Diamonds 6 of Diamonds 7 of Diamonds
8 of Diamonds 9 of Diamonds 10 of Diamonds Jack of Diamonds
Queen of Diamonds King of Diamonds Ace of Clubs 2 of Clubs
3 of Clubs 4 of Clubs 5 of Clubs 6 of Clubs
Jack of Clubs Queen of Clubs King of Clubs Ace of Spades
2 of Spades 3 of Spades 4 of Spades 5 of Spades
10 of Spades Jack of Spades Queen of Spades King of Spades
Next, let’s shuffle the deck and print the deck_of_cards object again. We did not specify
a seed for reproducibility, so each time you shuffle, you’ll get different results:
In [4]: deck_of_cards.shuffle()
King of Hearts Queen of Clubs Queen of Diamonds 10 of Clubs
5 of Clubs 8 of Diamonds 3 of Hearts 10 of Hearts
8 of Spades 5 of Spades Queen of Spades Ace of Clubs
8 of Clubs 7 of Spades Jack of Diamonds 10 of Spades
4 of Diamonds 8 of Hearts 6 of Spades King of Spades
9 of Hearts 4 of Spades 6 of Clubs King of Clubs
3 of Spades 9 of Diamonds 3 of Clubs Ace of Spades
Ace of Hearts 3 of Diamonds 2 of Diamonds 6 of Hearts
King of Diamonds Jack of Spades Jack of Clubs 2 of Spades
5 of Diamonds 4 of Clubs Queen of Hearts 9 of Clubs
10 of Diamonds 2 of Clubs Ace of Diamonds 7 of Diamonds
9 of Spades Jack of Hearts 6 of Diamonds 7 of Clubs
Dealing Cards
We can deal one Card at a time by calling method deal_card. IPython calls the returned
Card object’s __repr__ method to produce the string output shown in the Out[] prompt:
In [6]: deck_of_cards.deal_card()
Out[6]: Card(face='King', suit='Hearts')
Class Card’s Other Features

To demonstrate class Card’s __str__ method, let’s deal another card and pass it to the
built-in str function:
In [7]: card = deck_of_cards.deal_card()
In [8]: str(card)
Out[8]: 'Queen of Clubs'
Each Card has a corresponding image file name, which you can get via the image_name
read-only property. We’ll use this soon when we display the Cards as images:
In [9]: card.image_name
Out[9]: 'Queen_of_Clubs.png'
10.6.2 Class Card—Introducing Class Attributes

Each Card object contains three string properties representing that Card’s face, suit and
image_name (a file name containing a corresponding image). As you saw in the preceding
section’s IPython session, class Card also provides methods for initializing a Card and for
getting various string representations.
Class Attributes FACES and SUITS
Each object of a class has its own copies of the class’s data attributes. For example, each
Account object has its own name and balance. Sometimes, an attribute should be shared
by all objects of a class. A class attribute (also called a class variable) represents class-wide
information. It belongs to the class, not to a specific object of that class. Class Card defines
two class attributes (lines 5–7):
• FACES is a list of the card face names.
• SUITS is a list of the card suit names.
1 # card.py
2 """Card class that represents a playing card and its image file name."""
3
4 class Card:
5 FACES = ['Ace', '2', '3', '4', '5', '6',
6 '7', '8', '9', '10', 'Jack', 'Queen', 'King']
7 SUITS = ['Hearts', 'Diamonds', 'Clubs', 'Spades']
8
You define a class attribute by assigning a value to it inside the class’s definition, but
not inside any of the class’s methods or properties (in which case, they’d be local variables).
FACES and SUITS are constants that are not meant to be modified. Recall that the Style
Guide for Python Code recommends naming your constants with all capital letters.5
We’ll use elements of these lists to initialize each Card we create. However, we do not
need a separate copy of each list in every Card object. Class attributes can be accessed through
any object of the class, but are typically accessed through the class’s name (as in, Card.FACES
or Card.SUITS). Class attributes exist as soon as you import their class’s definition.
Card Method __init__
When you create a Card object, method __init__ defines the object’s _face and _suit
data attributes:
9 def __init__(self, face, suit):
10 """Initialize a Card with a face and suit."""
11 self._face = face
12 self._suit = suit
13
5. Recall that Python does not have true constants, so FACES and SUITS are still modifiable.
Read-Only Properties face, suit and image_name

Once a Card is created, its face, suit and image_name do not change, so we implement
these as read-only properties (lines 14–17, 19–22 and 24–27). Properties face and suit
return the corresponding data attributes _face and _suit. A property is not required to
have a corresponding data attribute. To demonstrate this, the Card property image_name’s
value is created dynamically by getting the Card object’s string representation with
str(self), replacing any spaces with underscores and appending the '.png' filename
extension. So, 'Ace of Spades' becomes 'Ace_of_Spades.png'. We’ll use this file name
to load a PNG-format image representing the Card. PNG (Portable Network Graphics) is
a popular image format for web-based images.
14 @property
15 def face(self):
16 """Return the Card's self._face value."""
17 return self._face
18
19 @property
20 def suit(self):
21 """Return the Card's self._suit value."""
22 return self._suit
23
24 @property
25 def image_name(self):
26 """Return the Card's image file name."""
27 return str(self).replace(' ', '_') + '.png'
28
Methods That Return String Representations of a Card

Class Card provides three special methods that return string representations. As in class
Time, method __repr__ returns a string representation that looks like a constructor expres-
sion for creating and initializing a Card object:
30 """Return string representation for repr()."""
31 return f"Card(face='{self.face}', suit='{self.suit}')"
32
Method __str__ returns a string of the format 'face of suit', such as 'Ace of Hearts':
34 """Return string representation for str()."""
35 return f'{self.face} of {self.suit}'
36
When the preceding section’s IPython session printed the entire deck, you saw that
the Cards were displayed in four left-aligned columns. As you’ll see in the __str__ method
of class DeckOfCards, we use f-strings to format the Cards in fields of 19 characters each.
Class Card’s special method __format__ is called when a Card object is formatted as a
string, such as in an f-string:
37 def __format__(self, format):
38 """Return formatted string representation for str()."""
39 return f'{str(self):{format}}'
This method’s second argument is the format string used to format the object. To use the
format parameter’s value as the format specifier, enclose the parameter name in braces to
the right of the colon. In this case, we’re formatting the Card object’s string representation
returned by str(self). We’ll discuss __format__ again when we present the __str__
method in class DeckOfCards.
10.6.3 Class DeckOfCards

Class DeckOfCards has a class attribute NUMBER_OF_CARDS, representing the number of
Cards in a deck, and creates two data attributes:
• _current_card keeps track of which Card will be dealt next (0–51) and
• _deck (line 12) is a list of 52 Card objects.
Method __init__
DeckOfCards method __init__ initializes a _deck of Cards. The for statement fills the list
_deck by appending new Card objects, each initialized with two strings—one from the list
Card.FACES and one from Card.SUITS. The calculation count % 13 always results in a
value from 0 to 12 (the 13 indices of Card.FACES), and the calculation count // 13 always
results in a value from 0 to 3 (the four indices of Card.SUITS). When the _deck list is ini-
tialized, it contains the Cards with faces 'Ace' through 'King' in order for all the Hearts,
then the Diamonds, then the Clubs, then the Spades.
1 # deck.py
2 """Deck class represents a deck of Cards."""
3 import random
4 from card import Card
5
6 class DeckOfCards:
7 NUMBER_OF_CARDS = 52 # constant number of Cards
8
9 def __init__(self):
10 """Initialize the deck."""
11 self._current_card = 0
12 self._deck = []
13
14 for count in range(DeckOfCards.NUMBER_OF_CARDS):
15 self._deck.append(Card(Card.FACES[count % 13],
16 Card.SUITS[count // 13]))
17
Method shuffle
Method shuffle resets _current_card to 0, then shuffles the Cards in _deck using the
random module’s shuffle function:
18 def shuffle(self):
19 """Shuffle deck."""
20 self._current_card = 0
21 random.shuffle(self._deck)
22
Method deal_card
Method deal_card deals one Card from _deck. Recall that _current_card indicates the
index (0–51) of the next Card to be dealt (that is, the Card at the top of the deck). Line 26
tries to get the _deck element at index _current_card. If successful, the method incre-
ments _current_card by 1, then returns the Card being dealt; otherwise, the method
returns None to indicate there are no more Cards to deal.
23 def deal_card(self):
24 """Return one Card."""
25 try:
26 card = self._deck[self._current_card]
27 self._current_card += 1
28 return card
29 except:
30 return None
31
Method __str__
Class DeckOfCards also defines special method __str__ to get a string representation of
the deck in four columns with each Card left aligned in a field of 19 characters. When line
37 formats a given Card, its __format__ special method is called with format specifier
'<19' as the method’s format argument. Method __format__ then uses '<19' to create
the Card’s formatted string representation.
33 """Return a string representation of the current _deck."""
34 s = ''
35
36 for index, card in enumerate(self._deck):
37 s += f'{self._deck[index]:<19}'
38 if (index + 1) % 4 == 0:
39 s += '\n'
40
41 return s
10.6.4 Displaying Card Images with Matplotlib

So far, we’ve displayed Cards as text. Now, let’s display Card images. For this demonstra-
tion, we downloaded public-domain6 card images from Wikimedia Commons:
https://commons.wikimedia.org/wiki/
Category:SVG_English_pattern_playing_cards
These are located in the ch10 examples folder’s card_images subfolder. First, let’s create a
DeckOfCards:
In [1]: from deck import DeckOfCards
6. https://creativecommons.org/publicdomain/zero/1.0/deed.en.
Enable Matplotlib in IPython

Next, enable Matplotlib support in IPython by using the %matplotlib magic:
In [3]: %matplotlib
Using matplotlib backend: Qt5Agg
Create the Base Path for Each Image

Before displaying each image, we must load it from the card_images folder. We’ll use the
pathlib module’s Path class to construct the full path to each image on our system. Snip-
pet [5] creates a Path object for the current folder (the ch10 examples folder), which is
represented by '.', then uses Path method joinpath to append the subfolder containing
the card images:
In [4]: from pathlib import Path
In [5]: path = Path('.').joinpath('card_images')
Import the Matplotlib Features

Next, let’s import the Matplotlib modules we’ll need to display the images. We’ll use a
function from matplotlib.image to load the images:
In [6]: import matplotlib.pyplot as plt
In [7]: import matplotlib.image as mpimg
Create the Figure and Axes Objects

The following snippet uses Matplotlib function subplots to create a Figure object in
which we’ll display the images as 52 subplots with four rows (nrows) and 13 columns
(ncols). The function returns a tuple containing the Figure and an array of the subplots’
Axes objects. We unpack these into variables figure and axes_list:
In [8]: figure, axes_list = plt.subplots(nrows=4, ncols=13)
When you execute this statement in IPython, the Matplotlib window appears immediately
with 52 empty subplots.
Configure the Axes Objects and Display the Images
Next, we iterate through all the Axes objects in axes_list. Recall that ravel provides a
one-dimensional view of a multidimensional array. For each Axes object, we perform the
following tasks:
• We’re not plotting data, so we do not need axis lines and labels for each image.
The first two statements in the loop hide the x- and y-axes.
• The third statement deals a Card and gets its image_name.
• The fourth statement uses Path method joinpath to append the image_name to
the Path, then calls Path method resolve to determine the full path to the image
on our system. We pass the resulting Path object to the built-in str function to
get the string representation of the image’s location. Then, we pass that string to
the matplotlib.image module’s imread function, which loads the image.
• The last statement calls Axes method imshow to display the current image in the
current subplot.
In [9]: for axes in axes_list.ravel():

...: axes.get_xaxis().set_visible(False)
...: axes.get_yaxis().set_visible(False)
...: image_name = deck_of_cards.deal_card().image_name
...: img = mpimg.imread(str(path.joinpath(image_name).resolve()))
...: axes.imshow(img)
...:
Maximize the Image Sizes

At this point, all the images are displayed. To make the cards as large as possible, you can
maximize the window, then call the Matplotlib Figure object’s tight_layout method.
This removes most of the extra white space in the window:
In [10]: figure.tight_layout()
The following image shows the contents of the resulting window:
Shuffle and Re-Deal the Deck

To see the images shuffled, call method shuffle, then re-execute snippet [9]’s code:

...:
Self Check
1 (Fill-In) Matplotlib function returns a tuple containing a Figure and an
array of Axes objects.
Answer: subplots.
2 (True/False) Path method appendpath appends to a Path object.
Answer: False. Path method joinpath appends to a Path object
3 (Fill-In) The Path object Path('.') represents .
Answer: the current folder from which the code was executed.
4 (IPython Session) Continue this section’s session by reshuffling the cards, then creat-
ing a new Figure containing two rows of five cards each—these might represent two five-
card poker hands.
In [14]: figure, axes_list = plt.subplots(nrows=2, ncols=5)

...:
In [16]: figure.tight_layout()
Answer:
10.7 Inheritance: Base Classes and Subclasses

Often, an object of one class is an object of another class as well. For example, a CarLoan
is a Loan as are HomeImprovementLoans and MortgageLoans. Class CarLoan can be said to
inherit from class Loan. In this context, class Loan is a base class, and class CarLoan is a
subclass. A CarLoan is a specific type of Loan, but it’s incorrect to claim that every Loan is
a CarLoan—the Loan could be any type of loan. The following table lists several simple
examples of base classes and subclasses—base classes tend to be “more general” and sub-
classes “more specific”:
Base class Subclasses
Student GraduateStudent, UndergraduateStudent

Shape Circle, Triangle, Rectangle, Sphere, Cube
Loan CarLoan, HomeImprovementLoan, MortgageLoan
Employee Faculty, Staff
BankAccount CheckingAccount, SavingsAccount
Because every subclass object is an object of its base class, and one base class can have
many subclasses, the set of objects represented by a base class is often larger than the set of
objects represented by any of its subclasses. For example, the base class Vehicle represents
all vehicles, including cars, trucks, boats, bicycles and so on. By contrast, subclass Car rep-
resents a smaller, more specific subset of vehicles.
CommunityMember Inheritance Hierarchy
Inheritance relationships form tree-like hierarchical structures. A base class exists in a hierar-
chical relationship with its subclasses. Let’s develop a sample class hierarchy (shown in the
following diagram), also called an inheritance hierarchy. A university community has thou-
sands of members, including employees, students and alumni. Employees are either faculty
or staff members. Faculty members are either administrators (e.g., deans and department
chairpersons) or teachers. The hierarchy could contain many other classes. For example, stu-
10.7 Inheritance: Base Classes and Subclasses 431
dents can be graduate or undergraduate students. Undergraduate students can be freshmen,

sophomores, juniors or seniors. With single inheritance, a class is derived from one base class.
With multiple inheritance, a subclass inherits from two or more base classes. Single inheri-
tance is straightforward. Multiple inheritance is beyond the scope of this book. Before you
use it, search online for the “diamond problem in Python multiple inheritance.”
CommunityMember
Employee Student Alum
Faculty Staff
Administrator Teacher
Each arrow in the hierarchy represents an is-a relationship. As we follow the arrows
upward in this class hierarchy, we can state, for example, that “an Employee is a
CommunityMember” and “a Teacher is a Faculty member.” CommunityMember is the direct
base class of Employee, Student and Alum and is an indirect base class of all the other classes
in the diagram. Starting from the bottom, you can follow the arrows and apply the is-a
relationship up to the topmost superclass. For example, Administrator is a Faculty mem-
ber, is an Employee, is a CommunityMember and, of course, ultimately is an object.
Shape Inheritance Hierarchy
Now consider the Shape inheritance hierarchy in the following class diagram, which
begins with base class Shape, followed by subclasses TwoDimensionalShape and ThreeDim-
ensionalShape. Each Shape is either a TwoDimensionalShape or a ThreeDimensional-
Shape. The third level of this hierarchy contains specific types of TwoDimensionalShapes
and ThreeDimensionalShapes. Again, we can follow the arrows from the bottom of the
diagram to the topmost base class in this class hierarchy to identify several is-a relation-
ships. For example, a Triangle is a TwoDimensionalShape and is a Shape, while a Sphere
is a ThreeDimensionalShape and is a Shape. This hierarchy could contain many other
classes. For example, ellipses and trapezoids also are TwoDimensionalShapes, and cones
and cylinders also are ThreeDimensionalShapes.
Shape
TwoDimensionalShape ThreeDimensionalShape
Circle Square Triangle Sphere Cube Tetrahedron

“is a” vs. “has a”

Inheritance produces “is-a” relationships in which an object of a subclass type may also
be treated as an object of the base-class type. You’ve also seen “has-a” (composition) rela-
tionships in which a class has references to one or more objects of other classes as members.
Self Check
1 (Fill-In) A base class exists in a(n) relationship with its subclasses.
Answer: hierarchical.
2 (Fill-In) In this section’s Shape class hierarchy, TwoDimensionalShape is a(n)
of Shape and a(n) of Circle, Square and Triangle.
Answer: subclass, base class.
10.8 Building an Inheritance Hierarchy; Introducing

Polymorphism
Let’s use a hierarchy containing types of employees in a company’s payroll app to discuss
the relationship between a base class and its subclass. All employees of the company have
a lot in common, but commission employees (who will be represented as objects of a base
class) are paid a percentage of their sales, while salaried commission employees (who will be
represented as objects of a subclass) receive a percentage of their sales plus a base salary.
First, we present base class CommissionEmployee. Next, we create a subclass Salaried-
CommissionEmployee that inherits from class CommissionEmployee. Then, we use an IPy-
thon session to create a SalariedCommissionEmployee object and demonstrate that it has
all the capabilities of the base class and the subclass, but calculates its earnings differently.
10.8.1 Base Class CommissionEmployee

Consider class CommissionEmployee, which provides the following features:
• Method __init__ (lines 8–15), which creates the data attributes _first_name,
_last_name and _ssn (Social Security number), and uses the setters of properties
gross_sales and commission_rate to create their corresponding data attributes.
• Read-only properties first_name (lines 17–19), last_name (lines 21–23) and
ssn(line 25–27), which return the corresponding data attributes.
• Read-write properties gross_sales (lines 29–39) and commission_rate (lines
41–52), in which the setters perform data validation.
• Method earnings (lines 54–56), which calculates and returns a CommissionEm-
ployee’s
earnings.
• Method __repr__ (lines 58–64), which returns a string representation of a Com-
missionEmployee.
1 # commmissionemployee.py
2 """CommissionEmployee base class."""
4
10.8 Building an Inheritance Hierarchy; Introducing Polymorphism 433
5 class CommissionEmployee:
6 """An employee who gets paid commission based on gross sales."""
7
8 def __init__(self, first_name, last_name, ssn,
9 gross_sales, commission_rate):
10 """Initialize CommissionEmployee's attributes."""
11 self._first_name = first_name
12 self._last_name = last_name
13 self._ssn = ssn
14 self.gross_sales = gross_sales # validate via property
15 self.commission_rate = commission_rate # validate via property
16
17 @property
18 def first_name(self):
19 return self._first_name
20
21 @property
22 def last_name(self):
23 return self._last_name
24
25 @property
26 def ssn(self):
27 return self._ssn
28
29 @property
30 def gross_sales(self):
31 return self._gross_sales
32
33 @gross_sales.setter
34 def gross_sales(self, sales):
35 """Set gross sales or raise ValueError if invalid."""
36 if sales < Decimal('0.00'):
37 raise ValueError('Gross sales must be >= to 0')
38
39 self._gross_sales = sales
40
41 @property
42 def commission_rate(self):
43 return self._commission_rate
44
45 @commission_rate.setter
46 def commission_rate(self, rate):
47 """Set commission rate or raise ValueError if invalid."""
48 if not (Decimal('0.0') < rate < Decimal('1.0')):
49 raise ValueError(
50 'Interest rate must be greater than 0 and less than 1')
51
52 self._commission_rate = rate
53
54 def earnings(self):
55 """Calculate earnings."""
56 return self.gross_sales * self.commission_rate
57
60 return ('CommissionEmployee: ' +
61 f'{self.first_name} {self.last_name}\n' +
62 f'social security number: {self.ssn}\n' +
63 f'gross sales: {self.gross_sales:.2f}\n' +
64 f'commission rate: {self.commission_rate:.2f}')
Properties first_name, last_name and ssn are read-only. We chose not to validate
them, though we could have. For example, we could validate the first and last names—
perhaps by ensuring that they’re of a reasonable length. We could validate the Social Secu-
rity number to ensure that it contains nine digits, with or without dashes (for example, to
ensure that it’s in the format ###-##-#### or #########, where each # is a digit).
All Classes Inherit Directly or Indirectly from Class object
You use inheritance to create new classes from existing ones. In fact, every Python class
inherits from an existing class. When you do not explicitly specify the base class for a new
class, Python assumes that the class inherits directly from class object. The Python class
hierarchy begins with class object, the direct or indirect base class of every class. So, class
CommissionEmployee’s header could have been written as
class CommissionEmployee(object):
The parentheses after CommissionEmployee indicate inheritance and may contain a single
class for single inheritance or a comma-separated list of base classes for multiple inheri-
tance. Once again, multiple inheritance is beyond the scope of this book.
Class CommissionEmployee inherits all the methods of class object. Class object
does not have any data attributes. Two of the many methods inherited from object are
__repr__ and __str__. So every class has these methods that return string representations
of the objects on which they’re called. When a base-class method implementation is inap-
propriate for a derived class, that method can be overridden (i.e., redefined) in the derived
class with an appropriate implementation. Method __repr__ (lines 58–64) overrides the
default implementation inherited into class CommissionEmployee from class object.7
Testing Class CommissionEmployee
Let’s quickly test some of CommissionEmployee’s features. First, create and display a Com-
missionEmployee:
In [1]: from commissionemployee import CommissionEmployee
In [3]: c = CommissionEmployee('Sue', 'Jones', '333-33-3333',

...: Decimal('10000.00'), Decimal('0.06'))
...:
In [4]: c
Out[4]:
CommissionEmployee: Sue Jones
social security number: 333-33-3333
gross sales: 10000.00
commission rate: 0.06
7. See https://docs.python.org/3/reference/datamodel.html for object’s overridable methods.

Next, let’s calculate and display the CommissionEmployee’s earnings:

In [5]: print(f'{c.earnings():,.2f}')
600.00
Finally, let’s change the CommissionEmployee’s gross sales and commission rate, then
recalculate the earnings:
In [6]: c.gross_sales = Decimal('20000.00')
In [7]: c.commission_rate = Decimal('0.1')
In [8]: print(f'{c.earnings():,.2f}')
2,000.00
Self Check
1 (Fill-In) When a base-class method implementation is inappropriate for a derived
class, that method can be (i.e., redefined) in the derived class with an appropriate
implementation.
Answer: overridden.
2 (What Does This Code Do?) In this section’s IPython session, explain in detail what
snippet [6] does:
c.gross_sales = Decimal('20000.00')
Answer: This statement creates a Decimal object and assigns it to a CommissionEmployee’s

gross_sales property, invoking the property’s setter. The setter checks whether the
new value is less than Decimal('0.00'). If so, the setter raises a ValueError, indicating
that the value must be greater than or equal to 0; otherwise, the setter assigns the new
value to the CommissionEmployee’s _gross_sales attribute.
10.8.2 Subclass SalariedCommissionEmployee

With single inheritance, the subclass starts essentially the same as the base class. The real
strength of inheritance comes from the ability to define in the subclass additions, replace-
ments or refinements for the features inherited from the base class.
Many of a SalariedCommissionEmployee’s capabilities are similar, if not identical, to
those of class CommissionEmployee. Both types of employees have first name, last name,
Social Security number, gross sales and commission rate data attributes, and properties
and methods to manipulate that data. To create class SalariedCommissionEmployee with-
out using inheritance, we could have copied class CommissionEmployee’s code and pasted it
into class SalariedCommissionEmployee. Then we could have modified the new class to
include a base salary data attribute, and the properties and methods that manipulate the
base salary, including a new earnings method. This copy-and-paste approach is often error-
prone. Worse yet, it can spread many physical copies of the same code (including errors)
throughout a system, making your code less maintainable. Inheritance enables us to
“absorb” the features of a class without duplicating code. Let’s see how.
Declaring Class SalariedCommissionEmployee
We now declare the subclass SalariedCommissionEmployee, which inherits most of its
capabilities from class CommissionEmployee (line 6). A SalariedCommissionEmployee is
a CommissionEmployee (because inheritance passes on the capabilities of class Commis-

sionEmployee), but class SalariedCommissionEmployee also has the following features:
• Method __init__ (lines 10–15), which initializes all the data inherited from class
CommissionEmployee (we’ll say more about this momentarily), then uses the
base_salary property’s setter to create a _base_salary data attribute.
• Read-write property base_salary (lines 17–27), in which the setter performs

data validation.
• A customized version of method earnings (lines 29–31).
• A customized version of method __repr__ (lines 33–36).
1 # salariedcommissionemployee.py
2 """SalariedCommissionEmployee derived from CommissionEmployee."""
3 from commissionemployee import CommissionEmployee
5
6 class SalariedCommissionEmployee(CommissionEmployee):
7 """An employee who gets paid a salary plus
8 commission based on gross sales."""
9
10 def __init__(self, first_name, last_name, ssn,
11 gross_sales, commission_rate, base_salary):
12 """Initialize SalariedCommissionEmployee's attributes."""
13 super().__init__(first_name, last_name, ssn,
14 gross_sales, commission_rate)
15 self.base_salary = base_salary # validate via property
16
17 @property
18 def base_salary(self):
19 return self._base_salary
20
21 @base_salary.setter
22 def base_salary(self, salary):
23 """Set base salary or raise ValueError if invalid."""
24 if salary < Decimal('0.00'):
25 raise ValueError('Base salary must be >= to 0')
26
27 self._base_salary = salary
28
29 def earnings(self):
30 """Calculate earnings."""
31 return super().earnings() + self.base_salary
32
35 return ('Salaried' + super().__repr__() +
36 f'\nbase salary: {self.base_salary:.2f}')
Inheriting from Class CommissionEmployee

To inherit from a class, you must first import its definition (line 3). Line 6
class SalariedCommissionEmployee(CommissionEmployee):
specifies that class SalariedCommissionEmployee inherits from CommissionEmployee.

Though you do not see class CommissionEmployee’s data attributes, properties and meth-
ods in class SalariedCommissionEmployee, they’re nevertheless part of the new class, as
you’ll soon see.
Method __init__ and Built-In Function super
Each subclass __init__ must explicitly call its base class’s __init__ to initialize the data attri-
butes inherited from the base class. This call should be the first statement in the subclass’s
__init__ method. SalariedCommissionEmployee’s __init__ method explicitly calls class
CommissionEmployee’s __init__ method (lines 13–14) to initialize the base-class portion
of a SalariedCommissionEmployee object (that is, the five inherited data attributes from
class CommissionEmployee). The notation super().__init__ uses the built-in function
super to locate and call the base class’s __init__ method, passing the five arguments that
initialize the inherited data attributes.
Overriding Method earnings
Class SalariedCommissionEmployee’s earnings method (lines 29–31) overrides class
CommissionEmployee’s earnings method (Section 10.8.1, lines 54–56) to calculate the
earnings of a SalariedCommissionEmployee. The new version obtains the portion of the
earnings based on commission alone by calling CommissionEmployee’s earnings method
with the expression super().earnings() (line 31). SalariedCommissionEmployee’s
earnings method then adds the base_salary to this value to calculate the total earnings.
By having SalariedCommissionEmployee’s earnings method invoke CommissionEm-
ployee’s earnings method to calculate part of a SalariedCommissionEmployee’s earnings,
we avoid duplicating the code and reduce code-maintenance problems.
Overriding Method __repr__
SalariedCommissionEmployee’s __repr__ method (lines 33–36) overrides class Commis-
sionEmployee’s __repr__ method (Section 10.8.1, lines 58–64) to return a String repre-
sentation that’s appropriate for a SalariedCommissionEmployee. The subclass creates part
of the string representation by concatenating 'Salaried' and the string returned by
super().__repr__(), which calls CommissionEmployee’s __repr__ method. The overrid-
den method then concatenates the base salary information and returns the resulting string.
Testing Class SalariedCommissionEmployee
Let’s test class SalariedCommissionEmployee to show that it indeed inherited capabilities
from class CommissionEmployee. First, let’s create a SalariedCommissionEmployee and
print all of its properties:
In [9]: from salariedcommissionemployee import SalariedCommissionEmployee
In [10]: s = SalariedCommissionEmployee('Bob', 'Lewis', '444-44-4444',

...: Decimal('5000.00'), Decimal('0.04'), Decimal('300.00'))
...:
In [11]: print(s.first_name, s.last_name, s.ssn, s.gross_sales,

...: s.commission_rate, s.base_salary)
Bob Lewis 444-44-4444 5000.00 0.04 300.00
Notice that the SalariedCommissionEmployee object has all of the properties of classes
CommissionEmployee and SalariedCommissionEmployee.
Next, let’s calculate and display the SalariedCommissionEmployee’s earnings.
Because we call method earnings on a SalariedCommissionEmployee object, the subclass
version of the method executes:
In [12]: print(f'{s.earnings():,.2f}')
500.00
Now, let’s modify the gross_sales, commission_rate and base_salary properties,

then display the updated data via the SalariedCommissionEmployee’s __repr__ method:
In [13]: s.gross_sales = Decimal('10000.00')
In [14]: s.commission_rate = Decimal('0.05')
In [15]: s.base_salary = Decimal('1000.00')
In [16]: print(s)
SalariedCommissionEmployee: Bob Lewis
base salary: 1000.00
Again, because this method is called on a SalariedCommissionEmployee object, the sub-

class version of the method executes. Finally, let’s calculate and display the Salaried-
CommissionEmployee’s updated earnings:
In [17]: print(f'{s.earnings():,.2f}')
1,500.00
Testing the “is a” Relationship

Python provides two built-in functions—issubclass and isinstance—for testing “is a”
relationships. Function issubclass determines whether one class is derived from another:
In [18]: issubclass(SalariedCommissionEmployee, CommissionEmployee)
Out[18]: True
Function isinstance determines whether an object has an “is a” relationship with a

specific type. Because SalariedCommissionEmployee inherits from CommissionEmployee,
both of the following snippets return True, confirming the “is a” relationship
In [19]: isinstance(s, CommissionEmployee)
Out[19]: True
In [20]: isinstance(s, SalariedCommissionEmployee)

Out[20]: True
Self Check
1 (Fill-In) Function determines whether an object has an “is a” relationship
with a specific type.
Answer: isinstance.
2 (Fill-In) Function determines whether one class is derived from another.
Answer: issubclass.
3 (What Does This Code Do?) Explain in detail what the following statement from class
SalariedCommissionEmployee’s earnings method does:
return super().earnings() + self.base_salary
Answer: This statement calculates a SalariedCommissionEmployee’s earnings by using

the built-in function super to invoke the base class CommissionEmployee’s version of
method earnings then adding to the result the base_salary.
10.8.3 Processing CommissionEmployees and

SalariedCommissionEmployees Polymorphically
With inheritance, every object of a subclass also may be treated as an object of that sub-
class’s base class. We can take advantage of this “subclass-object-is-a-base-class-object”
relationship to perform some interesting manipulations. For example, we can place objects
related through inheritance into a list, then iterate through the list and treat each element
as a base-class object. This allows a variety of objects to be processed in a general way. Let’s
demonstrate this by placing the CommissionEmployee and SalariedCommissionEmployee
objects in a list, then for each element displaying its string representation and earnings:
In [21]: employees = [c, s]
In [22]: for employee in employees:

...: print(employee)
...: print(f'{employee.earnings():,.2f}\n')
...:
2,000.00

base salary: 1000.00
1,500.00
As you can see, the correct string representation and earnings are displayed for each
employee. This is called polymorphism—a key capability of object-oriented programming
(OOP).
Self Check
1 (Fill-In) enables us to take advantage of the “subclass-object-is-a-base-class-
object” relationship to process objects in a general way.
Answer: Polymorphism.
10.8.4 A Note About Object-Based and Object-Oriented Programming

Inheritance with method overriding is a powerful way to build software components that
are like existing components but need to be customized to your application’s unique needs.
In the Python open-source world, there are a huge number of well-developed class libraries
for which your programming style is:
• know what libraries are available,

• know what classes are available,
• make objects of existing classes, and
• send them messages (that is, call their methods).
This style of programming called object-based programming (OBP). When you do compo-
sition with objects of known classes, you’re still doing object-based programming. Adding
inheritance with overriding to customize methods to the unique needs of your applications
and possibly process objects polymorphically is called object-oriented programming (OOP).
If you do composition with objects of inherited classes, that’s also object-oriented pro-
gramming.
10.9 Duck Typing and Polymorphism

Most other object-oriented programming languages require inheritance-based “is a” rela-
tionships to achieve polymorphic behavior. Python is more flexible. It uses a concept
called duck typing, which the Python documentation describes as:
A programming style which does not look at an object’s type to determine if it has
the right interface; instead, the method or attribute is simply called or used (“If it
looks like a duck and quacks like a duck, it must be a duck.”).8
So, when processing an object at execution time, its type does not matter. As long as the
object has the data attribute, property or method (with the appropriate parameters) you
wish to access, the code will work.
Let’s reconsider the loop at the end of Section 10.8.3, which processes a list of
employees:
for employee in employees:
print(employee)
print(f'{employee.earnings():,.2f}\n')
In Python, this loop works properly as long as employees contains only objects that:
• can be displayed with print (that is, they have a string representation) and
• have an earnings method which can be called with no arguments.
All classes inherit from object directly or indirectly, so they all inherit the default methods
for obtaining string representations that print can display. If a class has an earnings
method that can be called with no arguments, we can include objects of that class in the
list employees, even if the object’s class does not have an “is a” relationship with class Com-
missionEmployee. To demonstrate this, consider class WellPaidDuck:
In [1]: class WellPaidDuck:
...: def __repr__(self):
...: return 'I am a well-paid duck'
...: def earnings(self):
...: return Decimal('1_000_000.00')
...:
8. https://docs.python.org/3/glossary.html#term-duck-typing.
10.10 Operator Overloading 441
WellPaidDuck objects, which clearly are not meant to be employees, will work with
the preceding loop. To prove this, let’s create objects of our classes CommissionEmployee,
SalariedCommissionEmployee and WellPaidDuck and place them in a list:
In [3]: from commissionemployee import CommissionEmployee
In [4]: from salariedcommissionemployee import SalariedCommissionEmployee
In [5]: c = CommissionEmployee('Sue', 'Jones', '333-33-3333',

...: Decimal('10000.00'), Decimal('0.06'))
...:
In [6]: s = SalariedCommissionEmployee('Bob', 'Lewis', '444-44-4444',

...: Decimal('5000.00'), Decimal('0.04'), Decimal('300.00'))
...:
In [7]: d = WellPaidDuck()
In [8]: employees = [c, s, d]
Now, let’s process the list using the loop from Section 10.8.3. As you can see in the output,
Python is able to use duck typing to polymorphically process all three objects in the list:
In [9]: for employee in employees:
...: print(employee)
...: print(f'{employee.earnings():,.2f}\n')
...:
600.00

base salary: 300.00
500.00
I am a well-paid duck
1,000,000.00
10.10 Operator Overloading

You’ve seen that you can interact with objects by accessing their attributes and properties
and by calling their methods. Method-call notation can be cumbersome for certain kinds
of operations, such as arithmetic. In these cases, it would be more convenient to use
Python’s rich set of built-in operators.
This section shows how to use operator overloading to define how Python’s operators
should handle objects of your own types. You’ve already used operator overloading fre-
quently across wide ranges of types. For example, you’ve used:
• the + operator for adding numeric values, concatenating lists, concatenating

strings and adding a value to every element in a NumPy array.
• the [] operator for accessing elements in lists, tuples, strings and arrays and for
accessing the value for a specific key in a dictionary.
• the * operator for multiplying numeric values, repeating a sequence and multi-
plying every element in a NumPy array by a specific value.
You can overload most operators. For every overloadable operator, class object
defines a special method, such as __add__ for the addition (+) operator or __mul__ for the
multiplication (*) operator. Overriding these methods enables you to define how a given
operator works for objects of your custom class. For a complete list of special methods, see
https://docs.python.org/3/reference/datamodel.html#special-method-
names
Operator Overloading Restrictions

There are some restrictions on operator overloading:
• The precedence of an operator cannot be changed by overloading. However,
parentheses can be used to force evaluation order in an expression.
• The left-to-right or right-to-left grouping of an operator cannot be changed by
overloading.
• The “arity” of an operator—that is, whether it’s a unary or binary operator—can-
not be changed.
• You cannot create new operators—only existing operators can be overloaded.
• The meaning of how an operator works on objects of built-in types cannot be
changed. You cannot, for example, change + so that it subtracts two integers.
• Operator overloading works only with objects of custom classes or with a mixture
of an object of a custom class and an object of a built-in type.
Complex Numbers
To demonstrate operator overloading, we’ll define a class named Complex that represents
complex numbers. Complex numbers, like –3 + 4i and 6.2 – 11.73i, have the form
realPart + imaginaryPart * i
where i is – 1. Like ints, floats and Decimals, complex numbers are arithmetic types.
In this section, we’ll create a class Complex that overloads just the + addition operator and
the += augmented assignment, so we can add Complex objects using Python’s mathemat-
ical notations.9
10.10.1 Test-Driving Class Complex

First, let’s use class Complex to demonstrate its capabilities. We’ll discuss the class’s details
in the next section. Import class Complex from complexnumber.py:
In [1]: from complexnumber import Complex
9. Note that Python has built-in support for complex values. In the exercises, we’ll ask you to explore
using these built-in capabilities.
10.10 Operator Overloading 443
Next, create and display a couple of Complex objects. Snippets [3] and [5] implicitly call
the Complex class’s __repr__ method to get a string representation of each object:
In [2]: x = Complex(real=2, imaginary=4)
In [3]: x
Out[3]: (2 + 4i)
In [4]: y = Complex(real=5, imaginary=-1)
In [5]: y
Out[5]: (5 - 1i)
We chose the __repr__ string format shown in snippets [3] and [5] to mimic the
__repr__ strings produced by Python’s built-in complex type.10
Now, let’s use the + operator to add the Complex objects x and y. This expression adds
the real parts of the two operands (2 and 5) and the imaginary parts of the two operands
(4i and -1i), then returns a new Complex object containing the result:
In [6]: x + y
Out[6]: (7 + 3i)
The + operator does not modify either of its operands:

In [7]: x
Out[7]: (2 + 4i)
In [8]: y
Out[8]: (5 - 1i)
Finally, let’s use the += operator to add y to x and store the result in x. The += operator
modifies its left operand but not its right operand:
In [9]: x += y
In [10]: x
Out[10]: (7 + 3i)
In [11]: y
Out[11]: (5 - 1i)
10.10.2 Class Complex Definition

Now that we’ve seen class Complex in action, let’s look at its definition to see how those
capabilities were implemented.
Method __init__
The class’s __init__ method receives parameters to initialize the real and imaginary data
attributes:
10. Python uses j rather than i for – 1. For example, 3+4j (with no spaces around the operator) creates
a complex object with real and imag attributes. The __repr__ string for this complex value is
'(3+4j)'.
1 # complexnumber.py
2 """Complex class with overloaded operators."""
3
4 class Complex:
5 """Complex class that represents a complex number
6 with real and imaginary parts."""
7
8 def __init__(self, real, imaginary):
9 """Initialize Complex class's attributes."""
10 self.real = real
11 self.imaginary = imaginary
12
Overloaded + Operator
The following overridden special method __add__ defines how to overload the + operator
for use with two Complex objects:
13 def __add__(self, right):
14 """Overrides the + operator."""
15 return Complex(self.real + right.real,
16 self.imaginary + right.imaginary)
17
Methods that overload binary operators must provide two parameters—the first (self) is
the left operand and the second (right) is the right operand. Class Complex’s __add__
method takes two Complex objects as arguments and returns a new Complex object con-
taining the sum of the operands’ real parts and the sum of the operands’ imaginary parts.
We do not modify the contents of either of the original operands. This matches our
intuitive sense of how this operator should behave. Adding two numbers does not modify
either of the original values.
Overloaded += Augmented Assignment
Lines 18–22 overload special method __iadd__ to define how the += operator adds two
Complex objects:
18 def __iadd__(self, right):
19 """Overrides the += operator."""
20 self.real += right.real
21 self.imaginary += right.imaginary
22 return self
23
Augmented assignments modify their left operands, so method __iadd__ modifies the
selfobject, which represents the left operand, then returns self.
Method __repr__
Lines 24–28 return the string representation of a Complex number.
26 return (f'({self.real} ' +
27 ('+' if self.imaginary >= 0 else '-') +
28 f' {abs(self.imaginary)}i)')
10.11 Exception Class Hierarchy and Custom Exceptions 445
Self Check
1 (Fill-In) Suppose a and b are integer variables and a program calculates a + b. Now
suppose c and d are string variables and a program performs the concatenation c + d. The
two + operators here are clearly being used for different purposes. This is an example of
.
Answer: operator overloading.
2 (True/False) Python allows you to create new operators to overload and to change
how existing operators work for built-in types.
Answer: False. Python prohibits you from creating new operators, and operator overload-
ing cannot change how an operator works with built-in types.
3 (IPython Session) Modify class Complex to support operators - and -=, then test these
operators.
Answer: The new method definitions (located in complexnumber2.py) are:
def __sub__(self, right):
"""Overrides the - operator."""
return Complex(self.real - right.real,
self.imaginary - right.imaginary)
def __isub__(self, right):

"""Overrides the -= operator."""
self.real -= right.real
self.imaginary -= right.imaginary
return self
In [1]: from complexnumber2 import Complex
In [2]: x = Complex(real=2, imaginary=4)
In [3]: y = Complex(real=5, imaginary=-1)
In [4]: x - y
Out[4]: (-3 + 5i)
In [5]: x -= y
In [6]: x
Out[6]: (-3 + 5i)
In [7]: y
Out[7]: (5 - 1i)
10.11 Exception Class Hierarchy and Custom Exceptions

In the previous chapter, we introduced exception handling. Every exception is an object
of a class in Python’s exception class hierarchy11 or an object of a class that inherits from
one of those classes. Exception classes inherit directly or indirectly from base class Base-
Exception and are defined in module exceptions.
11. https://docs.python.org/3/library/exceptions.html.
Python defines four primary BaseException subclasses—SystemExit, KeyboardIn-

terrupt, GeneratorExit and Exception:
• SystemExit terminates program execution (or terminates an interactive session)
and when uncaught does not produce a traceback like other exception types.
• KeyboardInterrupt exceptions occur when the user types the interrupt com-
mand—Ctrl + C (or control + C) on most systems.
• GeneratorExit exceptions occur when a generator closes—normally when a gen-
erator finishes producing values or when its close method is called explicitly.
• Exception is the base class for most common exceptions you’ll encounter. You’ve
seen exceptions of the Exception subclasses ZeroDivisionError, NameError,
ValueError, StatisticsError, TypeError, IndexError, KeyError, Runtime-
Error and AttributeError. Often, StandardErrors can be caught and handled,
so the program can continue running.
Catching Base-Class Exceptions
One of the benefits of the exception class hierarchy is that an except handler can catch
exceptions of a particular type or can use a base-class type to catch those base-class excep-
tions and all related subclass exceptions. For example, an except handler that specifies the
base class Exception can catch objects of any subclass of Exception. Placing an except
handler that catches type Exception before other except handlers is a logic error, because
all exceptions would be caught before other exception handlers could be reached. Thus,
subsequent exception handlers are unreachable.
Custom Exception Classes
When you raise an exception from your code, you should generally use one of the existing
exception classes from the Python Standard Library. However, using the inheritance tech-
niques you learned earlier in this chapter, you can create your own custom exception
classes that derive directly or indirectly from class Exception. Generally, that’s discour-
aged, especially among novice programmers. Before creating custom exception classes,
look for an appropriate existing exception class in the Python exception hierarchy. Define
new exception classes only if you need to catch and handle the exceptions differently from
other existing exception types. That should be rare.
Self Check
1 (Fill-In) Most exceptions you’ll encounter inherit from base class and are
defined in module .
Answer: Exception, exceptions.
2 (True/False) When you raise an exception from your code, you should generally use
a new exception class.
Answer: False. When you raise an exception from your code, you should generally use one
of the existing exception classes from the Python Standard Library.
10.12 Named Tuples 447
10.12 Named Tuples

You’ve used tuples to aggregate several data attributes into a single object. The Python
Standard Library’s collections module also provides named tuples that enable you to
reference a tuple’s members by name rather than by index number.
Let’s create a simple named tuple that might be used to represent a card in a deck of
cards. First, import function namedtuple:
In [1]: from collections import namedtuple
Function namedtuple creates a subclass of the built-in tuple type. The function’s first
argument is your new type’s name and the second is a list of strings representing the iden-
tifiers you’ll use to reference the new type’s members:
In [2]: Card = namedtuple('Card', ['face', 'suit'])
We now have a new tuple type named Card that we can use anywhere a tuple can be used.
Let’s create a Card object, access its members by name and display its string representation:
In [3]: card = Card(face='Ace', suit='Spades')
In [4]: card.face
Out[4]: 'Ace'
In [5]: card.suit
Out[5]: 'Spades'
In [6]: card
Out[6]: Card(face='Ace', suit='Spades')
Other Named Tuple Features

Each named tuple type has additional methods. The type’s _make class method (that is, a
method called on the class) receives an iterable of values and returns an object of the named
tuple type:
In [7]: values = ['Queen', 'Hearts']
In [8]: card = Card._make(values)
In [9]: card
Out[9]: Card(face='Queen', suit='Hearts')
This could be useful, for example, if you have a named tuple type representing records in
a CSV file. As you read and tokenize CSV records, you could convert them into named
tuple objects.
For a given object of a named tuple type, you can get an OrderedDict dictionary rep-
resentation of the object’s member names and values. An OrderedDict remembers the
order in which its key–value pairs were inserted in the dictionary:
In [10]: card._asdict()
Out[10]: OrderedDict([('face', 'Queen'), ('suit', 'Hearts')])
For additional named tuple features see:

https://docs.python.org/3/library/
collections.html#collections.namedtuple
Self Check
1 (Fill-In) The Python Standard Library’s collections module’s function
creates a custom tuple type that enables you to reference the tuple’s members by name
rather than by index number.
Answer: namedtuple.
2 (IPython Session) Create a namedtuple called Time with members named hour, min-
ute and second. Then, create a Time object, access its members and display its string rep-
resentation.
Answer:
In [1]: from collections import namedtuple
In [2]: Time = namedtuple('Time', ['hour', 'minute', 'second'])
In [3]: t = Time(13, 30, 45)
In [4]: print(t.hour, t.minute, t.second)

13 30 45
In [5]: t
10.13 A Brief Intro to Python 3.7’s New Data Classes

Though named tuples allow you to reference their members by name, they’re still just
tuples, not classes. For some of the benefits of named tuples, plus the capabilities that tra-
ditional Python classes provide, you can use Python 3.7’s new data classes12 from the
Python Standard Library’s dataclasses module.
Data classes are among Python 3.7’s most important new features. They help you
build classes faster by using more concise notation and by autogenerating “boilerplate” code
that’s common in most classes. They could become the preferred way to define many
Python classes. In this section, we’ll present data-class fundamentals. At the end of the sec-
tion, we’ll provide links to more information.
Data Classes Autogenerate Code
Most classes you’ll define provide an __init__ method to create and initialize an object’s
attributes and a __repr__ method to specify an object’s custom string representation. If a
class has many data attributes, creating these methods can be tedious.
Data classes autogenerate the data attributes and the __init__ and __repr__ methods
for you. This can be particularly useful for classes that primarily aggregate related data
items. For example, in an application that processes CSV records, you might want a class
that represents each record’s fields as data attributes in an object. You’ll see in an exercise
that data classes can be generated dynamically from a list of field names.
Data classes also autogenerate method __eq__, which overloads the == operator. Any
class that has an __eq__ method also implicitly supports !=. All classes inherit class object’s
default __ne__ (not equals) method implementation, which returns the opposite of __eq__
(or NotImplemented if the class does not define __eq__). Data classes do not automatically
generate methods for the <, <=, > and >= comparison operators, but they can.
12. https://www.python.org/dev/peps/pep-0557/.
10.13 A Brief Intro to Python 3.7’s New Data Classes 449
10.13.1 Creating a Card Data Class

Let’s reimplement class Card from Section 10.6.2 as a data class. The new class is defined
in carddataclass.py. As you’ll see, defining a data class requires some new syntax. In the
subsequent subsections, we’ll use our new Card data class in class DeckOfCards to show
that it’s interchangeable with the original Card class, then discuss some of the benefits of
data classes over named tuples and traditional Python classes.
Importing from the dataclasses and typing Modules
The Python Standard Library’s dataclasses module defines decorators and functions for
implementing data classes. We’ll use the @dataclass decorator (imported at line 4) to
specify that a new class is a data class and causes various code to be written for you. Recall
that our original Card class defined class variables FACES and SUITS, which are lists of the
strings used to initialize Cards. We use ClassVar and List from the Python Standard
Library’s typing module (imported at line 5) to indicate that FACES and SUITS are class
variables that refer to lists. We’ll say more about these momentarily:
1 # carddataclass.py
2 """Card data class with class attributes, data attributes,
3 autogenerated methods and explicitly defined methods."""
4 from dataclasses import dataclass
5 from typing import ClassVar, List
6
Using the @dataclass Decorator

To specify that a class is a data class, precede its definition with the @dataclass decorator:13
7 @dataclass
8 class Card:
Optionally, the @dataclass decorator may specify parentheses containing arguments that
help the data class determine what autogenerated methods to include. For example, the
decorator @dataclass(order=True) would cause the data class to autogenerate over-
loaded comparison operator methods for <, <=, > and >=. This might be useful, for exam-
ple, if you need to sort your data-class objects.
Variable Annotations: Class Attributes
Unlike regular classes, data classes declare both class attributes and data attributes inside
the class, but outside the class’s methods. In a regular class, only class attributes are declared
this way, and data attributes typically are created in __init__. Data classes require addi-
tional information, or hints, to distinguish class attributes from data attributes, which also
affects the autogenerated methods’ implementation details.
Lines 9–11 define and initialize the class attributes FACES and SUITS:
9 FACES: ClassVar[List[str]] = ['Ace', '2', '3', '4', '5', '6', '7',
10 '8', '9', '10', 'Jack', 'Queen', 'King']
11 SUITS: ClassVar[List[str]] = ['Hearts', 'Diamonds', 'Clubs', 'Spades']
12
13. https://docs.python.org/3/library/dataclasses.html#module-level-decorators-
classes-and-functions.
In lines 9 and 11, The notation

: ClassVar[List[str]]
is a variable annotation14,15 (sometimes called a type hint) specifying that FACES is a class
attribute (ClassVar) which refers to a list of strings (List[str]). SUITS also is a class attri-
bute which refers to a list of strings.
Class variables are initialized in their definitions and are specific to the class, not indi-
vidual objects of the class. Methods __init__, __repr__ and __eq__, however, are for use
with objects of the class. When a data class generates these methods, it inspects all the vari-
able annotations and includes only the data attributes in the method implementations.
Variable Annotations: Data Attributes
Normally, we create an object’s data attributes in the class’s __init__ method (or methods
called by __init__) via assignments of the form self.attribute_name = value. Because a
data class autogenerates its __init__ method, we need another way to specify data attri-
butes in a data class’s definition. We cannot simply place their names inside the class,
which generates a NameError, as in:
In [1]: from dataclasses import dataclass
In [2]: @dataclass
...: class Demo:
...: x # attempting to create a data attribute x
...:
-------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-2-79ffe37b1ba2> in <module>()
----> 1 @dataclass
2 class Demo:
3 x # attempting to create a data attribute x
4
<ipython-input-2-79ffe37b1ba2> in Demo()
1 @dataclass
2 class Demo:
----> 3 x # attempting to create a data attribute x
4
NameError: name 'x' is not defined
Like class attributes, each data attribute must be declared with a variable annotation.
Lines 13–14 define the data attributes face and suit. The variable annotation ": str"
indicates that each should refer to string objects:
13 face: str
14 suit: str
15. Variable annotations are a recent language feature and are optional for regular classes. You will not
see them in most legacy Python code.
Defining a Property and Other Methods

Data classes are classes, so they may contain properties and methods and participate in
class hierarchies. For this Card data class, we defined the same read-only image_name prop-
erty and custom special methods __str__ and __format__ as in our original Card class ear-
lier in the chapter:
15 @property
16 def image_name(self):
17 """Return the Card's image file name."""
18 return str(self).replace(' ', '_') + '.png'
19
21 """Return string representation for str()."""
22 return f'{self.face} of {self.suit}'
23
24 def __format__(self, format):
25 """Return formatted string representation."""
26 return f'{str(self):{format}}'
Variable Annotation Notes

You can specify variable annotations using built-in type names (like str, int and float),
class types or types defined by the typing module (such as ClassVar and List shown ear-
lier). Even with type annotations, Python is still a dynamically typed language. So, type
annotations are not enforced at execution time. So, even though a Card’s face is meant to
be a string, you can assign any type of object to face, as you’ll do in a Self Check exercise.
Self Check
1 (Fill-In) Data classes require that specify each class attribute’s or data attri-
bute’s data type.
Answer: variable annotations.
2 (Fill-In) The decorator specifies that a new class is a data class.
Answer: @dataclass.
3 (True/False) The Python Standard Library’s annotations module defines the vari-
able annotations that are required in data class definitions.
Answer: False. The typing module defines the variable annotations that are required in
data-class definitions.
4 (True/False) Data classes have auto-generated <, <=, > and >= operators, by default.
Answer: False. The == and != operators are autogenerated by default. The <, <=, > and >=
operators are autogenerated only if the @dataclass decorator specifies the keyword argu-
ment order=True.
10.13.2 Using the Card Data Class

Let’s demonstrate the new Card data class. First, create a Card:
In [1]: from carddataclass import Card
In [2]: c1 = Card(Card.FACES[0], Card.SUITS[3])

Next, let’s use Card’s autogenerated __repr__ method to display the Card:
In [3]: c1
Our custom __str__ method, which print calls when passing it a Card object, returns a
string of the form 'face of suit':
In [4]: print(c1)
Ace of Spades
Let’s access our data class’s attributes and read-only property:

In [5]: c1.face
Out[5]: 'Ace'
In [6]: c1.suit
Out[6]: 'Spades'
In [7]: c1.image_name
Out[7]: 'Ace_of_Spades.png'
Next, let’s demonstrate that Card objects can be compared via the autogenerated == oper-
ator and inherited != operator. First, create two additional Card objects—one identical to
the first and one different:
In [9]: c2
In [11]: c3
Out[11]: Card(face='Ace', suit='Hearts')
Now, compare the objects using == and !=:

In [12]: c1 == c2
Out[12]: True
In [13]: c1 == c3
Out[13]: False
In [14]: c1 != c3
Out[14]: True
Our Card data class is interchangeable with the Card class developed earlier in this
chapter. To demonstrate this, we created the deck2.py file containing a copy of class
DeckOfCards from earlier in the chapter and imported the Card data class into the file. The
following snippets import class DeckOfCards, create an object of the class and print it.
Recall that print implicitly calls the DeckOfCards __str__ method, which formats each
Card in a field of 19 characters, resulting in a call to each Card’s __format__ method. Read
each row left-to-right to confirm that all the Cards are displayed in order from each suit
(Hearts, Diamonds, Clubs and Spades):
In [15]: from deck2 import DeckOfCards # uses Card data class

Ace of Hearts 2 of Hearts 3 of Hearts 4 of Hearts
9 of Hearts 10 of Hearts Jack of Hearts Queen of Hearts
King of Hearts Ace of Diamonds 2 of Diamonds 3 of Diamonds
4 of Diamonds 5 of Diamonds 6 of Diamonds 7 of Diamonds
8 of Diamonds 9 of Diamonds 10 of Diamonds Jack of Diamonds
Queen of Diamonds King of Diamonds Ace of Clubs 2 of Clubs
Jack of Clubs Queen of Clubs King of Clubs Ace of Spades
10 of Spades Jack of Spades Queen of Spades King of Spades
Self Check
1 (IPython Session) Python is a dynamically typed language, so variable annotations are
not enforced on objects of data classes. To prove this, create a Card object, then assign the
integer 100 to its face attribute and display the Card. Display the face attribute’s type
before and after the assignment
Answer:
In [1]: from carddataclass import Card
In [2]: c = Card('Ace', 'Spades')
In [3]: c
In [4]: type(c.face)
Out[4]: str
In [5]: c.face = 100
In [6]: c
Out[6]: Card(face=100, suit='Spades')
In [7]: type(c.face)
Out[7]: int
10.13.3 Data Class Advantages over Named Tuples

Data classes offer several advantages over named tuples16:
• Although each named tuple technically represents a different type, a named tuple
is a tuple and all tuples can be compared to one another. So, objects of different
named tuple types could compare as equal if they have the same number of mem-
bers and the same values for those members. Comparing objects of different data
classes always returns False, as does comparing a data class object to a tuple
object.
• If you have code that unpacks a tuple, adding more members to that tuple breaks
the unpacking code. Data class objects cannot be unpacked. So you can add more
data attributes to a data class without breaking existing code.
• A data class can be a base class or a subclass in an inheritance hierarchy.
10.13.4 Data Class Advantages over Traditional Classes

Data classes also offer various advantages over the traditional Python classes you saw earlier
in this chapter:
• A data class autogenerates __init__, __repr__ and __eq__, saving you time.
• A data class can autogenerate the special methods that overload the <, <=, > and
>= comparison operators.
• When you change data attributes defined in a data class, then use it in a script or
interactive session, the autogenerated code updates automatically. So, you have
less code to maintain and debug.
• The required variable annotations for class attributes and data attributes enable
you to take advantage of static code analysis tools. So, you might be able to elim-
inate additional errors before they can occur at execution time.
• Some static code analysis tools and IDEs can inspect variable annotations and
issue warnings if your code uses the wrong type. This can help you locate logic
errors in your code before you execute it. In an end-of-chapter exercise, we ask you
to use the static code analysis tool MyPy to demonstrate such warnings.
More Information
Data classes have additional capabilities, such as creating “frozen” instances which do not
allow you to assign values to a data class object’s attributes after the object is created. For
a complete list of data class benefits and capabilities, see
https://www.python.org/dev/peps/pep-0557/
and
https://docs.python.org/3/library/dataclasses.html
We’ll ask you to experiment with additional data class features in this chapter’s exercises.
10.14 Unit Testing with Docstrings and doctest

A key aspect of software development is testing your code to ensure that it works correctly.
Even with extensive testing, however, your code may still contain bugs. According to the
famous Dutch computer scientist Edsger Dijkstra, “Testing shows the presence, not the
absence of bugs.”17
Module doctest and the testmod Function
The Python Standard Library provides the doctest module to help you test your code and
conveniently retest it after you make modifications. When you execute the doctest mod-
17. J. N. Buxton and B. Randell, eds, Software Engineering Techniques, April 1970, p. 16. Report on a
conference sponsored by the NATO Science Committee, Rome, Italy, 27–31 October 1969
10.14 Unit Testing with Docstrings and doctest 455
ule’s testmod function, it inspects your functions’, methods’ and classes' docstrings look-
ing for sample Python statements preceded by >>>, each followed on the next line by the
given statement’s expected output (if any).18 The testmod function then executes those
statements and confirms that they produce the expected output. If they do not, testmod
reports errors indicating which tests failed so you can locate and fix the problems in your
code. Each test you define in a docstring typically tests a specific unit of code, such as a
function, a method or a class. Such tests are called unit tests.
Modified Account Class
The file accountdoctest.py contains the class Account from this chapter’s first example.
We modified the __init__ method’s docstring to include four tests which can be used to
ensure that the method works correctly:
• The test in line 11 creates a sample Account object named account1. This state-
ment does not produce any output.
• The test in line 12 shows what the value of account1’s name attribute should be
if line 11 executed successfully. The sample output is shown in line 13.
• The test in line 14 shows what the value of account1’s balance attribute should
be if line 11 executed successfully. The sample output is shown in line 15.
• The test in line 18 creates an Account object with an invalid initial balance. The
sample output shows that a ValueError exception should occur in this case. For
exceptions, the doctest module’s documentation recommends showing just the
first and last lines of the traceback.19
You can intersperse your tests with descriptive text, such as line 17.
1 # accountdoctest.py
2 """Account class definition."""
4
5 class Account:
6 """Account class for demonstrating doctest."""
7
8 def __init__(self, name, balance):
9 """Initialize an Account object.
10
11 >>> account1 = Account('John Green', Decimal('50.00'))
12 >>> account1.name
13 'John Green'
14 >>> account1.balance
15 Decimal('50.00')
16
17 The balance argument must be greater than or equal to 0.
18 >>> account2 = Account('John Green', Decimal('-50.00'))
19 Traceback (most recent call last):
20 ...
21 ValueError: Initial balance must be >= to 0.00.
22 """
18. The notation >>> mimics the standard python interpreter’s input prompts.
19. https://docs.python.org/3/library/doctest.html?highlight=doctest#module-doctest.
23
24 # if balance is less than 0.00, raise an exception
25 if balance < Decimal('0.00'):
26 raise ValueError('Initial balance must be >= to 0.00.')
27
28 self.name = name
29 self.balance = balance
30
31 def deposit(self, amount):
32 """Deposit money to the account."""
33
37
39
40 if __name__ == '__main__':
41 import doctest
42 doctest.testmod(verbose=True)
Module __main__
When you load any module, Python assigns a string containing the module’s name to a
global attribute of the module called __name__. When you execute a Python source file
(such as accountdoctest.py) as a script, Python uses the string '__main__' as the mod-
ule’s name. You can use __name__ in an if statement like lines 40–42 to specify code that
should execute only if the source file is executed as a script. In this example, line 41 imports
the doctest module and line 42 calls the module’s testmod function to execute the doc-
string unit tests.
Running Tests
Run the file accountdoctest.py as a script to execute the tests. By default, if you call
testmod with no arguments, it does not show test results for successful tests. In that case, if
you get no output, all the tests executed successfully. In this example, line 42 calls testmod
with the keyword argument verbose=True. This tells testmod to produce verbose output
showing every test’s results:
Trying:
Expecting nothing
ok
Trying:
account1.name
Expecting:
'John Green'
ok
Trying:
account1.balance
Expecting:
Decimal('50.00')
ok
Trying:
account2 = Account('John Green', Decimal('-50.00'))
10.14 Unit Testing with Docstrings and doctest 457
Expecting:
Traceback (most recent call last):
...
ValueError: Initial balance must be >= to 0.00.
ok
3 items had no tests:
__main__
__main__.Account
__main__.Account.deposit
1 items passed all tests:
4 tests in __main__.Account.__init__
4 tests in 4 items.
4 passed and 0 failed.
Test passed.
In verbose mode, testmod shows for each test what it’s "Trying" to do and what it’s
"Expecting" as a result, followed by "ok" if the test is successful. After completing the
tests in verbose mode, testmod shows a summary of the results.
To demonstrate a failed test, “comment out” lines 25–26 in accountdoctest.py by
preceding each with a #, then run accountdoctest.py as a script. To save space, we show
just the portions of the doctest output indicating the failed test:
...
**********************************************************************
File "accountdoctest.py", line 18, in __main__.Account.__init__
Failed example:
Expected:
...
Got nothing
**********************************************************************
1 items had failures:
1 of 4 in __main__.Account.__init__
4 tests in 4 items.
***Test Failed*** 1 failures.
In this case, we see that line 18’s test failed. The testmod function was expecting a traceback
indicating that a ValueError was raised due to the invalid initial balance. That exception
did not occur, so the test failed. As the programmer responsible for defining this class, this
failing test would be an indication that something is wrong with the validation code in
your __init__ method.
IPython %doctest_mode Magic
A convenient way to create doctests for existing code is to use an IPython interactive ses-
sion to test your code, then copy and paste that session into a docstring. IPython’s In []
and Out[] prompts are not compatible with doctest, so IPython provides the magic
%doctest_mode to display prompts in the correct doctest format. The magic toggles
between the two prompt styles. The first time you execute %doctest_mode, IPython
switches to >>> prompts for input and no output prompts. The second time you execute
%doctest_mode, IPython switches back to In [] and Out[] prompts.
Self Check
1 (Fill-In) When you execute a Python source file as a script, Python creates a global
attribute __name__ and assigns it the string .
Answer: '__main__'.
2 (True/False) When you execute the doctest module’s testmod function, it inspects
your code and automatically creates tests for you.
Answer: False. When you execute the doctest module’s testmod function, it inspects
your code’s function, method and class docstrings looking for sample Python statements
preceded by >>>, each followed on the next line by the given statement’s expected output
(if any).
3 (IPython Session) Add tests to the deposit method’s docstring, then execute the tests.
Your test should create an Account object, deposit a valid amount into it, then attempt to
deposit an invalid negative amount, which raises a ValueError.
Answer: The updated docstring for method deposit is shown below, followed by the ver-
bose doctest results:
"""Deposit money to the account.
>>> account1 = Account('John Green', Decimal('50.00'))

>>> account1.deposit(Decimal('10.55'))
>>> account1.balance
Decimal('60.55')
>>> account1.deposit(Decimal('-100.00'))
...
"""
Trying:
Expecting nothing
ok
Trying:
account1.name
Expecting:
'John Green'
ok
Trying:
account1.balance
Expecting:
Decimal('50.00')
ok
Trying:
Expecting:
...
ok
Trying:
10.15 Namespaces and Scopes 459
Expecting nothing
ok
Trying:
account1.deposit(Decimal('10.55'))
Expecting nothing
ok
Trying:
account1.balance
Expecting:
Decimal('60.55')
ok
Trying:
account1.deposit(Decimal('-100.00'))
Expecting:
...
ok
2 items had no tests:
__main__
__main__.Account
2 items passed all tests:
4 tests in __main__.Account.__init__
4 tests in __main__.Account.deposit
8 tests in 4 items.
Test passed.
10.15 Namespaces and Scopes

In the “Functions” chapter, we showed that each identifier has a scope that determines
where you can use it in your program, and we introduced the local and global scopes. Here
we continue our discussion of scopes with an introduction to namespaces.
Scopes are determined by namespaces, which associate identifiers with objects and are
implemented “under the hood” as dictionaries. All namespaces are independent of one
another. So, the same identifier may appear in multiple namespaces. There are three pri-
mary namespaces—local, global and built-in.
Local Namespace
Each function and method has a local namespace that associates local identifiers (such as,
parameters and local variables) with objects. The local namespace exists from the moment
the function or method is called until it terminates and is accessible only to that function
or method. In a function’s or method’s suite, assigning to a variable that does not exist cre-
ates a local variable and adds it to the local namespace. Identifiers in the local namespace
are in scope from the point at which you define them until the function or method termi-
nates.
Global Namespace
Each module has a global namespace that associates a module’s global identifiers (such as
global variables, function names and class names) with objects. Python creates a module’s
global namespace when it loads the module. A module’s global namespace exists and its
identifiers are in scope to the code within that module until the program (or interactive ses-
sion) terminates. An IPython session has its own global namespace for all the identifiers
you create in that session.
Each module’s global namespace also has an identifier called __name__ containing the
module’s name, such as 'math' for the math module or 'random' for the random module.
As you saw in the previous section’s doctest example, __name__ contains '__main__' for
a .py file that you run as a script.
Built-In Namespace
The built-in namespace associates identifiers for Python’s built-in functions (such as,
input and range) and types (such as, int, float and str) with objects that define those
functions and types. Python creates the built-in namespace when the interpreter starts exe-
cuting. The built-in namespace’s identifiers remain in scope for all code until the program
(or interactive session) terminates.20
Finding Identifiers in Namespaces
When you use an identifier, Python searches for that identifier in the currently accessible
namespaces, proceeding from local to global to built-in. To help you understand the name-
space search order, consider the following IPython session:
In [1]: z = 'global z'
In [2]: def print_variables():

...: y = 'local y in print_variables'
...: print(y)
...: print(z)
...:
In [3]: print_variables()
local y in print_variables
global z
The identifiers you define in an IPython session are placed in the session’s global
namespace. When snippet [3] calls print_variables, Python searches the local, global
and built-in namespaces as follows:
• Snippet [3] is not in a function or method, so the session’s global namespace and
the built-in namespace are currently accessible. Python first searches the session’s
global namespace, which contains print_variables. So print_variables is in
scope and Python uses the corresponding object to call print_variables.
• As print_variables begins executing, Python creates the function’s local name-
space. When function print_variables defines the local variable y, Python adds
y to the function’s local namespace. The variable y is now in scope until the func-
tion finishes executing.
20. This assumes you do not shadow the built-in functions or types by redefining their identifiers in a
local or global namespace. We discussed shadowing in the “Functions” chapter.
10.15 Namespaces and Scopes 461
• Next, print_variables calls the built-in function print, passing y as the argu-
ment. To execute this call, Python must resolve the identifiers y and print. The
identifier y is defined in the local namespace, so it’s in scope and Python will use
the corresponding object (the string 'local y in print_variables') as print’s
argument. To call the function, Python must find print’s corresponding object.
First, it looks in the local namespace, which does not define print. Next, it looks
in the session’s global namespace, which does not define print. Finally, it looks
in the built-in namespace, which does define print. So, print is in scope and
Python uses the corresponding object to call print.
• Next, print_variables calls the built-in function print again with the argu-
ment z, which is not defined in the local namespace. So, Python looks in the
global namespace. The argument z is defined in the global namespace, so z is in
scope and Python will use the corresponding object (the string 'global z') as
print’s argument. Again, Python finds the identifier print in the built-in name-
space and uses the corresponding object to call print.
• At this point, we reach the end of the print_variables function’s suite, so the
function terminates and its local namespace no longer exists, meaning the local
variable y is now undefined.
To prove that y is undefined, let’s try to display y:
In [4]: y
-------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-4-9063a9f0e032> in <module>()
----> 1 y
NameError: name 'y' is not defined
In this case, there’s no local namespace, so Python searches for y in the session’s global
namespace. The identifier y is not defined there, so Python searches for y in the built-in
namespace. Again, Python does not find y. There are no more namespaces to search, so
Python raises a NameError, indicating that y is not defined.
The identifiers print_variables and z still exist in the session’s global namespace, so
we can continue using them. For example, let’s evaluate z to see its value:
In [5]: z
Out[5]: 'global z'
Nested Functions
One namespace we did not cover in the preceding discussion is the enclosing namespace.
Python allows you to define nested functions inside other functions or methods. For
example, if a function or method performs the same task several times, you might define
a nested function to avoid repeating code in the enclosing function. When you access an
identifier inside a nested function, Python searches the nested function’s local namespace
first, then the enclosing function’s namespace, then the global namespace and finally the
built-in namespace. This is sometimes referred to as the LEGB (local, enclosing, global,
built-in) rule. In an exercise, we ask you to create a nested function to demonstrate this
namespace search order.
Class Namespace
A class has a namespace in which its class attributes are stored. When you access a class
attribute, Python looks for that attribute first in the class’s namespace, then in the base
class’s namespace, and so on, until either it finds the attribute or it reaches class object. If
the attribute is not found, a NameError occurs.
Object Namespace
Each object has its own namespace containing the object’s methods and data attributes.
The class’s __init__ method starts with an empty object (self) and adds each attribute
to the object’s namespace. Once you define an attribute in an object’s namespace, clients
using the object may access the attribute’s value.
Self Check
1 (Fill-In) A function’s namespace stores information about identifiers cre-
ated in the function, such as its parameters and local variables.
Answer: local.
2 (True/False) When a function attempts to get an attribute’s value, Python searches the
local namespace, then the global namespace, then the built-in namespace until it finds the
attribute; otherwise, a NameError occurs.
Answer: True.
10.16 Intro to Data Science: Time Series and Simple

Linear Regression
We’ve looked at sequences, such as lists, tuples and arrays. In this section, we’ll discuss
time series, which are sequences of values (called observations) associated with points in
time. Some examples are daily closing stock prices, hourly temperature readings, the
changing positions of a plane in flight, annual crop yields and quarterly company profits.
Perhaps the ultimate time series is the stream of time-stamped tweets coming from Twitter
users worldwide. In the “Data Mining Twitter” chapter, we’ll study Twitter data in depth.
In this section, we’ll use a technique called simple linear regression to make predic-
tions from time series data. We’ll use the 1895 through 2018 January average high tem-
peratures in New York City to predict future average January high temperatures and to
estimate the average January high temperatures for years preceding 1895.
In the “Machine Learning” chapter, we’ll revisit this example using the scikit-learn
library. In the “Deep Learning” chapter, we’ll use recurrent neural networks (RNNs) to ana-
lyze time series.
In later chapters, we’ll see that time series are popular in financial applications and
with the Internet of Things (IoT), which we’ll discuss in the “Big Data: Hadoop, Spark,
NoSQL and IoT” chapter.
In this section, we’ll display graphs with Seaborn and pandas, which both use Mat-
plotlib, so launch IPython with Matplotlib support:
ipython --matplotlib
10.16 Intro to Data Science: Time Series and Simple Linear Regression 463
Time Series
The data we’ll use is a time series in which the observations are ordered by year. Univariate
time series have one observation per time, such as the average of the January high tempera-
tures in New York City for a particular year. Multivariate time series have two or more
observations per time, such as temperature, humidity and barometric pressure readings in
a weather application. Here, we’ll analyze a univariate time series.
Two tasks often performed with time series are:
• Time series analysis, which looks at existing time series data for patterns, helping
data analysts understand the data. A common analysis task is to look for season-
ality in the data. For example, in New York City, the monthly average high tem-
perature varies significantly based on the seasons (winter, spring, summer or fall).
• Time series forecasting, which uses past data to predict the future.
We’ll perform time series forecasting in this section.
Simple Linear Regression
Using a technique called simple linear regression, we’ll make predictions by finding a lin-
ear relationship between the months (January of each year) and New York City’s average
January high temperatures. Given a collection of values representing an independent vari-
able (the month/year combination) and a dependent variable (the average high tempera-
ture for that month/year), simple linear regression describes the relationship between these
variables with a straight line, known as the regression line.
Linear Relationships
To understand the general concept of a linear relationship, consider Fahrenheit and Cel-
sius temperatures. Given a Fahrenheit temperature, we can calculate the corresponding
Celsius temperature using the following formula:
c = 5 / 9 * (f - 32)
In this formula, f (the Fahrenheit temperature) is the independent variable, and c (the Cel-
sius temperature) is the dependent variable—each value of c depends on the value of f used
in the calculation.
Plotting Fahrenheit temperatures and their corresponding Celsius temperatures pro-
duces a straight line. To show this, let’s first create a lambda for the preceding formula and
use it to calculate the Celsius equivalents of the Fahrenheit temperatures 0–100 in 10-
degree increments. We store each Fahrenheit/Celsius pair as a tuple in temps:
In [1]: c = lambda f: 5 / 9 * (f - 32)
In [2]: temps = [(f, c(f)) for f in range(0, 101, 10)]
Next, let’s place the data in a DataFrame, then use its plot method to display the lin-
ear relationship between the Fahrenheit and Celsius temperatures. The plot method’s
style keyword argument controls the data’s appearance. The period in the string '.-'
indicates that each point should appear as a dot, and the dash indicates that lines should
connect the dots. We manually set the y-axis label to 'Celsius' because the plot method
shows 'Celsius' only in the graph’s upper-left corner legend, by default.
In [3]: import pandas as pd
In [4]: temps_df = pd.DataFrame(temps, columns=['Fahrenheit', 'Celsius'])
In [5]: axes = temps_df.plot(x='Fahrenheit', y='Celsius', style='.-')
In [6]: y_label = axes.set_ylabel('Celsius')
Components of the Simple Linear Regression Equation

The points along any straight line (in two dimensions) like those shown in the preceding
graph can be calculated with the equation:
y = mx + b
where
• m is the line’s slope,
• b is the line’s intercept with the y-axis (at x = 0),
• x is the independent variable (the date in this example), and
• y is the dependent variable (the temperature in this example).
In simple linear regression, y is the predicted value for a given x.
Function linregress from the SciPy’s stats Module
Simple linear regression determines the slope (m) and intercept (b) of a straight line that
best fits your data. Consider the following diagram, which shows a few of the time-series
data points we’ll process in this section and a corresponding regression line. We added ver-
tical lines to indicate each data point’s distance from the regression line:
The simple linear regression algorithm iteratively adjusts the slope and intercept and, for
each adjustment, calculates the square of each point’s distance from the line. The “best fit”
occurs when the slope and intercept values minimize the sum of those squared distances.
This is known as an ordinary least squares calculation.21
The SciPy (Scientific Python) library is widely used for engineering, science and
math in Python. This library’s linregress function (from the scipy.stats module) per-
forms simple linear regression for you. After calling linregress, you’ll plug the resulting
slope and intercept into the y = mx + b equation to make predictions.
Pandas
In the three previous Intro to Data Science sections, you used pandas to work with data.
You’ll continue using pandas throughout the rest of the book. In this example, we’ll load
the data for New York City’s 1895–2018 average January high temperatures from a CSV
file into a DataFrame. We’ll then format the data for use in this example.
Seaborn Visualization
We’ll use Seaborn to plot the DataFrame’s data with a regression line that shows the aver-
age high-temperature trend over the period 1895–2018.
Getting Weather Data from NOAA
Let’s get the data for our study. The National Oceanic and Atmospheric Administration
(NOAA)22 offers lots of public historical data including time series for average high tem-
peratures in specific cities over various time intervals.
We obtained the January average high temperatures for New York City from 1895
through 2018 from NOAA’s “Climate at a Glance” time series at:
https://www.ncdc.noaa.gov/cag/
21. https://en.wikipedia.org/wiki/Ordinary_least_squares.
22. http://www.noaa.gov.
On that web page, you can select temperature, precipitation and other data for the entire
U.S., regions within the U.S., states, cities and more. Once you’ve set the area and time
frame, click Plot to display a diagram and view a table of the selected data. At the top of
that table are links for downloading the data in several formats including CSV, which we
discussed in the “Files and Exceptions” chapter. NOAA’s maximum date range available
at the time of this writing was 1895–2018. For your convenience, we provided the data in
the ch10 examples folder in the file ave_hi_nyc_jan_1895-2018.csv. If you download the
data on your own, delete the rows above the line containing "Date,Value,Anomaly".
This data contains three columns per observation:
• Date—A value of the form 'YYYYMM’ (such as '201801'). MM is always 01 because
we downloaded data for only January of each year.
• Value—A floating-point Fahrenheit temperature.
• Anomaly—The difference between the value for the given date and average values
for all dates. We do not use the Anomaly value in this example, so we’ll ignore it.
Loading the Average High Temperatures into a DataFrame
Let’s load and display the New York City data from ave_hi_nyc_jan_1895-2018.csv:
In [7]: nyc = pd.read_csv('ave_hi_nyc_jan_1895-2018.csv')
We can look at the DataFrame’s head and tail to get a sense of the data:
In [8]: nyc.head()
Out[8]:
Date Value Anomaly
0 189501 34.2 -3.2
1 189601 34.7 -2.7
2 189701 35.5 -1.9
3 189801 39.6 2.2
4 189901 36.4 -1.0
In [9]: nyc.tail()
Out[9]:
Date Value Anomaly
119 201401 35.5 -1.9
120 201501 36.1 -1.3
121 201601 40.8 3.4
122 201701 42.8 5.4
123 201801 38.7 1.3
Cleaning the Data

We’ll soon use Seaborn to graph the Date-Value pairs and a regression line. When plotting
data from a DataFrame, Seaborn labels a graph’s axes using the DataFrame’s column
names. For readability, let’s rename the 'Value' column as 'Temperature':
In [10]: nyc.columns = ['Date', 'Temperature', 'Anomaly']
In [11]: nyc.head(3)
Out[11]:
Date Temperature Anomaly
0 189501 34.2 -3.2
1 189601 34.7 -2.7
2 189701 35.5 -1.9
Seaborn labels the tick marks on the x-axis with Date values. Since this example pro-
cesses only January temperatures, the x-axis labels will be more readable if they do not con-
tain 01 (for January), we’ll remove it from each Date. First, let’s check the column’s type:
In [12]: nyc.Date.dtype
Out[12]: dtype('int64')
The values are integers, so we can divide by 100 to truncate the last two digits. Recall that
each column in a DataFrame is a Series. Calling Series method floordiv performs inte-
ger division on every element of the Series:
In [13]: nyc.Date = nyc.Date.floordiv(100)
In [14]: nyc.head(3)
Out[14]:
Date Temperature Anomaly
0 1895 34.2 -3.2
1 1896 34.7 -2.7
2 1897 35.5 -1.9
Calculating Basic Descriptive Statistics for the Dataset

For some quick statistics on the dataset’s temperatures, call describe on the Temperature
column. We can see that there are 124 observations, the mean value of the observations is
37.60, and the lowest and highest observations are 26.10 and 47.60 degrees, respectively:
In [15]: pd.set_option('precision', 2)
In [16]: nyc.Temperature.describe()
Out[16]:
count 124.00
mean 37.60
std 4.54
min 26.10
25% 34.58
50% 37.60
75% 40.60
max 47.60
Name: Temperature, dtype: float64
Forecasting Future January Average High Temperatures

The SciPy (Scientific Python) library is widely used for engineering, science and math in
Python. Its stats module provides function linregress, which calculates a regression
line’s slope and intercept for a given set of data points:
In [17]: from scipy import stats
In [18]: linear_regression = stats.linregress(x=nyc.Date,

...: y=nyc.Temperature)
...:
Function linregress receives two one-dimensional arrays23 of the same length represent-
ing the data points’ x- and y-coordinates. The keyword arguments x and y represent the
independent and dependent variables, respectively. The object returned by linregress
contains the regression line’s slope and intercept:
23. These arguments also can be one-dimensional array-like objects, such as lists or pandas Series.
In [19]: linear_regression.slope
Out[19]: 0.00014771361132966167
In [20]: linear_regression.intercept
Out[20]: 8.694845520062952
We can use these values with the simple linear regression equation for a straight line,
y = mx + b, to predict the average January temperature in New York City for a given year.
Let’s predict the average Fahrenheit temperature for January of 2019. In the following cal-
culation, linear_regression.slope is m, 2019 is x (the date value for which you’d like to
predict the temperature), and linear_regression.intercept is b:
In [21]: linear_regression.slope * 2019 + linear_regression.intercept
Out[21]: 38.51837136113298
We also can approximate what the average temperature might have been in the years
before 1895. For example, let’s approximate the average temperature for January of 1890:
In [22]: linear_regression.slope * 1890 + linear_regression.intercept
Out[22]: 36.612865774980335
For this example, we had data for 1895–2018. You should expect that the further you go
outside this range, the less reliable the predictions will be.
Plotting the Average High Temperatures and a Regression Line
Next, let’s use Seaborn’s regplot function to plot each data point with the dates on the
x-axis and the temperatures on the y-axis. The regplot function creates the scatter plot or
scattergram below in which the scattered blue dots represent the Temperatures for the
given Dates, and the straight line displayed through the points is the regression line:
First, close the prior Matplotlib window if you have not done so already—otherwise,
regplot will use the existing window that already contains a graph. Function regplot’s x
and y keyword arguments are one-dimensional arrays24 of the same length representing
the x-y coordinate pairs to plot. Recall that pandas automatically creates attributes for each
column name if the name can be a valid Python identifier:25
24. These arguments also can be one-dimensional array-like objects, such as lists or pandas Series.
In [23]: import seaborn as sns
In [24]: sns.set_style('whitegrid')
In [25]: axes = sns.regplot(x=nyc.Date, y=nyc.Temperature)

The regression line’s slope (lower at the left and higher at the right) indicates a warming
trend over the last 124 years. In this graph, the y-axis represents a 21.5-degree temperature
range between the minimum of 26.1 and the maximum of 47.6, so the data appears to be
spread significantly above and below the regression line, making it difficult to see the linear
relationship. This is a common issue in data analytics visualizations. When you have axes
that reflect different kinds of data (dates and temperatures in this case), how do you reason-
ably determine their respective scales? In the preceding graph, this is purely an issue of the
graph’s height—Seaborn and Matplotlib auto-scale the axes, based on the data’s range of
values. We can scale the y-axis range of values to emphasize the linear relationship. Here,
we scaled the y-axis from a 21.5-degree range to a 60-degree range (from 10 to 70 degrees):
In [26]: axes.set_ylim(10, 70)
Out[26]: (10, 70)
Getting Time Series Datasets

Here are some popular sites where you can find time series to use in your studies:
Time-series dataset sources
https://data.gov/
This is the U.S. government’s open data portal. Searching for “time series” yields over 7200
time-series datasets.
25. For readers with more statistics background, the shaded area surrounding the regression line is the
95% confidence interval for the regression line (https://en.wikipedia.org/wiki/Simple_lin-
ear_regression#Confidence_intervals). To draw the diagram without a confidence interval, add
the keyword argument ci=None to the regplot function’s argument list.
Time-series dataset sources
https://www.ncdc.noaa.gov/cag/
The National Oceanic and Atmospheric Administration (NOAA) Climate at a Glance portal
provides both global and U.S. weather-related time series.
https://www.esrl.noaa.gov/psd/data/timeseries/
NOAA’s Earth System Research Laboratory (ESRL) portal provides monthly and seasonal cli-
mate-related time series.
https://www.quandl.com/search
Quandl provides hundreds of free financial-related time series, as well as fee-based time series.
https://datamarket.com/data/list/?q=provider:tsdl
The Time Series Data Library (TSDL) provides links to hundreds of time series datasets across
many industries.
http://archive.ics.uci.edu/ml/datasets.html
The University of California Irvine (UCI) Machine Learning Repository contains dozens of
time-series datasets for a variety of topics.
http://inforumweb.umd.edu/econdata/econdata.html
The University of Maryland’s EconData service provides links to thousands of economic time
series from various U.S. government agencies.
Self Check
1 (Fill-In) Time series looks at existing time series data for patterns, helping
data analysts understand the data. Time series uses data from the past to predict
the future.
Answer: analysis, forecasting.
2 (True/False) In the formula, c = 5 / 9 * (f - 32), f (the Fahrenheit temperature) is
the independent variable and c (the Celsius temperature) is the dependent variable.
Answer: True.
3 (IPython Session) Assuming that this linear trend continues, based on the slope and
intercept values calculated in this section’s interactive session, in what year might the aver-
age January temperature in New York City reach 40 degrees Fahrenheit.
Answer:
In [27]: year = 2019
In [28]: slope = linear_regression.slope
In [29]: intercept = linear_regression.intercept
In [30]: temperature = slope * year + intercept
In [31]: while temperature < 40.0:

...: year += 1
...: temperature = slope * year + intercept
...:
In [32]: year
Out[32]: 2120
10.17 Wrap-Up 471
10.17 Wrap-Up
In this chapter, we discussed the details of crafting valuable classes. You saw how to define
a class, create objects of the class, access an object’s attributes and call its methods. You
define the special method __init__ to create and initialize a new object’s data attributes.
We discussed controlling access to attributes and using properties. We showed that all
object attributes may be accessed directly by a client. We discussed identifiers with single
leading underscores (_), which indicate attributes that are not meant to be accessed by cli-
ent code. We showed how to implement “private” attributes via the double-leading-
underscore (__) naming convention, which tells Python to mangle an attribute’s name.
We implemented a card shuffling and dealing simulation consisting of a Card class
and a DeckOfCards class that maintained a list of Cards, and displayed the deck both as
strings and as card images using Matplotlib. We introduced special methods __repr__,
__str__ and __format__ for creating string representations of objects.
Next, we looked at Python’s capabilities for creating base classes and subclasses. We
showed how to create a subclass that inherits many of its capabilities from its superclass,
then adds more capabilities, possibly by overriding the base class’s methods. We created a
list containing both base class and subclass objects to demonstrate Python’s polymorphic
programming capabilities.
We introduced operator overloading for defining how Python’s built-in operators work
with objects of custom class types. You saw that overloaded operator methods are imple-
mented by overriding various special methods that all classes inherit from class object. We
discussed the Python exception class hierarchy and creating custom exception classes.
We showed how to create a named tuple that enables you to access tuple elements via
attribute names rather than index numbers. Next, we introduced Python 3.7’s new data
classes, which can autogenerate various boilerplate code commonly provided in class defi-
nitions, such as the __init__, __repr__ and __eq__ special methods.
You saw how to write unit tests for your code in docstrings, then execute those tests con-
veniently via the doctest module’s testmod function. Finally, we discussed the various
namespaces that Python uses to determine the scopes of identifiers. In the next chapter, we’ll
introduce the computer science concepts of recursion, searching and sorting and Big O.
Exercises
10.1 (What’s Wrong with This Code?) What is wrong with the code in the following
IPython session?
In [1]: try:
...: raise RuntimeError()
...: except Exception:
...: print('An Exception occurred')
...: except RuntimeError:
...: print('A RuntimeError occurred')
...:
An Exception occurred
10.2 (Car Class with Read-Only Properties) Write a class Car that contains the model,
year (of manufacture), and speed of a car as hidden attributes (name these attributes with
a leading underscore). Provide the necessary read-only properties. Write two methods to
drive the car faster and slower. Test your Car class.
10.3 (Coin Class) Write a Coin Class to keep track of the number of 2 euro, 1 euro,
50 euro cent, 20 euro cent, and 10 euro cent coins in a wallet. Provide a read-only property
universal_str that returns a string with the number of coins for each coin type. Write a
second method that returns the total amount of money. Keep your attributes hidden and
use the read-only properties. Create a coin object and test the methods.
10.4 (Modifying the Internal Data Representation of a Class) Section 10.4.2’s Time
class represents the time as three integer values. Modify the class to store the time as the
total number of seconds since midnight. Replace the _hour, _minute and _second attri-
butes with one _total_seconds attribute. Modify the bodies of the hour, minute and
second properties’ methods to get and set _total_seconds. Re-execute Section 10.4’s
IPython session using the modified Time class to show that the updated class Time is inter-
changeable with the original one.
10.5 (Duck Typing) Recall that with duck typing, objects of unrelated classes can respond
to the same method calls if they implement those methods. In Section 10.8, you created a
list containing a CommissionEmployee and a SalariedCommissionEmployee. Then, you it-
erated through it, displaying each employee’s string representation and earnings. Create a
class SalariedEmployee for an employee that gets paid a fixed weekly salary. Do not inherit
from CommissionEmployee or SalariedCommissionEmployee. In class SalariedEmployee,
override method __repr__ and provide an earnings method. Demonstrate duck typing by
creating an object of your class, adding it to the list at the end of Section 10.8, then executing
the loop to show that it properly processes objects of all three classes.
10.6 (Calculating Vector Lengths) A vector is an object that has a magnitude and a di-
rection. A vector is represented as a line segment with an arrow where the arrow represents
the direction and the length of the vector is the magnitude. A vector can also be a single
point with x- and y-coordinates. The magnitude calculated from this type of vector equals
the distance between the origin of the cartesian coordinate system and the point. Write a
class Point that represents an (x-y) coordinate pair and provides x and y read-write prop-
erties as well as a method to calculate the distance between the point and the origin of the
coordinate system. Include __init__ and __repr__ methods. Write a class Vector that
has two Point objects as its attributes. Include __init__ and __repr__ methods and a
method that can calculate the magnitude of the vector. Test your Point and your
Vector class.
10.7 (Manipulating Dates and Times with Module datetime) The Python Standard Li-
brary’s datetime module contains a datetime class for manipulating dates and times. The
class provides various overloaded operators. Research class datetime’s capabilities, then
perform the following tasks:
a) Get the current date and time and store it in variable x.
b) Repeat Part (a) and store the result in variable y.
c) Display each datetime object.
d) Display each datetime object’s data attributes individually.
e) Use the comparison operators to compare the two datetime objects.
f) Calculate the difference between y and x.
10.8 (Converting Data Class Objects to Tuples and Dictionaries) In some cases, you
might want to treat data class objects as tuples or dictionaries. The dataclasses module
provides functions astuple and asdict for this purpose. Research these functions, then
create an object of this chapter’s Card data class and use these functions to convert the Card
to a tuple and a dictionary. Display the results.
Exercises 473
10.9 (Calculator Class) Write a class that implements a Calculator. The class should
contain 2 numbers. Provide an __init__ method that takes the 2 numbers as arguments.
Also, provide the following read-only properties:
a) sum returns the sum of the 2 numbers
b) difference returns the difference between the 2 numbers
c) product returns the product between the 2 numbers
d) division returns the quotient of number1 divided by number2
These properties should not have corresponding data attributes; rather, they should use
side in calculations that return the desired values. Create a Calculator object and dis-
play its properties.
10.10 (Player Class) Write a class called Player that can be used in a turn-based strategy
game to create player objects. Create the following data attributes-the name (a string), level
(an int), strength (an int), and Health Points (a Decimal). The class should have an
__init__ method to initialize the data attributes. Provide a property for each data attri-
bute. Use validation in the properties of the level and health attribute to ensure that they
remain non-negative. Provide a defence method to defend from an attack. The intensity
of the attack is calculated as follows—divide the strength of the attacker by a random num-
ber between 1 and 3, subtract from this result the strength of our player multiplied with
the level of our player. If the intensity is ≤ 0, the player loses, and the intensity is subtracted
from the health points of the player.
10.11 (Class Fraction) The Python Standard Library module fractions provides a
Fraction class that stores the numerator and denominator of a fraction, such as:
2---
4
Research Fraction’s capabilities, then demonstrate:
a) Adding two Fractions.
b) Subtracting two Fractions.
c) Multiplying two Fractions.
d) Dividing two Fractions.
e) Printing Fractions in the form a/b, where a is the numerator and b is the de-
nominator.
f) Converting Fractions to floating-point numbers with built-in function float.
10.12 (Built-in Type complex) Python supports complex numbers with the built-in type
complex.Research complex’s capabilities, then demonstrate:
a) Adding two complex numbers.
b) Subtracting two complex numbers.
c) Printing complex numbers.
d) Getting the real and imaginary parts of complex numbers.
10.13 (doctest) Create a script containing the following maximum function:
def maximum(value1, value2, value3):
"""Return the maximum of three values."""
max_value = value1
if value2 > max_value:
max_value = value2
if value3 > max_value:
max_value = value3
return max_value
Modify the function’s docstring to define tests for calling function maximum with three
ints, three floats and three strings. For each type, provide three tests—one with the
largest value as the first argument, one with the largest value as the second argument, one
with the largest value as the third argument. Use doctest to run your tests and confirm
that all execute correctly. Next, modify the maximum function to use < operators rather
than > operators. Run your tests again to see which tests fail.
10.14 (Creating an Account Data Class Dynamically) The dataclasses module’s
make_dataclass function creates a data class dynamically from a list of strings that repre-
sent the data class’s attributes. Research function make_dataclass, then use it to generate
an Account class from the following list of strings:
['account', 'name', 'balance']
Create objects of the new Account class, then display their string representations and
compare the objects with the == and != operators.
10.15 (Immutable Data Class Objects) Built-in types int, float, str and tuple are im-
mutable. Data classes can simulate immutability by designating that objects of the class
should be “frozen” after they’re created. Client code cannot assign values to the attributes of
a frozen object. Research “frozen” data classes, then reimplement this chapter’s Complex class
as a “frozen” data class. Show that you cannot modify a Complex object after you create it.
10.16 (Account Inheritance Hierarchy) Create an inheritance hierarchy that a bank
might use to represent customer bank accounts. All customers at this bank can deposit
money into their accounts and withdraw money from their accounts. More specific types
of accounts also exist. Savings accounts, for instance, earn interest on the money they hold.
Checking accounts, on the other hand, don’t earn interest and charge a fee per transaction.
Start with class Account from this chapter and create two subclasses SavingsAccount
and CheckingAccount. A SavingsAccount should also include a data attribute indicating
the interest rate. A SavingsAccount’s calculate_interest method should return the
Decimal result of multiplying the interest rate by the account balance. SavingsAccount
should inherit methods deposit and withdraw without redefining them.
A CheckingAccount should include a Decimal data attribute that represents the fee
charged per transaction. Class CheckingAccount should override methods deposit and
withdraw so that they subtract the fee from the account balance whenever either transac-
tion is performed successfully. CheckingAccount’s versions of these methods should
invoke the base-class Account versions to update the account balance. CheckingAccount’s
withdraw method should charge a fee only if money is withdrawn (that is, the withdrawal
amount does not exceed the account balance).
Create objects of each class and tests their methods. Add interest to the SavingsAc-
count object by invoking its calculate_interest method, then passing the returned
interest amount to the object’s deposit method.
10.17 (Nested Functions and Namespaces) Section 10.15 discussed namespaces and how
Python uses them to determine which identifiers are in scope. We also mentioned the
LEGB (local, enclosing, global, built-in) rule for the order in which Python searches for
identifiers in namespaces. For each of the print function calls in the following IPython
session, list the namespaces that Python searches for print’s argument:
In [1]: z = 'global z'
Exercises 475
In [2]: def print_variables():

...: y = 'local y in print_variables'
...: print(y)
...: print(z)
...: def nested_function():
...: x = 'x in nested function'
...: print(x)
...: print(y)
...: print(z)
...: nested_function()
...:
In [3]: print_variables()
global z
x in nested function
global z
10.18 (Intro to Data Science: Time Series) Reimplement the Intro to Data Science section’s
study using the Los Angeles Average January High Temperatures for 1985 through 2018,
which can be found in the file ave_hi_la_jan_1895-2018.csv located in the ch10 examples
folder. How does the Los Angeles temperature trend compare to that of New York City?
10.19 (Project: Static Code Analysis with Prospector and MyPy) In Exercise 3.24, you
used the prospector static code analysis tool to check your code for common errors and
suggested improvements. The prospector tool includes support for checking variable an-
notations with the MyPy static code analysis tool. Research MyPy online. Write a script
that creates objects of this chapter’s Card data class. In the script, assign integers to a Card’s
face and suit string attributes. Then, use MyPy to analyze the script and see the warning
messages that MyPy produces. For instructions on using MyPy with prospector, see
https://github.com/PyCQA/prospector/blob/master/docs/
supported_tools.rst
10.20 (Project: Solitaire) Using classes Card and DeckOfCards from this chapter’s exam-
ples, implement your favorite solitaire card game.
10.21 (Project: Blackjack) Using the DeckOfCards class from this chapter, create a simple
Blackjack game. The rules of the game are as follows:
• Two cards each are dealt to the dealer and the player. The player’s cards are dealt
face up. Only one of the dealer’s cards is dealt face up.
• Each card has a value. A card numbered 2 through 10 is worth its face value.
Jacks, queens and kings each count as 10. Aces can count as 1 or 11—whichever
value is more beneficial to the player (as we’ll soon see).
• If the sum of the player’s first two cards is 21 (that is, the player was dealt a card
valued at 10 and an ace, which counts as 11 in this situation), the player has
“blackjack” and immediately wins the game—if the dealer does not also have
blackjack, which would result in a “push” (or tie).
• Otherwise, the player can begin taking additional cards one at a time. These cards
are dealt face up, and the player decides when to stop taking cards. If the player
“busts” (that is, the sum of the player’s cards exceeds 21), the game is over and the
player loses. When the player is satisfied with the current set of cards, the player
“stands” (that is, stops taking cards), and the dealer’s hidden card is revealed.
• If the dealer’s total is 16 or less, the dealer must take another card; otherwise, the
dealer must stand. The dealer must continue taking cards until the sum of the
cards is greater than or equal to 17. If the dealer exceeds 21, the player wins. Oth-
erwise, the hand with the higher point total wins. If the dealer and the player have
the same point total, the game is a “push,” and no one wins.
An ace’s value for a dealer depends on the dealer’s other card(s) and the casino’s house
rules. A dealer typically must hit for totals of 16 or less and must stand for 17 or more.
For a “soft 17”—a total of 17 with one ace counted as 11—some casinos require the
dealer to hit and some require the dealer to stand (we require the dealer to stand). Such a
hand is known as a “soft 17” because taking another card cannot bust the hand.
Enable a player to interact with the game using the keyboard—'H' means hit (take
another card and 'S' means stand (do not take another card). Display the dealer’s and
player’s hands as card images using Matplotlib, as we did in this chapter.
10.22 (Project: Card Class with Overloaded Comparison Operators) Modify class Card to
support the comparison operators, so you can determine whether one Card is less than, equal
to or greater than another. Investigate the functools module’s total_ordering decorator.
If your class is preceded by @total_ordering and defines methods __eq__ and __lt__ (for
the < operator), the remaining comparison methods for <=, > and >= are autogenerated.
10.23 (Project: Poker) Exercises 5.25–5.26 asked you to create functions for comparing
poker hands. Develop equivalent features for use with this chapter’s DeckOfCards class.
Develop a new class called Hand that represents a five-card poker hand. Use operator over-
loading to enable two Hands to be compared with the comparison operators. Use your new
capabilities in a simple poker game script.
10.24 (Project: PyDealer Library) We demonstrated basic card shuffling and dealing in
this chapter, but many card games require significant additional capabilities. As is often
the case in Python, libraries already exist that can help you build more substantial card
games. One such library is PyDealer. Research this library’s extensive capabilities, then use
it to implement your favorite card game.
10.25 (Project: Enumerations) Many programming languages provide a language element
called an enumeration for creating sets of named constants. Often, these are used to make
code more readable. The Python Standard Library’s enum module enables you to emulate
this concept by creating subclasses of the Enum base class. Investigate the enum module’s ca-
pabilities, then create subclasses of Enum that represent card faces and card suits. Modify class
Card to use these to represent the face and suit as enum constants rather than as strings.
10.26 (Software Engineering with Abstract Classes and Abstract Methods) When we
think of a class, we assume that programs use it to create objects. Sometimes, it’s useful to
declare classes for which you never instantiate objects, because in some way they are incom-
plete. As you’ll see, such classes can help you engineer effective inheritance hierarchies.
Concrete Classes—Consider Section 10.7’s Shape hierarchy. If Circle, Square and
Triangle objects all have draw methods, its reasonable to expect that calling draw on a
Circle will display a Circle, calling draw on a Square will display a Square and calling
draw on a Triangle will display a Triangle. Objects of each class know all the details of
Exercises 477
the specific shapes to draw. Classes that provide (or inherit) implementations of every
method they define and that can be used to create objects are called concrete classes.
Abstract Classes—Now, let’s consider class TwoDimensionalShape in the Shape hier-
archy’s second level. If we were to create a TwoDimensionalShape object and call its draw
method, class TwoDimensionalShape knows that all two-dimensional shapes are drawable,
but it does not know what specific two-dimensional shape to draw—there are many! So it
does not make sense for TwoDimensionalShape to fully implement a draw method. A
method that is defined in a given class, but for which you cannot provide an implementa-
tion is called an abstract method. Any class with an abstract method has a “hole”—the
incomplete method implementation—and is called an abstract class. TypeErrors occur
when you try to create objects of abstract classes. In the Shape hierarchy, classes Shape,
TwoDimensionalShape and ThreeDimensionalShape all are abstract classes. They all know
that shapes should be drawable, but do not know what specific shape to draw. Abstract base
classes are too general to create real objects.
Inheriting a Common Design—An abstract class’s purpose is to provide a base class
from which subclasses can inherit a common design, such as a specific set of attributes and
methods. So, such classes often are called abstract base classes. In the Shape hierarchy,
subclasses inherit from the abstract base class Shape the notion of what it means to be a
Shape—that is, common properties, such as location and color, and common behaviors,
such as draw, move and resize.
Polymorphic Employee Payroll System—Now, let’s develop an Employee class hier-
archy that begins with an abstract class, then use polymorphism to perform payroll calcu-
lations for objects of two concrete subclasses. Consider the following problem statement:
A company pays its employees weekly. The employees are of two types. Salaried
employees are paid a fixed weekly salary regardless of the number of hours worked.
Hourly employees are paid by the hour and receive overtime pay (1.5 times their
hourly salary rate) for all hours worked in excess of 40 hours. The company wants
to implement an app that performs its payroll calculations polymorphically.
Employee Hierarchy Class Diagram—The following diagram shows the Employee
hierarchy. Abstract class Employee represents the general concept of an employee. Subclasses
SalariedEmployee and HourlyEmployee inherit from Employee. Employee is italicized by
convention to indicate that it’s an abstract class. Concrete class names are not italicized:
Employee
SalariedEmployee HourlyEmployee
Abstract Base Class Employee—The Python Standard Library’s abc (abstract base
class) module helps you define abstract classes by inheriting from the module’s ABC class.
Your abstract base class Employee class should declare the methods and properties that all
employees should have. Each employee, regardless of the way his or her earnings are cal-
culated, has a first name, a last name and a Social Security number. Also, every employee
should have an earnings method, but the specific calculation depends on the employee’s
type, so you’ll make earnings an abstract method that the subclasses must override. Your
Employee class should contain:
• An __init__ method that initializes the first name, last name and Social Security
number data attributes.
• Read-only properties for the first name, last name and Social Security number
data attributes.
• An abstract method earnings preceded by the abc module’s @abstractmethod
decorator. Concrete subclasses must implement this method. The Python docu-
mentation says you should raise a NotImplementedError in abstract methods.26
• A __repr__ method that returns a string containing the first name, last name and
Social Security number of the employee.
Concrete Subclass SalariedEmployee—This Employee subclass should override
earnings to return a SalariedEmployee’s weekly salary. The class also should include:
• An __init__ method that initializes the first name, last name, Social Security
number and weekly salary data attributes. The first three of these should be ini-
tialized by calling base class Employee’s __init__ method.
• A read-write weekly_salary property in which the setter ensures that the prop-
erty is always non-negative.
• A __repr__ method that returns a string starting with 'SalariedEmployee:' and
followed by all the information about a SalariedEmployee. This overridden
method should call Employee’s version.
Concrete Subclass HourlyEmployee—This Employee subclass should override earn-
ings to return an HourlyEmployee’s earnings, based on the hours worked and wage per
hour. The class also should include:
• An __init__ method to initialize the first name, last name, Social Security num-
ber, hours and wages data attributes. The first name, last name and Social Security
number should be initialized by calling base class Employee’s __init__ method.
• Read-write hours and wages properties in which the setters ensure that the
hours are in range (0–168) and wage per hour is always non-negative.
• A __repr__ method that returns a string starting with 'HourlyEmployee:' and
followed by all the information about a HourlyEmployee. This overridden
method should call Employee’s version.
Testing Your Classes—In an IPython session, test your hierarchy:
• Import the classes Employee, SalariedEmployee and HourlyEmployee.
• Attempt to create an Employee object to see the TypeError that occurs and prove
that you cannot create an object of an abstract class.
• Assign objects of the concrete classes SalariedEmployee and HourlyEmployee to
variables, then display each employee’s string representation and earnings.
• Place the objects into a list, then iterate through the list and polymorphically pro-
cess each object, displaying its string representation and earnings.
26. https://docs.python.org/3.7/library/exceptions.html#NotImplementedError.
Computer Science Thinking:
Recursion, Searching,
Sorting and Big O 11
Objectives
In this chapter you’ll:
 Learn the concept of
recursion.
 Write and use recursive
functions.
 Determine the base case and
recursion step in a recursive
algorithm.
 Learn how the system handles
recursive function calls.
 Compare recursion and
iteration, including when it’s
best to use each approach.
 Search for a given value in an
array using linear search and
binary search.
 Sort arrays using the simple
iterative selection and
insertion sort algorithms.
 Sort arrays using the more
complex but higher-
performance recursive merge
sort algorithm.
 Use Big O notation to
compare the efficiencies of
searching and sorting
algorithms.
 Use Seaborn and Matplotlib to
build an animated selection
sort algorithm visualization.
 In the exercises, implement
additional sorting algorithms
and animated visualizations,
and determine the Big O of
additional algorithms.

Chapter 10

Uploaded by

Document Informationclick to expand document information

Copyright:

Available Formats

Chapter 10

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Chapter 10

Uploaded by

Copyright:

Available Formats

Object-Oriented

10.1 Introduction 10.8.3 Processing Commission-

Class Libraries and Object-Based Programming

10.2 Custom Class Account

10.2.1 Test-Driving Class Account

Importing Classes Account and Decimal

Create an Account Object with a Constructor Expression

Getting an Account’s Name and Balance

Depositing Money into an Account

Account Methods Perform Validation

~/Documents/examples/ch10/account.py in deposit(self, amount)

ValueError: Deposit amount must be positive.

10.2.2 Account Class Definition

Initializing Account Objects: Method __init__

8 def __init__(self, name, balance):

10.2.3 Composition: Object References as Members of Classes

and is sometimes referred to as the “has a” relationship. An end-of-chapter exercise asks

# if amount is greater than balance, raise an exception

Testing method withdraw:

In [2]: from decimal import Decimal

In [3]: account1 = Account('John Green', Decimal('50.00'))

ValueError: amount must be <= to balance.

ValueError: amount must be positive.

10.3 Controlling Access to Attributes

In [2]: from decimal import Decimal

In [3]: account1 = Account('John Green', Decimal('50.00'))

10.4 Properties for Data Access

10.4.1 Test-Driving Class Time

Creating a Time Object

Displaying a Time Object

Getting an Attribute Via a Property

Setting an Attribute via a Property

In [10]: wake_up.hour = 100

~/Documents/examples/ch10/timewithproperties.py in hour(self, hour)

ValueError: Hour (100) must be 0-23

10.4.2 Class Time Definition

Class Time: hour Read-Write Property

We also invoked this setter inside the class at line 9 of __init__:

Class Time: Method set_time

Class Time: Special Method __repr__

In [1]: from timewithproperties import Time

In [4]: t.time = (12, 30, 45)

10.4.3 Class Time Definition Design Notes

In [2]: wake_up = Time(hour=7, minute=45, second=30)

In [4]: wake_up._hour = 100

10.5 Simulating “Private” Attributes

Let’s create an object of class PrivateData to demonstrate these data attributes:

In [2]: my_object = PrivateClass()

However, when we attempt to access __private_data directly in snippet [4], we get an

AttributeError: 'PrivateClass' object has no attribute '__private_data'

In [6]: my_object._PrivateClass__private_data = 'modified'

10.6 Case Study: Card Shuffling and Dealing Simulation

10.6.1 Test-Driving Classes Card and DeckOfCards

In [2]: deck_of_cards = DeckOfCards()

Class Card’s Other Features

10.6.2 Class Card—Introducing Class Attributes

Read-Only Properties face, suit and image_name

Methods That Return String Representations of a Card

Initializing Account Objects: Method init

8 def init(self, name, balance):

We also invoked this setter inside the class at line 9 of init:

Class Time: Special Method repr

def isub(self, right):