Learning Objectives

Students will:

• know the difference between classes and objects
• realize that they've been using objects when using strings and lists.
• become aware that in Python, everything is an object
• know how to define their own classes
• be able to write their own modules
• see an example of using Python's docstrings

First things first...

What is a class?

• A class is a "blueprint" for an object.

So what's an object?

• An object is a collection of related data and a set of operations (methods) to manipulate that data.

The data and methods are collectively called "attributes".

We've already seen objects provided to us by Python; for example, lists and strings are objects defined by the list and string classes built into Python.

An object example

So, for example, when we do the following:

>>> my_list = ["alice", "bob"]
>>> my_list.append("eve")
>>> print(my_list)
['alice', 'bob', 'eve']

We are first creating a list object with the initial items "alice" and "bob", then we are using the append() method of the list object to add "eve" to the list.

• The list.append() method operates on the list's internal data to add "eve" to the list in a way defined by the list class itself.
• We don't have to worry about how the list manages its data. We just know the methods of the object and what they do. The code in the method handles the rest.

The methods of an object are typically the elements that compose its interface.

• By hiding the internals of the object and instead presenting a set of methods to work with, we define the object to the user by its externally-visible behavior.
• One of the primary benefits to this is that we could completely change the internal behavior of the list, as long as we didn't change the interface, and the user would never need to know anything changed. Their programs would work exactly like they did before.

Some other method examples

Let's look a little more at the list class and some of its methods for other examples of how objects are created.

• list.append(x): What we just saw. Typically methods are listed with their class names in front for clarity; this demonstrates that the given function is a method, and furthermore that it is a method of the list class.
• list.extend(L): Extends the list by appending all items of the incoming list, L, onto end of the list list.
• list.insert(i, x): Inserts item x into the list at position i.
• list.reverse(): Reverses all the elements of the list.

The list class contains many more methods than this, but these are good examples. Imagine having to write code to do all of this yourself; you'd have to worry about how the list is represented in memory, and you'd have to figure out a lot of operations (imagine the list.insert() method on a grocery list on paper (assuming there's no space between items); it's not fun).

Why use classes and objects?

It's not strictly necessary to use objects in programming; the concept of object-oriented programming is actually rather new. Programs used to be (and often still are) written entirely using functions. This is called "procedural" programming. However, many people find object-oriented programming to be a more intuitive way to program (for certain types of problems). Some reasons are:

• Objects are a great way to represent abstract data types.
  1. They hide the implementation details fairly well.
  2. They provide an interface to the user that "acts" directly on the object.
  3. They encapsulate data well.
• You can know that a list object contains all the information necessary to work on the collection of data as a list and not as a string or a set.

The difference between classes and objects

It can be difficult to remember the difference between a class and an object. As we stated before:

• A class is the "blueprint" for an object.
• An object is an instance of a class. When we talk about an instance, we typically mean a unique object defined by a class (for example, you are a unique instance of Homo Sapiens).

So, for example, in a housing subdivision:

• The plans for a particular type of house would be the class.
• The houses themselves would be the objects, with methods like house.open() and house.buy() and data like house.address and house.bathrooms.

Instantiating objects

When we create an instance of a class, we instantiate it. We can instantiate objects that don't have explicit classes, too; for example, we can instantiate an integer or a float.

In Python, everything is an object (this is not true for many other languages). Therefore, everything must be instantiated.

Some objects can be instantiated in special ways; for example, there are several ways to create the same floating point number:

my_num1 = 3.0
my_num2 = float(3)
my_num3 = 7.0 / 2.0

1. In the first case, a float (being a special object for the language) can be instantiated with just the number.
2. The second case has us directly using the constructor to create the object (a constructor is a special method which creates the object. (You'll learn more about constructors later)
3. In the third case, a float is implicitly returned as the result of the division of two other floats.

When we instantiate our own objects, we can generally only use the constructor method.

Defining your own classes

You'll eventually want to define your own classes to solve problems. Here's an example from the book of a problem neatly solved by utilizing object-oriented design.

Imagine we're writing a ballistic simulation where we must track the path of a shot fired from a catapult. The shot is affected by gravity, so we must simulate the effects of gravity on the shot. We need to perform the following operations:

• Take input from the user to get the initial height, initial velocity and firing angle of the shot.
• At each step:
  • Update the position of the shot given the velocity, current position and time difference.
  • Update the velocity of the shot given gravity, the current velocity and the time difference (ignoring air resistance).
• Once the shot has hit the ground, print out the distance traveled.

We'll step through the procedural approach to this and then the object-oriented approach.

The procedural approach

We'll assume that the input has already been handled and that we have variables xpos and ypos for the initial position, where (xpos is the initial height, while ypos is just 0.0), xvel and yvel for the initial velocity, and timestep for the timestep (in seconds).

The position update function might look like this:

def updateShotPosition(xpos, ypos, xvel, yvel, timestep):
    xpos += xvel * timestep
    ypos += yvel * timestep
    return xpos, ypos

And the velocity update might look like this:

def updateShotVelocity(yvel, timestep):
    # Gravity is an acceleration of -9.8 meters/second^2.
    yvel -= 9.8 * timestep

    # Return the Y velocity
    # X velocity is constant since we're ignoring air resistance
    return yvel

Our main simulation loop would then look like this:

# Run until we hit the ground.
while ypos >= 0:
    # Update our positions based on the velocity and a timestep.
    xpos, ypos = updateShotPosition(xpos, ypos, xvel, yvel, timestep)

    # Update our velocity based on gravity and the same timestep.
    yvel = updateShotVelocity(yvel, timestep)
    
# Print our horizontal distance traveled.
print("Distance traveled: %0.1f meters." % (xpos))

That doesn't seem so bad, but it could be prettier. Let's look at the object-oriented way.

The object-oriented approach

We'll go over the details of actually defining the class on the next slide, but for now, let's think about how moving to objects simplifies things.

• The data for the shot is all neatly encapsulated in the object (let's call the class Projectile). This means we don't have to keep track of lots of variables.
  
  This would be especially useful if we wanted to simulate a seige on a castle and have lots of shots flying around all over the place.
• We can change our update functions into a single method that takes only the timestep as a parameter and returns nothing.

We'll also add some methods to access the position data in the object from the outside called Projectile.getX() and Projectile.getY() (we'll learn why in a bit).

We will instantiate an instance of our projectile before we start the main loop, initializing it with the initial position and velocity. This will look like:

shot = Projectile(xpos, ypos, xvel, yvel)

Given all that, our main loop (with an initialized Projectile object named shot) will look like:

while shot.getY() >= 0.0:
    shot.update(timestep)
    
print( "Distance traveled: %0.1f meters." % (shot.getX()) )

Defining the Projectile class

So how do we define the class? Our class definition will look like this:

class Projectile:
    def __init__(self, xpos, ypos, xvel, yvel):
        self.xpos = xpos
        self.ypos = ypos
        self.xvel = xvel
        self.yvel = yvel
        
    def getX(self):
        return self.xpos
        
    def getY(self):
        return self.ypos
        
    def update(self, timestep):
        # Update the position according to the velocity and timestep.
        self.xpos += self.xvel * timestep
        self.ypos += self.yvel * timestep
        
        # Update the velocity accordint to gravity and the timestep (the X
        # velocity is constant, so we don't change it).
        self.yvel -= 9.8 * timestep

Let's talk about the elements of this definition on the next slide.

The Constructor

• Methods are defined the same way as any other function, with the special qualification that they are defined within the class definition and they also contain the self parameter, described below.
  • Nothing can see these function names outside of their use as a method in an object of class Projectile
  • If we were to just call getX() from our program instead of shot.getX(), we would encounter an error.
• The __init__() method is a special method name that defines the constructor of a class.
  • The constructor's job is to set up an object's initial state
  • It doesn't have to take initial values, but ours does in order to set up the object's internal variables properly.
• This is the method called when we instantiate an object like this:

shot = Projectile(xpos, ypos, xvel, yvel)

self

You'll notice that all the object's internal variables are prefixed with self, and all of the methods take a first parameter called "self", which is not explicitly passed to the methods when we call them.

The call to the method looks like this:

shot.update(timestep)

not

shot.update(shot, timestep)

nor

update(shot, timestep)

This variable is actually just the reference to the instance. So when you call shot.update(timestep), self is a reference to shot.

All object variables must be referenced through the self variable.

If you tried to access ypos instead of self.ypos in Projectile.update(), you would encounter an error, because ypos is neither a parameter nor a local variable in Projectile.update().

For example (using a simplified Projectile class):

>>> class Projectile:
...     def __init__(self):
...         self.xpos = 3.3
...     
...     def getX(self):
...         return xpos
... 
>>> shot = Projectile()
>>> shot.getX()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 6, in getX
NameError: global name 'xpos' is not defined

Note that you could write to just xpos, but it would just go to a local variable and be destroyed once the method returns, which is probably not what you intended.

Internal object variables

Notice that the internal object variables are all defined inside the constructor. This is good programming practice.

You could add more variables in other methods, but it's not a good idea.

• Defining variables after the constructor means a method that needs to use that variable may not find it available, if it is called before the variable is defined.
• Your code will also be harder to read, since all the variables will not be defined in one place.

For example:

>>> class Human:
...     def __init__(self):
...         self.position = (0.0, 0.0)
...      
...     def setName(self, name):
...         self.name = name
...     
...     def describe(self):
...         print("Position:", self.position, "Name:", self.name)
... 
>>> frank = Human()
>>> frank.setName("Frank")
>>> frank.describe()
Position: (0.0, 0.0) Name: Frank
>>> bob = Human()
>>> bob.describe()
Position: (0.0, 0.0) Name:
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 9, in describe
AttributeError: Human instance has no attribute 'name'

Accessors & Mutators

• The Projectile.getX() and Projectile.getY() methods are the way we access the internal xpos and ypos elements from outside the object.
• This type of method is called an accessor
• Methods which serve to modify an object (e.g. a hypothetical Projectile.setX() and Projectile.setY()) are called mutators.
• Having accessors and mutators are not necessary in Python, so this approach may seem excessive given that the user can directly access the data.
• Some other OO languages, like C++, require the use of accessors and mutators to enforce privacy of data. And they can be useful. Here's an example:
  • Defining the accessors as methods abstracts the implementation from the user. If you decided to change the underlying structure of the object from Projectile.xpos and Projectile.ypos to a tuple called position, any programs which accessed the data members directly would break, whereas any that used the accessors would act like nothing happened.
  • We could also add a method Projectile.getPos() which returned a tuple. Adding methods is generally considered OK, or at least more so than removing or changing methods that are already in use elsewhere.
• Accessors and mutators are generally considered an important part of object-oriented design because they abstract the underlying data representation of an object into an interface for users.
  • Opinions vary, of course, and not everyone feels they are a beneficial thing, especially in the Python community.
  • Most object-oriented languages, however, tend to use the accessor/mutator pattern in their objects, so it would be a good thing to get used to.
• The usual principle in object-oriented programming is to hide your data representation as much as possible so the user has to interact with it as little as possible.

Constructor advice

A little bit more about constructors -

Consider the following class for tracking student grades:

class Student:
    def __init__(self, name, credits, points):
        self.name    = name
        self.credits = credits
        self.points  = points
        
    def getName(self):
        return self.name
        
    def getCredits(self):
        return self.credits
    
    def getPoints(self):
        return self.points
        
    def gpa(self):
        return (self.points / self.credits)

• What happens if the user passes strings in for the credits and points?
  • This is entirely reasonable and will generally happen when reading from a file. In this case, Student.credits and Student.points will be strings, and we'll get an error when we try to divide them in Student.gpa().
  • Similarly, if the user passes integers in, the result of Student.gpa() will be an integer division, which will likely be a wrong answer.
• A good way to avoid problems like this is to force the items into particular types in the constructor, like so:

class Student:
    def __init__(self, name, credits, points):
        self.name    = str(name)
        self.credits = float(credits)
        self.points  = float(points)
    .
    .
    .

Modules

We've seen modules before.

• We have to import math when we want to do heavy math like trigonometry.
• We have to import time when we want our program to pause.
• We have to import random when we want to get random numbers.

We can create our own modules, too, so that we can keep our class definitions in separate files. This eliminates clutter and makes it much easier to reuse your objects in later programs.

You don't have to do anything special to make a module besides putting the code in a separate file. Once you want to use your code in that file, you simply need to import the code file.

For example, if we had defined our Projectile class in a file called projectile.py, we would do the following to use the Projectile class:

>>> import projectile
>>> shot = projectile.Projectile(3.0, 0.0, 1.0, 5.0) 
>>> shot
<projectile.Projectile instance at 0x6b440>

We might find it a little more convenient to do it this way instead:

>>> from projectile import Projectile
>>> shot = Projectile(3.0, 0.0, 1.0, 5.0)
>>> shot
<projectile.Projectile instance at 0x6b6e8>

The "from <x> import <y>" approach is generally a little nicer with objects, but it restricts what we import from the module to what was specified.

If we had a whole lot of functions or constants in the module (e.g. math.sin() and math.pi), we might want to just import the module and live with the module prefix.

Module and class documentation

Documenting your programs with comments is a good practice in general. There is more we can do, however, to help users. Modules and objects have a special attribute called __doc__, known as the docstring, which can be examined at runtime. For example, if we wanted to get the dirt on the random.random() method:

>>> import random
>>> print(random.random.__doc__)
random() -> x in the interval [0, 1).

There is an even simpler way to get this info:

>>> import random
>>> help(random.random)

Help on built-in function random:

random(...)
    random() -> x in the interval [0, 1).

For something even more useful, try the above on your own computer, to get help on the entire random module (after importing random, just type "help(random)").

We can write our own docstrings for our modules, classes and methods. Simply include a string at the top of your definition:

class Student:
    """A class defining a student for the purpose of grade tracking."""
    
    def __init__(self, name, credits, points):
        """Initialize a student with given name, credit hours and quality
        points."""
        self.name = str(name)
        .
        .
        .

Cards Example

Now that we know about classes, I thought I'd like to try to write a Card class.

I eventually want to have this be graphical, but to start I'll be happy if I can just get it to work and print out the names of the cards that are being dealt.

from graphics import *
import string
import sys
import random

RANK_NAMES = {1:'Ace', 2:'Two', 3:'Three', 4:'Four', 5:'Five', 
6:'Six', 7:'Seven', 8:'Eight', 9:'Nine', 10:'Ten', 11:'Jack', 
12:'Queen', 13:'King'}

SUIT_NAMES = {'s':'spades', 'c':'clubs', 'h':'hearts', 'd':'diamonds'}


class Card:

    # Constructor
    def __init__(self, rank, suit):
        self.rank = int(rank)
        self.suit = str(suit)
        
        if self.rank == 1:
            self.bJPts = 1
            self.rummyPts = 15
        elif self.rank > 1 and self.rank < 10:
            self.bJPts = self.rank
            self.rummyPts = 5
        else:
            self.bJPts = self.rummyPts = 10

        self.name = RANK_NAMES.get(self.rank) + ' of '
        self.name = self.name + self.suit

        self.filename = str(self.rank) + self.suit + ".GIF"

    # Accessors
    def getRank(self):
        return self.rank

    def getSuit(self):
        return self.suit

    def getBJPts(self):
        return self.bJPts

    def getRummyPts(self):
        return self.rummyPts

    def getName(self):
        return self.name

    def getFilename(self):
        return self.filename



# dealHand(hand, deck, numCards) deals numCards
# from the deck into the hand
#
# Inputs: hand, an empty list to put cards into
#         deck, the remaining undealt cards
#         numCards, the number of cards to be
#                   dealt into this hand
# Outputs: None, but hand and deck will be modified
def dealHand(hand, deck, numCards):

    deckSize = len(deck)
    if deckSize < numCards:
        print("There are only", deckSize, "cards left in the deck")
        print("So I can't deal a hand of", numCards, "cards")
        sys.exit()
        
    for i in range(numCards):
        hand.append(deck[i])
        del(deck[i])


def main():

    deck = []
    numRanks = len(RANK_NAMES)

    # Make a deck of cards
    for suit in SUIT_NAMES:
        for rank in range(1, numRanks + 1):
            deck.append(Card(rank, SUIT_NAMES.get(suit)))

    print("\nLet's play cards!\n")
    
    # Shuffle it
    print("I'm shuffling the deck.\n")
    random.shuffle(deck)

    # Get number of cards for this hand
    numCardsPerHand = int(input("How many cards would you like ? "))
    
    hand = []
    dealHand(hand, deck, numCardsPerHand)

    # Print their names
    numCards = len(hand)
    for i in range(numCards):
        name = Card.getName(hand[i])
        print(name)

main()

linuxserver1.cs.umbc.edu[109] python cards.py

Let's play cards!

I'm shuffling the deck.

How many cards would you like ? 5
Ace of clubs
Seven of clubs
Two of spades
Nine of spades
Ten of diamonds
linuxserver1.cs.umbc.edu[110] python cards.py

Let's play cards!

I'm shuffling the deck.

How many cards would you like ? 5
Eight of clubs
Jack of clubs
Five of hearts
King of diamonds
Two of clubs

That figures! Two poker hands and the best I get is Ace-high.

Let's work on the graphical version

from graphics import *
import string
import sys
import random
import time

RANK_NAMES = {1:'Ace', 2:'Two', 3:'Three', 4:'Four', 5:'Five', 
6:'Six', 7:'Seven', 8:'Eight', 9:'Nine', 10:'Ten', 11:'Jack', 
12:'Queen', 13:'King'}

SUIT_NAMES = {'s':'spades', 'c':'clubs', 'h':'hearts', 'd':'diamonds'}


class Card:

    # Constructor
    def __init__(self, rank, suit):
        self.rank = int(rank)
        self.suit = str(suit)
        
        if self.rank == 1:
            self.bJPts = 1
            self.rummyPts = 15
        elif self.rank > 1 and self.rank < 10:
            self.bJPts = self.rank
            self.rummyPts = 5
        else:
            self.bJPts = self.rummyPts = 10

        self.name = RANK_NAMES.get(self.rank) + ' of '
        self.name = self.name + self.suit

        self.filename = str(self.rank) + self.suit + ".GIF"

    # Accessors
    def getRank(self):
        return self.rank

    def getSuit(self):
        return self.suit

    def getBJPts(self):
        return self.bJPts

    def getRummyPts(self):
        return self.rummyPts

    def getName(self):
        return self.name

    def getFilename(self):
        return self.filename



# dealHand(hand, deck, numCards) deals numCards
# from the deck into the hand
#
# Inputs: hand, an empty list to put cards into
#         deck, the remaining undealt cards
#         numCards, the number of cards to be
#                   dealt into this hand
# Outputs: None, but hand and deck will be modified
def dealHand(hand, deck, numCards):

    deckSize = len(deck)
    if deckSize < numCards:
        print("There are only", deckSize, "cards left in the deck")
        print("So I can't deal a hand of", numCards, "cards")
        sys.exit()
        
    for i in range(numCards):
        hand.append(deck[i])
        del(deck[i])


def main():

    deck = []
    numRanks = len(RANK_NAMES)

    # Make a deck of cards
    for suit in SUIT_NAMES:
        for rank in range(1, numRanks + 1):
            deck.append(Card(rank, SUIT_NAMES.get(suit)))

    print("\nLet's play cards!\n")
    
    # Shuffle it
    print("I'm shuffling the deck.\n")
    random.shuffle(deck)

    # Get number of cards for this hand
    numCardsPerHand = int(input("How many cards would you like ? "))
    
    hand = []
    dealHand(hand, deck, numCardsPerHand)

    # Show them to the player
    numCards = len(hand)
    
    win = GraphWin("Let's Play Cards!", numCards * 100, 300)
    win.setBackground("green3")
    x = 50
    y = 100
    
    for i in range(numCards):
        pic = Image(Point(x, y), Card.getFilename(hand[i]))
        x += 100
        pic.draw(win)

    time.sleep(10)
    win.close()


main()

Let's see if my luck has changed!

Class Exercise

Write a class to represent a geometric solid cube.

• The constuctor should accept the length of one side as a parameter.
• It should have accessors.
• It should have methods that:
  • return the surface area of the cube
  • return the volume of the cube