1 #!/usr/bin/python

     2 #

     3 # Copyright 2007 Google Inc.

     4 #

     5 # Licensed under the Apache License, Version 2.0 (the "License");

     6 # you may not use this file except in compliance with the License.

     7 # You may obtain a copy of the License at

     8 #

     9 #      http://www.apache.org/licenses/LICENSE-2.0

    10 #

    11 # Unless required by applicable law or agreed to in writing, software

    12 # distributed under the License is distributed on an "AS IS" BASIS,

    13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    14 # See the License for the specific language governing permissions and

    15 # limitations under the License.

    16 

    17 """

    18 An interactive, stateful AJAX shell that runs Python code on the server.

    19 

    20 Part of http://code.google.com/p/google-app-engine-samples/.

    21 

    22 May be run as a standalone app or in an existing app as an admin-only handler.

    23 Can be used for system administration tasks, as an interactive way to try out

    24 APIs, or as a debugging aid during development.

    25 

    26 The logging, os, sys, db, and users modules are imported automatically.

    27 

    28 Interpreter state is stored in the datastore so that variables, function

    29 definitions, and other values in the global and local namespaces can be used

    30 across commands.

    31 

    32 To use the shell in your app, copy shell.py, static/*, and templates/* into

    33 your app's source directory. Then, copy the URL handlers from app.yaml into

    34 your app.yaml.

    35 

    36 TODO: unit tests!

    37 """

    38 

    39 import logging

    40 import new

    41 import os

    42 import pickle

    43 import sys

    44 import traceback

    45 import types

    46 import wsgiref.handlers

    47 

    48 from django.template import loader

    49 from google.appengine.api import users

    50 from google.appengine.ext import db

    51 from google.appengine.ext import webapp

    52 from google.appengine.ext.webapp import template

    53 

    54 import gae_django

    55 

    56 

    57 # Set to True if stack traces should be shown in the browser, etc.

    58 _DEBUG = True

    59 

    60 # The entity kind for shell sessions. Feel free to rename to suit your app.

    61 _SESSION_KIND = '_Shell_Session'

    62 

    63 # Types that can't be pickled.

    64 UNPICKLABLE_TYPES = (

    65   types.ModuleType,

    66   types.TypeType,

    67   types.ClassType,

    68   types.FunctionType,

    69   )

    70 

    71 # Unpicklable statements to seed new sessions with.

    72 INITIAL_UNPICKLABLES = [

    73   'import logging',

    74   'import os',

    75   'import sys',

    76   'from google.appengine.ext import db',

    77   'from google.appengine.api import users',

    78   ]

    79 

    80 

    81 class ShellSession(db.Model):

    82   """A shell session. Stores the session's globals.

    83 

    84   Each session globals is stored in one of two places:

    85 

    86   If the global is picklable, it's stored in the parallel globals and

    87   global_names list properties. (They're parallel lists to work around the

    88   unfortunate fact that the datastore can't store dictionaries natively.)

    89 

    90   If the global is not picklable (e.g. modules, classes, and functions), or if

    91   it was created by the same statement that created an unpicklable global,

    92   it's not stored directly. Instead, the statement is stored in the

    93   unpicklables list property. On each request, before executing the current

    94   statement, the unpicklable statements are evaluated to recreate the

    95   unpicklable globals.

    96 

    97   The unpicklable_names property stores all of the names of globals that were

    98   added by unpicklable statements. When we pickle and store the globals after

    99   executing a statement, we skip the ones in unpicklable_names.

   100 

   101   Using Text instead of string is an optimization. We don't query on any of

   102   these properties, so they don't need to be indexed.

   103   """

   104   global_names = db.ListProperty(db.Text)

   105   globals = db.ListProperty(db.Blob)

   106   unpicklable_names = db.ListProperty(db.Text)

   107   unpicklables = db.ListProperty(db.Text)

   108 

   109   def set_global(self, name, value):

   110     """Adds a global, or updates it if it already exists.

   111 

   112     Also removes the global from the list of unpicklable names.

   113 

   114     Args:

   115       name: the name of the global to remove

   116       value: any picklable value

   117     """

   118     blob = db.Blob(pickle.dumps(value))

   119 

   120     if name in self.global_names:

   121       index = self.global_names.index(name)

   122       self.globals[index] = blob

   123     else:

   124       self.global_names.append(db.Text(name))

   125       self.globals.append(blob)

   126 

   127     self.remove_unpicklable_name(name)

   128 

   129   def remove_global(self, name):

   130     """Removes a global, if it exists.

   131 

   132     Args:

   133       name: string, the name of the global to remove

   134     """

   135     if name in self.global_names:

   136       index = self.global_names.index(name)

   137       del self.global_names[index]

   138       del self.globals[index]

   139 

   140   def globals_dict(self):

   141     """Returns a dictionary view of the globals.

   142     """

   143     return dict((name, pickle.loads(val))

   144                 for name, val in zip(self.global_names, self.globals))

   145 

   146   def add_unpicklable(self, statement, names):

   147     """Adds a statement and list of names to the unpicklables.

   148 

   149     Also removes the names from the globals.

   150 

   151     Args:

   152       statement: string, the statement that created new unpicklable global(s).

   153       names: list of strings; the names of the globals created by the statement.

   154     """

   155     self.unpicklables.append(db.Text(statement))

   156 

   157     for name in names:

   158       self.remove_global(name)

   159       if name not in self.unpicklable_names:

   160         self.unpicklable_names.append(db.Text(name))

   161 

   162   def remove_unpicklable_name(self, name):

   163     """Removes a name from the list of unpicklable names, if it exists.

   164 

   165     Args:

   166       name: string, the name of the unpicklable global to remove

   167     """

   168     if name in self.unpicklable_names:

   169       self.unpicklable_names.remove(name)

   170 

   171 

   172 class FrontPageHandler(webapp.RequestHandler):

   173   """Creates a new session and renders the shell.html template.

   174   """

   175 

   176   def get(self):

   177     # set up the session. TODO: garbage collect old shell sessions

   178     session_key = self.request.get('session')

   179     if session_key:

   180       session = ShellSession.get(session_key)

   181     else:

   182       # create a new session

   183       session = ShellSession()

   184       session.unpicklables = [db.Text(line) for line in INITIAL_UNPICKLABLES]

   185       session_key = session.put()

   186 

   187     template_file = os.path.join(os.path.dirname(__file__), 'templates',

   188                                  'shell.html')

   189     session_url = '/?session=%s' % session_key

   190     vars = { 'server_software': os.environ['SERVER_SOFTWARE'],

   191              'python_version': sys.version,

   192              'session': str(session_key),

   193              'user': users.get_current_user(),

   194              'login_url': users.create_login_url(session_url),

   195              'logout_url': users.create_logout_url(session_url),

   196              }

   197     

   198     rendered = loader.render_to_string('shell.html', dictionary=vars)

   199     # rendered = webapp.template.render(template_file, vars, debug=_DEBUG)

   200     self.response.out.write(rendered)

   201 

   202 

   203 class StatementHandler(webapp.RequestHandler):

   204   """Evaluates a python statement in a given session and returns the result.

   205   """

   206 

   207   def get(self):

   208     self.response.headers['Content-Type'] = 'text/plain'

   209 

   210     # extract the statement to be run

   211     statement = self.request.get('statement')

   212     if not statement:

   213       return

   214 

   215     # the python compiler doesn't like network line endings

   216     statement = statement.replace('\r\n', '\n')

   217 

   218     # add a couple newlines at the end of the statement. this makes

   219     # single-line expressions such as 'class Foo: pass' evaluate happily.

   220     statement += '\n\n'

   221 

   222     # log and compile the statement up front

   223     try:

   224       logging.info('Compiling and evaluating:\n%s' % statement)

   225       compiled = compile(statement, '<string>', 'single')

   226     except:

   227       self.response.out.write(traceback.format_exc())

   228       return

   229 

   230     # create a dedicated module to be used as this statement's __main__

   231     statement_module = new.module('__main__')

   232 

   233     # use this request's __builtin__, since it changes on each request.

   234     # this is needed for import statements, among other things.

   235     import __builtin__

   236     statement_module.__builtins__ = __builtin__

   237 

   238     # load the session from the datastore

   239     session = ShellSession.get(self.request.get('session'))

   240 

   241     # swap in our custom module for __main__. then unpickle the session

   242     # globals, run the statement, and re-pickle the session globals, all

   243     # inside it.

   244     old_main = sys.modules.get('__main__')

   245     try:

   246       sys.modules['__main__'] = statement_module

   247       statement_module.__name__ = '__main__'

   248 

   249       # re-evaluate the unpicklables

   250       for code in session.unpicklables:

   251         exec code in statement_module.__dict__

   252 

   253       # re-initialize the globals

   254       for name, val in session.globals_dict().items():

   255         try:

   256           statement_module.__dict__[name] = val

   257         except:

   258           msg = 'Dropping %s since it could not be unpickled.\n' % name

   259           self.response.out.write(msg)

   260           logging.warning(msg + traceback.format_exc())

   261           session.remove_global(name)

   262 

   263       # run!

   264       old_globals = dict(statement_module.__dict__)

   265       try:

   266         old_stdout = sys.stdout

   267         old_stderr = sys.stderr

   268         try:

   269           sys.stdout = self.response.out

   270           sys.stderr = self.response.out

   271           exec compiled in statement_module.__dict__

   272         finally:

   273           sys.stdout = old_stdout

   274           sys.stderr = old_stderr

   275       except:

   276         self.response.out.write(traceback.format_exc())

   277         return

   278 

   279       # extract the new globals that this statement added

   280       new_globals = {}

   281       for name, val in statement_module.__dict__.items():

   282         if name not in old_globals or val != old_globals[name]:

   283           new_globals[name] = val

   284 

   285       if True in [isinstance(val, UNPICKLABLE_TYPES)

   286                   for val in new_globals.values()]:

   287         # this statement added an unpicklable global. store the statement and

   288         # the names of all of the globals it added in the unpicklables.

   289         session.add_unpicklable(statement, new_globals.keys())

   290         logging.debug('Storing this statement as an unpicklable.')

   291 

   292       else:

   293         # this statement didn't add any unpicklables. pickle and store the

   294         # new globals back into the datastore.

   295         for name, val in new_globals.items():

   296           if not name.startswith('__'):

   297             session.set_global(name, val)

   298 

   299     finally:

   300       sys.modules['__main__'] = old_main

   301 

   302     session.put()

   303 

   304 

   305 def main():

   306   """Main program.

   307   """

   308   

   309   application = webapp.WSGIApplication(

   310     [('/admin/shell', FrontPageHandler),

   311      ('/admin/shell/shell.do', StatementHandler)], debug=_DEBUG)

   312   wsgiref.handlers.CGIHandler().run(application)

   313 

   314 

   315 if __name__ == '__main__':

   316   main()