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], [log_server=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,$ \,$ log_server,$ \,$ 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_log,$ \,$ server_pool,$ \,$ set_accounts,$ \,$ set_color,$ \,$ set_debug,$ \,$ set_directory,$ \,$ set_log_server,$ \,$ 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'

create_default_users( self, passwd)

Create the default users for a notebook.

Input:

passwd
- a string

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

create_user_with_same_password( self, user, other_user)

Input:

user
- a string
other_user
- a string
Output: creates the given user and makes their password the same as for other_user.

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

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: nb = sage.server.notebook.notebook.Notebook('notebook-test') 
sage: sorted(os.listdir('notebook-test')) 
['backups', 'nb.sobj', 'objects', 'worksheets']
sage: nb.delete()

Now the directory is gone.

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

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: n = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: n.add_user('sage','sage','sage@sagemath.org',force=True)
sage: W = n.new_worksheet_with_title_from_text('Sage', owner='sage')
sage: W.move_to_trash('sage')
sage: n.worksheet_names()
['sage/0']
sage: n.empty_trash('sage')
sage: n.worksheet_names()
[]
sage: n.delete()

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

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

Returns 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('notebook-test')
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=]
sage: nb.delete()

migrate_old( self)

Migrate all old worksheets, i.e., ones with no owner, to ile/pub.

passwords( self)

Return the username:password dictionary.

publish_worksheet( self, worksheet, username)

Publish the given worksheet.

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

user( self, username)

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

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

user_exists( self, username)

Return whether or not a user exists given a username.

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

users( self)

Returns dictionary of users in a notebook.

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

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: n = sage.server.notebook.notebook.Notebook(tmp_dir())
sage: n.add_user('sage','sage','sage@sagemath.org',force=True)
sage: W = n.new_worksheet_with_title_from_text('Sage', owner='sage')
sage: n.add_user('wstein','sage','wstein@sagemath.org',force=True)
sage: W2 = n.new_worksheet_with_title_from_text('Elliptic Curves', owner='wstein')
sage: n.worksheet_names()
['sage/0', 'wstein/0']
sage: n.delete()

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('notebook-test')
            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']
sage: nb.delete()

_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 create a worksheet, make a file, and import it using this function.

            sage: nb = sage.server.notebook.notebook.Notebook('notebook-test')
            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=]
            sage: nb.delete()

_initialize_worksheet( self, src, W)

src and W are worksheets and W is brand new.

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