#7506 notebook_object documentation is out of date diff -r 251a45bfd7fb -r 693579a7f65b sagenb/notebook/notebook_object.py --- a/sagenb/notebook/notebook_object.py Wed Jan 20 05:04:25 2010 +0800 +++ b/sagenb/notebook/notebook_object.py Wed Jan 20 05:57:22 2010 +0800 @@ -1,5 +1,8 @@ # -*- coding: utf-8 -* """nodoctest +Starting the Notebook + +This is used for configuring and starting the Sage notebook server. """ ############################################################################# # Copyright (C) 2007 William Stein @@ -9,12 +12,6 @@ ############################################################################# -""" -Notebook control object - -This is used for configuring and starting the Sage notebook server. -""" - import time, os, shutil, signal, tempfile import notebook as _notebook @@ -23,40 +20,41 @@ class NotebookObject: r""" -Start the Sage Notebook server. More documentation is available in the -Sage installation guide, in the "Running the Sage Notebook Securely" -chapter, and at http://wiki.sagemath.org/StartingTheNotebook. + Start the Sage Notebook server. More documentation is available in the + Sage installation guide, in the "Running the Sage Notebook Securely" + chapter, and at http://wiki.sagemath.org/StartingTheNotebook. INPUT: - ``directory`` -- directory that contains the Sage notebook files; - the default is .sage/sage_notebook, in your home directory. - - ``port`` -- (default: 8000), port to serve the notebook on. - - ``interface`` -- (default: 'localhost'), address of network - interface to listen on; give '' to listen on all interfaces. + the default is ``.sage/sage_notebook.sagenb``, in your home directory. + - ``port`` -- (default: ``8000``), port to serve the notebook on. + - ``interface`` -- (default: ``'localhost'``), address of network + interface to listen on; give ``''`` to listen on all interfaces. You may use ``address`` here for backwards compatibility, but this is deprecated and will be removed in the future. - - ``port_tries`` -- (default: 0), number of additional ports to try if + - ``port_tries`` -- (default: ``0``), number of additional ports to try if the first one doesn't work (*not* implemented). - - ``secure`` -- (default: False) if True use https so all - communication, e.g., logins and passwords, between - web browsers and the Sage notebook is encrypted - via GNU TLS. *Highly recommended!* - - ``require_login`` -- (default: True) if True login is required else web + - ``secure`` -- (default: ``False``) if True use https so all + communication, e.g., logins and passwords, between web + browsers and the Sage notebook is encrypted via GNU TLS. + *Highly recommended!* + - ``require_login`` -- (default: ``True``) if True login is required else web user is automatically logged in as user admin. - - ``reset`` -- (default: False) if True allows you to set the + - ``reset`` -- (default: ``False``) if True allows you to set the admin password. Use this if you forget your admin password. - - ``accounts`` -- (default: False) if True, any visitor to the - website will be able to create a new account. If - False, only the admin can create accounts - (currently, this can only be done by running with - accounts=True for a few minutes, or on the command + - ``accounts`` -- (default: ``False``) if True, any visitor to the + website will be able to create a new account. If False, + only the admin can create accounts (currently, this can only + be done by running with ``accounts=True`` and shutting down the + server properly (``SIG_INT`` or ``SIG_TERM``), or on the command line with, e.g., :: - nb = load('./sage/sage_notebook/nb.sobj') + from sagenb.notebook.notebook import load_notebook + nb = load_notebook(dir) nb.set_accounts(True) nb.add_user("username", "password", "email@place", "user") nb.save() @@ -64,12 +62,16 @@ - ``open_viewer`` -- (default: True) whether to pop up a web browser. You can override the default browser by setting the SAGE_BROWSER environment variable, e.g., by putting + + :: + export SAGE_BROWSER="firefox" + in the file .bashrc in your home directory. - ``timeout`` -- (default: 0) seconds until idle worksheet sessions automatically timeout, i.e., the corresponding Sage session terminates. 0 means - `never timeout'. If your server is running out + "never timeout". If your server is running out of memory, setting a timeout can be useful as this will free the memory used by idle sessions. - ``server_pool`` -- (default: None) list; this option specifies that @@ -87,7 +89,7 @@ is always allowed no matter what. NOTE: If you have problems with the server certificate hostname not - matching, do \code{notebook.setup()}. + matching, do ``notebook.setup()``. EXAMPLES: @@ -102,7 +104,7 @@ the first time you do this you'll be prompted to set an administrator password. Use this to login. NOTE: You may have to run - notebook.setup() again and change the hostname. + ``notebook.setup()`` again and change the hostname. 3. I just want to run the server locally on my laptop and do not want to be bothered with having to log in:: @@ -116,7 +118,7 @@ 4. I want to create a Sage notebook server that is open to anybody in the world to create new accounts. To run the Sage notebook publicly (1) at a minimum run it from a chroot jail or inside a virtual - machine (see wiki.sagemath.org/StartingTheNotebook and the Sage + machine (see http://wiki.sagemath.org/StartingTheNotebook and the Sage install guide) and (2) use a command like:: notebook(address='', server_pool=['sage1@localhost'], @@ -124,15 +126,16 @@ The server_pool option specifies that worksheet processes run as a separate user. The ulimit option restricts the memory available to - each worksheet processes to 500MB. See help on the `accounts' option + each worksheet processes to 500MB. See help on the ``accounts`` option above. - Be sure to make that the sage_notebook/nb.sobj and contents of - sage_notebook/backups is chmod og-rwx, i.e., only readable by the - notebook process, since otherwise any user can read nb.sobj, which - contains user email addresses and account information (password are - stored hashed, so fewer worries there). You will need to use the - `directory' option to accomplish this. + Be sure to make that the ``sage_notebook.sagenb/users.pickle`` + and contents of ``sage_notebook.sagenb/backups`` is chmod + ``og-rwx``, i.e., only readable by the notebook process, since + otherwise any user can read users.pickle, which contains user email + addresses and account information (password are stored hashed, + so fewer worries there). You will need to use the ``directory`` + option to accomplish this. INPUT: (more advanced) @@ -145,13 +148,17 @@ time the notebook command was called. - ``server_pool`` -- (initial default: None), if given, should be a list - like ['sage1@localhost', 'sage2@localhost'], where + like \['sage1@localhost', 'sage2@localhost'\], where you have setup ssh keys so that typing + + :: + ssh sage1@localhost + logs in without requiring a password, e.g., by typing - `ssh-keygen' as the notebook server user, then - putting ~/.ssh/id_rsa.pub as the file - .ssh/authorized_keys. Note: you have to get the + ``ssh-keygen`` as the notebook server user, then + putting ``~/.ssh/id_rsa.pub`` as the file + ``.ssh/authorized_keys``. Note: you have to get the permissions of files and directories just right -- see the above wiki page for more details. Also, every user in the serverpool must share the same /tmp/ directory right @@ -170,17 +177,17 @@ - ``-v`` The maximum amount of virtual memory available to the process. - Values are in 1024-byte increments, except for `-t', - which is in seconds, and `-u' which is a positive + Values are in 1024-byte increments, except for ``-t``, + which is in seconds, and ``-u`` which is a positive integer. Example: ulimit="-v 400000 -t 30" OTHER NOTES: - - If you create a file ``$DOT_SAGE/notebook.css`` then it will + - If you create a file ``\\$DOT_SAGE/notebook.css`` then it will get applied when rendering the notebook HTML. This allows notebook administrators to customize the look of the - notebook. Note that by default ``$DOT_SAGE`` is - ``$HOME/.sage``. + notebook. Note that by default ``\\$DOT_SAGE`` is + ``\\$HOME/.sage``. """ def __call__(self, *args, **kwds): return self.notebook(*args, **kwds) @@ -193,7 +200,7 @@ def inotebook(*args, **kwds): """ - Exactly the same as notebook(...) but with secure=False. + Exactly the same as ``notebook(...)`` but with ``secure=False``. """ kwds['secure'] = False notebook(*args, **kwds) @@ -203,7 +210,8 @@ """ This function is used to test notebook server functions. - EXAMPLE: + EXAMPLE:: + sage: from sagenb.notebook.notebook_object import test_notebook sage: passwd = str(randint(1,1<<128)) sage: nb = test_notebook(passwd, address='localhost', port=8060) @@ -214,7 +222,7 @@ sage: 'html' in homepage True sage: nb.dispose() - """ + """ import socket, pexpect if directory is None: