IT 117: Intermediate Scripting

IT 117: Intermediate Scripting
Class 18

Review

Different Ways to Write Programs
An Example Problem
First Approach
Procedural Programming Approach
Object Oriented Programming
Object Oriented Approach

New Material

Classes Are Used by Other Programs
The Constructor Is Special
Defining a Class
Creating An Object from A Class
The self Variable
Using a Class
Improving the Date Class
Refactoring the Date Class
The Time Class
Static Methods
Changing the Attributes of a Class
Professional Responsibility
Codes of Conduct

Microphone

Readings

If you have the textbook read Chapter 10, Classes and Object-Oriented Programming sections 10.3 and 10.4, Working with Instances and Techniques for Designing Classes.

Homework 8

I have posted homework 8 here.

It is due this coming Sunday at 11:59 PM.

Quiz 6

Let's review the answers to Quiz 6.

Questions

Are there any questions before I begin?

Review

Different Ways to Write Programs

When programs were first written they were not organized
There was no structure to the code
This made them hard to read ...
and to debug
Then programmers embraced procedural programming
The idea was to break up big programs into a collection of functions ...
which were called by the main body of the code
Each function had a specific task
Which isolated it from the rest of the code
This made the code easier to read
And to change as needed
A more recent approach is called object oriented programming
All the variables containing data about one thing ...
like a car, a person, or a company ...
are put inside an object
The functions that work with these variables are also in the object
The functions inside an object are called methods
This keeps all the code dealing with a particular thing ...
in the same place
To define the object we create a class

An Example Problem

Let's say I needed to read in a date from a text file
Where the first line has the following format
```
YYYY-MM-DD
```
I want to turn this into a string with the following format
```
MONTH_NAME DAY_OF_MONTH, YEAR
```
I will use this to demonstrate the different ways to write code

First Approach

The first version of the code has no structure

#! /usr/bin/python3

# code to convert a date in the format 
#    YYYY-MM-DD
# stored as the first line in a file whose name
# is stored in the variable DATA_FILENAME
# into a string in the format
#    MONTH_NAME DAY_OF_MONTH, YEAR

DATA_FILENAME = "data.txt"
data_file = open(DATA_FILENAME, "r") # open the file for reading
date_string = data_file.readline()
year, month, day = date_string.strip().split("-")
year, month, day = int(year), int(month), int(day) 

month_names = {1:"January",    2:"February", 3:"March",     4:"April",
               5:"May",        6:"June",     7:"July",      8:"August",
               9:"September", 10:"October", 11:"November", 12:"December"}

new_date_string = month_names[month] + " " + str(day) + ", " + str(year)
print(new_date_string)

Procedural Programming Approach

Let's rewrite the code using the procedural programming approach
We can refactoring this code into four functions
- get_first_line
- get_date
- get_month_name
- format_date
We will also need three global variables
- year
- month
- day

Here is the code for the first function

# opens a file and returns the first line in
# that file without the newline
def get_first_line(filename):
    data_file = open(filename, "r")
    date_string = data_file.readline()
    data_file.close()
    return date_string.strip()

The last three functions all deal with dates
And I might want to use them in other scripts
So I am going to put them in a separate module called date_functions.py

Here is the code for these functions

# turns a string with a date in the format
# YYYY-MM-DD
# into integer values for year, month and date
def get_date(date_string):
    year, month, day = date_string.split("-")
    return int(year), int(month), int(day)
    
# converts a month number into a month name
def get_month_name(month_number):
    month_names = {1:"January",    2:"February", 3:"March",     4:"April",
                   5:"May",        6:"June",     7:"July",      8:"August",
                   9:"September", 10:"October", 11:"November", 12:"December"}
    return month_names[month_number]

# returns a date in standard format
def format_date(year, month, day):
    return get_month_name(month) + " " + str(day) + ", " + str(year)

We can now rewrite the script as follows

#! /usr/bin/python3

import date_functions

# code to convert a date in the format 
#    YYYY-MM-DD
# stored as the first line in a file whose name
# is stored in the variable DATA_FILENAME
# into a string in the format
#    MONTH_NAME DAY_OF_MONTH, YEAR


# opens a file and returns the first line in
# that file without the newline
def get_first_line(filename):
    data_file = open(filename, "r")
    date_string = data_file.readline()
    data_file.close()
    return date_string.strip()

DATA_FILENAME = "data.txt"

date_string = get_first_line(DATA_FILENAME)
year, month, day = date_functions.get_date(date_string)
print(date_functions.format_date(year, month, day))

Notice that I had to import the date_functions.py module

Object Oriented Programming

To create an object you need to define a class
A class is a template used to create individual objects
The objects are the things in RAM ...
that are created from the class definition
The class defines all variable and methods inside the object
Functions defined inside a class are called methods
Every class must have a special method called the constructor
In Python, the constructor must be named __init__
It is used to create objects of the class
An actual object created by the constructor is called an instance

Object Oriented Approach

Let's rewrite the script for our problem using objects
I will define a Date class ...
which will be stored in the module date
To do this, I have to move the functions from the date_functions.py module ...
into the Date class ...
along with the variables year, month and day
I will have to modify the code slightly
Every method in a class takes the self parameter
self represents the object that is created
This parameter allows you to access all the variables and methods in the class ...
using dot notation

Here is the code for __init__

def __init__(self, date_string):
    self.year, self.month, self.day = date_string.split("-")
    self.year  = int(self.year) 
    self.month = int(self.month)
    self.day   = int(self.day)

Here is the class version of get_month_name

# converts a month number into a month name             
def get_month_name(self):
    month_names = {1:"January",    2:"February", 3:"March",     4:"April",
                   5:"May",        6:"June",     7:"July",      8:"August",
                   9:"September", 10:"October", 11:"November", 12:"December"}
    return month_names[self.month]

format_date undergoes similar changes

# returns a date in standard format             
def format_date(self):
    return self.get_month_name() + " " + str(self.day) + ", " + str(self.year)

In the script that uses this class we have to import the Date class definition
Then we create a Date object like this
```
date = Date(date_string)
```
date is a variable in the client code
The code that is using the class
date points to the object created by the constructor
Notice that although the name of the constructor inside the class is __init__ ...
outside the class we call it using the name of the class
While __init__ takes two parameters ...
we only use one parameter in the call to the constructor
This is true for all methods
Methods must take self as a parameter
But it never appears in the method call

Here is the code for the latest version of our script

#! /usr/bin/python3

# code to convert a date in the format 
#     YYYY-MM-DD
# stored as the first line in a file whose name
# is stored in the variable DATA_FILENAME
# into a string in the format
#     MONTH_NAME DAY_OF_MONTH, YEAR

from date import Date

# opens a file and returns the first line in
# that file without the newline
def get_first_line(filename):
    data_file = open(filename, "r")
    date_string = data_file.readline()
    data_file.close()
    return date_string.strip()

DATA_FILENAME = "data.txt"

date_string = get_first_line(DATA_FILENAME)
date = Date(date_string)
print(date.format_date())

We'll go into more detail below

Attendance

New Material

Classes Are Used by Other Programs

A class does nothing by itself
Instead it is used by other code ...
to form a working program
A class can be defined inside a script ...
or contained in a module ...
which is what we will do
To keep things simple, the module will be in the same directory ...
as the script that will use it
A script that uses a class is often called the client code

The Constructor Is Special

A constructor is a special kind of method
It creates an object ...
and returns a pointer to the object
Constructors never have a return statement

Defining a Class

In the example above I declared the following class

# represents a calendar date
class Date:

    def __init__(self, date_string):
        self.year, self.month, self.day = date_string.split("-")
        self.year  = int(self.year) 
        self.month = int(self.month)
        self.day   = int(self.day)

    # converts a month number into a month name
    def get_month_name(self):
        month_names = {1:"January",    2:"February", 3:"March",     4:"April",
                       5:"May",        6:"June",     7:"July",      8:"August",
                       9:"September", 10:"October", 11:"November", 12:"December"}
        return month_names[self.month]

    # returns a date in standard format
    def format_date(self):
        return self.get_month_name() + " " + str(self.day) + ", " + str(self.year)

The general format for a class is

class CLASS_NAME:
    def __init__(self[, PARAMETER, ...]):
        ...

    def METHOD_NAME(self[, PARAMETER, ...]):
        ...

By convention, all class names in Python are Capitalized
A class definition consists of a number of method declarations
One of which has the constructor ...
which must be named __init__
This method is used to create the objects of the class
The class definition is the template used to create the object
The object is the thing that lives in memory

Creating An Object from A Class

You create an object with an assignment statement that calls the constructor
The __init__ method cannot be called directly
Instead you use the name of the class
The general format for the assignment statement that creates the class is
```
OBJECT_VARIABLE = CLASS_NAME([PARAMETER, ...])
```
Here is an example
```
date = Date(date_string)
```
We call the constructor using class name Date
It returns a pointer to a newly created Date object ...
which is stored in the object variable date
We use date to work with the object ...
using dot notation
```
print(date.format_date())
```

The self Variable

Every method defined in a class has self as a parameter
self is only used inside the class definition
Inside the modules of the class we use dot notation with self ...
to refer to class variables and other class methods
self is only used inside the class definition
It is never used in the code that uses the class

Using a Class

The client code calls the constructor to create objects of the class
If I call the Date constructor twice

I will create two different objects

>>> date_1 = Date("2015-10-03")
>>> date_2 = Date("2016-05-14")

These objects now live in the program's RAM ...
and are pointed to by the variables date_1 and date_2
Each object has its own unique ID

Which we can see using the built-in function id

>>> id(date_1)
4325278944
>>> id(date_2)
4325279280

Each of these objects is an instance of the Date class
Each of these objects has its own object variables
The variables contained in an object are called attributes
The year attribute in date_1 has the value 2015
The same attribute in date_2 has the value 2016
To view the attributes in the client code we also use dot notation
But here what comes before the . (dot) is not self ...
but the object variable

After the dot comes the attribute name

>>> date_1.year
2015
>>> date_2.year
2016

We do the same thing when we call each object's methods
```
>>> date_1.format_date()
'October 3, 2015'
```
In the client code dot notation begins with the object variable
But inside the class dot notation starts with self

Improving the Date Class

The constructor for the Date object needs a date string in the following format
```
YYYY-MM-DD
```
Where YYYY is a four digit year ...
MM is a two digit month ...
and DD is a two digit day
This format is actually specified in the standard ISO 8601
Date strings created using this format have an interesting property
When we sort them alphabetically ...
we are also sorting them by date
At the moment, Date can only produce a string in the following format
```
MONTH_NAME DAY_NUMBER, YEAR
```
But there is another common date format that is shorter
```
MM/DD/YYYY
```

Let's add a new method to return a string in this format

# returns a date in the short format M[M]/D[D]/YYYY
def short_format_date(self):
    return str(self.month) + "/" + str(self.day) + "/" + str(self.year)

When called, short_format_date produces the following
```
>>> date_1.short_format_date()
'10/3/2015'
```
Notice the order in which the different parts of the date are printed
- month
- day
- year
This order does not make a great deal of sense
We are the only country that does this
Most of the world puts the day first ...
followed by the month and year

Let's add two additional methods for these formats

# returns a date in the long format D[D] MONTH_NAME YYYY
def format_date_international(self):
    return str(self.day) + " " + self.get_month_name()  + " " + str(self.year)

# returns a date in the short format D[D]/M[M]/YYYY
def short_format_date_international(self):
    return str(self.day) + "/" + str(self.month) +  "/" + str(self.year)

We can use these as follows

>>> date_1.format_date_international()
'3 October 2015'
>>> date_1.short_format_date_international()
'3/10/2015'

Refactoring the Date Class

With the changes I noted above in the Date class ...
it now has four formating methods with similar names
It would be better if I had two functions long_format and short_foramt
I can do this if I give the new methods an additional parameter ...
that would specify either US or international format ...

with "US" as the default value for this new parameter

# returns a date in the long format 
#        MONTH_NAME D[D], YYYY
# if the region parameter is US, otherwise
#        D[D] MONTH_NAME YYYY
def long_format(self, region="US"):
    if region == "US":
        return self.get_month_name() + " " + str(self.day) + ", " + str(self.year)
    else:
        return str(self.day) + " " + self.get_month_name()  + " " + str(self.year)

Calling the method with only one parameter returns the US version
```
>>> date_1.long_format()
'October 3, 2015'
```
Any other value return the international version
```
>>> date_1.long_format("UK")
'3 October 2015'
```

I can take the same approach with short_format

# returns a date in the short format 
#        M[M]/D[D]/YYYY
# if the region parameter is US, otherwise
#        D[D]/M[M]/YYYY
def short_format(self, region="US"):
    if region == "US":
        return str(self.month) + "/" + str(self.day) + "/" + str(self.year)
    else:
        return str(self.day) + "/" + str(self.month) +  "/" + str(self.year)

Here is what happens when I call them

>>> date_1.short_format()
'10/3/2015'
>>> date_1.short_format("UK")
'3/10/2015'

The Time Class

Let's create another class called Time
It will record a specific point in time in a day
The constructor takes a time string in this format
```
HH:MM:SS
```
Where HH is the hours on a 24 hour clock
These values range from 0 to 23
MM is a two digit minute ...
and SS is a two digit second
Both range from 0 to 59

Here is the constructor

# expects a string of the form HH:MM:SS
# where hours are expressed in numbers from 0 to 23
def __init__(self, time_string):
    self.hours, self.minutes, self.seconds = time_string.split(":")
    self.hours   = int(self.hours) 
    self.minutes = int(self.minutes)
    self.seconds = int(self.seconds)

The constructor creates three object attributes
- hours
- minutes
- seconds
Each of these attributes is an integer
Let's also create the format_time method ...

to give us an nicely formated string representing the time

# returns a string in the form HH:MM:SS AM/PM
def format_time(self):
    hours = self.hours
    am_pm = "AM"
    if hours > 12:
        hours -= 12
        am_pm = "PM"
    return str(hours) + ":" + str(self.minutes) + ":" + str(self.seconds) + " " + am_pm

Notice that there are two variables containing the hour
hours is a local variable ...
that only exists when the method is called
But self.hours is an attribute of the object
This variable exits as long as the object exists

Here is what we get when we call this new method

>>> t1 = Time("10:45:30")
>>> t1.format_time()
'10:45:30 AM'

Let's also add the method difference

It show the difference between two times in seconds

# returns the difference in seconds between two times
def difference(self, other_time):
    seconds  = (self.hours - other_time.hours) * 60 * 60
    seconds += (self.minutes - other_time.minutes) * 60
    seconds += self.seconds - other_time.seconds
    return seconds

This method works with two objects
self refers to the current object
The one we are using to call the method
other_time refers to the second time object

We can use this method as follows

>>> midnight = Time("00:00:00")
>>> t2 = Time("03:04:13")
>>> t2.difference(midnight)
11053

Static Methods

The difference method returns the number of seconds ...
between the two time objects
But if the time difference were a couple of hours ...
the result would a be a large integer ...
which would be hard to understand
It would be nice to see the value returned by difference ...
broken up into hours, minutes, seconds
We could write another method format_differnence ...
which would calculate the difference and return a string in that format
But there is a better way to go
Remember that a function should only do one thing ...
but do it well
Let's create the method format_seconds
It takes the seconds as its argument

And returns a string in the proper format

# returns a string formated as follows
#    H[H] hours M[M] minutes S[S] seconds
def format_seconds(seconds):
    hours = seconds // (60 * 60)
    remainder = seconds % (60 * 60)
    minutes = remainder // 60
    seconds = remainder % 60
    return str(hours) + " hours " + str(minutes)+ " minutes " + str(seconds) + " seconds"

// means integer division

The function can be used like this

>>> midnight = Time("00:00:00")
>>> t2 = Time("03:04:13")
>>> Time.format_seconds(t2.difference(midnight))
'3 hours 4 minutes 13 seconds'

Look carefully at the line in red
I used dot notation
But the name in front of the dot is Time
Time is the name of the class
Not a variable pointing to a Time object
What's going on?
Look at the header for format_seconds
It does not take self as a parameter
This means it does not use the values in any object
So it is not like the other methods
Methods like this are called static methods
When we call a method we use dot notation
But a static method is not connected to any particular object
So we have to use the class name when calling the method

Changing the Attributes of a Class

Objects have many advantages
One is that we can change the internals of an object ...
as long as all the methods give the same results
The client code does not care how a method works
only how it is called
In the Time class we represented time with three attributes
- hours
- minutes
- seconds
This seems natural to use ...
because that is how we describe time when making an appointment
But it makes the difference calculation very complicated
However, here is another way to represent a time during the day
We can represent time as the number of seconds since midnight
This will make the difference calculation easier
But we need to change the other methods so they give the same results
If we do this it will not affect any client code
After we are finished the internal structure will be different
But all the methods will give the same results
The first thing we need to do is to change the constructor
We will still take a time string ...
and turn it into integer values for hours, minutes and seconds
But we will only use them to calculate our new attribute, seconds
So these variables will become local variables of the constructor
When the constructor finishes, these local variables disappear
Only the attribute seconds remains in the object

Here is the new code for the constructor

# expects a string of the form HH:MM:SS
# where hours are expressed in numbers from 0 to 23
def __init__(self, time_string):
    hours, minutes, seconds = time_string.split(":")
    hours   = int(hours) 
    minutes = int(minutes)
    seconds = int(seconds)
    self.seconds = hours * 60 * 60 + minutes * 60 + seconds

To modify format_time we need to turn seconds back into hours, minutes and seconds

Here is the revised code

# returns a string in the form HH:MM:SS AM/PM
def format_time(self):
    hours = self.seconds // (60 * 60)
    remainder = self.seconds % (60 * 60)
    minutes = remainder // 60
    seconds = remainder % 60
    am_pm = "AM"
    if hours > 12:
        hours -= 12
        am_pm = "PM"
    return str(hours) + ":" + str(minutes) + ":" + str(seconds) + " " + am_pm

The modified code is shown in red
We also have to change difference

But here the code is much simpler

# returns the difference in seconds between two times
def difference(self, other_time):
    return self.seconds - other_time.seconds

The method format_seconds remains unchanged

When we test the new class we get the same results

>>> from time_2 import Time
>>> midnight = Time("00:00:00")
>>> t2 = Time("03:04:13")
>>> t2.format_time()
'3:4:13 AM'
>>> Time.format_seconds(t2.difference(midnight))
'3 hours 4 minutes 13 seconds'

Professional Responsibility

Codes of Conduct