added a bunch of files

Author: Philip Guo

README

@@ -0,0 +1,106 @@
+Online Python Tutor
+Copyright (C) 2010 Philip J. Guo ([email protected])
+https://github.com/pgbovine/OnlinePythonTutor/
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+======
+Introduction:
+
+The Online Python Tutor is a web application where you can type Python
+scripts directly in your web browser, execute those scripts, and
+single-step FORWARDS AND BACKWARDS through execution in order to view
+the state of run-time data.
+
+Using this application, teachers and students can write small Python
+code snippets together and see what happens to the data structures when
+the code gets executed.
+
+---
+
+Try it out live at: http://people.csail.mit.edu/pgbovine/python/
+
+---
+Original vision (from January 2010):
+
+I want to create a web-based interactive learning platform for students
+to explore programming.  I envision an HTML UI where a student can enter
+in code and then single-step through it and see how the data structures
+change during execution.
+
+I realized that for the small programs that students write, it might be
+possible to simply LOG all execution (and data structures) and then we
+can simply play it back with single-step forwards and also BACKWARDS
+
+After all, we don't need students to be able to interactive probe and
+make changes in the middle of execution, which is the only value-added
+of a REAL debugger.
+
+What kinds of things do we want to log?
+
+  On the execution of each line, log:
+    - the line number just executed
+    - all data created by the program
+
+  Also log calls and returns of a student's function 
+  (NOT library functions)
+
+We can use the Python JSON module to encode data structures in JSON and
+send it to the client's web browser
+
+The PDB debugger (Lib/pdb.py) is written in pure Python:
+  http://docs.python.org/library/pdb.html
+  - the bdb debugger framework is the C module that pdb calls
+    http://docs.python.org/library/bdb.html
+
+---
+
+Informal system architecture overview --- sent in an email on 2010-09-05
+
+'''
+i'll give you a bit of background on the architecture of the system:
+
+1.) The front-end is HTML/javascript (using the jQuery library) ... it's
+responsible for the input text box, submitting the Python code (as
+plaintext) to the backend, receiving an execution trace from the
+backend, and then rendering that trace as data structure visualizations.
+all the front-end code is already publicly available in these 5 files:
+
+http://people.csail.mit.edu/pgbovine/python/index.html
+http://people.csail.mit.edu/pgbovine/python/jquery-1.3.2.min.js
+http://people.csail.mit.edu/pgbovine/python/jquery.textarea.js
+http://people.csail.mit.edu/pgbovine/python/edu-python.js
+http://people.csail.mit.edu/pgbovine/python/edu-python.css
+
+
+2.) The back-end is a server-side app that takes Python script source
+code as input, executes the entire script (up to 100 executed lines, to
+prevent infinite loops), and collects a full trace of all variable
+values after each line is executed.  It then sends that trace to the
+front-end in an encoded JSON format.  The front-end then parses that
+trace, which is how it's able to single-step forwards AND backwards
+through execution.
+
+The back-end currently runs on my server, and I think the most
+convenient thing to do right now is to simply invoke it as a web
+service.  This is the URL:
+
+http://people.csail.mit.edu/pgbovine/python/cgi-bin/web_exec.py
+
+and it expects only ONE following parameter to be passed in via POST.
+that parameter is called 'user_script', and it's a string that contains
+the text of the script to be executed.  so the interface is pretty
+simple ;)
+'''
+

TODO

@@ -0,0 +1,207 @@
+A disorganized collection of TODOs, bug reports, and suggestions from friends
+---
+
+Ideas for programming tutorials
+  - Could do a track on more advanced Python concepts for people who are
+    already pretty comfortable with programming ... an intro to Python
+    for programmers
+
+
+Don't display boilerplate code when classes are being initialized
+
+
+Rob Miller's suggestions for handling aliasing:
+
+'''
+Incidentally, for the aliasing example, it might help if you strive to
+have one object be the "official" one, in a sense, and make the aliases
+to it look different.  For example, the x list would be displayed
+normally, but the y list might be displayed faded out (with a little
+note that says "this is the same object as x above").  Mousing over the
+x list or y list might highlight its aliases.
+
+That would reinforce the fact that there's only one object in memory.
+We usually do that on the blackboard -- draw only one object, and have
+arrows from x and y pointing to that single object.
+'''
+
+
+Hubert's suggestions for permalinks:
+'''
+Hubert: 1) It would be cool to have the ability to link directly to an
+execution point, so that when I send you a link, you could see the code
+I'd written and the point in execution that I want to discuss.
+
+me: good suggestion.  that also requires me to save your code in
+something other than a regular POST variable, which i'm not doing right
+now.  then i could send links of the following form:
+
+  http://python.pgrind.com/code_id=20#4 (for line 4 of code snippet 20)
+
+Hubert: yup, yeah the problem lies in storing the code, which brings in
+a whole can of worms.  but suppose you did, consider a RESTful approach
+(which I am drilling into deeply, hence it's on my mind):
+
+http://python.pgrind.com/pg/code/20#4
+
+...quite easy to do and manage in a framework like Django.
+'''
+
+
+Cory: 'Might be nice to be able to automatically jump to particular step
+# rather than just inc/decrement and jump to ends, particular if the
+number of steps executed is significant.'
+
+
+Maybe integrate in this snazzy code EditArea, if it doesn't look too ugly:
+  (ugh kinda cheesy tho)
+  http://www.cdolivet.com/index.php?page=editArea&sess=3a3d89b7ef37aa5f74d6d4682aeda876
+
+
+Deployment on Google App Engine for scalability
+  http://code.google.com/appengine/docs/python/runtime.html
+  - the main issue is whether their restricted Python will allow us to
+    run 'import bdb' and other necessary modules
+  - could try to get Sal Khan to pay for my hosting if I host it
+    alongside Khan Academy
+  - could store analytics and user data in Google's db
+
+
+Related work:
+  - PyWhip: http://pywhip.appspot.com/
+    - also powered by Google App Engine
+  - Crunchy: http://code.google.com/p/crunchy/
+
+
+From Hubert, regarding rendering linked structures vs. using
+containment:
+'''
+i totally agree with the sentiment that if you're not ever going to use it (for
+any binding of "it"), don't add the complexity.  i sympathize with the laziness
+argument, that it's easy to do HTML tables than arrowheads, but if you change
+your mind, consider using HTML5's canvas -- many browsers support it.
+regarding the aliasing, from an epistemological standpoint, do you foresee that
+you'll have to cover the difference between passing by reference vs by value?
+this was a rather big stumbling block for me when learning Python, having come
+from C where the different passing styles are syntactically explicit.  i
+recognize that the current visualizations don't depict argument passing, so it
+may be moot.  but one cheap trick you can explore is to "color" identical
+objects with the same color, so that if a data structure appears in multiple
+places, it is colored differently, if they are indeed different objects.
+'''
+
+---
+2010-09-05
+
+From an email from Peter Wentworth ([email protected])
+
+'''
+I'd like to see the heap explicitly represented, so that mutable
+structures like lists are created in the heap rather than "in the stack
+frame".  Passing a list as an argument then becomes "pass the
+reference".
+ 
+I appreciate that you do have the id tags to indicate which are the
+aliases, but I think the instructional value would be even more
+compelling to see some pointers referencing the same underlying object.
+'''
+
+---
+From Hacker News feedback:
+
+- support for raw_input() sounds like something reasonable to include,
+  though, since it could simply pop up a text box and ask the user to
+  input a string e.g., javascript:alert("hello, " + prompt("what is your
+  name?"))
+
+---
+2010-09-29
+
+Chas Leichner ([email protected]) emailed me to show me his related
+project:
+
+  http://www.youtube.com/watch?v=ZiS4MZF5eDQ
+  http://code.google.com/p/idlecarpentry/
+
+He had an interesting idea of annotating lines of code with special
+comments, and those comments would display when those lines were being
+executed.  That way, you can have sorta like 'literate programming
+tutorials' that intermix code and comments.  I could think about
+implementing something similar within my Online Python Tutor.
+
+e.g.,
+
+#> declare a variable
+x = 5
+
+#> an if statement tests a condition
+if x < 5:
+  y = x + 5
+else:
+  y = x - 5
+
+the appropriate annotations would display when you stepped through the
+line of code immediately below each annotation.
+
+---
+2011-01-16
+
+Bug report from Peter Wentworth
+
+'''
+I also have what I think is a bug report:   your front-end javascript treats variables with the value None as if they are undefined.  (They are reflected in the trace that we get from the server.)
+ 
+X = 123
+z = 'hello'
+x = None
+y = 123
+ 
+del  y
+print(x)
+print(type(x))
+ 
+---
+I changed your script  - around line 293 of edu-python.js, you have a condition checking for undefined (search for the comment containing “which is OKAY!”).  I just eliminated the check, and can’t figure out which cases I might have broken it for!
+'''
+
+---
+2011-05-23
+
+Bug report from Peter Wentworth
+
+'''
+Hi Philip
+ 
+I hope you are keeping well!  
+ 
+Scripts fail in the visualizer when the user has a variable called “length”, because somehow the front-end jquery is doing something wrong.  It happens both when used as a local or as a global variable.  See my image of what is happening on your site.  (Tried in both Firefox and Internet Explorer).
+ 
+It looks like a jquery bug (I haven’t tried moving to a newer version – I’m using 1.3.2 that I got from your version).
+ 
+The iterators  + lambda functions appear to be misbehaving when varname has the value “length”.
+So I’ve had to rip out the iterators and gone for vanilla javascript loops, which has solved it for me.
+ 
+I’ve done changes similar to this in 4 places in function  updateOutput  in file edu_python.js
+ 
+ 
+//      $.each(curTrace[i].globals, function(varname, val) {
+//        // eliminate duplicates (act as an ordered set)
+//        if ($.inArray(varname, orderedGlobals) == -1) {
+//          orderedGlobals.push(varname);
+//          curGlobalFields[varname] = undefined; // 'unset it'
+//        }
+//      });
+ 
+      for (varname in curTrace[i].globals) {
+          // eliminate duplicates (act as an ordered set)                
+           if ($.inArray(varname, orderedGlobals) == -1) {
+              orderedGlobals.push(varname);
+              curGlobalFields[varname] = undefined; // 'unset it'
+           }
+      }
+ 
+Regards
+ 
+Peter
+'''
+

cgi-bin/.htaccess

@@ -0,0 +1,2 @@
+Options +ExecCGI
+AddHandler cgi-script .py

cgi-bin/create_db.py

@@ -0,0 +1,26 @@
+# Setup sqlite database for optional query logging
+
+from db_common import *
+import os
+
+# the 'post_date' field is stored as an int representing GMT time since
+# the UNIX epoch; to convert to localtime in sqlite, use:
+#   SELECT datetime(1092941466, 'unixepoch', 'localtime'); 
+
+def create_db():
+  assert not os.path.exists(DB_FILE)
+  (con, cur) = db_connect()
+  cur.execute('''CREATE TABLE query_log
+    (id INTEGER PRIMARY KEY,
+     post_date TEXT,
+     ip_addr TEXT,
+     user_agent TEXT,
+     input_script TEXT,
+     had_error INTEGER)''')
+  con.commit()
+  cur.close()
+
+if __name__ == "__main__":
+  create_db()
+  print 'Created', DB_FILE
+

cgi-bin/db_common.py

@@ -0,0 +1,11 @@
+# Setup sqlite database for optional query logging
+
+import sqlite3
+
+DB_FILE = 'edu-python-log.sqlite3'
+
+def db_connect():
+  con = sqlite3.connect(DB_FILE)
+  cur = con.cursor()
+  return (con, cur)
+