Command line

README.md

@@ -1,12 +1,60 @@
 # StudentGroupGenerator
-create random student groups of varying sizes
 
-Input: a list of student names, one student per line
+`StudentGroupGenerator` will shuffle a given student list and create groups of varying sizes (individuals, pairs, or triplets). 
+It can be run either from the command line or from the interpreter/Jupyter Notebook.
 
-Program will shuffle the student list and create groups of varying sizes (individuals, pairs, or triplets). 
+## Usage
 
-If you have student pictures, put them in the photodir directory (or modify the code to a directoy of your own choosing). You can then use the showStudents function to pop up their pictures along with the group names (this function is handy if your students don't know each others' names well yet, where a visual reference might help them find each other more quickly). 
+### From the Command Line
+
+```
+$ python student_group_creator /path/to/my_name_list.txt
+
+GROUP PAIRS:
+
+    ['Full Name One', 'Full Name Two']
+    ['Full Name Three', 'Full Name Four']
+    ['Full Name Five', 'Full Name Six']
+    ['Full Name Seven', 'Full Name Eight']
+
+```
+
+### From the Interpreter
+
+In addition to the path to your list of student names, you must also supply a list specifying how many groups of a certain number you want.
+
+- If you have 10 students and want 5 pairs: `[0, 5]`
+- If you have 10 students and want 3 trios: `[1, 0, 3]`
+
+etc.
+
+
+```
+>>> from student_group_creator import create_groups
+>>> groups = create_groups("/path/to/my_name_list", [0, 4])
+```
+
+**Note:** the total students from each group type needs to equal the total number of students. So if you supply `[1, 0, 3]` you need to have 10 students.
+
+### Other Functionality
+
+- `show_students(groups)` - print the student names in an interpreter
+- `show_students_in_browser(groups)` - print groupings of student names in the browser as an HTML table
+
+## Formatting the Input
+
+You need to supply a list of student names whether you run from the command line or inside of an interpreter. The list should look like so:
+
+```
+Full Name One
+Full Name Two
+Full Name Three
+...
+Full Name N
+```
+
+## Using Photos with Names
+
+If you have student pictures, put them in the `photodir` directory (or modify the code to a directoy of your own choosing). You can then use the `show_students` function to pop up their pictures along with the group names (this function is handy if your students don't know each others' names well yet, where a visual reference might help them find each other more quickly). 
 
-Output:
 
-Student groups can be printed, displayed in inline in an IPython notebook using showStudents(), or displayed on a nicely formatted web page using showStudentsInBrowser().

student_group_creator.py

@@ -1,121 +1,186 @@
 #!/usr/bin/env python
+from __future__ import print_function
+
 import random
-from IPython.display import Image, HTML, display
+from IPython.display import HTML, display
 import webbrowser
 
 
-def showStudents(groups):
-    # make student pictures display in their groups in an IPython notebook
-    # NB: requires that image file names are the same as student names in the input list
-
-    photoDir = './photodir/'
-    #take each group list and parse student names into image file names (strip space, add .jpg)
-    for i in range(0,len(groups)):
-        studentGroup = groups[i]
-        listOfImageNames = [ ]
-        captionNames = ' '
-        for j in range(0,len(studentGroup)):
-            individualName = studentGroup[j]
-            individualName = individualName.replace(" ", "")
-            individualName+='.jpg'
-            fileName = photoDir+individualName
-            listOfImageNames.append(fileName)
-            # we also want the student name captions to be generated automatically from file names
-            if j != len(studentGroup)-1:
-                captionNames += studentGroup[j] + ', '
+def show_students(groups):
+    """Make student pictures display in their groups in an IPython notebook
+    NB: requires that image file names are the same as student names in the
+    input list"""
+    photo_dir = './photodir/'
+    # take each group list and parse student names into image file names
+    # (strip space, add .jpg)
+    for i in range(0, len(groups)):
+        student_group = groups[i]
+        list_of_image_names = []
+        caption_names = ' '
+        for j in range(0, len(student_group)):
+            individual_names = student_group[j]
+            individual_names = individual_names.replace(" ", "")
+            individual_names += '.jpg'
+            file_name = photo_dir + individual_names
+            list_of_image_names.append(file_name)
+            # we also want the student name captions to be generated
+            # automatically from file names
+            if j != len(student_group) - 1:
+                caption_names += student_group[j] + ', '
             else:
-                captionNames += studentGroup[j]
-
-        #display each group member's image with their name
-        preFormatHTMLTags = ["<figure>"]
-        postFormatHTMLTags = ["</figure>"]
-        imageSources = [ "<img style='width: 200px; border: 1px solid black;' src='%s' />"  % str(s) for s in listOfImageNames ]
-        preCaptionsTag = ["<figcaption><h1>"]
-        captionMid = [ captionNames ]
-        postCaptionsTag = ["</figcaption>"]
-        fullImageDisplayTags = preFormatHTMLTags + imageSources + preCaptionsTag + captionMid + postCaptionsTag + postFormatHTMLTags
-
-        imagesList=' '.join( fullImageDisplayTags )
-        display(HTML(imagesList))
-
-def showStudentsInBrowser(groups):
-    # make student pictures display in their groups in a local browser window
-    # NB: requires that image file names are the same as student names in the input list
-    # default browser is chrome, preferred browser can be set by altering the below
+                caption_names += student_group[j]
+
+        # display each group member's image with their name
+        preformat_html_tags = ["<figure>"]
+        postformat_html_tags = ["</figure>"]
+        image_sources = [
+            "<img style='width: 200px; border: 1px solid black;' src='%s' />" % str(s) for s in list_of_image_names]
+        pre_captions_tag = ["<figcaption><h1>"]
+        caption_mid = [caption_names]
+        post_captions_tag = ["</figcaption>"]
+        full_img_display_tags = preformat_html_tags + image_sources + \
+            pre_captions_tag + caption_mid + \
+            post_captions_tag + postformat_html_tags
+
+        images_list = ' '.join(full_img_display_tags)
+        display(HTML(images_list))
+
+
+def show_students_in_browser(groups):
+    """Make student pictures display in their groups in a local browser window
+    NB: requires that image file names are the same as student names in the input list
+    default browser is chrome, preferred browser can be set by altering the
+    below."""
     browser_path = 'open -a /Applications/Google\ Chrome.app %s'
-    photoDir = './photodir/'
-    outFile = open("groups.html", "w")
-
-    #create html to go before and after code generated for student groups
-    htmlPreamble = "<!DOCTYPE html><html><head><style>table {    font-family: arial, sans-serif;    border-collapse: collapse; } td, th {    border: 1px solid #dddddd;    text-align: center;    padding: 0px;} tr:nth-child(even) {    background-color: #dddddd;}</style></head><body><table>"
-    htmlClosing = "</table></body></html>"
-
-    #take each group list and parse student names into image file names (strip space, add .jpg)
-    outFile.write(htmlPreamble)
-    for i in range(0,len(groups)):
-        studentGroup = groups[i]
-        captionNames = [ ]
-        listOfImageNames = [ ]
-        for j in range(0,len(studentGroup)):
-            individualName = studentGroup[j]
-            individualName = individualName.replace(" ", "")
-            individualName+='.jpg'
-            fileName = photoDir+individualName
-            listOfImageNames.append(fileName)
-            # we also want the student name captions to be generated automatically from file names
-            captionNames.append(studentGroup[j])
-
-        #construct html to display each group member's image with their name
-        preFormatHTMLTags = ["<tr>"]
-        postFormatHTMLTags = ["</tr>"]
-        lineBreak = ["</tr><tr>"]
-        imageSources = [ "<td><img style='width: 200px; border: 1px solid black;' src='%s' /><td>"  % str(s) for s in listOfImageNames ]
-        captionSources = [ "<td><h1> %s </h1><td>"  % str(s) for s in captionNames ]
-        fullImageDisplayTags = preFormatHTMLTags + imageSources + lineBreak + captionSources + postFormatHTMLTags
-        imagesList=' '.join( fullImageDisplayTags )
-        outFile.write(imagesList)
-
-    #replace the below with writing the html file and displaying it in a browser window
-    outFile.write(htmlClosing)
-    outFile.close()
+    photo_dir = './photodir/'
+    outfile = open("groups.html", "w")
+
+    # create html to go before and after code generated for student groups
+    html_preamble = "<!DOCTYPE html><html><head><style>table {    font-family: arial, sans-serif;    border-collapse: collapse; } td, th {    border: 1px solid #dddddd;    text-align: center;    padding: 0px;} tr:nth-child(even) {    background-color: #dddddd;}</style></head><body><table>"
+    html_closing = "</table></body></html>"
+
+    # take each group list and parse student names into image file names
+    # (strip space, add .jpg)
+    outfile.write(html_preamble)
+    for i in range(0, len(groups)):
+        student_group = groups[i]
+        caption_names = []
+        list_of_image_names = []
+        for j in range(0, len(student_group)):
+            individual_names = student_group[j]
+            individual_names = individual_names.replace(" ", "")
+            individual_names += '.jpg'
+            file_name = photo_dir + individual_names
+            list_of_image_names.append(file_name)
+            # we also want the student name captions to be generated
+            # automatically from file names
+            caption_names.append(student_group[j])
+
+        # construct html to display each group member's image with their name
+        preformat_html_tags = ["<tr>"]
+        postformat_html_tags = ["</tr>"]
+        linebreak = ["</tr><tr>"]
+        image_sources = [
+            "<td><img style='width: 200px; border: 1px solid black;' src='%s' /><td>" % str(s) for s in list_of_image_names]
+        caption_sources = ["<td><h1> %s </h1><td>" %
+                           str(s) for s in caption_names]
+        full_img_display_tags = preformat_html_tags + image_sources + \
+            linebreak + caption_sources + postformat_html_tags
+        images_list = ' '.join(full_img_display_tags)
+        outfile.write(images_list)
+
+    # replace the below with writing the html file and displaying it in a
+    # browser window
+    outfile.write(html_closing)
+    outfile.close()
     brwsr = webbrowser.get(browser_path)
     brwsr.open_new('groups.html')
 
-def nameCounter(pars):
-    #Parameters consists of numbers to indicate how many groups of each size should be created.
-    # e.g. [0,8,1] will result in no students in individual groups, 8 pairs of students, and 1 group of 3.
-    totalNames = 0
+
+def name_counter(pars):
+    """Parameters consists of numbers to indicate how many groups of each size should be created.
+    e.g. [0,8,1] will result in no students in individual groups, 8 pairs of
+    students, and 1 group of 3."""
+    total_names = 0
     i = 0
     for item in pars:
         i = i + 1
-        totalNames = totalNames + i*pars[i-1]
-    return totalNames
+        total_names = total_names + i * pars[i - 1]
+    return total_names
+
+
+def get_name_list(student_file):
+    """Read in student names from a file."""
+    student_names = [line.rstrip() for line in open(student_file)]
 
-def createGroups(studentFile, Parameters):
+    return student_names
 
-    listOfGroups = []
 
-    #read in student names from a file
-    studentNames = [line.rstrip() for line in open(studentFile)]
+def create_groups(student_file, parameters):
+    """Create groups of students from a text file of student names."""
+    list_of_groups = []
 
-    #return error if number of students in groups != total number students
-    total = nameCounter(Parameters)
+    # read in student names from a file
+    student_names = get_name_list(student_file)
 
-    if total != len(studentNames):
-        numStudents = len(studentNames)
-        print 'There are ' + str(numStudents) + ' students in total. The total number of students included in groups not equal to total number of students! Check input pars.'
+    # return error if number of students in groups != total number students
+    total = name_counter(parameters)
+
+    if total != len(student_names):
+        num_students = len(student_names)
+        print('There are ' + str(num_students) +
+              ' students in total. The total number of students included in groups not equal to total number of students! Check input pars.')
     else:
-        #shuffle student names and assemble into groups
-        random.shuffle(studentNames)
+        # shuffle student names and assemble into groups
+        random.shuffle(student_names)
         i = 0
         curr_index = 0
         num = 1
-        for item in Parameters:
-            if (item!=0):
-                for i in range(0,item):
-                    temp_group = studentNames[0:num]
-                    listOfGroups.append(temp_group)
-                    studentNames.__delslice__(0,num)
-            num +=1
-
-    return listOfGroups
+        for item in parameters:
+            if (item != 0):
+                for i in range(0, item):
+                    temp_group = student_names[0:num]
+                    list_of_groups.append(temp_group)
+                    student_names.__delslice__(0, num)
+            num += 1
+
+    return list_of_groups
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) > 1:
+        fname = sys.argv[1]
+        namelist = get_name_list(fname)
+
+        if len(namelist) % 2:
+            group_configs = [1, int(len(namelist) / 2)]
+
+        else:
+            group_configs = [0, int(len(namelist) / 2)]
+
+        groups = create_groups(fname, group_configs)
+
+        print("\nGROUP PAIRS:\n")
+        for group in groups:
+            print("\t" + str(group))
+
+        print("\n")
+
+    else:
+        outstr = [
+            "\n              ****************************************\n",
+            "              ****************************************\n",
+            "              **                                    **\n",
+            "              **               ERROR                **\n",
+            "              **                                    **\n",
+            "              ****************************************\n",
+            "              ****************************************\n",
+            "\nThis will not work from the command line without a file ",
+            "containing a list\nof student names.\n\nEach full name should ",
+            "be separated by a new line.\n\nSupply the name of the file ",
+            "containing the list like so:\n\n$ python ",
+            "student_group_creator.py my_name_list.txt\n"
+        ]
+
+        print("".join(outstr))

testinputlist

@@ -6,3 +6,4 @@ Steve BruleGoT
 Steve BruleGramble
 Steve BruleHunk
 Steve BrulePluto
+Steve BruleFoo