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

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.

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 some 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
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.py.get_date(date_string)
print(date_functions.py.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
It 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
It 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 function call
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 in our next class

New Material

Classes Are Used by Other Programs

Classes are usually contained in modules
In other words in separate files
To use a class you have to import it
In this class we will create module files in the same directory as the script
The modules can be put in other directories
But then we would have to change the PYTHONPATH system variables
The script that uses a class is often called the client program

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",
                  x     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 methods declarations
One of which has the special name __init__
This method is the constructor
Which 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

The __init__ cannot be called directly
Instead you use the name of the class

The general format is

OBJECT_VARIABLE = CLASS_NAME([PARAMETER, ...])

Here is an example
```
date = Date(date_string)
```
We call the constructor using Date
It returns a pointer to the Date object
Which is stored in the object variable date
We use date to call the methods in the class
Like this
```
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 class we use dot notation with self
To refer to class variables
And 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
With the object variable

And 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'
```
So we always use dot notation
When referring to an object's attributes
Or methods
But inside the class definition we use self
While in the client code we use the object variable

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
The class can render the date 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 new 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 wha 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
Where the values range from 0 to 23
MM is a two digit minute
And SS is a two digit second

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)

Let's also create the format_time method

Which will 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 the 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

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
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
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 is will not affect any client software
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

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