Support for Notebook Introspection and Setup

AUTHORS:

  • William Stein (much of this code is from IPython).
  • Nick Alexander
class sagenb.misc.support.AutomaticVariable

Bases: sage.symbolic.expression.Expression

An automatically created symbolic variable with an additional __call__() method designed so that doing self(foo,...) results in foo.self(...).

sagenb.misc.support.automatic_name_eval(s, globals, max_names=10000)

Exec the string s in the scope of the globals dictionary, and if any NameErrors are raised, try to fix them by defining the variable that caused the error to be raised, then eval again. Try up to max_names times.

INPUT:

  • s – a string
  • globals – a dictionary
  • max_names – a positive integer (default: 10000)
sagenb.misc.support.automatic_name_filter(s)

Wrap the string s in a call that will cause evaluation of s to automatically create undefined variable names.

INPUT:

  • s – a string

OUTPUT:

  • a string
sagenb.misc.support.automatic_names(state=None)

Turn automatic creation of variables and functional calling of methods on or off. Returns the current state if no argument is given.

This ONLY works in the Sage notebook. It is not supported on the command line.

INPUT:

  • state – a boolean (default: None); whether to turn automatic variable creation and functional calling on or off

OUTPUT:

  • a boolean, if state is None; otherwise, None

EXAMPLES:

sage: automatic_names(True)      # not tested
sage: x + y + z                  # not tested
x + y + z

Here, trig_expand, y, and theta are all automatically created:

sage: trig_expand((2*x + 4*y + sin(2*theta))^2)   # not tested
4*(sin(theta)*cos(theta) + x + 2*y)^2

IMPLEMENTATION: Here’s how this works, internally. We define an AutomaticVariable class derived from Expression. An instance of AutomaticVariable is a specific symbolic variable, but with a special __call__() method. We overload the call method so that foo(bar, ...) gets transformed to bar.foo(...). At the same time, we still want expressions like f^2 - b to work, i.e., we don’t want to have to figure out whether a name appearing in a NameError is meant to be a symbolic variable or a function name. Instead, we just make an object that is both!

This entire approach is very simple—we do absolutely no parsing of the actual input. The actual real work amounts to only a few lines of code. The primary catch to this approach is that if you evaluate a big block of code in the notebook, and the first few lines take a long time, and the next few lines define 10 new variables, the slow first few lines will be evaluated 10 times. Of course, the advantage of this approach is that even very subtle code that might inject surprisingly named variables into the namespace will just work correctly, which would be impossible to guarantee with static parsing, no matter how sophisticated it is. Finally, given the target audience: people wanting to simplify use of Sage for Calculus for undergrads, I think this is an acceptable tradeoff, especially given that this implementation is so simple.

sagenb.misc.support.completions(s, globs, format=False, width=90, system='None')

Return a list of completions in the given context.

INPUT:

  • globs - a string:object dictionary; context in which to search for completions, e.g., globals()
  • format - a bool (default: False); whether to tabulate the list
  • width - an int; character width of the table
  • system - a string (default: ‘None’); system prefix for the completions

OUTPUT:

  • a list of strings, if format is False, or a string
sagenb.misc.support.cython_import(filename, verbose=False, compile_message=False, use_cache=False, create_local_c_file=True)

Compile a file containing Cython code, then import and return the module. Raises an ImportError if anything goes wrong.

INPUT:

  • filename - a string; name of a file that contains Cython code

OUTPUT:

  • the module that contains the compiled Cython code.
sagenb.misc.support.cython_import_all(filename, globals, verbose=False, compile_message=False, use_cache=False, create_local_c_file=True)

Imports all non-private (i.e., not beginning with an underscore) attributes of the specified Cython module into the given context. This is similar to:

from module import *

Raises an ImportError exception if anything goes wrong.

INPUT:

  • filename - a string; name of a file that contains Cython code
sagenb.misc.support.do_preparse()

Return True if the preparser is set to on, and False otherwise.

sagenb.misc.support.docstring(obj_name, globs, system='sage')

Format an object’s docstring to process and display in the Sage notebook.

INPUT:

  • obj_name - a string; a name of an object
  • globs - a string:object dictionary; a context in which to evaluate obj_name
  • system - a string (default: ‘sage’); the system to which to confine the search

OUTPUT:

  • a string containing the object’s file, type, definition, and docstring or a message stating the object is not defined

AUTHORS:

  • William Stein: partly taken from IPython for use in Sage
  • Nick Alexander: extensions
sagenb.misc.support.get_rightmost_identifier(s)
sagenb.misc.support.help(obj)

Display HTML help for obj, a Python object, module, etc. This help is often more extensive than that given by ‘obj?’. This function does not return a value — it prints HTML as a side effect.

Note

This a wrapper around the built-in help. If formats the output as HTML without word wrap, which looks better in the notebook.

INPUT:

  • obj - a Python object, module, etc.
sagenb.misc.support.html_markup(s)
sagenb.misc.support.init(object_directory=None, globs={})

Initialize Sage for use with the web notebook interface.

sagenb.misc.support.preparse_worksheet_cell(s, globals)

Preparse the contents of a worksheet cell in the notebook, respecting the user using preparser(False) to turn off the preparser. This function calls preparse_file() which also reloads attached files. It also does displayhook formatting by calling the displayhook_hack() function.

INPUT:

  • s - a string containing code
  • globals - a string:object dictionary; passed directly to preparse_file()

OUTPUT:

  • a string
sagenb.misc.support.setup_systems(globs)
sagenb.misc.support.source_code(s, globs, system='sage')

Format an object’s source code to process and display in the Sage notebook.

INPUT:

  • s - a string; a name of an object
  • globs - a string:object dictionary; a context in which to evaluate s
  • system - a string (default: ‘sage’); the system to which to confine the search

OUTPUT:

  • a string containing the object’s file, starting line number, and source code

AUTHORS:

  • William Stein: partly taken from IPython for use in Sage
  • Nick Alexander: extensions
sagenb.misc.support.syseval(system, cmd, dir=None)

Evaluate an input with a “system” object that can evaluate inputs (e.g., python, gap).

INPUT:

  • system - an object with an eval method that takes an input
  • cmd - a string input
  • sage_globals - a string:object dictionary
  • dir - a string (default: None); an optional directory to change to before calling system.eval()

OUTPUT:

  • system.eval()‘s output

EXAMPLES:

sage: from sage.misc.python import python
sage: sagenb.misc.support.syseval(python, '2+4//3')
3
''
sage: sagenb.misc.support.syseval(python, 'import os; os.chdir(".")')
''
sage: sagenb.misc.support.syseval(python, 'import os; os.chdir(1,2,3)')
Traceback (most recent call last):
...
TypeError: chdir() takes exactly 1 argument (3 given)
sage: sagenb.misc.support.syseval(gap, "2+3")
'5'
sagenb.misc.support.tabulate(v, width=90, ncols=3)