Maximizing grad student happiness

A local university's graduate school has a field placement that's a required component for graduation. Each student works in the field (something like a residency for medical students) for one year in addition to completing their course work.

The process of matching students with placement locations is called the match. The various placement agencies work with the university to establish field instructors and placement slots. An individual agency can have slots for one or more students. Students then indicate their first, second and third choices for placements. The university then tries to accommodate the students wishes to the extent possible. In the past this had been a manual process, but I wrote a Python program to automate this matching process and attempt to maximize collective student happiness.

The inputs

There are three input files. The first is the list of weights for the happiness for first, second, third and lower choices. The second is a list and count of placements, and the third is a list of students and their choices. There are guaranteed to always be more placement slots than students.

weights.txt

# this file contains the weights for first, second, third, and
# lower choices. Weights must be monotonically nondecreasing
# (that is, each number must be greater than or equal to the
# number on the line above)
0
1
3
5


placements.txt

# number, name, slots
1,Agency A,3
2,Agency B,1
3,Agency C,1
4,Agency D,1
5,Agency E,2


students.txt

# comment lines begin with a # in the first column
# name, first, second, third
Annabelle,1,9,9
Margaret,1,9,3
Edward,2,9,1
Catherine,2,4,1
Marie,1,3,5
Katie,4,5,3
Michael,4,5,3
Justin,9,1,9
Jennifer,9,5,4


The program

The program reads in all three of the input files and attempts to match each student to a placement. In the first pass, the program simply assigns each student to his or her first choice placement unless there are no slots left, in which case it assigns the student to a second pl

Docstrings

The docstrings don't go above the functions, and they don't use the pound sign. They use triple quotes """ Something """ So:

# reads in a file containing student names and preferences
def read_students(filename):

Becomes:

def read_students(filename):
"""Reads in a file containing student names and preferences"""

(Note you can access __doc__ with the latter, but not the former.)

Unnecessary parenthesis

The parenthesis here, for instance:

if (line[0] != '#'):

Are unneeded. Just replace it with:

if line[0] != '#':

This is favorable when programming in Python. (There are other instances where this occurs).

add_student

I wouldn't return False. What if the data is corrupt and student is good? Your code doesn't handle this now anyway, but if you get an invalid student you would like to know the difference between an invalid student, and not being able to add because of space. I would make different exceptions for these.

main is also a sort of a thing in Python too

This:

match("weights.txt", "placements.txt", "students.txt")

Should be wrapped in

if __name__ == "__main__":
    match("weights.txt", "placements.txt", "students.txt")

See this for more information.

print_org

There are no print calls in print_org, maybe change the name to get_org or format_org?

More PEP 8.

pylint complains when there aren't two newlines between functions (unless they are all class methods.) Maybe this is a pylint only thing but I would put two newlines between your methods.

StackExchange Code Review Q#151164, answer score: 3