3.1 The Sage Notebook object

Module: sage.server.notebook.notebook

The Sage Notebook object

Module-level Functions

clean_name( name)

load_notebook( dir, [address=None], [port=None], [secure=None])

Load the notebook from the given directory, or create one in that directory if one isn't already there.

Input:

dir: - a string that defines a directory name
address: - the address that the notebook server will listen on
port: - the port the server listens on
secure: - whether or not the notebook is secure

make_path_relative( dir): If easy, replace the absolute path dir by a relative one.

sort_worksheet_list( v, sort, reverse)

Input:

sort: - 'last_edited', 'owner', or 'name'
reverse: - if True, reverse the order of the sort.

Class: Notebook

class Notebook

Notebook( self, dir, [system=None], [pretty_print=False], [show_debug=False], [address=localhost], [port=8000], [secure=True], [server_pool=[]])

Functions: add_to_history, $\,$ add_to_user_history, $\,$ add_user, $\,$ backup_directory, $\,$ change_password, $\,$ change_worksheet_key, $\,$ color, $\,$ conf, $\,$ copy_worksheet, $\,$ create_default_users, $\,$ create_new_worksheet, $\,$ create_new_worksheet_from_history, $\,$ create_user_with_same_password, $\,$ default_user, $\,$ del_user, $\,$ delete, $\,$ delete_doc_browser_worksheets, $\,$ delete_worksheet, $\,$ deleted_worksheets, $\,$ DIR, $\,$ directory, $\,$ empty_trash, $\,$ export_worksheet, $\,$ get_accounts, $\,$ get_all_worksheets, $\,$ get_server, $\,$ get_ulimit, $\,$ get_worksheet_names_with_collaborator, $\,$ get_worksheet_names_with_viewer, $\,$ get_worksheet_with_filename, $\,$ get_worksheet_with_name, $\,$ get_worksheets_with_collaborator, $\,$ get_worksheets_with_owner, $\,$ get_worksheets_with_owner_that_are_viewable_by_user, $\,$ get_worksheets_with_viewer, $\,$ history, $\,$ history_count, $\,$ history_count_inc, $\,$ history_html, $\,$ history_text, $\,$ history_with_start, $\,$ html, $\,$ html_afterpublish_window, $\,$ html_banner, $\,$ html_banner_and_control, $\,$ html_beforepublish_window, $\,$ html_check_col, $\,$ html_debug_window, $\,$ html_doc, $\,$ html_download_or_delete_datafile, $\,$ html_edit_window, $\,$ html_new_or_upload, $\,$ html_notebook_help_window, $\,$ html_notebook_settings, $\,$ html_owner_collab_view, $\,$ html_plain_text_window, $\,$ html_pretty_print_check_form_element, $\,$ html_search, $\,$ html_settings, $\,$ html_share, $\,$ html_slide_controls, $\,$ html_specific_revision, $\,$ html_src, $\,$ html_system_select_form_element, $\,$ html_topbar, $\,$ html_upload_data_window, $\,$ html_user_control, $\,$ html_user_settings, $\,$ html_worksheet_actions, $\,$ html_worksheet_link, $\,$ html_worksheet_list, $\,$ html_worksheet_list_for_user, $\,$ html_worksheet_list_public, $\,$ html_worksheet_list_top, $\,$ html_worksheet_page_template, $\,$ html_worksheet_revision_list, $\,$ html_worksheet_settings, $\,$ html_worksheet_topbar, $\,$ import_worksheet, $\,$ list_window_javascript, $\,$ max_history_length, $\,$ migrate_old, $\,$ new_worksheet_with_title_from_text, $\,$ number_of_backups, $\,$ object_directory, $\,$ object_list_html, $\,$ objects, $\,$ passwords, $\,$ plain_text_worksheet_html, $\,$ pretty_print, $\,$ publish_worksheet, $\,$ quit, $\,$ quit_idle_worksheet_processes, $\,$ save, $\,$ scratch_worksheet, $\,$ server_pool, $\,$ set_accounts, $\,$ set_color, $\,$ set_debug, $\,$ set_directory, $\,$ set_not_computing, $\,$ set_pretty_print, $\,$ set_server_pool, $\,$ set_system, $\,$ set_ulimit, $\,$ system, $\,$ upload_window, $\,$ user, $\,$ user_conf, $\,$ user_exists, $\,$ user_history, $\,$ user_history_html, $\,$ user_history_text, $\,$ user_is_admin, $\,$ user_is_guest, $\,$ user_list, $\,$ usernames, $\,$ users, $\,$ valid_login_names, $\,$ worksheet_directory, $\,$ worksheet_html, $\,$ worksheet_names

add_user( self, username, password, email, [account_type=user], [force=False])

Input:

username: - the username
password: - the password
email: - the email address
account_type: - one of 'user', 'admin', or 'guest'
force: - bool

If the method get_accounts return False then user can only be added if force=True

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.add_user('Mark', 'password', '', force=True)
sage: nb.user('Mark')
Mark
sage: nb.add_user('Sarah', 'password', '')
Traceback (most recent call last):
ValueError: creating new accounts disabled.
sage: nb.set_accounts(True)
sage: nb.add_user('Sarah', 'password', '')
sage: nb.user('Sarah')
Sarah

change_password( self, username, password)

Input:

username: - the username
password: - the password to change the user's password to

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.add_user('Mark', 'password', '', force=True)
sage: nb.user('Mark').password()
'aajfMKNH1hTm2'
sage: nb.change_password('Mark', 'different_password')
sage: nb.user('Mark').password()
'aaTlXok5npQME'

create_default_users( self, passwd)

Create the default users for a notebook.

Input:

passwd: - a string

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: list(sorted(nb.users().iteritems()))
[('_sage_', _sage_), ('admin', admin), ('guest', guest), ('pub', pub)]
sage: list(sorted(nb.passwords().iteritems()))
[('_sage_', 'aaQSqAReePlq6'), ('admin', 'aajfMKNH1hTm2'), ('guest',
'aaQSqAReePlq6'), ('pub', 'aaQSqAReePlq6')]
sage: nb.create_default_users('newpassword')
Creating default users.
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: list(sorted(nb.passwords().iteritems()))
[('_sage_', 'aaQSqAReePlq6'), ('admin', 'aajH86zjeUSDY'), ('guest',
'aaQSqAReePlq6'), ('pub', 'aaQSqAReePlq6')]

create_user_with_same_password( self, user, other_user)

Input:

user: - a string
other_user: - a string

Output: Changes password of user to that of other_user.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.add_user('bob', 'an**d', 'bob@gmail.com', force=True)
sage: nb.user('bob').password()
'aa4Q6Jbx/MiUs'
sage: nb.add_user('mary', 'ccd', 'mary@gmail.com', force=True)
sage: nb.user('mary').password()
'aaxr0gcWJMXKU'
sage: nb.create_user_with_same_password('bob', 'mary')
sage: nb.user('bob').password() == nb.user('mary').password()
True

default_user( self)

Return a default login name that the user will see when confronted with the Sage notebook login page.

Output: string

Currently this returns 'admin' if that is the *only* user. Otherwise it returns the string ''.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: nb.default_user()
'admin'
sage: nb.add_user('AnotherUser', 'password', '', force=True)
sage: nb.default_user()
''

del_user( self, username)

Deletes the given user

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.add_user('Mark', 'password', '', force=True)
sage: nb.user('Mark')
Mark
sage: nb.del_user('Mark')
sage: nb.user('Mark')
Traceback (most recent call last):
KeyError: "no user 'Mark'"

delete( self)

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.

sage: tmp = tmp_dir()
sage: nb = sage.server.notebook.notebook.Notebook(tmp) 
sage: sorted(os.listdir(tmp)) 
['backups', 'nb.sobj', 'objects', 'worksheets']
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_worksheet( self, filename): Delete the given worksheet and remove its name from the worksheet list.

DIR( self): Return the absolute path to the directory that contains the Sage Notebook directory.

empty_trash( self, 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.

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

export_worksheet( self, worksheet_filename, output_filename, [verbose=True])

Export a worksheet with given directory filenmae to output_filename.

Input:

worksheet_filename: - string
output_filename: - string
verbose: - bool (default: True) if True print some the tar command used to extract the sws file.

Output: creates a file on the filesystem

get_accounts( self)

Return __accounts

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.get_accounts()
False
sage: nb.set_accounts(True)
sage: nb.get_accounts()
True

get_worksheet_with_filename( self, filename)

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

Input: string Output: a worksheet or KeyError

html_afterpublish_window( self, worksheet, username, addr, dtime)

Return the html code for a page dedicated to worksheet publishing after the publication of the given worksheet.

Input: worksheet - instance of Worksheet username - string addr - string dtime - instance of time.struct_time

html_beforepublish_window( self, worksheet, username)

Return the html code for a page dedicated to worksheet publishing prior to the publication of the given worksheet.

Input: worksheet - instance of Worksheet username - string

html_edit_window( self, worksheet, username)

Return a window for editing worksheet.

Input:

worksheet: - a worksheet

html_plain_text_window( self, worksheet, username)

Return a window that displays a plain text version of the worksheet

Input:

worksheet: - a worksheet
username: - name of the user

import_worksheet( self, filename, owner)

Upload the worksheet with name filename and make it have the given owner.

Input:

filename: - a string
owner: - a string

Output:

worksheet: - a newly created worksheet

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

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
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()
'foo'
sage: W.cell_list()
[Cell 0; in=2+3, out=]

migrate_old( self): Migrate all old worksheets, i.e., ones with no owner, to ile/pub.

passwords( self)

Return the username:password dictionary.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: nb.add_user('Mark', 'password', '', force=True)
sage: list(sorted(nb.passwords().iteritems()))
[('Mark', 'aajfMKNH1hTm2'), ('_sage_', 'aaQSqAReePlq6'), ('admin',
'aajfMKNH1hTm2'), ('guest', 'aaQSqAReePlq6'), ('pub', 'aaQSqAReePlq6')]

publish_worksheet( self, worksheet, username)

Publish the given worksheet.

This creates a new worksheet in the pub directory with the same contents as worksheet.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.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.publish_worksheet(nb.get_worksheet_with_filename('Mark/0'), 'Mark')

[Cell 0; in=, out=]
sage: sorted(nb.worksheet_names())
['Mark/0', 'pub/0']

set_accounts( self, value)

Changes __accounts to value

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.get_accounts()
False
sage: nb.set_accounts(True)
sage: nb.get_accounts()
True
sage: nb.set_accounts(False)
sage: nb.get_accounts()
False

user( self, username)

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

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: nb.user('admin')
admin
sage: nb.user('admin')._User__email
''
sage: nb.user('admin')._User__password
'aajfMKNH1hTm2'

user_conf( self, username)

Return a user's configuration.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: config = nb.user_conf('admin')
sage: config['max_history_length']
500
sage: config['default_system']
'sage'
sage: config['autosave_interval']
180
sage: config['default_pretty_print']
False

user_exists( self, username)

Return whether or not a user exists given a username.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: nb.user_exists('admin')
True
sage: nb.user_exists('pub')
True
sage: nb.user_exists('mark')
False
sage: nb.user_exists('guest')
True

user_is_admin( self, user)

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.add_user('Administrator', 'password', '', 'admin', True)
sage: nb.add_user('RegularUser', 'password', '', 'user', True)
sage: nb.user_is_admin('Administrator')
True
sage: nb.user_is_admin('RegularUser')
False

user_is_guest( self, username)

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: nb.user_is_guest('guest')
True
sage: nb.user_is_guest('admin')
False

user_list( self)

Return list of user objects.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: sorted(nb.user_list(), key=lambda k: k.username())
[_sage_, admin, guest, pub]

usernames( self)

Return list of usernames.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: sorted(nb.usernames())
['_sage_', 'admin', 'guest', 'pub']

users( self)

Return dictionary of users in a notebook.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: list(sorted(nb.users().iteritems()))
[('_sage_', _sage_), ('admin', admin), ('guest', guest), ('pub', pub)]

valid_login_names( self)

Return list of users that can be signed in.

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.create_default_users('password')
Creating default users.
sage: nb.valid_login_names()
['admin']
sage: nb.add_user('Mark', 'password', '', force=True)
sage: nb.add_user('Sarah', 'password', '', force=True)
sage: nb.add_user('David', 'password', '', force=True)
sage: sorted(nb.valid_login_names())
['David', 'Mark', 'Sarah', 'admin']

worksheet_names( self)

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

Output: list of strings.

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

sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: nb.add_user('sage','sage','sage@sagemath.org',force=True)
sage: W = nb.new_worksheet_with_title_from_text('Sage', owner='sage')
sage: nb.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']

Special Functions: __init__, $\,$ _html_authorize, $\,$ _html_body, $\,$ _html_head, $\,$ _import_worksheet_sws, $\,$ _import_worksheet_txt, $\,$ _initialize_worksheet, $\,$ _migrate_worksheets, $\,$ _Notebook__makedirs

_import_worksheet_sws( self, filename, owner, [verbose=True])

Import an sws format worksheet into this notebook as a new worksheet.

Input:

filename: - string; a filename that ends in .sws; internally it must be a tar'd bz2'd file.
owner: - string
verbose: - bool (default: True) if True print some the tar command used to extract the sws file.

Output: a new worksheet

We create a notebook, then make a worksheet from a plain text file first.

            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
            sage: name = tmp_filename() + '.txt'  
            sage: open(name,'w').write('foo
{{{
2+3
}}}')
            sage: W = nb.import_worksheet(name, 'admin')
            sage: W.filename()
            'admin/0'

We then export the worksheet to an sws file.

sage: nb.export_worksheet(W.filename(),  'tmp.sws', verbose=False)

Now we import the sws.

sage: nb._import_worksheet_sws('tmp.sws', 'admin', verbose=False)
[Cell 0; in=2+3, out=]

Yep, it's there now (as admin/2):

sage: nb.worksheet_names()
['admin/0', 'admin/2']

_import_worksheet_txt( self, filename, owner)

Import a plain text file as a new worksheet.

Input:

filename: - string; a filename that ends in .txt
owner: - string; who will own this worksheet when imported

Output: a new worksheet

We write a plain text worksheet to a file and import it using this function.

            sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir())
            sage: name = tmp_filename() + '.txt'  
            sage: open(name,'w').write('foo
{{{
a = 10
}}}')
            sage: W = nb._import_worksheet_txt(name, 'admin'); W
            [Cell 0; in=a = 10, out=]

_initialize_worksheet( self, src, W): src and W are worksheets and W is brand new.

See About this document... for information on suggesting changes.