# Support for Notebook Introspection and Setup

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 `NameError`s 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

  TESTS:

  Check that Trac 10860 is fixed and we can handle Unicode help strings in the notebook, see also Trac 26906:

      sage: from sagenb.misc.support import init, docstring
      sage: init()
      sage: D = docstring("r.lm", globs=globals())

`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.

  TESTS:

      sage: import numpy.linalg
      sage: current_dir = os.getcwd()
      sage: os.chdir(tmp_dir('server_doctest'))
      sage: sagenb.misc.support.help(numpy.linalg.norm)
      <html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">
      &nbsp;&nbsp;&nbsp;<a target='_new' href='cell://docs-....html'>Click to open help window</a>&nbsp;&nbsp;&nbsp;
      <br></font></tr></td></table></html>
      sage: os.chdir(current_dir)

`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)