IT 117: Intermediate Scripting

IT 117: Intermediate Scripting
Class 20

Review

Data Hiding
The __str__ Method
Accessor and Mutator Methods
Data Validation in The Constructor
Hiding Methods

New Material

Decorators
The Property Decorator
Getters Using the Property Decorator
Setters Using the Property Decorator
A Practical Example of A Class
Other Methods for the Student Class
Creating Student Objects
Storing Objects for Future Use
Pickling in student_load.py
The Section Class
Adding Students to A Section Object
Import Statements and Global Variables
Being a Good Citizen

Microphone

Homework 9

I have posted homework 9 here.

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

Quiz 7

Let's look at the answers to Quiz 7

Questions

Are there any questions before I begin?

Review

Data Hiding

Client code can change the attributes of a class directly ...
unless you do something to prevent this
This might seem harmless but it can lead to trouble

The latest version of the Time class has one attribute

>>> t1 = Time("14:35:12")
>>> t1.seconds
52512
t1.format_time()
'2:35:12 PM'

If a user wanted to change that value ...
they would have to change a time like 9:45 into seconds
It would be quite a lot of work to perform this calculataion
And it would be easy to make a mistake

Worse than that, they might enter a totally ridiculous value

>>> t1.seconds  = 1000000000
>>> t1.format_time()
'277765:46:40 PM'

To prevent this we need to make the attributes invisible ...
outside the class definition
This is called data hiding
To do this in Python we change the name of attributes ...
so they start with two underscore characters, __

The str Method

Classes can have certain methods whose names begin and end with __
These methods are sometime called magic methods
They are special because they are never called directly
In Python documentation they are called special methods
__init__ is an example of a magic method
The client code calls __init__ using the name of the class
```
t1 = Time("09:45:00")
```
__str__ is another magic method
It is called whenever you need a string representing an object ...
like when you print it
```
print(t1)
```

If Time had no __str__ method and we tried to print it we would get

>>> t = Time("09:30:00")
>>> print(t)
<time_3.Time object at 0x1013e8358>

The __str__ method must return a string

Like this

    def __str__(self):
        hours = self.seconds // (60 * 60)
        remainder = self.seconds % (60 * 60)
        minutes = remainder // 60
        seconds = remainder % 60
        return str(hours) + " hours " + str(minutes)+ " minutes " + str(seconds) + " seconds

You see the latest version of the Time class here

Accessor and Mutator Methods

A well designed class hides its attributes
But the client code sometimes needs to see those values
So you need to create special methods called accessors
It is common practice for the name of an accessor to begin with "get"
So another name for an accessor is a getter
Let's say you need to keep track of each computer in an office
You would need to record the following information about each machine
- Manufacturer
- Model
- Serial number
- Processor
- RAM
- Hostname
- Disk size

The first thing we need to do is create a constructor

def __init__(self, manufacturer, model, serial_number, processor, ram, hostname, disk_size):
    self.__manufacturer  = manufacturer
    self.__model         = model
    self.__serial_number = serial_number
    self.__processor     = processor
    self.__ram           = ram
    self.__hostname      = hostname
    self.__disk_size     = disk_size

All the attributes are hidden ...

so we need to create accessor for each

def get_manufacturer(self):
    return self.__manufacturer

def get_model(self):
    return self.__model

def get_serial_number(self):
    return self.__serial_number

def get_processor(self):
    return self.__processor

def get_ram(self):
    return self.__ram

def get_hostname(self):
    return self.__hostname

def get_disk_size(self):
    return self.__disk_size

The values of the following attributes should never change
- __manufacturer
- __model
- __serial_number
- __processor
That is one of the reasons we hide attributes
But some attributes could change with time
- __ram
- __hostname
- __disk_size
We need special methods to change these values
Such methods are called mutators
Common practice is to start a mutator name with "set"
So mutators are sometimes called setters

Here are the mutators for the Computer class

def set_ram(self, ram):
    self.__ram = ram

def set_hostname(self, hostname):
    self.__hostname = hostname

def set_disk_size(self, disk_size):
    self.__disk_size = disk_siz

Data Validation in The Constructor

The Time constructor needs to check its time_string parameter ...
to make sure it represents a valid time
Checking that values make sense before they are used is called data validation
First we need to make sure that time_string is is really a string
We can do this with the built-in function isinstance
The isinstance function takes two arguments
- An object
- The name of a class
It returns True if the object is an instance of the class
```
>>> isinstance("14:35:12", str)
True
```
If we don't get a string we should raise an exception

Like this

if not isinstance(time_string, str):
    raise TypeError("Time constructor expects a string argument")

Next we need to check whether the string has the right format

I am going to put this code in a method of its own called has_valid_format

# returns true if the string has the form HH:MM:SS
def has_valid_format(s):
    pattern = re.compile("\d\d:\d\d:\d\d")
    match = pattern.match(s)
    return match

Here we use regular expressions to try to match the string
If we have a match, match points to an object ...
the calling statement will interpret this as True ...
and nothing will happen
If the string does not match, match will be None ...
which is False in an if statement
This means the code block of the if statement will be run ...
and the constructor will raise an exception
Finally, we make sure that hours is between 0 and 23 ...
and minutes and seconds are between 0 and 59

To do this I am going to create a new method date_numbers_in_range

# returns true if the numbers for hours, minutes and seconds
# are within the proper range
def date_numbers_in_range(hours, minutes, seconds):
    if not 0 <= hours <= 23:
        return False
    if not 0 <= minutes <= 59:
        return False
    if not 0 <= seconds <= 59:
        return False
    return True

Now we change the constructor to call these methods

# expects a string of the form HH:MM:SS
# where hours are expressed in numbers from 0 to 23    
def __init__(self, time_string):
    if not isinstance(time_string, str):
        raise TypeError("Time constructor expects a string argument")
    if not self.has_valid_format(time_string):
        raise ValueError("String must have the format HH:MM:SS")
    hours, minutes, seconds = time_string.split(":")
    hours   = int(hours) 
    minutes = int(minutes)
    seconds = int(seconds)
    if not self.date_numbers_in_range(hours, minutes, seconds):
        raise ValueError("One of the time values is not in the proper range")
    self.__seconds = hours * 60 * 60 + minutes * 60 + seconds

Hiding Methods

The methods has_valid_format and date_numbers_in_range are only used by the constructor
They are not intended for use outside the class
So we should hide them by starting their names with __
Any method that is not needed outside the class should be hidden
A class should be a black box
With specified inputs and outputs
The client code has no need to know the internal workings of the class

Attendance

New Material

Decorators

In Python everything is an object
Even functions
Since functions are objects, they can be used as the argument to another function
This means you can write one function ...
to change another function
This makes possible a special Python feature called decorators
If you write a special string on the line above a function header ...
that has this format
```
@DECORATOR_NAME
```
The Python interpreter will run that decorator on the function ...
before running the script itself
Each decorator adds new features to the function
There is one decorator that makes data hiding much cleaner ...
than starting attribute names with two underscores, __

The Property Decorator

Built into the Python interpreter is a decorator called property ...
which is used to create special getters and setters
But for this to work we have to change the names of the attributes ...
so their names begin with an underscore, _
Not two as we did in the last class

So the constructor for the Computer class now becomes

def __init__(self, manufacturer, model, serial_number, processor, ram, hostname, disk_size):
    self._manufacturer  = manufacturer
    self._model         = model
    self._serial_number = serial_number
    self._processor     = processor
    self._ram           = ram
    self._hostname      = hostname
    self._disk_size     = disk_size

Getters Using the Property Decorator

The next change is adding a decorator before each accessor header
So we write
```
@property
```
Then we change the name by removing "get_" ...
and return the attribute using it's new name ...

Here is the code for the new getters

		
@property
def manufacturer(self):
  return self._manufacturer

@property
def model(self):
  return self._model

@property
def serial_number(self):
  return self._serial_number

@property
def processor(self):
  return self._processor
  
@property
def ram(self):
  return self._ram

@property
def hostname(self):
  return self._hostname
  
@property
def disk_size(self):
  return self._disk_size

We can now get the attribute values without making a function call

>>> c1 = Computer("Apple", "Mac Studio", "FD5C640XZH", "Apple M2 Max", "32 GB", "Jupiter", "2 TB")
>>> c1.manufacturer
'Apple'
>>> c1.model
'Mac Studio'
>>> c1.serial_number
'FD5C640XZH'
>>> c1.processor
'Apple M2 Max'
>>> c1.ram
'32 GB'
>>> c1.hostname
'Jupiter'
>>> c1.disk_size
'2 TB'

Setters Using the Property Decorator

The changes made to the setters is similar ...
but the line above the definition has a new format
```
@ATTRIBUTE_NAME.setter
```

So the code for the 3 attributes that can be changed is

@ram.setter
def ram(self, new_ram):
    self._ram = new_ram
    
@hostname.setter
def hostname(self, new_hostname):
    self._hostname = new_hostname
    
@disk_size.setter
def disk_size(self, new_disk_size):
    self._disk_size = new_disk_size
	self._facing = facing

We can now change these values more intuitively

>>> c1.ram
'32 GB'
>>> c1.ram = "64 GB"
>>> c1.ram
'64 GB'
>>> c1.hostname
'Jupiter'
>>> c1.hostname = "Jupiter II"
>>> c1.hostname
'Jupiter II'
>>> c1.disk_size
'2 TB'
>>> c1.disk_size = "3 TB"
>>> c1.disk_size
'3 TB'

A Practical Example of A Class

I use Python to help me administer my course work
Let's create a Student class that will help me do this
And let's use properties when we write the code
I need at least three values for each student
- Student ID
- Last Name
- First Name
This is all the information I have at the start of the semester
I will need other attributes for this class
- Preferred first name
- Phonetic spelling of the name
- Email address
- Unix username
But they will be added later
So the constructor sets them to the empty string

Here is the code for the constructor

def __init__(self, id, last_name, first_name):
    self._id             = id
    self._last_name      = last_name
    self._first_name     = first_name
    self._preferred_name = ""
    self._phonetic_name  = ""
    self._email          = ""
    self._unix_username  = ""

I need accessors for each of these attributes

@property
def id(self):
    return self._id

@property
def last_name(self):
    return self._last_name

@property
def first_name(self):
    return self._first_name

@property
def preferred_name(self):
    return self._preferred_name

@property
def phonetic_name(self):
    return self._phonetic_name

@property
def email(self):
    return self._email

@property
def unix_username(self):
    return self._unix_username

Now I need mutators for the last four attributes

@preferred_name.setter
def preferred_name(self, preferred_name):
    self._preferred_name = preferred_name

@phonetic_name.setter
def phonetic_name(self, phonetic_name):
    self._phonetic_name = phonetic_name

@email.setter
def email(self, email):
    self._email = email

@unix_username.setter
def unix_username(self, unix_username):
    self._unix_username = unix_username

Other Methods for the Student Class

Now I need to create a __str__ method for this class

def __str__(self):
    return self._first_name + " " + self._last_name + ", " + self._id

The first thing you should do after you create a method ...

is to test it

>>> student = Student("12345", "Smith", "William")
>>> print(student)
William Smith, 12345

I also need a method that returns the full name of the student
We'll call this method full_name
Normally this is the first name, a space and the last name
But I want to use the preferred first name ...
if the student has provided one

Here is the code

def full_name(self):
    if self._preferred_name:
        return self._preferred_name + " " + self._last_name
    else:
        return self._first_name + " " + self._last_name

Now I test

>>> student.full_name()
'William Smith'
>>> student._preferred_name("Bill")
>>> student.get_full_name()
'Bill Smith'

Since I will be creating alphabetized lists I need a sort name
This is the last name, a comma and a space, and the first name ...

or the preferred name

def sort_name(self):
    if self._preferred_name:
        return self._last_name + ", "  + self._preferred_name 
    else:
        return self._last_name + ", "  + self._first_name

Again I have to test
```
>>> student.sort_name()
'Smith, Bill'
```
You can see the code here

Creating Student Objects

When the semester starts I go to my class register in WISER ...
and copy it into a text file
This file has the information I need ...
but not in the right format
So I will have to modify the file ...
to get the data into a format I can use
Each entry in this new file will have student data in the following format
```
STUDENT_ID,LAST_NAME,FIRST_NAME
```
Let's create another script, student_load.py
To read the file and create Student objects
The objects will be stored in a dictionary ...
where the ID is the key ...
and the value is the Student object
This script is going to have three parts
- Setup
- Create the objects and store them
- Print student names
The last part is not strictly necessary
But it lets me know that the script is working properly
In the setup I will
- Import the Student class
- Create an empty dictionary
- Get the filename
- Create a file object

Here is the code

from student import Student

students = {}

data_filename = input("Data filename: ")
data_file     = open(data_filename, "r")

With the file object I can loop through the lines ...
to get the id, last name and first name ...
using the string method split and multitple assignment
With these values in hand I can call the constructor ...
and store the object in the dictionary

Here is the code

for line in data_file:
    id, last_name, first_name = line.split(",")
    student = Student(id, last_name, first_name)
    students[id] = student

The last section loops through the dictionary printing each entry
The loop variable is set to the student ID ...
which I use to retrieve the object ...

and call its methods

for id in students:
    student = students[id]
    name = student.get_first_name() + " " + student.get_last_name()
    print(name)

You can see the code here

Storing Objects for Future Use

There is a major problem with this script
The dictionary disappears after the script ends
We need to store the dictionary for future use
All modern computer languages allow you to store objects ...
as a file on disk
These files can be read in later to restore the object
This process is called serializing
Python lets you serialize an object but it calls the process pickling
Pickling is a process for preserving food through fermentation
Examples are pickles, sauerkraut and kimchi
There is a module in the standard library named pickle
It contains functions to serialize objects
Here is how it works
First you must import the pickle module
```
import pickle
```
Next you have to open a file using a special access mode
I have told you to use the "w" access mode to write to a file
But that it for text files
Pickling uses binary files ...
which need different acces modes
To open a file for writing binary data we use the "wb" access mode
```
pickle_file = open(PICKLE_FILENAME, "wb")
```
Then we use the dump function of the pickle module ...
to serialize the object
dump takes two arguments
- The object being serialized
- A binary file object
We call it like this
```
pickle.dump(students, pickle_file)
```
Loading an object from a data file is a similar process
First we open the file with the "rb" (read binary) access mode
```
pickle_file = open(PICKLE_FILENAME, "rb")
```
Then we reconstruct the object using load
It takes the file object as its only parameter
```
students = pickle.load(pickle_file)
```

Pickling in student_load.py

There is another problem with student_load.py
Students may register for the class after I have create the students dictionary ...
and have pickled it
When this happens I create another copy of the WISER roster ...
and another copy of the text file with id, last name and first name
If I run the script on the new version of the input file ...
some students will be entered twice
So I need a more sophisticated algorithm
First I need to see if there is a pickle file
If there is, I need to load the students dictionary
If there isn't, I need to create an empty dictionary
Then I need to open the text file ...
and read in the data for each student
But I will only add it to the dictionary if it is a new student

Here is the pseudocode

try to open the pickle file
if the file exists
    create the students dictionary from the pickle file
else:
    create an empty dictionary
open the text file with student data
loop through the text file
    get the id, first name and last name
    if the id is not in the students dictionary:
        create a student object
        add the new object to the dictionary

Here is the code

PICKLE_FILENAME = "students.dat"
try:
    pickle_file = open(PICKLE_FILENAME, "rb")
except:
    students = {}
else:
    students = pickle.load(pickle_file)
    pickle_file.close()

data_filename = input("Data filename: ")    
try:
    data_file = open(data_filename, "r")
except:
    print("Cannot open", data_file)
    sys.exit()

for line in data_file:
    id, last_name, first_name = line.split(",")
    if id not in students:
        student = Student(id, last_name, first_name)
        students[id] = student
data_file.close()

The Section Class

I can teach the same class at different times
Each different meeting time is a section
I have a script that I use to take attendance
This script needs an alphabetical list of all students in the section
To get this list I will create a Section class
The class will have four attributes
- A unique ID to identify the course
- The semester
- The section number
- IDs of registered students
For a course ID I use "it" followed by the course number
So this course has a course ID of "it117"
Each year has three semesters
- Fall - abbreviated "f"
- Spring - abbreviated "s"
- Summer - abbreviated "sum"
The semester value uses these abbreviations ...
followed by a two digit year
So the Fall 2020 semester will be recorded as "f20"

Here is the constructor

def __init__(self, course_id, semester, section_no):
    self._course_id   = course_id
    self._semester    = semester
    self._section_no  = section_no
    self._student_ids = set()

Notice that the _student_ids is assigned the empty set
It is a set since there should be no duplicate student IDs

Adding Students to A Section Object

I will use a Section object to create lists of students in that section
To do this the Section class needs an add_students method to populate _student_ids
It will do by reading in a file with the format
```
STUDENT_ID,LAST_NAME,FIRST_NAME
```
I need a method to read in this file ...
and store IDs in _student_ids
When we wrote student_load.py we changed the code ...
so it would not create duplicates
It is impossible to store duplicate entries in a set
So we don't have to write code to check for this
This is why the attribute is a set, not a list

Here is the code

    # reads a text file that has the format
    #        STUDENT_ID,LAST_NAME,FIRST_NAME
    # adds these students to _student_ids
    def add_students(self, data_filename):
        try:
            data_file = open(data_filename, "r") 
        except:
            print("Could not open", data_file)
            sys.exit()
        for line in data_file:
            id, last_name, first_name = line.split(",")
            self._student_ids.add(id)
        data_file.close()

get_enrolled_students returns a dictionary of student objects

For all students enrolled in the section

    # retrieves the pickled students dictionary
    # and uses it to create a new dictionary
    # of student objects for students enrolled in this section
    def get_enrolled_students(self):
        enrolled_students = {}
        try:
            pickle_file = open(PICKLE_FILENAME, "rb")
        except:
            print("Could not open", PICKLE_FILENAME)
            sys.exit()
        students = pickle.load(pickle_file)
        pickle_file.close()
        for id in self._student_ids:
            enrolled_students[id] = students[id]
        return enrolled_students

When I run this with the following test code

from section import Section

section = Section("it117", "s17", 1)
print(section)
section.add_students("students.txt")
enrolled_students = section.get_enrolled_students()
for id in enrolled_students:
    print(enrolled_students[id])

I get

it117 s17 section 1
 Smith  John, 34524
 Adams  Jane, 45235

You will find the code for this class here

Import Statements and Global Variables

add_students uses code imported from two modules
- student
- pickle
Where to these import statements belong?
Import statements make module code available to the entire class
That means they need to appear at the top of the file
Before the class definition
If the class uses global variables

They also need to be declared at the top of the file

from student import Student
import pickle

PICKLE_FILENAME = "students.dat"

class Section:
...

Being a Good Citizen