Lab 10: Using and Defining Classes

--- FAQ ---

Goals

After the lab, you should be proficient at

creating and testing your own classes from a specification
developing a larger program (set of classes) to solve a data management problem

Deadlines Update

We will have a staggered deadline for this lab:

For Friday before class, you should have completed up through the SocialNetwork's addConnections method and tested all the methods you implemented. Turn in your assignment electronically.
Before lab on Tuesday, you should finish the assignment and submit it electronically as well as print it out.

Objective: Set Up

Run the help client
run labhelp
Instead of creating a lab10 directory, copy the entire /csci/courses/cs111/handouts/lab10 directory and all its contents to your cs111 directory (which again means you should use what command-line option?).

Review

Review the slides for today's lab.

For this lab, you'll use "real" program names instead of the "lab10_x.py" names we typically use.

Objective: Preparing to Create a Social Network

Problem: Create InstaFace, an application to manage social networks. A social network is a set of users, some of whom are friends. You will keep track of the users and allow users to add friends to their social network.

What is provided

Several Python files are provided for you. Don't start from scratch. Leverage these files, which contain some code.
Data files for the social network.

Testing (25 pts)

Before you start implementing, we want to make sure that you know that you need to TEST! The points for testing have been separated out explicitly from the other code implementation to show testing's importance.

Test each class in its test function before moving on to the user interface.

Writing tests helps you isolate problems and debug more easily. If you were to find a problem when you use the user interface, you won't know if there is a problem with your class or with the user interface's use of the class.

Best practices:

Implement (i.e., override) the constructor and string representation method for each class.
Programmatically test the string representation.
Implement another method and test it.
Continue in this way. You'll need to adapt, depending on the purpose of the methods.

If you ask for help and have not sufficiently tested the other methods you already wrote, we will not help until after you have tested and (perhaps) debugged other methods. Your programs are becoming larger, more complex, and more difficult to debug if you don't test each part, individually, to make sure that they are all working.

Output

Save the output from executing your tests for each class in an appropropriately named file, e.g., person.out

Test Data

I have provided a number of test files for the social network that should be in the data directory of your lab10 directory.

The files are named such that you'll know which is the "people" file and which is the "connections" file. For example, the smallest social network is created from default.txt, which contains the people, and default_connections.txt, which contains the connections.

(simple.txt and simple_connections.txt are copies of the respective default files, in case the default files are corrupted.)

Organization

Each class should be in its own module. The driver/UI program will import the SocialNetwork class, and the SocialNetwork will import the Person class. Edit the files that you copied during the Set Up step.

Implementing the Classes

Now that you have all of that background, you're ready to start programming!

Class: Person (20)

This class represents an individual in a social network. You'll need to use this class in your other classes.

Data:

user id - string
name - string
friends - a list of Person objects

Functionality:

constructor, which takes as a parameter the userid, which is a string. (What should the other data "start out" as? We've done something similar before--where we don't pass in all the initial data for the object--for example with the DataFrequency class. There is a reason I don't want you to pass in any other information; trust me. :) )
string representation -- returns a string in the form: userid: Name has num friends.
accessors/getters for the data, specifically methods that get

userid
name
friends
number of friends

a "set"ter to update a person's name. (You should not allow a change in userid because that will affect the SocialNetwork class adversely, and you don't want that.)
add a friend, which takes as a parameter a Person object.

Class: Social Network (54)

The provided template includes the method headers, doc strings, and placeholders for the method body. The placeholders should be removed after you've implemented the method. An overview of the methods are described below, with links to more detailed descriptions of the more complex methods.

Implement a few methods and then start testing. If you wait to test, you will make similar mistakes in multiple methods.

Data:

the people in the social network, specifically a dictionary that maps a user id to the appropriate Person object

Functionality:

constructor, which takes no parameters. What should happen within the constructor?
string representation - already implemented; however, requires getPeople() method to be implemented. Wait to test this method until after getPeople() is implemented.
hasUserID(userid) determines if a user id is already in use, i.e., returns True iff the given user id is already used by a person in the social network.
addPerson(person) add a new person to the social network. The parameter should be a Person object. Returns True if person was successfully added to the social network; otherwise, returns False.
Consider: What should happen if you try to add a Person who has the same user id as a Person who is already in the network? You shouldn't allow that because you wouldn't want a new user to take someone else's username. In other words, that person would not be successfully added to the social network.
getters/accessors for data, specifically

getPerson(userid) - get a specific Person in the network, using his/her userid
getPeople() - get the people in the network (a list of Person objects)
getUserIDs() - get the list of user ids of people in the network (a list of str objects)

addConnection(userid1, userid2) - add a new connection to the network. Parameters should be two user ids, which are strings. After this method executes, the two Persons with those user ids should be each other's friend
display - a "pretty" way to display the social network. (Note that this is different than the __str__ method because accumulating everything into a string is more difficult than just printing it out in a formatted way. Also, we may not want to create such a big string every time we print the social network.) (See below for more information)
addPeople(filename) - add people to the network, from a file (See below for more information)
addConnections(filename) - add connections to the network, from a file (See below for more information)
exportPeople(outname) - exporting the people in the social network to a file in the appropriate format (See below for more information)
exportConnections(outname) - exporting the connections between people in the social network to a file in the appropriate format (This method is provided for you. See below for more information)

The more complex methods are described in more detail below:

String Representation

Already implemented, but requires other methods to be implemented. The string you create should represent the SocialNetwork but does not need to look as "pretty" as the display method, described later. In the given implementation, the string representation contains all the Persons in the social network. (You may want to have some order for the Persons so that it's easier to find them.)

Displaying the Social Network

Display the people in the network in a pretty, sorted-by-id way. For example, for the Hollywood social network:

ID            Name                           Num Friends
--------------------------------------------------------
adamsa        Amy Adams                                3
affleckb      Ben Affleck                              8
cavillh       Henry Cavill                             6
fisherr       Ray Fisher                               9
gadotg        Gal Gadot                                8
hemsworthc    Chris Hemsworth                          7
jacksons      Samuel L. Jackson                        8
johanssons    Scarlett Johansson                       5
larsonb       Brie Larson                              5
momoaj        Jason Momoa                              5

The output above doesn't always render correctly in the browser because "ff" in Affleck gets rendered as one character rather than two.

Adding People to the Network, from a File

See the Lab 10 Slides for the algorithm.

This method will take as input the name of a file and process the file, which contains people that should be added to the social network. (Note that the people do not have friends yet.) To make your code simpler, leverage a method you already wrote.

The format of the file is below:

num_of_users
user_id
name
user_id
name
...

Adding Connections to the Network, from a File

See the Lab 10 Slides for the algorithm.

This method will take as input the name of a file and process the file, which contains the connections between people in the social network. Each line of the file contains two ids and represents the people with those ids are friends.

The format of the file is below:

user_id user_id
user_id user_id
...

Exporting the people to a file

After updating your social network, you may want to save the network to a file so that you can use it later. There are two parts to the network: the people/users and the connections between the people.

This method should write the people in the social network to a file, named by the parameter to this method. The format of the file is as seen above. Essentially, you want to do the opposite of your method that reads in the people from the file.

A good test of this function is to write out the social network (that you did not update) to another file and then check if the files match.

Exporting the connections to a file

This method handles writing the connections to a file. If you're not using the provided template, copy this method from the template. Note the assumptions about the method names. You may need to edit this method to match your API.

Objective: Using the Classes via a User Interface Program - InstaFace (16)

This program maintains a SocialNetwork object and provides an interface for users to manage the social network. If you developed the Person and SocialNetwork classes correctly, the majority of this program should be getting input from the user and calling Person and SocialNetwork methods.

The bulk of the code has been written for you and is in the instaface.py file. If you're having issues with the user interface, make sure that the given program calls the correct methods, as named in your class files.

Part 0: Reading in Your Social Network (3)

Your program should allow the user to enter the names of the people file and the connections file as command-line arguments (see the lab slides). The program should call the appropriate methods to read those files to initialize the social network. If the user does not provide command-line arguments, the program will attempt to read the default files, data/default.txt and data/default_connections.txt.

You must test command-line arguments from the terminal. If you use IDLE, you'll always use the defaults.

For example, in a terminal, navigate to your cs111/lab10 directory and run: python instaface.py data/hollywood.txt data/hollywood_connections.txt

Part 1: Interactions with the User (10)

Most of the interactions with the user are implemented for you. You are responsible for implementing the following interactions:

Viewing a person's information:

Which option do you want? v

What is the id of the person you want to view? doej
doej: Jane Doe has 2 friends

Which option do you want? v

What is the id of the person you want to view? a
There is no person with id a

Adding a user and displaying the updated network:

Which option do you want? u

What is the id of the user to add? doej
That user name is already taken

What is the id of the user to add? ht8
What is the name of the user to add? Henry the Eighth

Henry the Eighth has been added to the network

********************************************************************************
Select one of the following options:
        (D)isplay the social network
        (V)iew a person in the social network
        Add (P)eople to the social network from a file
        Add (C)onnections to the social network from a file
        Add a (U)ser to the social network
        Add a pair of (F)riends to the social network
        E(X)port the social network
        (Q)uit the program
Which option do you want? d

ID         Name                           Num Friends
-----------------------------------------------------
astleyr    Rick Astley                              1
doej       Jane Doe                                 2
ht8        Henry the Eighth                         0
schmoj     Joe Schmo                                1

Part 2: Storing the Social Network Before Quitting (3)

Before exiting the program when the user selects the quit option, you should save the social network to the files specified on the command-line/the default files, as appropriate.

Output from InstaFace

Run InstaFace in Idle (which means that it will not test your use of command-line arguments--I will test that functionality) and save the output, as usual, in an appropriately named file. Make sure you demonstrate the error handling abilities of your code. This is your grand finale! Show me what you got!

Extra Credit

Additional Functionality (up to 12 pts)

We discussed as a class some additional functionality that your classes may have. After you have completed the required functionality, you can add more functionality. (When implementing, consider which class should implement this functionality?) Some of suggestions include

Checking if another Person is a friend
Determining who has the most friends
Determining the number of common friends between two Persons
Removing friends/people -- needs to be implemented based on the userids

Searching by name will wait until Lab 11.

More points will be awarded for completely implemented and well-tested functionality (e.g., integrated into Person, SocialNetwork, and instaface) rather than implementing a lot of functionality.

Finishing up: What to turn in for this lab

Save paper: Make sure you don't have any data files (e.g., outputs from the exported people files) in the lab10 directory. Those files should be in your data directory. Also, make sure there aren't any backup files (files whose names end in ~).

Note that each command links to a page with more information about using the command.

Create the printable lab assignment, using the createPrintableLab command.
View your file using the evince command.
Check that the PDF contains all (and only) the necessary files.
Print the file from evince. You can print to other printers if there are issues with the computer science printers (which do not cost you anything to print computer science work).
Submit your lab directory into your turnin directory.
Log out of your machine when you are done.

Labs are due at the beginning of Friday's class. The electronic version should be in the turnin directory before class on Friday.

Ask well before the deadline if you need help turning in your assignment!

Grading (115 pts)

Python programs: 115 pts; see above for breakdown