The Sage Notebook

AUTHORS:

  • William Stein
class sagenb.notebook.notebook.Notebook(dir, user_manager=None)

Bases: object

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','[email protected]',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','[email protected]',force=True)
sage: W = nb.new_worksheet_with_title_from_text('Sage', owner='sage')
sage: nb.user_manager().add_user('wstein','sage','[email protected]',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