# The Sage Notebook

The Sage Notebook

AUTHORS:

- William Stein

class `sagenb.notebook.notebook.``Notebook`(dir, user_manager=None)

  Bases: `object`

  `HISTORY_MAX_OUTPUT` = 460
  `HISTORY_NCOLS` = 90
  `active_worksheets_for`(username)
  `add_to_user_history`(entry, username)
  `change_worksheet_key`(old_key, new_key)
  `change_worksheet_name_to_avoid_collision`(worksheet)

    Change the display name of the worksheet if there is already a worksheet with the same name as this one.

  `color`()

    The default color scheme for the notebook.

  `conf`()
  `copy_worksheet`(ws, owner)
  `create_default_users`(passwd)

    Create the default users for a notebook.

    INPUT:

    - `passwd` - a string

    EXAMPLES:

        sage: from six import iteritems
        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: sorted(list(iteritems(nb.user_manager().users())))
        [('_sage_', _sage_), ('admin', admin), ('guest', guest), ('pub', pub)]
        sage: sorted(list(iteritems(nb.user_manager().passwords()))) #random
        [('_sage_', ''), ('admin', ''), ('guest', ''), ('pub', '')]
        sage: nb.create_default_users('newpassword')
        WARNING: User 'pub' already exists -- and is now being replaced.
        WARNING: User '_sage_' already exists -- and is now being replaced.
        WARNING: User 'guest' already exists -- and is now being replaced.
        WARNING: User 'admin' already exists -- and is now being replaced.
        sage: sorted(list(iteritems(nb.user_manager().passwords()))) #random
        [('_sage_', ''), ('admin', ''), ('guest', ''), ('pub', '')]
        sage: len(list(iteritems(nb.user_manager().passwords())))
        4

  `create_new_worksheet`(worksheet_name, username)
  `create_new_worksheet_from_history`(name, username, maxlen=None)
  `delete`()

    Delete all files related to this notebook.

    This is used for doctesting mainly. This command is obviously VERY dangerous to use on a notebook you actually care about. You could easily lose all data.

    EXAMPLES:

        sage: tmp = tmp_dir(ext='.sagenb')
        sage: nb = sagenb.notebook.notebook.Notebook(tmp)
        sage: sorted(os.listdir(tmp))
        ['home']
        sage: nb.delete()

    Now the directory is gone.:

        sage: os.listdir(tmp)
        Traceback (most recent call last):
        ...
        OSError: [Errno 2] No such file or directory: '...

  `delete_doc_browser_worksheets`()
  `delete_worksheet`(filename)

    Delete the given worksheet and remove its name from the worksheet list. Raise a KeyError, if it is missing.

    INPUT:

    - `filename` - a string
  `deleted_worksheets`()
  `empty_trash`(username)

    Empty the trash for the given user.

    INPUT:

    - `username` - a string

    This empties the trash for the given user and cleans up all files associated with the worksheets that are in the trash.

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.user_manager().add_user('sage','sage','sage@sagemath.org',force=True)
        sage: W = nb.new_worksheet_with_title_from_text('Sage', owner='sage')
        sage: W._notebook = nb
        sage: W.move_to_trash('sage')
        sage: nb.worksheet_names()
        ['sage/0']
        sage: nb.empty_trash('sage')
        sage: nb.worksheet_names()
        []

  `export_worksheet`(worksheet_filename, output_filename, title=None)

    Export a worksheet, creating a sws file on the file system.

    INPUT:

    > - `worksheet_filename` - a string e.g., ‘username/id_number’
    > - `output_filename` - a string, e.g., ‘worksheet.sws’
    > - `title` - title to use for the exported worksheet (if
    >     None, just use current title)

  `get_all_worksheets`()

    We should only call this if the user is admin!

  `get_server`()
  `get_ulimit`()
  `get_worksheet_with_filename`(filename)

    Get the worksheet with the given filename. If there is no such worksheet, raise a `KeyError`.

    INPUT:

    - `filename` - a string

    OUTPUT:

    - a Worksheet instance
  `get_worksheets_with_owner`(owner)
  `get_worksheets_with_viewer`(username)
  `html`(worksheet_filename=None, username='guest', admin=False, do_print=False)

    Return the HTML for a worksheet’s index page.

    INPUT:

    - `worksheet_filename` - a string (default: None)
    - `username` - a string (default: ‘guest’)
    - `admin` - a bool (default: False)

    OUTPUT:

    - a string - the worksheet rendered as HTML

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html(W.filename(), 'admin')
        u'...Test...cell_input...if (e.shiftKey)...state_number...'

  `html_afterpublish_window`(worksheet, username, url, dtime)

    Return HTML for a given worksheet’s post-publication page.

    INPUT:

    - `worksheet` - an instance of Worksheet
    - `username` - a string
    - `url` - a string representing the URL of the published worksheet
    - `dtime` - an instance of time.struct_time representing the publishing time

    OUTPUT:

    - a string - the post-publication page rendered as HTML
  `html_beforepublish_window`(worksheet, username)

    Return HTML for the warning and decision page displayed prior to publishing the given worksheet.

    INPUT:

    - `worksheet` - an instance of Worksheet
    - `username` - a string

    OUTPUT:

    - a string - the pre-publication page rendered as HTML

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html_beforepublish_window(W, 'admin')
        u'...want to publish this worksheet?...re-publish when changes...'

  `html_download_or_delete_datafile`(ws, username, filename)

    Return the HTML for the download or delete datafile page.

    INPUT:

    - `username` - a string
    - `ws` - an instance of Worksheet
    - `filename` - a string; the name of the file

    OUTPUT:

    - a string - the page rendered as HTML

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html_download_or_delete_datafile(W, 'admin', 'bar')
        u'...Data file: bar...DATA is a special variable...uploaded...'

  `html_edit_window`(worksheet, username)

    Return HTML for a window for editing `worksheet`.

    INPUT:

    - `username` - a string containing the username
    - `worksheet` - a Worksheet instance

    OUTPUT:

    - a string - the editing window’s HTML representation

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html_edit_window(W, 'admin')
        u'...textarea class="plaintextedit"...{{{id=1|...//...}}}...'

  `html_plain_text_window`(worksheet, username)

    Return HTML for the window that displays a plain text version of the worksheet.

    INPUT:

    - `worksheet` - a Worksheet instance
    - `username` - a string

    OUTPUT:

    - a string - the plain text window rendered as HTML

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html_plain_text_window(W, 'admin')
        u'...pre class="plaintext"...cell_intext...textfield...'

  `html_share`(worksheet, username)

    Return the HTML for the “share” page of a worksheet.

    INPUT:

    - `username` - a string
    - `worksheet` - an instance of Worksheet

    OUTPUT:

    - string - the share page’s HTML representation

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html_share(W, 'admin')
        u'...currently shared...add or remove collaborators...'

  `html_specific_revision`(username, ws, rev)

    Return the HTML for a specific revision of a worksheet.

    INPUT:

    - `username` - a string
    - `ws` - an instance of Worksheet
    - `rev` - a string containing the key of the revision

    OUTPUT:

    - a string - the revision rendered as HTML
  `html_upload_data_window`(ws, username)

    Return HTML for the “Upload Data” window.

    INPUT:

    - `worksheet` - an instance of Worksheet
    - `username` - a string

    OUTPUT:

    - a string - the HTML representation of the data upload window

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: nb.html_upload_data_window(W, 'admin')
        u'...Upload or Create Data File...Browse...url...name of a new...'

  `html_worksheet_revision_list`(username, worksheet)

    Return HTML for the revision list of a worksheet.

    INPUT:

    - `username` - a string
    - `worksheet` - an instance of Worksheet

    OUTPUT:

    - a string - the HTML for the revision list

    EXAMPLES:

        sage: from sagenb.flask_version import base # random output -- depends on warnings issued by other sage packages
        sage: app = base.create_app(tmp_dir(ext='.sagenb'))
        sage: ctx = app.app_context()
        sage: ctx.push()
        sage: nb = base.notebook
        sage: nb.create_default_users('password')
        sage: W = nb.create_new_worksheet('Test', 'admin')
        sage: W.body()
        u'\n\n{{{id=1|\n\n///\n}}}'
        sage: W.save_snapshot('admin')
        sage: nb.html_worksheet_revision_list('admin', W)
        u'...Revision...Last Edited...ago...'

  `import_worksheet`(filename, owner)

    Import a worksheet with the given `filename` and set its `owner`. If the file extension is not recognized, raise a ValueError.

    INPUT:

    - `filename` - a string
    - `owner` - a string

    OUTPUT:

    - `worksheet` - a newly created Worksheet instance

    EXAMPLES:

    We create a notebook and import a plain text worksheet into it.

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: name = tmp_filename() + '.txt'
        sage: open(name,'w').write('foo\n{{{\n2+3\n}}}')
        sage: W = nb.import_worksheet(name, 'admin')

    W is our newly-created worksheet, with the 2+3 cell in it:

        sage: W.name()
        u'foo'
        sage: W.cell_list()
        [TextCell 0: foo, Cell 1: in=2+3, out=]

  `logout`(username)

    Do not do anything on logout (so far).

    In particular, do NOT stop all `username`’s worksheets!

  `new_id_number`(username)

    Find the next worksheet id for the given user.

  `new_worksheet_process`()

    Return a new worksheet process object with parameters determined by configuration of this notebook server.

  `new_worksheet_with_title_from_text`(text, owner)
  `pretty_print`(username=None)

    The default typeset setting for new worksheets for a given user or the whole notebook (if username is None).

    TODO – only implemented for the notebook right now

  `pub_worksheets`()
  `publish_worksheet`(worksheet, username)

    Publish a user’s worksheet. This creates a new worksheet in the ‘pub’ directory with the same contents as `worksheet`.

    INPUT:

    - `worksheet` - an instance of Worksheet
    - `username` - a string

    OUTPUT:

    - a new or existing published instance of Worksheet

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.load_notebook(tmp_dir(ext='.sagenb'))
        sage: nb.user_manager().add_user('Mark','password','',force=True)
        sage: W = nb.new_worksheet_with_title_from_text('First steps', owner='Mark')
        sage: nb.worksheet_names()
        ['Mark/0']
        sage: nb.create_default_users('password')
        sage: nb.publish_worksheet(nb.get_worksheet_with_filename('Mark/0'), 'Mark')
        pub/0: [Cell 1: in=, out=]
        sage: sorted(nb.worksheet_names())
        ['Mark/0', 'pub/0']

  `quit`()
  `quit_idle_worksheet_processes`()
  `quit_worksheet`(W)
  `readonly_user`(username)

    Returns True if the user is supposed to only be a read-only user.

  `save`()

    Save this notebook server to disk.

  `save_worksheet`(W, conf_only=False)
  `scratch_worksheet`()
  `server_pool`()
  `set_color`(color)
  `set_not_computing`()
  `set_pretty_print`(pretty_print)
  `set_server_pool`(servers)
  `set_ulimit`(ulimit)
  `system`(username=None)

    The default math software system for new worksheets for a given user or the whole notebook (if username is None).

  `system_names`()
  `systems`(username=None)
  `update_worksheet_processes`()
  `upgrade_model`()

    Upgrade the model, if needed.

    - Version 0 (or non-existent model version, which defaults to 0): Original flask notebook
    - Version 1: shared worksheet data cached in the User object
  `user`(username)

    Return an instance of the User class given the `username` of a user in a notebook.

    INPUT:

    - `username` - a string

    OUTPUT:

    - an instance of User

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.user_manager().create_default_users('password')
        sage: nb.user('admin')
        admin
        sage: nb.user('admin').get_email()
        ''
        sage: nb.user('admin').password() #random
        '256$7998210096323979f76e9fedaf1f85bda1561c479ae732f9c1f1abab1291b0b9$373f16b9d5fab80b9a9012af26a6b2d52d92b6d4b64c1836562cbd4264a6e704'

  `user_history`(username)
  `user_history_text`(username, maxlen=None)
  `user_manager`()

    Returns self’s UserManager object.

    EXAMPLES:

        sage: n = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: n.user_manager()
        <sagenb.notebook.user_manager.OpenIDUserManager object at 0x...>

  `users_worksheets`(username)

    Returns all worksheets owned by username

  `users_worksheets_view`(username)

    Returns all worksheets viewable by username

  `valid_login_names`()

    Return a list of users that can log in.

    OUTPUT:

    - a list of strings

    EXAMPLES:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.create_default_users('password')
        sage: nb.valid_login_names()
        ['admin']
        sage: nb.user_manager().add_user('Mark', 'password', '', force=True)
        sage: nb.user_manager().add_user('Sarah', 'password', '', force=True)
        sage: nb.user_manager().add_user('David', 'password', '', force=True)
        sage: sorted(nb.valid_login_names())
        ['David', 'Mark', 'Sarah', 'admin']

  `worksheet`(username, id_number=None)

    Create a new worksheet with given id_number belonging to the user with given username, or return an already existing worksheet. If id_number is None, creates a new worksheet using the next available new id_number for the given user.

    INPUT:

    > - `username` – string
    > - `id_number` - nonnegative integer or None (default)

  `worksheet_list_for_public`(username, sort='last_edited', reverse=False, search=None)
  `worksheet_list_for_user`(user, typ='active', sort='last_edited', reverse=False, search=None)
  `worksheet_names`()

    Return a list of all the names of worksheets in this notebook.

    OUTPUT:

    - a list of strings.

    EXAMPLES:

    We make a new notebook with two users and two worksheets, then list their names:

        sage: nb = sagenb.notebook.notebook.Notebook(tmp_dir(ext='.sagenb'))
        sage: nb.user_manager().add_user('sage','sage','sage@sagemath.org',force=True)
        sage: W = nb.new_worksheet_with_title_from_text('Sage', owner='sage')
        sage: nb.user_manager().add_user('wstein','sage','wstein@sagemath.org',force=True)
        sage: W2 = nb.new_worksheet_with_title_from_text('Elliptic Curves', owner='wstein')
        sage: nb.worksheet_names()
        ['sage/0', 'wstein/0']

class `sagenb.notebook.notebook.``WorksheetDict`(notebook, *args, **kwds)

  Bases: `dict`

`sagenb.notebook.notebook.``load_notebook`(dir, interface=None, port=None, secure=None, user_manager=None)

  Load and return a notebook from a given directory. Create a new one in that directory, if one isn’t already there.

  INPUT:

  - `dir` - a string that defines a directory name
  - `interface` - the address of the interface the server listens at
  - `port` - the port the server listens on
  - `secure` - whether the notebook is secure

  OUTPUT:

  - a Notebook instance

`sagenb.notebook.notebook.``make_path_relative`(dir)

  Replace an absolute path with a relative path, if possible. Otherwise, return the given path.

  INPUT:

  - `dir` - a string containing, e.g., a directory name

  OUTPUT:

  - a string

`sagenb.notebook.notebook.``migrate_old_notebook_v1`(dir)

  Back up and migrates an old saved version of notebook to the new one (sagenb)

`sagenb.notebook.notebook.``sort_worksheet_list`(v, sort, reverse)

  Sort a given list on a given key, in a given order.

  INPUT:

  - `sort` - a string; ‘last_edited’, ‘owner’, ‘rating’, or ‘name’
  - `reverse` - a bool; if True, reverse the order of the sort.

  OUTPUT:

  - the sorted list