# HG changeset patch # User Mitesh Patel # Date 1249912330 25200 # Node ID 6b319da23983c6adc44e752c2471f4c7ed138e85 # Parent 832b4605800675c661715a511041de9ea77904a7 #6840 Fixes documentation for sage.server.* diff -r 832b46058006 -r 6b319da23983 doc/en/reference/notebook.rst --- a/doc/en/reference/notebook.rst Fri Aug 14 18:37:05 2009 -0700 +++ b/doc/en/reference/notebook.rst Mon Aug 10 06:52:10 2009 -0700 @@ -11,10 +11,14 @@ sage/server/notebook/worksheet sage/server/notebook/twist + sage/server/notebook/interact sage/server/notebook/js sage/server/notebook/config sage/server/notebook/css + sage/server/notebook/docHTMLProcessor + sage/server/notebook/template + sage/server/misc sage/server/support sage/server/introspect diff -r 832b46058006 -r 6b319da23983 sage/server/introspect.py --- a/sage/server/introspect.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/introspect.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,6 +1,9 @@ """ -Sage Notebook: Introspection +Sage Notebook Introspection +""" + +""" TODO: - add support for grabbing source code from Pyrex functions (even if not perfect is better than nothing). - PNG or MathML output format for docstring diff -r 832b46058006 -r 6b319da23983 sage/server/misc.py --- a/sage/server/misc.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/misc.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,5 +1,5 @@ """ -Misc code useful for the notebook +Miscellaneous Notebook Functions """ ############################################################################# @@ -19,12 +19,18 @@ web browser to a certain URL. INPUT: - address -- a computer address - port -- a port number - secure -- bool (default: False); whether to put HTTP or HTTPS - path -- path after the port. - EXAMPLES: + - ``address`` -- a string; a computer address or name + + - ``port`` -- an int; a port number + + - ``secure`` -- a bool (default: False); whether to prefix the URL + with 'http' or 'https' + + - ``path`` -- a string; the URL's path following the port. + + EXAMPLES:: + sage: sage.server.misc.print_open_msg('localhost', 8000, True) **************************************************** * * @@ -72,19 +78,25 @@ import socket def find_next_available_port(start, max_tries=100, verbose=False): """ - Find the next port that is available to be used, where available means that - currently trying to connect to it gives a 'Connection refused' - error message. + Find for the next available port, that is, a port for which a + current connection attempt returns a 'Connection refused' error + message. If no port is found, raise a RuntimError exception. INPUT: - start -- integer; a port number to start scanning for a new port at - max_tries -- integer (default: 100); how many ports to try - verbose -- bool (default: True); whether or not to print out info about scanning results. + + - ``start`` - an int; the starting port number for the scan + + - ``max_tries`` - an int (default: 100); how many ports to scan + + - ``verbose`` - a bool (default: True); whether to print information + about the scan OUTPUT: - an integer, or if no port is found, raises a RuntimError exception - EXAMPLES: + - an int - the port number + + EXAMPLES:: + sage: sage.server.misc.find_next_available_port(9000, verbose=False) # random output -- depends on network 9002 """ diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/avatars.py --- a/sage/server/notebook/avatars.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/avatars.py Mon Aug 10 06:52:10 2009 -0700 @@ -28,7 +28,8 @@ OUTPUT: string -- 'invalid_user', 'admin', 'user' - EXAMPLES: + EXAMPLES:: + sage: import sage.server.notebook.twist sage: import sage.server.notebook.avatars as avatars sage: avatars.user_type(avatars.FailedLogin('fake')) diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/cell.py --- a/sage/server/notebook/cell.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/cell.py Mon Aug 10 06:52:10 2009 -0700 @@ -251,6 +251,8 @@ def plain_text(self, prompts=False): """ + Returns a plain text version of self. + EXAMPLES:: sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) @@ -261,6 +263,8 @@ def edit_text(self): """ + Returns the text to be displayed in the Edit window. + EXAMPLES:: sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) @@ -271,6 +275,12 @@ def id(self): """ + Returns self's id. + + OUTPUT: + + - int -- self's id. + EXAMPLES:: sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) @@ -281,6 +291,8 @@ def is_auto_cell(self): """ + Returns true if self is automatically evaluated. + EXAMPLES:: sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) @@ -291,6 +303,8 @@ def __cmp__(self, right): """ + Compares cells by `id`. + EXAMPLES:: sage: C1 = sage.server.notebook.cell.TextCell(0, '2+3', None) @@ -339,6 +353,8 @@ def set_asap(self, asap): """ + Set whether this cell is evaluated as soon as possible. + EXAMPLES:: sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) @@ -568,6 +584,22 @@ mainly because there is no good way to distinguish content (e.g., images in the current directory) that goes into the interactive template and content that would go here. + + EXAMPLES:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) + sage: C.evaluate() + sage: W.check_comp(wait=9999) + ('d', Cell 0; in=plot(sin(x),0,5), out= + + + ) + sage: C.update_html_output() + sage: C.output_html() + '' """ if self.is_interactive_cell(): self.__out_html = "" @@ -702,6 +734,8 @@ def __cmp__(self, right): """ + Compares cells by their `id`s. + EXAMPLES:: sage: C1 = sage.server.notebook.cell.Cell(0, '2+3', '5', None) @@ -718,6 +752,8 @@ def __repr__(self): """ + Returns a string representation of self. + EXAMPLES:: sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None); C @@ -755,10 +791,14 @@ return 70 def plain_text(self, ncols=0, prompts=True, max_out=None): - """ + r""" Returns the plain text version of self. - - TODO: Add more comprehensive doctests. + + EXAMPLES:: + + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) + sage: len(C.plain_text()) + 11 """ if ncols == 0: ncols = self.word_wrap_cols() @@ -831,6 +871,8 @@ def edit_text(self, ncols=0, prompts=False, max_out=None): r""" + Returns the text displayed in the Edit window. + EXAMPLES:: sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) @@ -986,13 +1028,24 @@ def is_interacting(self): """ - Returns True + Returns True if this cell is currently interacting with the user. + + EXAMPLES:: + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = W.new_cell_after(0, "@interact\ndef f(a=slider(0,10,1,5):\n print a^2") + sage: C.is_interacting() + False """ return hasattr(self, 'interact') def stop_interacting(self): """ - + Stops interaction with user. + + TODO: Add doctests for :meth: `stop_interacting`. + """ if self.is_interacting(): del self.interact @@ -1224,6 +1277,18 @@ self.__in = new_text def set_output_text(self, output, html, sage=None): + r""" + Sets the output text for self. + + EXAMPLES:: + + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) + sage: len(C.plain_text()) + 11 + sage: C.set_output_text('10', '10') + sage: len(C.plain_text()) + 12 + """ if output.count('') > 1: html = '

WARNING: multiple @interacts in one cell disabled (not yet implemented).

' output = '' @@ -1279,20 +1344,75 @@ return None def output_html(self): + """ + Returns the HTML for self's output. + + EXAMPLES:: + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) + sage: C.output_html() + '' + sage: C.set_output_text('5', '5') + sage: C.output_html() + '5' + """ try: return self.__out_html except AttributeError: self.__out_html = '' return '' - def process_cell_urls(self, x): + def process_cell_urls(self, urls): + """ + Processes urls of the form 'cell://.*?' by replacing the + protocol with the path to self and appending self's version + number. + + INPUT: + + - ``urls`` - a string + + EXAMPLES:: + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) + sage: C.process_cell_urls('"cell://foobar"') + '/home/sage/0/cells/0/foobar?0"' + """ end = '?%d"'%self.version() begin = self.url_to_self() - for s in re_cell.findall(x) + re_cell_2.findall(x): - x = x.replace(s,begin + s[7:-1] + end) - return x + for s in re_cell.findall(urls) + re_cell_2.findall(urls): + urls = urls.replace(s,begin + s[7:-1] + end) + return urls def output_text(self, ncols=0, html=True, raw=False, allow_interact=True): + """ + Returns the text for self's output. + + INPUT: + + - ``ncols`` - maximum number of columns + + - ``html`` - boolean stating whether to output html + + - ``raw`` - boolean stating whether to output raw text + (takes precedence over html) + + - ``allow_interact`` - boolean stating whether to allow interaction + + EXAMPLE:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) + sage: C.output_text() + '
5
' + sage: C.output_text(html=False) + '
5
' + sage: C.output_text(raw=True) + '5' + """ if allow_interact and hasattr(self, '_interact_output'): # Get the input template z = self.output_text(ncols, html, raw, allow_interact=False) @@ -1337,6 +1457,23 @@ return s.strip('\n') def parse_html(self, s, ncols): + """ + Parse HTML for output. + + INPUT: + + - ``s`` - the input string containing HTML + + - ``ncols`` - maximum number of columns + + EXAMPLES:: + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) + sage: C.parse_html('\nTest', 80) + '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0...Test' + """ def format(x): return word_wrap(escape(x), ncols=ncols) @@ -1442,6 +1579,24 @@ ``verbose`` is not easily accessible now -- if you need to debug, you have to edit this file, changing its value to True, and run 'sage -b'. + + EXAMPLES:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) + sage: C.introspect() + False + sage: C.evaluate(username='sage') + sage: W.check_comp(9999) + ('d', Cell 0; in=sage?, out=) + sage: C.set_introspect_html('foobar') + sage: C.introspect_html() + '
foobar
' + sage: C.set_introspect_html('`foobar`') + sage: C.introspect_html() + '
\n \n

foobar

\n\n\n
' """ if html == "" or completing: self.__introspect_html = html @@ -1599,6 +1754,23 @@ return def introspect_html(self): + """ + Returns html for introspection. + + EXAMPLES:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) + sage: C.introspect() + False + sage: C.evaluate(username='sage') + sage: W.check_comp(9999) + ('d', Cell 0; in=sage?, out=) + sage: C.introspect_html() + u'
...
' + """ if not self.introspect(): return '' try: @@ -1609,17 +1781,21 @@ def introspect(self): """ - TODO: Figure out what the __introspect method is for and write a - better doctest. + Returns self's introspection text. EXAMPLES:: - - sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) sage: C.introspect() False - sage: C.set_introspect("a", "b") + sage: C.evaluate(username='sage') + sage: W.check_comp(9999) + ('d', Cell 0; in=sage?, out=) sage: C.introspect() - ['a', 'b'] + ['sage?', ''] """ try: return self.__introspect @@ -1628,15 +1804,21 @@ def unset_introspect(self): """ - TODO: Figure out what the __introspect method is for and write a - better doctest. + Unsets self's introspection text. EXAMPLES:: - - sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) - sage: C.set_introspect("a", "b") + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) sage: C.introspect() - ['a', 'b'] + False + sage: C.evaluate(username='sage') + sage: W.check_comp(9999) + ('d', Cell 0; in=sage?, out=) + sage: C.introspect() + ['sage?', ''] sage: C.unset_introspect() sage: C.introspect() False @@ -1645,8 +1827,7 @@ def set_introspect(self, before_prompt, after_prompt): """ - TODO: Figure out what the __introspect method is for and write a - better doctest. + Set self's introspection text. EXAMPLES:: @@ -1670,7 +1851,9 @@ [before_cursor, after_cursor] of strings. - EXAMPLES: We create a notebook, worksheet, and cell and evaluate it + EXAMPLES: + + We create a notebook, worksheet, and cell and evaluate it in order to compute `3^5`:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -1753,6 +1936,8 @@ This is a hack and needs to be improved. The problem is how to get the documentation html to display nicely between the example cells. The type setting (jsMath formatting) needs attention too. + + TODO: Remove this hack ( :meth: `doc_html` ) """ self.evaluate() if wrap is None: @@ -1773,6 +1958,28 @@ return s def html(self, wrap=None, div_wrap=True, do_print=False): + r""" + Returns the html for self. + + INPUT: + + - ``wrap`` - a boolean stating whether to wrap lines. Defaults to + configuration if not given, + + - ``div_wrap`` - a boolean stating whether to wrap ``div``s. + + - ``do_print`` - a boolean stating whether the HTML is for + print or not. + + EXAMPLES:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) + sage: C.html() + '\n\n
' + """ if do_print: wrap = 68 div_wrap = 68 @@ -1910,7 +2117,7 @@ sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) sage: W = nb.create_new_worksheet('Test', 'sage') - sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', ", W) + sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) sage: C.evaluate() sage: W.check_comp(wait=9999) ('d', Cell 0; in=plot(sin(x),0,5), out= @@ -1937,7 +2144,7 @@ sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) sage: W = nb.create_new_worksheet('Test', 'sage') - sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', ", W) + sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) sage: C.evaluate() sage: W.check_comp(wait=9999) ('d', Cell 0; in=plot(sin(x),0,5), out= @@ -1960,6 +2167,29 @@ def files_html(self, out): + """ + Returns html to display the files in self's directory. + + INPUT: + + - ``out`` - string to exclude files. + Format: To exclude bar, foo, ...`'cell://bar cell://foo ...'` + + EXAMPLES:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) + sage: C.evaluate() + sage: W.check_comp(wait=9999) + ('d', Cell 0; in=plot(sin(x),0,5), out= + + + ) + sage: C.files_html('') + '' + """ import time D = self.files() D.sort() @@ -2027,6 +2257,25 @@ return images + files def html_out(self, ncols=0, do_print=False): + r""" + Returns the html for self's output. + + INPUT: + + - ``do_print`` - a boolean stating whether to output html + for print + + - ``ncols`` - the number of columns + + EXAMPLES:: + + sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) + sage: W = nb.create_new_worksheet('Test', 'sage') + sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) + sage: C.html_out() + '\n......
' + """ if do_print and self.cell_output_type() == 'hidden': return '
\n
' diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/config.py --- a/sage/server/notebook/config.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/config.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,5 +1,5 @@ """ -Customization of the Notebook Keybindings +Notebook Keybindings This module is responsible for setting the keyboard bindings for the notebook. """ diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/css.py --- a/sage/server/notebook/css.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/css.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,5 +1,5 @@ """nodoctest -Sage Notebook CSS +Notebook Stylesheets (CSS) """ diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/docHTMLProcessor.py --- a/sage/server/notebook/docHTMLProcessor.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/docHTMLProcessor.py Mon Aug 10 06:52:10 2009 -0700 @@ -4,19 +4,22 @@ Processes Sage documentation into notebook worksheet format with evaluatable examples. -This takes in any HTML document, i.e. Sage documentation, and returns +This takes in any HTML document, i.e., Sage documentation, and returns it in the editable format (like the notebook edit window). It also -returns a string representing the css link for the document. The SGML -parser is setup to return only the body of the html documentation page +returns a string representing the CSS link for the document. The SGML +parser is setup to return only the body of the HTML documentation page and to re-format Sage examples and type-setting. Note: This extension of sgmllib.SGMLParser was partly inspired by Mark Pilgrim's 'Dive Into Python' examples. Author: - -- Dorian Raymer (2006): first version - -- William Stein (2007-06-10): rewrite to work with twisted Sage notebook - -- Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation + + - Dorian Raymer (2006): first version + + - William Stein (2007-06-10): rewrite to work with twisted Sage notebook + + - Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation """ ############################################################################# # Copyright (C) 2007 William Stein and Dorian Raimer @@ -32,10 +35,11 @@ class SphinxHTMLProcessor(SGMLParser): def reset(self): """ - This function is called by SGMLParser.__init__ so all necessary things - are initialized here. + Initialize necessary variables. Called by + :meth:`SGMLParser.__init__`. - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor sage: d = SphinxHTMLProcessor() sage: d.bodyQ @@ -64,14 +68,20 @@ def process_doc_html(self, doc_in): """ - process_doc_html is the only function that needs to be called - externally. docin should be a properly marked up html file. + Returns processed HTML input as HTML output. This is the only + method that needs to be called externally. - self.feed() is a - SGMLParser method and starts everything off; Most of the - functions here are extensions to SGMLParser, and may never - actually be visibly called here. - """ + INPUT: + + - ``doc_in`` - a string containing properly formed HTML + + OUTPUT: + + - a string; the processed HTML + """ + # self.feed() is a SGMLParser method and starts everything + # off; Most of the functions here are extensions to + # SGMLParser, and may never actually be visibly called here. self.feed(doc_in) #SGMLParser call self.close() #SGMLParser call self.hand_off_temp_pieces('to_doc_pieces') @@ -81,10 +91,15 @@ def hand_off_temp_pieces(self, piece_type): """ - To separate documentation content from sage examples, - everything is split into one of two cell types. This function - is called to put the current self.temp_pieces into - self.all_pieces. + To separate the documentation's content from the Sage + examples, everything is split into one of two cell types. + This method puts the current ``self.temp_pieces`` into + ``self.all_pieces``. + + INPUT: + + - ``piece_type`` - a string; indicates the type of and how to + process the current ``self.temp_pieces`` """ pieces = "".join(self.temp_pieces) pieces = pieces.lstrip() @@ -100,10 +115,14 @@ def get_cellcount(self): """ - Returns the current cell count and increments it - by one. + Return the current cell count and increment it by one. - EXAMPLES: + OUTPUT: + + - an int + + EXAMPLES:: + sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor sage: d = SphinxHTMLProcessor() sage: d.get_cellcount() @@ -116,14 +135,26 @@ def process_cell_input_output(self, cell_piece): """ - All class='highlight' div's contain code examples. - Some examples are models of how the function works; - those begin with INPUT: or something. - The rest of the examples should have sage:input and - output. If the example is a model, it is made into a - div class='usage_model' so it can be stylized. - If it is actual input/output, the input is separated - from the output according to the Notebook edit format. + Process and return a ``cell_piece``. + + All divs with CSS class="highlight" contain code examples. + They include + + - Models of how the function works. These begin with, e.g., + 'INPUT:' and are re-styled as divs with + class="usage_model". + + - Actual Sage input and ouput. These begin with 'sage:'. + The input and output are separated according to the + Notebook edit format. + + INPUT: + + - ``cell_piece`` - a string; a cell piece + + OUTPUT: + + - a string; the processed cell piece """ if cell_piece[:5] != 'sage:' and cell_piece[:12] != '>'*3: piece = '
'
@@ -215,9 +246,15 @@
     ##
     def start_body(self, attrs):
         """
-        This just sets self.bodyQ to True once we've hit the body tag.
+        Set ``self.bodyQ`` to True upon finding the opening body tag.
 
-        EXAMPLES:
+        INPUT:
+
+        - ``attrs`` - a string:string dictionary containing the
+          element's attributes
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor
             sage: d = SphinxHTMLProcessor()
             sage: d.bodyQ
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/interact.py
--- a/sage/server/notebook/interact.py	Fri Aug 14 18:37:05 2009 -0700
+++ b/sage/server/notebook/interact.py	Mon Aug 10 06:52:10 2009 -0700
@@ -6,15 +6,19 @@
 #############################################################################
 
 r"""
-Interact Sage functions in the notebook
+Interact Functions in the Notebook
 
-This module implements a interact decorator for function in the Sage
+This module implements an :func:`interact` function decorator for the Sage
 notebook.
 
 AUTHORS:
-    -- William Stein (2008-03-02): version 1.0 at Sage/Enthought Days 8 in Texas
-    -- Jason Grout (2008-03): discussion and first few prototypes
-    -- Jason Grout (2008-05): input_grid control
+
+    - William Stein (2008-03-02): version 1.0 at Sage/Enthought Days
+       8 in Texas
+
+    - Jason Grout (2008-03): discussion and first few prototypes
+
+    - Jason Grout (2008-05): :class:`input_grid` control
 """
 
 """
@@ -158,9 +162,10 @@
 
 def reset_state():
     """
-    Reset the interact state of this sage process.
+    Reset the :func:`interact` state of this sage process.
 
-    EXAMPLES:
+    EXAMPLES::
+
         sage: sage.server.notebook.interact.state  # random output
         {1: {'function': , 'variables': {'m': 3, 'n': 5}, 'adapt': {1: , 2: }}}
         sage: from sage.server.notebook.interact import reset_state
@@ -180,9 +185,11 @@
     e.g., makes sure the control always produces int's.
 
     OUTPUT:
-        integer
 
-    EXAMPLES:
+    - an integer
+
+    EXAMPLES::
+
         sage: sage.server.notebook.interact.new_adapt_number()   # random output -- depends on when called
         1    
     """
@@ -193,16 +200,16 @@
 
 def html(s):
     """
-    Render the input string s in a form that tells the notebook
-    to display it in the HTML portion of the output.
+    Print the input string ``s`` in a form that tells the notebook to
+    display it in the HTML portion of the output.  This function has
+    no return value.
 
     INPUT:
-        s -- a string
 
-    OUTPUT:
-        string -- html format
+    - ``s`` - a string
 
-    EXAMPLES:
+    EXAMPLES::
+
         sage: sage.server.notebook.interact.html('hello')
         hello    
     """
@@ -213,17 +220,34 @@
     Return the HTML representation of a jQuery slider.
 
     INPUT:
-        id      -- string -- the DOM id of the slider (better be unique)
-        values  -- 'null' or javascript string containing array of values on slider
-        callback-- javascript that is executed whenever the slider is done moving
-        steps   -- number of steps from minimum to maximum value.
-        default -- (default: 0) the default position of the slider
-        margin  -- (default: 0) size of margin to insert around the slider
+
+    - ``id`` - a string; the DOM id of the slider (better be unique)
+
+    - ``values`` - a string; 'null' or JavaScript string containing
+      array of values on slider
+
+    - ``callback`` - a string; JavaScript that is executed whenever
+      the slider is done moving
+
+    - ``steps`` - an integer; number of steps from minimum to maximum
+      value.
+
+    - ``default`` - an integer (default: 0); the default position of
+      the slider
+
+    - ``margin`` - an integer (default: 0); size of margin to insert
+      around the slider
+
+    OUTPUT:
+    
+    - a string - HTML format
 
     EXAMPLES:
-    We create a jQuery HTML slider.    If you do the following in the notebook
-    you should obtain a slider that when moved pops up a window showing its
-    current position.
+
+    We create a jQuery HTML slider.  If you do the following in the
+    notebook you should obtain a slider that when moved pops up a
+    window showing its current position::
+
         sage: from sage.server.notebook.interact import html_slider, html
         sage: html(html_slider('slider-007', 'null', 'alert(position)', steps=5, default=2, margin=5))
         ...
@@ -257,18 +281,37 @@
     Return the HTML representation of a jQuery range slider.
 
     INPUT:
-        id      -- string -- the DOM id of the slider (better be unique)
-        values  -- 'null' or javascript string containing array of values on slider
-        callback-- javascript that is executed whenever the slider is done moving
-        steps   -- number of steps from minimum to maximum value.
-        default_l -- (default: 0) the default position of the left edge of the slider
-        default_r -- (default: 1) the default position of the right edge of the slider
-        margin  -- (default: 0) size of margin to insert around the slider
+
+    - ``id`` - a string; the DOM id of the slider (better be unique)
+
+    - ``values`` - a string; 'null' or JavaScript string containing
+      array of values on slider
+
+    - ``callback`` - a string; JavaScript that is executed whenever
+      the slider is done moving
+
+    - ``steps`` - an integer; number of steps from minimum to maximum
+      value.
+
+    - ``default_l`` - an integer (default: 0); the default position of
+      the left edge of the slider
+
+    - ``default_r`` - an integer (default: 1); the default position of
+      the right edge of the slider
+
+    - ``margin`` - an integer (default: 0); size of margin to insert
+      around the slider
+
+    OUTPUT:
+
+    - a string - HTML format
 
     EXAMPLES:
-    We create a jQuery range slider. If you do the following in the notebook
-    you should obtain a slider that when moved pops up a window showing its
-    current position.
+
+    We create a jQuery range slider. If you do the following in the
+    notebook you should obtain a slider that when moved pops up a
+    window showing its current position::
+
         sage: from sage.server.notebook.interact import html_rangeslider, html
         sage: html(html_rangeslider('slider-007', 'null', 'alert(pos[0]+", "+pos[1])', steps=5, default_l=2, default_r=3, margin=5))
         ...
@@ -324,15 +367,22 @@
     Return HTML representation of a jQuery color selector.
 
     INPUT:
-        id -- integer; the id of the html div element that this selector should have
-        change -- javascript code to execute when the color selector changes. 
-        default -- string (default: '000000'); default color as a 6-character
-                   HTML hex string.
+
+    - ``id`` - an integer; the id of the HTML div element that this
+      selector should have
+
+    - ``change`` - a string; JavaScript code to execute when the color
+      selector changes.
+
+    - ``default`` - a string (default: ``'000000'``); default color as
+      a 6-character HTML hex string.
 
     OUTPUT:
-        string -- HTML that creates the slider.
 
-    EXAMPLES:
+    - a string - HTML that creates the slider.
+
+    EXAMPLES::
+
         sage: sage.server.notebook.interact.html_color_selector(0, 'alert("changed")', '', default='0afcac')
         '...'
     """
@@ -366,7 +416,12 @@
         Returns an empty label for this element. This should be
         overridden for subclasses that need a label.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import UpdateButton, InteractElement
             sage: b = UpdateButton(1)
             sage: isinstance(b, InteractElement)
@@ -378,11 +433,12 @@
     
     def set_canvas(self, canvas):
         """
-        Sets the InteractCanvas on which this element appears.  This
-        method is primarily called in the constructor for
-        InteractCanvas.
+        Sets the :class:`InteractCanvas` on which this element appears.
+        This method is primarily called in the constructor for
+        :class:`InteractCanvas`.
 
-        EXAMPLES:
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InputBox, InteractCanvas
             sage: B = InputBox('x',2)
             sage: canvas1 = InteractCanvas([B], 3)
@@ -398,11 +454,12 @@
 
     def canvas(self):
         """
-        Returns the InteractCanvas associated to this element.  If no
-        canvas has been set (via the set_canvas method), then this
-        will return a ValueError.
+        Returns the :class:`InteractCanvas` associated to this element.  If
+        no canvas has been set (via the :meth:`set_canvas` method), then
+        raise a ValueError.
 
-        EXAMPLES:
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InputBox, InteractCanvas
             sage: B = InputBox('x',2)
             sage: canvas1 = InteractCanvas([B], 3)
@@ -420,19 +477,24 @@
 class InteractControl(InteractElement):
     def __init__(self, var, default_value, label=None):
         """
-        Abstract base class for interact controls.  These are controls
-        that are used in a specific interact.  They have internal
-        state information about the specific function being interactd,
+        Abstract base class for :func:`interact` controls.  These are controls
+        that are used in a specific :func:`interact`.  They have internal
+        state information about the specific function being interacted,
         etc.
         
         INPUT:
-             var -- string; name of variable that this control interacts
-             default_value -- the default value of the variable
-                              corresponding to this control. 
-             label -- string (default: None) label of this control; if None
-                      then defaults to var.
 
-        EXAMPLES:
+        - ``var`` - a string; name of variable that this control
+          interacts
+
+        - ``default_value`` - the default value of the variable
+          corresponding to this control.
+
+        - ``label`` - a string (default: None); label for this
+          control; if None then defaults to ``var``.
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InteractControl
             sage: InteractControl('x', default_value=5)
             A InteractControl (abstract base class)
@@ -450,9 +512,14 @@
 
     def __repr__(self):
         """
-        String representation of interact control.
+        String representation of :func:`interact` control.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InteractControl
             sage: InteractControl('x', default_value=5).__repr__()
             'A InteractControl (abstract base class)'
@@ -461,13 +528,15 @@
 
     def value_js(self):
         """
-        Javascript that when evaluated gives the current value of this
+        JavaScript that when evaluated gives the current value of this
         control.  This should be redefined in a derived class.
 
         OUTPUT:
-            string -- defaults to NULL -- this should be redefined.
 
-        EXAMPLES:
+        - a string - defaults to 'NULL' - this should be redefined.
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InteractControl('x', default_value=5).value_js()
             'NULL'        
         """
@@ -475,9 +544,14 @@
 
     def label(self):
         """
-        Return the text label of this interact control.
+        Return the text label of this :func:`interact` control.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InteractControl
             sage: InteractControl('x', default_value=5, label='the x value').label()
             'the x value'        
@@ -487,12 +561,14 @@
     def default_value(self):
         """
         Return the default value of the variable corresponding to this
-        interact control.
+        :func:`interact` control.
 
         OUTPUT:
-            object
 
-        EXAMPLES:
+        - an object
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InteractControl
             sage: InteractControl('x', 19/3).default_value()
             19/3
@@ -502,11 +578,16 @@
     def html_escaped_default_value(self):
         """
         Returns the HTML escaped default value of the variable
-        corresponding to this interact control.  Note that any
-        HTML that uses quotes around this should use double
-        quotes and not single quotes.
+        corresponding to this :func:`interact` control.  Note that any
+        HTML that uses quotes around this should use double quotes and
+        not single quotes.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InteractControl
             sage: InteractControl('x', '"cool"').html_escaped_default_value()
             '"cool"'
@@ -528,9 +609,11 @@
         called to adapt the values of this control to Python.
 
         OUTPUT:
-            an integer
 
-        EXAMPLES:
+        - an integer
+
+        EXAMPLES::
+
             sage: from sage.server.notebook.interact import InteractControl
             sage: InteractControl('x', 19/3).adapt_number()       # random -- depends on call order
             2
@@ -543,14 +626,19 @@
         by this control.
 
         INPUT:
-            value -- the string the user typed in
-            globs -- the globals interpreter variables, e.g.,
-                     globals(), which is useful for evaling value.
+
+        - ``value`` - the string the user typed in
+
+        - ``globs`` - a string:object dictionary; the globals
+          interpreter variables, e.g., :func:`globals`, which is
+          useful for evaling value.
 
         OUTPUT:
-            object
 
-        EXAMPLES:
+        - an object
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InteractControl('x', 1)._adaptor('2/3', globals())
             2/3        
         """
@@ -558,8 +646,8 @@
         
     def interact(self, *args):
         """
-        Return a string that when evaluated in Javascript calls the
-        javascript interact function with appropriate inputs for
+        Return a string that when evaluated in JavaScript calls the
+        JavaScript :func:`interact` function with appropriate inputs for
         this control.
 
         This method will check to see if there is a canvas attached to
@@ -569,9 +657,11 @@
         automatically update.
 
         OUTPUT:
-            string -- that is meant to be evaluated in Javascript
 
-        EXAMPLES:
+        - a string - that is meant to be evaluated in JavaScript
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InteractControl('x', 1).interact()
             'interact(..., "sage.server.notebook.interact.update(..., \\"x\\", ..., sage.server.notebook.interact.standard_b64decode(\\""+encode64(NULL)+"\\"), globals());sage.server.notebook.interact.recompute(0)")'
         """
@@ -599,9 +689,11 @@
         Return the name of the variable that this control interacts.
 
         OUTPUT:
-            string -- name of a variable as a string.
 
-        EXAMPLES:
+        - a string - name of a variable as a string.
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InteractControl('theta', 1).var()
             'theta'        
         """
@@ -609,13 +701,16 @@
 
     def cell_id(self):
         """
-        Return the id of the cell that contains this interact control.
+        Return the id of the cell that contains this :func:`interact` control.
 
         OUTPUT:
-            integer -- id of cell that this control interacts
+
+        - an integer - id of cell that this control interacts
 
         EXAMPLES:
-        The output below should equal the ID of the current cell. 
+
+        The output below should equal the id of the current cell::
+
             sage: sage.server.notebook.interact.InteractControl('theta', 1).cell_id()
             0
         """
@@ -624,11 +719,10 @@
 class InputBox(InteractControl):
     def __init__(self, var, default_value, label=None, type=None, width = 80):
         """
-        An input box interact control.
+        An input box :func:`interact` control.
 
-        InputBox(var, default_value, label, type)
+        EXAMPLES::
 
-        EXAMPLES:
             sage: sage.server.notebook.interact.InputBox('theta', 1, 'theta')
             An InputBox interactive control with theta=1 and label 'theta'
             sage: sage.server.notebook.interact.InputBox('theta', 1, 'theta', int)
@@ -640,9 +734,14 @@
         
     def __repr__(self):
         """
-        String representation of an InputBox interactive control.
+        String representation of an :class:`InputBox` interactive control.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InputBox('theta', 1).__repr__()
             "An InputBox interactive control with theta=1 and label 'theta'"
         """
@@ -655,13 +754,18 @@
         element selected by this control.
 
         INPUT:
-            value -- text entered by user
-            globs -- the globals interpreter variables (not used here).
+
+        - ``value`` - text entered by user
+
+        - ``globs`` - a string:object dictionary; the :func:`globals`
+          interpreter variables (not used here).
 
         OUTPUT:
-            object
 
-        EXAMPLES:
+        - an object
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InputBox('theta', Color('red'), type=Color)._adaptor('#aaaaaa',globals())
             RGB color (0.6640625, 0.6640625, 0.6640625)
         """
@@ -676,13 +780,15 @@
 
     def value_js(self):
         """
-        Return javascript string that will give the value of this
+        Return JavaScript string that will give the value of this
         control element.
 
         OUTPUT:
-             string -- javascript
 
-        EXAMPLES:
+        - a string - JavaScript
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InputBox('theta', 1).value_js()
             'this.value'
         """
@@ -696,9 +802,11 @@
         Render this control as a string.
 
         OUTPUT:
-             string -- html format
 
-        EXAMPLES:
+        - a string - HTML format
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.InputBox('theta', 1).render()
             ''
         """
@@ -715,15 +823,21 @@
 class ColorInput(InputBox):
     def value_js(self, n):
         """
-        Return javascript that evaluates to value of this control.
+        Return JavaScript that evaluates to value of this control.
+        If ``n`` is 0 return code for evaluation by the actual color
+        control.  If ``n`` is 1, return code for the text area that
+        displays the current color.
 
         INPUT:
-            n -- integer, either 0 or 1.
 
-        If n is 0 return code for evaluation by the actual color control.
-        If n is 1, return code for the text area that displays the current color.
+        - ``n`` - integer, either 0 or 1.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string
+
+        EXAMPLES::
+
             sage: C = sage.server.notebook.interact.ColorInput('c', Color('red'))
             sage: C.value_js(0)
             'color'
@@ -737,9 +851,14 @@
 
     def render(self):
         """
-        Render this color input box to html.
+        Render this color input box to HTML.
 
-        EXAMPLES:
+        OUTPUT:
+
+        - a string - HTML format
+
+        EXAMPLES::
+
             sage: sage.server.notebook.interact.ColorInput('c', Color('red')).render()
             '
...' """ @@ -754,20 +873,28 @@ """ A grid interact control. - INPUT - var -- the variable - rows -- the number of rows - columns -- the number of columns - default_value -- if this is a scalar, it is put in every - cell; if it is a list, it is filled into the cells row by - row; if it is a nested list, then it is filled into the - cells according to the nesting structure. - label -- the label for the control - to_value -- a function which is applied to the nested list - from user input when assigning the variable - width -- the width of the input boxes + INPUT: - EXAMPLES: + - ``var`` - an object; the variable + + - ``rows`` - an integer; the number of rows + + - ``columns`` - an integer; the number of columns + + - ``default_value`` - an object; if this is a scalar, it is + put in every cell; if it is a list, it is filled into the + cells row by row; if it is a nested list, then it is filled + into the cells according to the nesting structure. + + - ``label`` - a string; the label for the control + + - ``to_value`` - a function applied to the nested list from + user input when assigning the variable + + - ``width`` - an integer; the width of the input boxes + + EXAMPLES:: + sage: sage.server.notebook.interact.InputGrid('M', 2,2, default_value = 0, label='M') A 2 x 2 InputGrid interactive control with M=[[0, 0], [0, 0]] and label 'M' sage: sage.server.notebook.interact.InputGrid('M', 2,2, default_value = [[1,2],[3,4]], label='M') @@ -795,9 +922,14 @@ def __repr__(self): """ - String representation of an InputGrid interactive control. + String representation of an :class:`InputGrid` interactive control. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: sage.server.notebook.interact.InputGrid('M', 2,2).__repr__() "A 2 x 2 InputGrid interactive control with M=[[None, None], [None, None]] and label 'M'" """ @@ -812,13 +944,18 @@ element selected by this control. INPUT: - value -- text entered by user - globs -- the globals interpreter variables (not used here). + + - ``value`` - text entered by user + + - ``globs`` - a string:object dictionary; the :func:`globals` + interpreter variables (not used here). OUTPUT: - object - EXAMPLES: + - an object + + EXAMPLES:: + sage: sage.server.notebook.interact.InputGrid('M', 1,3, default_value=[[1,2,3]], to_value=lambda x: vector(flatten(x)))._adaptor("[[4,5,6]]", globals()) (4, 5, 6) """ @@ -827,13 +964,15 @@ def value_js(self): """ - Return javascript string that will give the value of this + Return JavaScript string that will give the value of this control element. OUTPUT: - string -- javascript - EXAMPLES: + - string - JavaScript + + EXAMPLES:: + sage: sage.server.notebook.interact.InputGrid('M', 2,2).value_js() ' "[["+jQuery(this).parents("table").eq(0).find("tr").map(function(){return jQuery(this).find("input").map(function() {return jQuery(this).val();}).get().join(",");}).get().join("],[")+"]]" ' """ @@ -848,9 +987,11 @@ Render this control as a string. OUTPUT: - string -- html format - EXAMPLES: + - string - HTML format + + EXAMPLES:: + sage: sage.server.notebook.interact.InputGrid('M', 1,2).render() '
' sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).render() @@ -1066,19 +1233,26 @@ class SliderGeneric(InteractControl): def __init__(self, var, values, default_value, label=None, display_value=True): """ - An abstract slider interact control that takes on the given list of - values. + An abstract slider :func:`interact` control that takes on the + given list of values. INPUT: - var -- string; name of variable being interactd - values -- list; a list of the values that the slider will take on - default_value -- default valueoif slider. - label -- alternative label to the left of the slider, - instead of the variable. - display_value -- boolean, whether to display the current value - on the slider - EXAMPLES: + - ``var`` - a string; name of variable being interacted + + - ``values`` - a list; a list of the values that the slider + will take on + + - ``default_value`` - an object; default value of the slider. + + - ``label`` - a string; alternative label to the left of the + slider, instead of the variable. + + - ``display_value`` - a bool; whether to display the current + value on the slider + + EXAMPLES:: + sage: sage.server.notebook.interact.SliderGeneric('x', [1..5], 2, 'alpha') Abstract Slider Interact Control: alpha [1--|2|---5] """ @@ -1090,7 +1264,12 @@ """ Return string representation of this slider control. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: sage.server.notebook.interact.SliderGeneric('x', [1..5], 2, 'alpha').__repr__() 'Abstract Slider Interact Control: alpha [1--|2|---5]' """ @@ -1103,9 +1282,11 @@ Return list of values the slider acts on. OUTPUT: - list + + - a list - EXAMPLES: + EXAMPLES:: + sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').values() [1, 2, 3, 4, 5] """ @@ -1116,9 +1297,11 @@ Returns whether to display the value on the slider. OUTPUT: - boolean + + - a bool - EXAMPLES: + EXAMPLES:: + sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').display_value() True """ @@ -1126,12 +1309,15 @@ def values_js(self): """ - Returns Javascript array representation of values or null if display_value is False + Returns JavaScript array representation of values or 'null' if + display_value=False OUTPUT: - string + + - a string - EXAMPLES: + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').values_js() '["1","2","3","4","5"]' sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha', False).values_js() @@ -1152,19 +1338,27 @@ class Slider(SliderGeneric): def __init__(self, var, values, default_position, label=None, display_value=True): """ - A slider interact control that takes on the given list of + A slider :func:`interact` control that takes on the given list of values. INPUT: - var -- string; name of variable being interactd - values -- list; a list of the values that the slider will take on - default_position -- int; default location that the slider is set to. - label -- alternative label to the left of the slider, - instead of the variable. - display_value -- boolean, whether to display the current value right - of the slider - EXAMPLES: + - ``var`` - a string; name of variable being interacted + + - ``values`` - a list; a list of the values that the slider + will take on + + - ``default_position`` - an integer; default location that the + slider is set to. + + - ``label`` - a string; alternative label to the left of the + slider, instead of the variable. + + - ``display_value`` - a bool, whether to display the current + value right of the slider + + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha') Slider Interact Control: alpha [1--|3|---5] """ @@ -1175,7 +1369,12 @@ """ Return string representation of this slider control. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').__repr__() 'Slider Interact Control: alpha [1--|3|---5]' """ @@ -1187,7 +1386,12 @@ """ Return the default position (as an integer) of the slider. - EXAMPLES: + OUTPUT: + + - an integer + + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').default_position() 2 """ @@ -1195,13 +1399,15 @@ def value_js(self): """ - Return javascript string that will give the - value of this control element. + Return JavaScript string that will give the value of this + control element. OUTPUT: - string -- javascript - EXAMPLES: + - a string - JavaScript + + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').value_js() 'position' """ @@ -1213,13 +1419,18 @@ element selected by this control. INPUT: - position -- position of the slider - globs -- the globals interpreter variables (not used here). + + - ``position`` - an object; position of the slider + + - ``globs`` - a string:object dictionary; the :func:`globals` + interpreter variables (not used here). OUTPUT: - object - EXAMPLES: + - an object + + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha')._adaptor(2,globals()) 3 """ @@ -1233,9 +1444,11 @@ Render this control as an HTML string. OUTPUT: - string -- html format - EXAMPLES: + - a string - HTML format + + EXAMPLES:: + sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').render() '...
...
something
' """ @@ -1390,16 +1639,22 @@ class InteractCanvas: def __init__(self, controls, id, **options): """ - Base class for interact canvases. This is where all the controls - along with the output of the interactd function are laid out - and rendered. + Base class for :func:`interact` canvases. This is where all + the controls along with the output of the interacted function + are laid out and rendered. INPUT: - controls -- a list of InteractControl instances. - id -- the id of the cell that contains this InteractCanvas. - options -- any additional keyword arguments (for example, auto_update=False) + + - ``controls`` - a list of :class:`InteractControl` instances. + + - ``id`` - an integer; the id of the cell that contains this + InteractCanvas. + + - ``options`` - any additional keyword arguments (for example, + auto_update=False) - EXAMPLES: + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3) Interactive canvas in cell 3 with 1 controls @@ -1415,7 +1670,12 @@ """ Print representation of an interactive canvas. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).__repr__() 'Interactive canvas in cell 3 with 1 controls' @@ -1424,13 +1684,18 @@ self.__cell_id, len(self.__controls)) def is_auto_update(self): - """ + r""" Returns True if any change of the values for the controls on - this canvas should cause an update. If auto_update=False was + this canvas should cause an update. If `auto_update=False` was not specified in the constructor for this canvas, then this will default to True. - EXAMPLES: + OUTPUT: + + - a bool + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: canvas = sage.server.notebook.interact.InteractCanvas([B], 3) sage: canvas.is_auto_update() @@ -1442,10 +1707,15 @@ return self.__options.get('auto_update', True) def cell_id(self): - """ - Returns the cell id associated to this InteractCanvas. + r""" + Returns the cell id associated to this :class:`InteractCanvas`. - EXAMPLES: + OUTPUT: + + - an integer + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: canvas = sage.server.notebook.interact.InteractCanvas([B], 3) sage: canvas.cell_id() @@ -1455,11 +1725,16 @@ def controls(self): """ - Return list of controls in this canvas. + Return a list of controls in this canvas. - WARNING: Returns a reference to a mutable list. + OUTPUT: - EXAMPLES: + - list of controls + + .. note:: Returns a reference to a mutable list. + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).controls() [An InputBox interactive control with x=2 and label 'x'] @@ -1470,7 +1745,12 @@ """ Return the cell id that contains this interactive canvas. - EXAMPLES: + OUTPUT: + + - an integer + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).cell_id() 3 @@ -1479,16 +1759,19 @@ def render_output(self): """ - Render in text (html) form the output portion of the interact canvas. + Render in text (HTML) form the output portion of the + :func:`interact` canvas. The output contains two special tags, and , - which get replaced at runtime by the text and html parts + which get replaced at runtime by the text and HTML parts of the output of running the function. OUTPUT: - string -- html - EXAMPLES: + - a string - HTML format + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).render_output() "
" @@ -1501,12 +1784,14 @@ def render_controls(self): """ - Render in text (html) form all the input controls. + Render in text (HTML) form all the input controls. OUTPUT: - string -- html - EXAMPLES: + - a string - HTML format + + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).render_controls() '
...' @@ -1523,16 +1808,19 @@ def wrap_in_outside_frame(self, inside): """ Return the entire HTML for the interactive canvas, obtained by - wrapping all the inside html of the canvas in a div and a + wrapping all the inside HTML of the canvas in a div and a table. INPUT: - inside -- string (of HTML) + + - ``inside`` - a string; HTML OUTPUT: - string of HTML + + - a string - HTML format - EXAMPLES: + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).wrap_in_outside_frame('') "
...
\n " @@ -1553,12 +1841,14 @@ def render(self): """ - Render in text (html) the entire interact canvas. + Render in text (HTML) the entire :func:`interact` canvas. OUTPUT: - string -- html + + - string - HTML format - EXAMPLES: + EXAMPLES:: + sage: B = sage.server.notebook.interact.InputBox('x',2) sage: sage.server.notebook.interact.InteractCanvas([B], 3).render() '
...
\n ' @@ -1570,10 +1860,11 @@ class JavascriptCodeButton(InteractElement): def __init__(self, label, code): """ - This interact element displays a button which when clicked - executes Javascript code in the notebook. + This :func:`interact` element displays a button which when clicked + executes JavaScript code in the notebook. - EXAMPLES: + EXAMPLES:: + sage: b = sage.server.notebook.interact.JavascriptCodeButton('Push me', 'alert("2")') """ self.__label = label @@ -1584,7 +1875,12 @@ r""" Returns the HTML to display this button. - EXAMPLES: + OUTPUT: + + - a string - HTML format + + EXAMPLES:: + sage: b = sage.server.notebook.interact.JavascriptCodeButton('Push me', 'alert("2")') sage: b.render() '\n' @@ -1595,11 +1891,16 @@ class UpdateButton(JavascriptCodeButton): def __init__(self, cell_id): r""" - This interact element creates a button which when clicked - causes the interact function in the cell cell_id to be + This :func:`interact` element creates a button which when clicked + causes the :func:`interact` function in the cell ``cell_id`` to be recomputed with the current values of the variables. - EXAMPLES: + INPUT: + + - ``cell_id`` - an integer; the ambient cell's id + + EXAMPLES:: + sage: b = sage.server.notebook.interact.UpdateButton(0) sage: b.render() '\n' @@ -1612,68 +1913,81 @@ r""" Use interact as a decorator to create interactive Sage notebook cells with sliders, text boxes, radio buttons, check boxes, and - color selectors. Simply put @interact on the line before a + color selectors. Simply put ``@interact`` on the line before a function definition in a cell by itself, and choose appropriate defaults for the variable names to determine the types of controls (see tables below). INPUT: - f -- a Python function + + - ``f`` - a Python function EXAMPLES: + In each example below we use a single underscore for the function - name. You can use \emph{any} name you want; it does not have to + name. You can use *any* name you want; it does not have to be an underscore. We create an interact control with two inputs, a text input for - the variable $a$ and a $y$ slider that runs through the range of - integers from $0$ to $19$. + the variable ``a`` and a ``y`` slider that runs through the range of + integers from `0` to `19`. + + :: + sage: @interact ... def _(a=5, y=(0..20)): print a + y ... ... - Draw a plot interacting with the ``continuous'' variable $a$. By + Draw a plot interacting with the "continuous" variable ``a``. By default continuous variables have exactly 50 possibilities. + + :: + sage: @interact ... def _(a=(0,2)): ... show(plot(sin(x*(1+a*x)), (x,0,6)), figsize=4) ... Interact a variable in steps of 1 (we also use an unnamed - function): + function):: + sage: @interact ... def _(n=(10,100,1)): ... show(factor(x^n - 1)) ... - Interact two variables: + Interact two variables:: + sage: @interact ... def _(a=(1,4), b=(0,10)): ... show(plot(sin(a*x+b), (x,0,6)), figsize=3) ... - Place a block of text among the controls: + Place a block of text among the controls:: + sage: @interact ... def _(t1=text_control("Factors an integer."), n="1"): ... print factor(Integer(n)) ... You do not have to use interact as a decorators; you can also - simply write \code{interact(f)} where f is any Python function - that you have defined, though this is frowned on. E.g., f can - also be a library function as long as it is written in Python: + simply write ``interact(f)`` where ``f`` is any Python function + that you have defined, though this is frowned upon. E.g., ``f`` + can also be a library function as long as it is written in + Python:: sage: interact(matrix) # put ZZ, 2,2,[1..4] in boxes... ... If your the time to evaluate your function takes awhile, you may not want to have it reevaluated every time the inputs change. In - order to prevent this, you can add a keyword - \code{auto_update=False} to your function to prevent it from - updating whenever the values are changed. This will cause a - button labeled 'Update' to appear which you can click on to - re-evaluate your function. + order to prevent this, you can add a keyword ``auto_update=False`` to + your function to prevent it from updating whenever the values are + changed. This will cause a button labeled 'Update' to appear + which you can click on to re-evaluate your function. + + :: sage: @interact ... def _(n=(10,100,1), auto_update=False): @@ -1681,79 +1995,113 @@ ... DEFAULTS: + Defaults for the variables of the input function determine - interactive controls. The standard controls are \code{input_box}, - \code{slider}, \code{range_slider}, \code{checkbox}, \code{selector}, - \code{input_grid}. There is also a color selector and text control + interactive controls. The standard controls are ``input_box``, + ``slider``, ``range_slider``, ``checkbox``, ``selector``, and + ``input_grid``. There is also a color selector and text control (see defaults below). + - \begin{itemize} - \item u = input_box(default=None, label=None, type=None) - -- input box with given default; use type=str to - get input as an arbitrary string - \item u = slider(vmin, vmax=None,step_size=1,default=None,label=None) - -- slider with given list of possible values; vmin can be a list - \item u = range_slider(vmin, vmax=None,step_size=1,default=None,label=None) - -- range slider with given list of possible values; - vmin can be a list - \item u = checkbox(default=True, label=None) - -- a checkbox - \item u = selector(values, label=None, nrows=None, ncols=None, buttons=False) - -- a dropdown menu or buttons (get buttons if nrows, - ncols, or buttons is set, otherwise a dropdown menu) - \item u = input_grid(nrows, ncols, default=None, label=None, - to_value=lambda x:x, width=4) - -- an editable grid of objects (a matrix or array) - \item u = text_control(value='') - -- a block of text - \end{itemize} + * ``u = input_box(default=None, label=None, type=None)`` - + input box with given ``default``; use ``type=str`` to get + input as an arbitrary string + + + * ``u = slider(vmin, vmax=None, step_size=1, default=None, + label=None)`` - slider with given list of possible values; + ``vmin`` can be a list + + + * ``u = range_slider(vmin, vmax=None, step_size=1, + default=None, label=None)`` - range slider with given list + of possible values; ``vmin`` can be a list + + + * ``u = checkbox(default=True, label=None)`` - a checkbox + + + * ``u = selector(values, label=None, nrows=None, ncols=None, + buttons=False)`` - a dropdown menu or buttons (get buttons + if ``nrows``, ``ncols``, or ``buttons`` is set, otherwise a + dropdown menu) + + + * ``u = input_grid(nrows, ncols, default=None, label=None, + to_value=lambda x:x, width=4)`` - an editable grid of + objects (a matrix or array) + + + * ``u = text_control(value='')`` - a block of text + You can create a color selector by setting the default value for a - variable to Color(...). + variable to ``Color(...)``. There are also some convenient defaults that allow you to make controls automatically without having to explicitly specify them. - E.g., you can make $x$ a continuous slider of values between $u$ - and $v$ by just writing \code{x=(u,v)} in the argument list of + E.g., you can make ``x`` a continuous slider of values between ``u`` + and ``v`` by just writing ``x=(u,v)`` in the argument list of your function. These are all just convenient shortcuts for creating the controls listed above. - \begin{itemize} - \item u -- blank input_box field - \item u = element -- input_box with default=element, if element not below. - \item u = (umin,umax) -- continuous slider (really 100 steps) - \item u = (umin,umax,du)-- slider with step size du - \item u = list -- buttons if len(list) at most 5; otherwise, drop down - \item u = generator -- a slider (up to 10000 steps) - \item u = bool -- a checkbox - \item u = Color('blue') -- a 2d RGB color selector; returns Color object - \item u = (default, v) -- v as above, with given default value - \item u = (label, v) -- v as above, with given label (a string) - \item u = matrix -- an input_grid with to_value set to matrix.parent() - and default values given by the matrix - \end{itemize} + * ``u`` - blank input_box field - WARNING: Suppose you would like to make a interactive with a - default rgb color of (1,0,0), so the function would have signature - \code{f(color=(1,0,0))}. Unfortunately, the above shortcuts reinterpret - the (1,0,0) as a discrete slider with step size 0 between 1 and 0. - Instead you should do the following: - sage: @interact - ... def _(v = input_box((1,0,0))): - ... show(plot(sin,color=v)) - ... + * ``u = element`` - input_box with ``default=element``, if + element not below. + + * ``u = (umin,umax)`` - continuous slider (really `100` steps) + + * ``u = (umin,umax,du)`` - slider with step size ``du`` + + * ``u = list`` - buttons if ``len(list)`` at most `5`; + otherwise, drop down + + * ``u = generator`` - a slider (up to `10000` steps) + + * ``u = bool`` - a checkbox + + * ``u = Color('blue')`` - a 2D RGB color selector; returns + ``Color`` object + + * ``u = (default, v)`` - ``v`` as above, with given + ``default`` value + + * ``u = (label, v)`` - ``v`` as above, with given ``label`` + (a string) + + * ``u = matrix`` - an ``input_grid`` with ``to_value`` set to + ``matrix.parent()`` and default values given by the matrix + + .. note:: + + Suppose you would like to make a interactive with a default + RGB color of ``(1,0,0)``, so the function would have signature + ``f(color=(1,0,0))``. Unfortunately, the above shortcuts + reinterpret the ``(1,0,0)`` as a discrete slider with step + size 0 between 1 and 0. Instead you should do the + following:: + + sage: @interact + ... def _(v = input_box((1,0,0))): + ... show(plot(sin,color=v)) + ... MORE EXAMPLES: - We give an input box that allows one to enter completely arbitrary strings. + + We give an input box that allows one to enter completely arbitrary + strings:: + sage: @interact ... def _(a=input_box('sage', label="Enter your name", type=str)): ... print "Hello there %s"%a.capitalize() ... - The scope of variables that you control via interact are local to - the scope of the function being interacted with. However, by using - the global Python keyword, you can still modify global variables - as follows: + The scope of variables that you control via :func:`interact` are local + to the scope of the function being interacted with. However, by + using the ``global`` Python keyword, you can still modify global + variables as follows:: + sage: xyz = 10 sage: @interact ... def _(a=('xyz',5)): @@ -1761,8 +2109,8 @@ ... xyz = a ... - If you enter the above you obtain an interact canvas. Entering - values in the box, changes the global variable xyz. + If you enter the above you obtain an :func:`interact` canvas. Entering + values in the box changes the global variable ``xyz``:: sage: @interact ... def _(title=["A Plot Demo", "Something silly", "something tricky"], a=input_box(sin(x*sin(x*sin(x))), 'function'), @@ -1772,34 +2120,40 @@ ... show(plot(a, -zoom*pi,zoom*pi, color=clr, thickness=thickness, plot_points=plot_points)) ... - We give defaults and name the variables: + We give defaults and name the variables:: + sage: @interact ... def _(a=('first', (1,4)), b=(0,10)): ... show(plot(sin(a*x+sin(b*x)), (x,0,6)), figsize=3) ... - Another example involving labels and defaults, and the - slider command. + Another example involving labels, defaults, and the slider + command:: + sage: @interact ... def _(a = slider(1, 4, default=2, label='Multiplier'), ... b = slider(0, 10, default=0, label='Phase Variable')): ... show(plot(sin(a*x+b), (x,0,6)), figsize=4) ... - An example where the range slider control is useful. + An example where the range slider control is useful:: + sage: @interact ... def _(b = range_slider(-20, 20, 1, default=(-19,3), label='Range')): ... plot(sin(x)/x, b[0], b[1]).show(xmin=b[0],xmax=b[1]) ... - An example using checkboxes, obtained by making the default values bools. + An example using checkboxes, obtained by making the default values + bools:: + sage: @interact ... def _(axes=('Show axes', True), square=False): ... show(plot(sin, -5,5), axes=axes, aspect_ratio = (1 if square else None)) ... - An example generating a random walk that uses a checkbox control to determine - whether points are placed at each step: + An example generating a random walk that uses a checkbox control + to determine whether points are placed at each step:: + sage: @interact ... def foo(pts = checkbox(True, "points"), n = (50,(10..100))): ... s = 0; v = [(0,0)] @@ -1811,15 +2165,17 @@ ... show(L) ... - You can rotate and zoom into 3D graphics while - interacting with a variable. + You can rotate and zoom into 3D graphics while interacting with a + variable:: + sage: @interact ... def _(a=(0,1)): ... x,y = var('x,y') ... show(plot3d(sin(x*cos(y*a)), (x,0,5), (y,0,5)), figsize=4) ... - A random polygon: + A random polygon:: + sage: pts = [(random(), random()) for _ in xrange(20)] sage: @interact ... def _(n = (4..len(pts)), c=Color('purple') ): @@ -1827,8 +2183,9 @@ ... show(G, figsize=5, xmin=0, ymin=0) ... - Two "sinks" displayed simultaneously via a contour plot and a 3d - interactive plot: + Two "sinks" displayed simultaneously via a contour plot and a 3D + interactive plot:: + sage: @interact ... def _(q1=(-1,(-3,3)), q2=(-2,(-3,3))): ... x,y = var('x,y') @@ -1838,7 +2195,9 @@ ... show(plot3d(f, (x,-2,2), (y,-2,2)), figsize=4) ... - This is similar to above, but you can select the color map from a dropdown menu: + This is similar to above, but you can select the color map from a + dropdown menu:: + sage: @interact ... def _(q1=(-1,(-3,3)), q2=(-2,(-3,3)), ... cmap=['autumn', 'bone', 'cool', 'copper', 'gray', 'hot', 'hsv', @@ -1849,7 +2208,8 @@ ... show(C, figsize=3, aspect_ratio=1) ... - A quadratic roots etch-a-sketch: + A quadratic roots etch-a-sketch:: + sage: v = [] sage: html('

Quadratic Root Etch-a-sketch

')

Quadratic Root Etch-a-sketch

@@ -1863,10 +2223,11 @@ ... show(line(v, rgbcolor='purple') + point(P, pointsize=200)) ... - In the following example, we only generate data for a given n - once, so that as one varies p the data doesn't not randomly - change. We do this by simply caching the results for each n - in a dictionary. + In the following example, we only generate data for a given ``n`` + once, so that as one varies ``p`` the data does not randomly change. + We do this by simply caching the results for each ``n`` in a + dictionary.:: + sage: data = {} sage: @interact ... def _(n=(500,(100,5000,1)), p=(1,(0.1,10))): @@ -1876,7 +2237,8 @@ ... show(points([(x^p,y^p) for x,y in data[n]], rgbcolor='black'), xmin=0, ymin=0, axes=False) ... - A conchoid: + A conchoid:: + sage: @interact ... def _(k=(1.2,(1.1,2)), k_2=(1.2,(1.1,2)), a=(1.5,(1.1,2))): ... u, v = var('u,v') @@ -1884,7 +2246,8 @@ ... show(parametric_plot3d(f, (u,0,6*pi), (v,0,2*pi), plot_points=[40,40], texture=(0,0.5,0))) ... - An input grid: + An input grid:: + sage: @interact ... def _(A=matrix(QQ,3,3,range(9)), v=matrix(QQ,3,1,range(3))): ... try: @@ -1937,13 +2300,15 @@ class control: def __init__(self, label=None): """ - An interactive control object used with the interact command. + An interactive control object used with the :func:`interact` command. This is the abstract base class. INPUTS: - label -- a string + + - ``label`` - a string - EXAMPLES: + EXAMPLES:: + sage: sage.server.notebook.interact.control('a control') Interative control 'a control' (abstract base class) """ @@ -1951,10 +2316,15 @@ def __repr__(self): """ - Return string representation of this control. - (It just mentions the label and that this is an abstract base class.) + Return string representation of this control. (It just + mentions the label and that this is an abstract base class.) - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: sage.server.notebook.interact.control('a control').__repr__() "Interative control 'a control' (abstract base class)" """ @@ -1965,9 +2335,11 @@ Return the label of this control. OUTPUT: - a string - - EXAMPLES: + + - a string + + EXAMPLES:: + sage: sage.server.notebook.interact.control('a control').label() 'a control' sage: selector([1,2,7], 'alpha').label() @@ -1980,9 +2352,11 @@ Set the label of this control. INPUT: - label -- a string + + - ``label`` - a string - EXAMPLES: + EXAMPLES:: + sage: C = sage.server.notebook.interact.control('a control') sage: C.set_label('sage'); C Interative control 'sage' (abstract base class) @@ -1993,18 +2367,22 @@ def __init__(self, default=None, label=None, type=None, width = 80): r""" An input box interactive control. Use this in conjunction - with the interact command. - - \code{input_box(default=None, label=None, type=None)} + with the :func:`interact` command. INPUT: - default -- object; the default put in this input box - label -- the label rendered to the left of the box. - type -- coerce inputs to this; this doesn't have to be - an actual type, since anything callable will do. - width -- width of text box in characters + + - ``default`` - an object; the default put in this input box + + - ``label`` - a string; the label rendered to the left of the + box. + + - ``type`` - a type; coerce inputs to this; this doesn't + have to be an actual type, since anything callable will do. + + - ``width`` - an integer; width of text box in characters - EXAMPLES: + EXAMPLES:: + sage: input_box("2+2", 'expression') Interact input box labeled 'expression' with default value '2+2' sage: input_box('sage', label="Enter your name", type=str) @@ -2019,7 +2397,12 @@ """ Return print representation of this input box. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: input_box("2+2", 'expression').__repr__() "Interact input box labeled 'expression' with default value '2+2'" """ @@ -2029,7 +2412,12 @@ """ Return the default value of this input box. - EXAMPLES: + OUTPUT: + + - an object + + EXAMPLES:: + sage: input_box('2+2', 'Expression').default() '2+2' sage: input_box(x^2 + 1, 'Expression').default() @@ -2042,10 +2430,15 @@ def type(self): """ Return the type that elements of this input box are coerced to - or None if they are not coerced (they have whatever type they - evaluate to). + or None if they are not coerced (they have whatever type + they evaluate to). - EXAMPLES: + OUTPUT: + + - a type + + EXAMPLES:: + sage: input_box("2+2", 'expression', type=int).type() sage: input_box("2+2", 'expression').type() is None @@ -2055,17 +2448,21 @@ def render(self, var): r""" - Return rendering of this input box as an InputBox to be used - for an interact canvas. Basically this specializes this - input to be used for a specific function and variable. + Return rendering of this input box as an :class:`InputBox` to be + used for an :func:`interact` canvas. Basically this specializes + this input to be used for a specific function and variable. INPUT: - var -- a string (variable; one of the variable names input to f) + + - ``var`` - a string (variable; one of the variable names + input to ``f``) OUTPUT: - InputBox -- an InputBox object. - EXAMPLES: + - an :class:`InputBox` instance + + EXAMPLES:: + sage: input_box("2+2", 'Exp').render('x') An InputBox interactive control with x='2+2' and label 'Exp' """ @@ -2079,19 +2476,27 @@ def __init__(self, nrows, ncols, default=None, label=None, to_value=lambda x: x, width=4): r""" An input grid interactive control. Use this in conjunction - with the interact command. + with the :func:`interact` command. INPUT: - nrows -- integer - ncols -- integer - default -- object; the default put in this input box - label -- the label rendered to the left of the box. - to_value -- the grid output (list of rows) is sent through - this function. This may reformat the data or - coerce the type. - width -- size of each input box in characters + + - ``nrows`` - an integer + + - ``ncols`` - an integer + + - ``default`` - an object; the default put in this input box + + - ``label`` - a string; the label rendered to the left of the + box. + + - ``to_value`` - a list; the grid output (list of rows) is + sent through this function. This may reformat the data or + coerce the type. + + - ``width`` - an integer; size of each input box in characters NOTEBOOK EXAMPLE: + @interact def _(m = input_grid(2,2, default = [[1,7],[3,4]], label='M=', to_value=matrix), @@ -2103,8 +2508,8 @@ except: html('There is no solution to $$%s x=%s$$'%(latex(m), latex(v))) + EXAMPLES:: - EXAMPLES: sage: input_grid(2,2, default = 0, label='M') Interact 2 x 2 input grid control labeled M with default value 0 sage: input_grid(2,2, default = [[1,2],[3,4]], label='M') @@ -2126,7 +2531,12 @@ """ Return print representation of this input box. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: input_grid(2,2, label='M').__repr__() 'Interact 2 x 2 input grid control labeled M with default value None' @@ -2140,7 +2550,12 @@ """ Return the default value of this input grid. - EXAMPLES: + OUTPUT: + + - an object + + EXAMPLES:: + sage: input_grid(2,2, default=1).default() 1 """ @@ -2149,17 +2564,21 @@ def render(self, var): r""" - Return rendering of this input grid as an InputGrid to be used - for an interact canvas. Basically this specializes this - input to be used for a specific function and variable. + Return rendering of this input grid as an :class:`InputGrid` to be + used for an :func:`interact` canvas. Basically this specializes + this input to be used for a specific function and variable. INPUT: - var -- a string (variable; one of the variable names input to f) + + - ``var`` - a string (variable; one of the variable names + input to ``f``) OUTPUT: - InputGrid -- an InputGrid object. - EXAMPLES: + - an :class:`InputGrid` instance. + + EXAMPLES:: + sage: input_grid(2,2).render('x') A 2 x 2 InputGrid interactive control with x=[[None, None], [None, None]] and label 'x' @@ -2171,14 +2590,19 @@ class checkbox(input_box): def __init__(self, default=True, label=None): """ - A checkbox interactive control. Use this in conjecture - with the interact command. + A checkbox interactive control. Use this in conjunction with + the :func:`interact` command. INPUT: - default -- bool (default: True); whether box should be checked or not - label -- str or None (default: None) text label rendered to the left of the box - EXAMPLES: + - ``default`` - a bool (default: True); whether box should be + checked or not + + - ``label`` - a string (default: None) text label rendered to + the left of the box + + EXAMPLES:: + sage: checkbox(False, "Points") Interact checkbox labeled 'Points' with default value False sage: checkbox(True, "Points") @@ -2194,7 +2618,12 @@ """ Print representation of this checkbox. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: checkbox(True, "Points").__repr__() "Interact checkbox labeled 'Points' with default value True" """ @@ -2248,11 +2677,13 @@ Returns list of values that this slider takes on, in order. OUTPUT: - list -- list of values - WARNING: This is a reference to a mutable list. + - a list - EXAMPLES: + .. note:: This is a reference to a mutable list. + + EXAMPLES:: + sage: sage.server.notebook.interact.slider(1,10,1/2).values() [1, 3/2, 2, 5/2, 3, 7/2, 4, 9/2, 5, 11/2, 6, 13/2, 7, 15/2, 8, 17/2, 9, 19/2, 10] """ @@ -2263,9 +2694,11 @@ Returns whether to display the value on the slider. OUTPUT: - boolean + + - a bool - EXAMPLES: + EXAMPLES:: + sage.server.notebook.interact.slider_generic(1,10,1/2).display_value() True """ @@ -2276,33 +2709,43 @@ def __init__(self, vmin, vmax=None, step_size=None, default=None, label=None, display_value=True): r""" An interactive slider control, which can be used in conjunction - with the interact command. - - \code{slider(vmin, vmax=None, step_size=1, default=None, label=None)} + with the :func:`interact` command. INPUT: - vmin -- object or number - vmax -- object or None; if None then vmin must be a list, and the slider - then varies over elements of the list. - step_size -- integer (default: 1) - default -- object or None; default value is ``closest'' in vmin or range - to this default. - label -- string - display_value -- boolean, whether to display the current value to the right - of the slider - EXAMPLES: - We specify both vmin and vmax. We make the default 3, but - since 3 isn't one of 3/17-th spaced values between 2 and 5, - 52/17 is instead chosen as the default (it is closest). + - ``vmin`` - an object + + - ``vmax`` - an object (default: None); if None then ``vmin`` + must be a list, and the slider then varies over elements of + the list. + + - ``step_size`` - an integer (default: 1) + + - ``default`` - an object (default: None); default value is + "closest" in ``vmin`` or range to this default. + + - ``label`` - a string + + - ``display_value`` - a bool, whether to display the current + value to the right of the slider + + EXAMPLES:: + + We specify both ``vmin`` and ``vmax``. We make the default + `3`, but since `3` isn't one of `3/17`-th spaced values + between `2` and `5`, `52/17` is instead chosen as the + default (it is closest):: + sage: slider(2, 5, 3/17, 3, 'alpha') Slider: alpha [2--|52/17|---5] - Here we give a list: + Here we give a list:: + sage: slider([1..10], None, None, 3, 'alpha') Slider: alpha [1--|3|---10] - The elements of the list can be anything: + The elements of the list can be anything:: + sage: slider([1, 'x', 'abc', 2/3], None, None, 'x', 'alpha') Slider: alpha [1--|x|---2/3] """ @@ -2329,7 +2772,12 @@ """ Return string representation of this slider. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: slider(2, 5, 1/5, 3, 'alpha').__repr__() 'Slider: alpha [2--|3|---5]' """ @@ -2343,9 +2791,11 @@ Return default index into the list of values. OUTPUT: - int - EXAMPLES: + - an integer + + EXAMPLES:: + sage: slider(2, 5, 1/2, 3, 'alpha').default_index() 2 """ @@ -2353,13 +2803,19 @@ def render(self, var): """ - Render the interact control for the given function and + Render the :func:`interact` control for the given function and variable. INPUT: - var -- string; variable name - EXAMPLES: + - ``var`` - a string; variable name + + OUTPUT: + + - a :class:`Slider` instance + + EXAMPLES:: + sage: S = slider(0, 10, 1, default=3, label='theta'); S Slider: theta [0--|3|---10] sage: S.render('x') @@ -2375,30 +2831,37 @@ def __init__(self, vmin, vmax=None, step_size=None, default=None, label=None, display_value=True): r""" An interactive range slider control, which can be used in conjunction - with the interact command. + with the :func:`interact` command. - \code{range_slider(vmin, vmax=None, step_size=1, default=None, label=None)} - INPUT: - vmin -- object or number - vmax -- object or None; if None then vmin must be a list, and the slider - then varies over elements of the list. - step_size -- integer (default: 1) - default -- (object, object) or None; default range is ``closest'' in vmin or range - to this default. - label -- string - display_value -- boolean, whether to display the current value below - the slider - EXAMPLES: - We specify both vmin and vmax. We make the default (3,4) but - since neither is one of 3/17-th spaced values between 2 and 5, - the closest values: 52/17 and 67/17, are instead chosen as the - default. + - ``vmin`` - an object + + - ``vmax`` - object or None; if None then ``vmin`` must be a + list, and the slider then varies over elements of the list. + + - ``step_size`` - integer (default: 1) + + - ``default`` - a 2-tuple of objects (default: None); default + range is "closest" in ``vmin`` or range to this default. + + - ``label`` - a string + + - ``display_value`` - a bool, whether to display the current + value below the slider + + EXAMPLES:: + + We specify both ``vmin`` and ``vmax``. We make the default + `(3,4)` but since neither is one of `3/17`-th spaced + values between `2` and `5`, the closest values: `52/17` + and `67/17`, are instead chosen as the default:: + sage: range_slider(2, 5, 3/17, (3,4), 'alpha') Range Slider: alpha [2--|52/17==67/17|---5] - Here we give a list: + Here we give a list:: + sage: range_slider([1..10], None, None, (3,7), 'alpha') Range Slider: alpha [1--|3==7|---10] """ @@ -2430,7 +2893,12 @@ """ Return string representation of this slider. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: range_slider(2, 5, 1/5, (3,4), 'alpha').__repr__() 'Range Slider: alpha [2--|3==4|---5]' """ @@ -2443,9 +2911,11 @@ Return default index into the list of values. OUTPUT: - (int, int) - EXAMPLES: + - an integer 2-tuple + + EXAMPLES:: + sage: range_slider(2, 5, 1/2, (3,4), 'alpha').default_index() (2, 4) """ @@ -2453,13 +2923,19 @@ def render(self, var): """ - Render the interact control for the given function and + Render the :func:`interact` control for the given function and variable. INPUT: - var -- string; variable name - EXAMPLES: + - ``var`` - string; variable name + + OUTPUT: + + - a :class:`RangeSlider` instance + + EXAMPLES:: + sage: S = range_slider(0, 10, 1, default=(3,7), label='theta'); S Range Slider: theta [0--|3==7|---10] sage: S.render('x') @@ -2477,32 +2953,42 @@ r""" A drop down menu or a button bar that when pressed sets a variable to a given value. Use this in conjunction with the - interact command. - - \code{selector(values, label=None, nrows=None, ncols=None, buttons=False)} + :func:`interact` command. We use the same command to create either a drop down menu or selector bar of buttons, since conceptually the two controls - do exactly the same thing -- they only look different. If - either nrows or ncols is given, then you get a buttons instead - of a drop down menu. + do exactly the same thing - they only look different. If + either ``nrows`` or ``ncols`` is given, then you get a buttons + instead of a drop down menu. INPUT: - values -- [val0, val1, val2, ...] or - [(val0, lbl0), (val1,lbl1), ...] where all labels must be - given or given as None. - label -- (default: None); if given, this label is placed to - the left of the entire button group - default -- object (default: 0) default value in values list - nrows -- (default: None); if given determines the number - of rows of buttons; if given buttons option below is set to True - ncols -- (default: None); if given determines the number - of columns of buttons; if given buttons option below is set to True - width -- (default: None); if given, all buttons are the same - width, equal to this in html ex units's. - buttons -- (default: False); if True, use buttons - EXAMPLES: + - ``values`` - [val0, val1, val2, ...] or [(val0, lbl0), + (val1,lbl1), ...] where all labels must be given or given as + None. + + - ``label`` - a string (default: None); if given, this label + is placed to the left of the entire button group + + - ``default`` - an object (default: 0); default value in values + list + + - ``nrows`` - an integer (default: None); if given determines + the number of rows of buttons; if given buttons option below + is set to True + + - ``ncols`` - an integer (default: None); if given determines + the number of columns of buttons; if given buttons option + below is set to True + + - ``width`` - an integer (default: None); if given, all + buttons are the same width, equal to this in HTML ex + units's. + + - ``buttons`` - a bool (default: False); if True, use buttons + + EXAMPLES:: + sage: selector([1..5]) Drop down menu with 5 options sage: selector([1,2,7], default=2) @@ -2516,7 +3002,9 @@ sage: selector([1,2,7], buttons=True) Button bar with 3 buttons - We create an interactive that involves computing charpolys of matrices over various rings: + We create an :func:`interact` that involves computing charpolys of + matrices over various rings:: + sage: @interact ... def _(R=selector([ZZ,QQ,GF(17),RDF,RR]), n=(1..10)): ... M = random_matrix(R, n) @@ -2526,7 +3014,8 @@ ... print f ... - Here we create a drop-down + Here we create a drop-down:: + sage: @interact ... def _(a=selector([(2,'second'), (3,'third')])): ... print a @@ -2553,7 +3042,12 @@ """ Return print representation of this button. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: selector([1,2,7], default=2).__repr__() 'Drop down menu with 3 options' """ @@ -2568,9 +3062,11 @@ selector can take on. OUTPUT: - list - EXAMPLES: + - a list + + EXAMPLES:: + sage: selector([1..5]).values() [1, 2, 3, 4, 5] sage: selector([(5,'fifth'), (8,'eight')]).values() @@ -2583,9 +3079,11 @@ Return the default choice for this control. OUTPUT: - int -- an integer, with 0 corresponding to the first choice. - EXAMPLES: + - an integer, with 0 corresponding to the first choice. + + EXAMPLES:: + sage: selector([1,2,7], default=2).default() 1 """ @@ -2593,16 +3091,20 @@ def render(self, var): r""" - Return rendering of this button as a Button instance to be - used for an interact canvas. + Return rendering of this button as a :class:`Selector` + instance to be used for an :func:`interact` canvas. INPUT: - var -- a string (variable; one of the variable names input to f) + + - ``var`` - a string (variable; one of the variable names + input to ``f``) OUTPUT: - Button -- a Button instance - EXAMPLES: + - a :class:`Selector` instance + + EXAMPLES:: + sage: selector([1..5]).render('alpha') Selector with 5 options for variable 'alpha' """ @@ -2614,12 +3116,14 @@ class text_control(control): def __init__(self, value=''): """ - Text that can be inserted among other interact controls. + Text that can be inserted among other :func:`interact` controls. INPUT: - value -- HTML for the control - EXAMPLES: + - ``value`` - HTML for the control + + EXAMPLES:: + sage: text_control('something') Text field: something """ @@ -2630,7 +3134,12 @@ """ Return print representation of this control. - EXAMPLES: + OUTPUT: + + - a string + + EXAMPLES:: + sage: text_control('something') Text field: something """ @@ -2641,10 +3150,13 @@ Return rendering of the text field INPUT: - var -- a string (variable; one of the variable names input to f) + + - ``var`` - a string (variable; one of the variable names + input to ``f``) OUTPUT: - TextControl -- a TextControl instance + + - a :class:`TextControl` instance """ return TextControl(var, self.__default) @@ -2655,13 +3167,16 @@ value of the variable. INPUT: - default -- the default value for v given by the function; see - the documentation to interact? for details. + + - ``default`` - the default value for ``v`` given by the function; + see the documentation to :func:`interact` for details. OUTPUT: - a interact control - EXAMPLES: + - an :func:`interact` control + + EXAMPLES:: + sage: sage.server.notebook.interact.automatic_control('') Interact input box labeled None with default value '' sage: sage.server.notebook.interact.automatic_control(15) @@ -2737,13 +3252,17 @@ Given an iterator v, return first n elements it produces as a list. INPUT: - v -- an iterator - n -- an integer + + - ``v`` - an iterator + + - ``n`` - an integer OUTPUT: - list - EXAMPLES: + - a list + + EXAMPLES:: + sage: sage.server.notebook.interact.list_of_first_n(Primes(), 10) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29] sage: sage.server.notebook.interact.list_of_first_n((1..5), 10) @@ -2764,22 +3283,29 @@ def update(cell_id, var, adapt, value, globs): - """ + r""" Called when updating the positions of an interactive control. Note that this just causes the values of the variables to be updated; it does not reevaluate the function with the new values. INPUT: - cell_id -- the id of a interact cell - var -- a variable associated to that cell - adapt -- the number of the adapt function - value -- new value of the control - globs -- global variables. + + - ``cell_id`` - an integer; the id of an :func:`interact` cell + + - ``var`` - an object; a variable associated to that cell + + - ``adapt`` - in integer; the number of the adapt function + + - ``value`` - an object; new value of the control + + - ``globs`` - global variables. EXAMPLES: + The following outputs __SAGE_INTERACT_RESTART__ to indicate that - not all the state of the interrupt canvas has been setup yet (this - setup happens when javascript calls certain functions). + not all the state of the :func:`interact` canvas has been set up yet + (this setup happens when JavaScript calls certain functions):: + sage: sage.server.notebook.interact.update(0, 'a', 0, '5', globals()) __SAGE_INTERACT_RESTART__ """ @@ -2795,14 +3321,20 @@ def recompute(cell_id): """ - Evaluates the interact function associated to the cell - cell_id. This typically gets called after a call to - sage.server.notebook.interact.update. + Evaluates the :func:`interact` function associated to the cell + ``cell_id``. This typically gets called after a call to + :func:`update`. + INPUT: + + - ``cell_id`` - an integer + EXAMPLES: + The following outputs __SAGE_INTERACT_RESTART__ to indicate that - not all the state of the interrupt canvas has been setup yet (this - setup happens when javascript calls certain functions). + not all the state of the :func:`interact` canvas has been set up yet + (this setup happens when JavaScript calls certain functions):: + sage: sage.server.notebook.interact.recompute(10) __SAGE_INTERACT_RESTART__ diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/js.py --- a/sage/server/notebook/js.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/js.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,5 +1,5 @@ r"""nodoctest -Javascript (AJAX) Component of \sage Notebook +JavaScript (AJAX) Components of the Notebook AUTHORS: diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/notebook.py --- a/sage/server/notebook/notebook.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/notebook.py Mon Aug 10 06:52:10 2009 -0700 @@ -182,11 +182,9 @@ Create the default users for a notebook. INPUT: - - + - ``passwd`` - a string - EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -213,8 +211,16 @@ def user_exists(self, username): """ - Return whether or not a user exists given a username. + Return whether a user with the given ``username`` exists. + INPUT: + + - ``username`` - a string + + OUTPUT: + + - a bool + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -233,8 +239,12 @@ def users(self): """ - Return dictionary of users in a notebook. + Return a dictionary of users in a notebook. + OUTPUT: + + - a string:User instance dictionary + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -251,9 +261,17 @@ def user(self, username): """ - Return an instance of the User class given the username of a user + 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 = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -284,17 +302,14 @@ def create_user_with_same_password(self, user, other_user): r""" + Change the password of ``user`` to that of ``other_user``. + INPUT: - - ``user`` - a string - ``other_user`` - a string - - OUTPUT: Changes password of ``user`` to that of - ``other_user``. - EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -315,11 +330,21 @@ def user_is_admin(self, user): """ + Return true if ``user`` is an admin. + + INPUT: + + - ``user`` - an instance of User + + OUTPUT: + + - a bool + EXAMPLES:: 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.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') @@ -329,6 +354,16 @@ def user_is_guest(self, username): """ + Return true if ``username`` is a guest. + + INPUT: + + - ``username`` - a string + + OUTPUT: + + - a bool + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -346,8 +381,12 @@ def user_list(self): """ - Return list of user objects. + Return a list of user objects. + OUTPUT: + + - a list of User instances + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -360,8 +399,12 @@ def usernames(self): """ - Return list of usernames. + Return a list of usernames. + OUTPUT: + + - a list of strings + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -375,8 +418,12 @@ def valid_login_names(self): """ - Return list of users that can be signed in. + Return a list of users that can log in. + OUTPUT: + + - a list of strings + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -384,23 +431,24 @@ 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: 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'] """ return [x for x in self.usernames() if not x in ['guest', '_sage_', 'pub']] def default_user(self): - """ - Return a default login name that the user will see when confronted - with the Sage notebook login page. + r""" + Return a default login name that the user will see when + confronted with the Sage notebook login page. Currently, this + returns 'admin' if that is the *only* user. Otherwise it + returns an empty string (''). - OUTPUT: string - - Currently this returns 'admin' if that is the *only* user. - Otherwise it returns the string ". + OUTPUT: + + - a string - the default username. EXAMPLES:: @@ -409,7 +457,7 @@ Creating default users. sage: nb.default_user() 'admin' - sage: nb.add_user('AnotherUser', 'password', ", force=True) + sage: nb.add_user('AnotherUser', 'password', '', force=True) sage: nb.default_user() '' """ @@ -420,8 +468,12 @@ def set_accounts(self, value): r""" - Changes ``__accounts`` to ``value`` + Set the attribute ``__accounts`` to ``value``. + INPUT: + + - ``value`` - a bool + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -438,8 +490,12 @@ def get_accounts(self): r""" - Return ``__accounts`` + Return ``__accounts``. + OUTPUT: + + - a bool + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -457,28 +513,27 @@ def add_user(self, username, password, email, account_type="user", force=False): """ + Add a user with the given credentials. + INPUT: - - + - ``username`` - the username - ``password`` - the password - ``email`` - the email address - - ``account_type`` - one of 'user', 'admin', or - 'guest' + - ``account_type`` - one of 'user', 'admin', or 'guest' - - ``force`` - bool + - ``force`` - a bool (default: False) - - If the method get_accounts return False then user can only be - added if force=True - + If the method :meth:`get_accounts` returns False then user can + only be added if ``force`` is True. + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) - sage: nb.add_user('Mark', 'password', ", force=True) + sage: nb.add_user('Mark', 'password', '', force=True) sage: nb.user('Mark') Mark sage: nb.add_user('Sarah', 'password', ") @@ -500,19 +555,18 @@ def change_password(self, username, password): """ + Change a user's password. + INPUT: + - ``username`` - a string, the username - - ``username`` - the username - - - ``password`` - the password to change the user's - password to - + - ``password`` - a string, the user's new password EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) - sage: nb.add_user('Mark', 'password', ", force=True) + sage: nb.add_user('Mark', 'password', '', force=True) sage: nb.user('Mark').password() 'aajfMKNH1hTm2' sage: nb.change_password('Mark', 'different_password') @@ -523,12 +577,16 @@ def del_user(self, username): """ - Deletes the given user + Delete the given user. + INPUT: + + - ``username`` - a string + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) - sage: nb.add_user('Mark', 'password', ", force=True) + sage: nb.add_user('Mark', 'password', '', force=True) sage: nb.user('Mark') Mark sage: nb.del_user('Mark') @@ -542,14 +600,18 @@ def passwords(self): """ - Return the username:password dictionary. + Return a username:password dictionary. + OUTPUT: + + - a string:string dictionary + EXAMPLES:: 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: nb.add_user('Mark', 'password', '', force=True) sage: list(sorted(nb.passwords().iteritems())) [('Mark', 'aajfMKNH1hTm2'), ('_sage_', 'aaQSqAReePlq6'), ('admin', 'aajfMKNH1hTm2'), ('guest', 'aaQSqAReePlq6'), ('pub', 'aaQSqAReePlq6')] """ @@ -557,8 +619,12 @@ def user_conf(self, username): """ - Return a user's configuration. + Return a user's configuration object. + OUTPUT: + + - an instance of Configuration. + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -581,8 +647,13 @@ ########################################################## def _initialize_worksheet(self, src, W): r""" - ``src`` and ``W`` are worksheets and - ``W`` is brand new. + Initialize a new worksheet from a source worksheet. + + INPUT: + + - ``src`` - a Worksheet instance; the source + + - ``W`` - a new Worksheet instance; the target """ # Copy over images and other files data = src.data_directory() @@ -595,15 +666,23 @@ def publish_worksheet(self, worksheet, username): r""" - Publish the given worksheet. + Publish a user's worksheet. This creates a new worksheet in + the 'pub' directory with the same contents as ``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 = sage.server.notebook.notebook.Notebook(tmp_dir()) - sage: nb.add_user('Mark','password',",force=True) + 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'] @@ -691,7 +770,11 @@ def delete_worksheet(self, filename): """ Delete the given worksheet and remove its name from the worksheet - list. + list. Raise a KeyError, if it is missing. + + INPUT: + + - ``filename`` - a string """ if not (filename in self.__worksheets.keys()): print self.__worksheets.keys() @@ -715,10 +798,8 @@ 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. @@ -745,7 +826,9 @@ """ Return a list of all the names of worksheets in this notebook. - OUTPUT: list of strings. + OUTPUT: + + - a list of strings. EXAMPLES: We make a new notebook with two users and two worksheets, then list their names:: @@ -764,8 +847,9 @@ def migrate_old(self): """ - Migrate all old worksheets, i.e., ones with no owner, to - ``/pub``. + Migrate all old worksheets, i.e., those with no owner, to + ``/pub``. Currently, this always raises a + NotImplementedError. """ raise NotImplementedError for w in self.__worksheets.itervalues(): @@ -927,21 +1011,16 @@ ########################################################## def export_worksheet(self, worksheet_filename, output_filename, verbose=True): """ - Export a worksheet with given directory filenmae to - output_filename. + Export a worksheet, creating a sws file on the file system. INPUT: + - ``worksheet_filename`` - a string - - ``worksheet_filename`` - string + - ``output_filename`` - a 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 + - ``verbose`` - a bool (default: True); if True, print the tar + command used to create the sws file. """ W = self.get_worksheet_with_filename(worksheet_filename) W.save() @@ -968,22 +1047,19 @@ def import_worksheet(self, filename, owner): r""" - Upload the worksheet with name ``filename`` and make it - have the given owner. + Import a worksheet with the given ``filename`` and set its + ``owner``. If the file extension is not txt or sws, raise a + ValueError. INPUT: - - ``filename`` - a string - ``owner`` - a string - OUTPUT: - - - ``worksheet`` - a newly created worksheet - + - ``worksheet`` - a newly created Worksheet instance EXAMPLES: We create a notebook and import a plain text worksheet into it. @@ -1024,14 +1100,13 @@ INPUT: + - ``filename`` - a string; a filename that ends in .txt - - ``filename`` - string; a filename that ends in .txt + - ``owner`` - a string; the imported worksheet's owner - - ``owner`` - string; who will own this worksheet when - imported - - - OUTPUT: a new worksheet + OUTPUT: + + - a new instance of Worksheet EXAMPLES: We write a plain text worksheet to a file and import it using this function. @@ -1055,21 +1130,22 @@ def _import_worksheet_sws(self, filename, owner, verbose=True): r""" Import an sws format worksheet into this notebook as a new - worksheet. + worksheet. If the worksheet cannot be read, raise a + ValueError. INPUT: - - - ``filename`` - string; a filename that ends in .sws; + - ``filename`` - a string; a filename that ends in .sws; internally it must be a tar'd bz2'd file. - - ``owner`` - string + - ``owner`` - a string - - ``verbose`` - bool (default: True) if True print - some the tar command used to extract the sws file. + - ``verbose`` - a bool (default: True) if True print some the + tar command used to extract the sws file. - - OUTPUT: a new worksheet + OUTPUT: + + - a new Worksheet instance EXAMPLES: We create a notebook, then make a worksheet from a plain text file first. @@ -1096,7 +1172,7 @@ sage: nb._import_worksheet_sws('tmp.sws', 'admin', verbose=False) [Cell 0; in=2+3, out=] - Yep, it's there now (as admin/2):: + Yes, it's there now (as admin/2):: sage: nb.worksheet_names() ['admin/0', 'admin/2'] @@ -1167,14 +1243,18 @@ def plain_text_worksheet_html(self, filename, prompts=True): """ - Outputs html containing the plain text version of a worksheet + Return HTML containing the plain text version of a worksheet. INPUT: - - ``filename`` - filename of a worksheet - - ``prompts`` - boolean + + - ``filename`` - a string; filename of a worksheet + + - ``prompts`` - a bool (default: True); whether to format the + text for inclusion in docstrings OUTPUT: - - A string containing the html for the plain text version + + - a string - the worksheet's HTML representation """ worksheet = self.get_worksheet_with_filename(filename) text = escape(worksheet.plain_text(prompts = prompts)) @@ -1193,8 +1273,12 @@ def DIR(self): """ - Return the absolute path to the directory that contains the Sage - Notebook directory. + Return the absolute path to the parent of this Notebook + instance's home directory. + + OUTPUT: + + - a string """ P = os.path.abspath('%s/..'%self.__dir) if not os.path.exists(P): @@ -1309,15 +1393,19 @@ return s def worksheet_html(self, filename, do_print=False): - """ - Returns the HTML for the worksheet. + r""" + Return the HTML for a given worksheet. INPUT: - - ``username`` - a string - - ``worksheet`` - an instance of Worksheet + + - ``filename`` - a string; the worksheet's filename + + - ``do_print`` - a bool (default: False); whether this is a + printed worksheet OUTPUT: - - a string containing the HTML + + - a string - the worksheet rendered as HTML EXAMPLES:: @@ -1359,15 +1447,18 @@ # Revision history for a worksheet ########################################################## def html_worksheet_revision_list(self, username, worksheet): - """ - Returns the HTML for the revision list of a worksheet. + r""" + Return HTML for the revision list of a worksheet. INPUT: + - ``username`` - a string + - ``worksheet`` - an instance of Worksheet OUTPUT: - - a string containing the HTML + + - a string - the HTML for the revision list EXAMPLES:: @@ -1389,16 +1480,20 @@ def html_specific_revision(self, username, ws, rev): - """ - Returns the HTML for a revision of the worksheet. + r""" + 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 containing the HTML + + - a string - the revision rendered as HTML """ t = time.time() - float(rev[:-4]) time_ago = worksheet.convert_seconds_to_meaningful_time_span(t) @@ -1434,15 +1529,18 @@ def html_share(self, worksheet, username): - """ - Returns the HTML for the share page of a worksheet. + r""" + Return the HTML for the "share" page of a worksheet. INPUT: + - ``username`` - a string + - ``worksheet`` - an instance of Worksheet OUTPUT: - - a string containing the HTML + + - string - the share page's HTML representation EXAMPLES:: @@ -1466,16 +1564,20 @@ def html_download_or_delete_datafile(self, ws, username, filename): - """ - Returns the HTML for the download or delete datafile page. + r""" + Return the HTML for the download or delete datafile page. INPUT: + - ``username`` - a string + - ``ws`` - an instance of Worksheet - - ``filename`` - the name of the file + + - ``filename`` - a string; the name of the file OUTPUT: - - a string containing the HTML + + - a string - the page rendered as HTML EXAMPLES:: @@ -1554,10 +1656,16 @@ def get_worksheet_with_filename(self, filename): """ - Get the worksheet with given filename. If there is no such - worksheet, raise a ``KeyError``. + Get the worksheet with the given filename. If there is no + such worksheet, raise a ``KeyError``. - INPUT: string OUTPUT: a worksheet or KeyError + INPUT: + + - ``filename`` - a string + + OUTPUT: + + - a Worksheet instance """ if self.__worksheets.has_key(filename): return self.__worksheets[filename] @@ -1613,39 +1721,37 @@ # HTML -- generate most html related to the whole notebook page ########################################################### def html_debug_window(self): - """ - Returns the HTML for the debug window + r""" + Return the HTML for the debug window. OUTPUT: - - the HTML for the debug window + + - a string - the debug window rendered as HTML EXAMPLES:: - sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) - sage: print(nb.html_debug_window()) -
-
- -
+ sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) + sage: nb.html_debug_window() + "\n
...
" """ return template("notebook/debug_window.html") def html_plain_text_window(self, worksheet, username): - """ - Returns a window that displays a plain text version of the - worksheet - + r""" + Return HTML for the window that displays a plain text version + of the worksheet. + INPUT: - - ``worksheet`` - a worksheet - - ``username`` - name of the user + + - ``worksheet`` - a Worksheet instance + + - ``username`` - a string OUTPUT: - - a window that displays a plain text version of the - worksheet - + + - a string - the plain text window rendered as HTML + EXAMPLES:: sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) @@ -1666,14 +1772,17 @@ def html_edit_window(self, worksheet, username): r""" - Return a window for editing ``worksheet``. + Return HTML for a window for editing ``worksheet``. INPUT: + - ``username`` - a string containing the username + - ``worksheet`` - a Worksheet instance OUTPUT: - - html for a window for editing ``worksheet``. + + - a string - the editing window's HTML representation EXAMPLES:: @@ -1695,13 +1804,19 @@ sage_jsmath_macros = sage_jsmath_macros) def 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. + r""" + Return HTML for the warning and decision page displayed prior + to publishing the given worksheet. INPUT: - - ``worksheet`` - instance of Worksheet - - ``username`` - string + + - ``worksheet`` - an instance of Worksheet + + - ``username`` - a string + + OUTPUT: + + - a string - the pre-publication page rendered as HTML EXAMPLES:: @@ -1728,15 +1843,25 @@ sage_jsmath_macros = sage_jsmath_macros) def html_afterpublish_window(self, worksheet, username, url, dtime): - """ - Return the html code for a page dedicated to worksheet publishing - after the publication of the given worksheet. + r""" + Return HTML for a given worksheet's post-publication page. INPUT: - - ``worksheet`` - instance of Worksheet - - ``username`` - string - - ``url`` - a string representing the url of the published worksheet - - ``dtime`` - instance of time.struct_time representing the publishing time + + - ``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 + """ from time import strftime time = strftime("%B %d, %Y %I:%M %p", dtime) @@ -1750,12 +1875,18 @@ sage_jsmath_macros = sage_jsmath_macros) def html_upload_data_window(self, ws, username): - """ - Returns the html for the "Upload Data" window + r""" + Return HTML for the "Upload Data" window. INPUT: - - ``worksheet`` - instance of Worksheet - - ``username`` - string + + - ``worksheet`` - an instance of Worksheet + + - ``username`` - a string + + OUTPUT: + + - a string - the HTML representation of the data upload window EXAMPLES:: @@ -1773,14 +1904,22 @@ def html(self, worksheet_filename=None, username='guest', show_debug=False, admin=False): - """ - Returns the html for index page of a worksheet. + r""" + Return the HTML for a worksheet's index page. INPUT: - - ``worksheet_filename`` - a string - - ``username`` - a string - - ``show_debug`` - a boolean - - ``admin`` - a boolean + + - ``worksheet_filename`` - a string (default: None) + + - ``username`` - a string (default: 'guest') + + - ``show_debug`` - a bool (default: False) + + - ``admin`` - a bool (default: False) + + OUTPUT: + + - a string - the worksheet rendered as HTML EXAMPLES:: @@ -1820,12 +1959,18 @@ def html_worksheet_settings(self, ws, username): - """ - Returns the html for the setings page of the worksheet. + r""" + Return the HTML for a worksheet's settings page. INPUT: - - ``ws`` - instance of Worksheet - - ``username`` - string + + - ``ws`` - an instance of Worksheet + + - ``username`` - a string + + OUTPUT: + + - a string - HTML representation of the settings page EXAMPLES:: @@ -1856,14 +2001,16 @@ return s def html_doc(self, username): - """ - Returns the html for the documentation pages. + r""" + Return the HTML for the a documentation page. INPUT: - - ``worksheet_filename`` - a string + - ``username`` - a string - - ``show_debug`` - a boolean - - ``admin`` - a boolean + + OUTPUT: + + - a string - the doc page rendered as HTML EXAMPLES:: @@ -1883,20 +2030,22 @@ def 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. + 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 - - ``address`` - the address that the notebook server - will listen on + - ``address`` - the address the server listens at - ``port`` - the port the server listens on - - ``secure`` - whether or not the notebook is secure + - ``secure`` - whether the notebook is secure + + OUTPUT: + + - a Notebook instance """ sobj = '%s/nb.sobj'%dir nb = None @@ -1937,8 +2086,16 @@ def make_path_relative(dir): r""" - If easy, replace the absolute path ``dir`` by a - relative one. + 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 """ base, file = os.path.split(dir) if os.path.exists(file): @@ -1954,14 +2111,17 @@ def 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' - - ``sort`` - 'last_edited', 'owner', 'rating', or - 'name' - - - ``reverse`` - if True, reverse the order of the - sort. + - ``reverse`` - a bool; if True, reverse the order of the sort. + + OUTPUT: + + - the sorted list """ f = None if sort == 'last_edited': diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/sage_email.py --- a/sage/server/notebook/sage_email.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/sage_email.py Mon Aug 10 06:52:10 2009 -0700 @@ -6,7 +6,8 @@ email server or anything else, since Sage already includes by default a sophisticated email server (which is part of Twisted). -EXAMPLES: +EXAMPLES:: + sage: email('xxxsageuser@gmail.com', 'The calculation finished!') # not tested Child process ... is sending email to xxxsageuser@gmail.com @@ -32,7 +33,8 @@ OUTPUT: string - EXAMPLES: + EXAMPLES:: + sage: sage.server.notebook.sage_email.default_email_address() '...@...' """ @@ -64,7 +66,8 @@ be a problem, but might be useful for certain users. - EXAMPLES: + EXAMPLES:: + sage: email('xxxsageuser@gmail.com', 'The calculation finished!') # not tested Child process ... is sending email to xxxsageuser@gmail.com diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/sagetex.py --- a/sage/server/notebook/sagetex.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/sagetex.py Mon Aug 10 06:52:10 2009 -0700 @@ -8,7 +8,8 @@ THIS IS ONLY A PROOF-of-CONCEPT. - EXAMPLES: + EXAMPLES:: + sage: sagetex('foo.tex') # not tested [pops up web browser with live version of foo.tex.] """ diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/template.py --- a/sage/server/notebook/template.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/template.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,10 +1,12 @@ # -*- coding: utf-8 -*- """ -HTML templating for the notebook +HTML Templating for the Notebook AUTHORS: - -- Bobby Moretti (2007-07-18): initial version - -- Timothy Clemans and Mike Hansen (2008-10-27): major update + + - Bobby Moretti (2007-07-18): initial version + + - Timothy Clemans and Mike Hansen (2008-10-27): major update """ ############################################################################# @@ -22,11 +24,17 @@ def contained_in(container): """ - Returns a function which takes in an environment, context, and value - and returns True if that value is in the container and False - otherwise. This is registered and used as a test in the templates. + Given a container, returns a function which takes an environment, + context, and value and returns True if that value is in the + container and False otherwise. This is registered and used as a + test in the templates. - EXAMPLES: + INPUT:: + + - ``container`` - a container, e.g., a list or dictionary + + EXAMPLES:: + sage: from sage.server.notebook.template import contained_in sage: f = contained_in([1,2,3]) sage: f(None, None, 2) @@ -48,13 +56,23 @@ def template(filename, **user_context): """ - Returns a rendered template as a string. + Returns HTML, CSS, etc., for a template file rendered in the given + context. INPUT: - filename -- the filename of the template relative to - $SAGE_ROOT/devel/sage/sage/server/notebook/templates - EXAMPLES: + - ``filename`` - a string; the filename of the template relative + to $SAGE_ROOT/devel/sage/sage/server/notebook/templates + + - ``user_context`` - a dictionary; the context in which to evaluate + the file's template variables + + OUTPUT: + + - a string - the rendered HTML, CSS, etc. + + EXAMPLES:: + sage: from sage.server.notebook.template import template sage: s = template('yes_no.html'); type(s) diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/twist.py --- a/sage/server/notebook/twist.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/twist.py Mon Aug 10 06:52:10 2009 -0700 @@ -134,7 +134,8 @@ Returns an HTMLResponse object whose 'Content-Type' header has been set to 'text/html; charset=utf-8 - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.twist import HTMLResponse sage: response = HTMLResponse(stream='TestTest') sage: response.headers diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/user.py --- a/sage/server/notebook/user.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/user.py Mon Aug 10 06:52:10 2009 -0700 @@ -63,7 +63,8 @@ def username(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: User('andrew', 'tEir&tiwk!', 'andrew@matrixstuff.com', 'user').username() 'andrew' @@ -79,7 +80,8 @@ def conf(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: config = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin').conf(); config Configuration: {} @@ -102,7 +104,8 @@ def password(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.password() @@ -112,7 +115,8 @@ def set_password(self, password): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: old = user.password() @@ -127,7 +131,8 @@ def set_hashed_password(self, password): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.set_hashed_password('Crrc!') @@ -138,7 +143,8 @@ def get_email(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.get_email() @@ -148,7 +154,8 @@ def set_email(self, email): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.get_email() @@ -161,7 +168,8 @@ def set_email_confirmation(self, value): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.is_email_confirmed() @@ -178,7 +186,8 @@ def is_email_confirmed(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.is_email_confirmed() @@ -192,7 +201,8 @@ def password_is(self, password): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') sage: user.password_is('ecc') @@ -206,7 +216,8 @@ def account_type(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: User('A', account_type='admin').account_type() 'admin' @@ -221,7 +232,8 @@ def is_admin(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: User('A', account_type='admin').is_admin() True @@ -232,7 +244,8 @@ def is_guest(self): """ - EXAMPLES: + EXAMPLES:: + sage: from sage.server.notebook.user import User sage: User('A', account_type='guest').is_guest() True diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/worksheet.py --- a/sage/server/notebook/worksheet.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/notebook/worksheet.py Mon Aug 10 06:52:10 2009 -0700 @@ -1236,7 +1236,7 @@ OUTPUT: - - ``string`` - a string of HTML as a bunch of table + - ``string`` -- a string of HTML as a bunch of table rows. @@ -2097,7 +2097,7 @@ - ``text`` - a string - ``ignore_ids`` - bool (default: False); if True - ignore all the id's in the code block. + ignore all the id's in the {{{}}} code block. EXAMPLES: We create a new test notebook and a worksheet. @@ -2212,13 +2212,18 @@ ########################################################## def html(self, include_title=True, do_print=False, confirm_before_leave=False, read_only=False): - """ - INPUT: + r""" + INPUT: + + - publish - a boolean stating whether the worksheet is published + - do_print - a boolean OUTPUT: - - returns the html for the worksheet + + + - string -- the html for the worksheet EXAMPLES:: @@ -2275,7 +2280,8 @@ def html_save_discard_buttons(self): r""" OUTPUT: - - returns the html for the save, discard, etc. buttons + + - string -- the html for the save, discard, etc. buttons EXAMPLES:: @@ -2289,11 +2295,16 @@ def html_share_publish_buttons(self, select=None, backwards=False): r""" INPUT: + + - select - a boolean + - backwards - a boolean OUTPUT: - - returns the html for the share, publish, etc. buttons + + + - string -- the html for the share, publish, etc. buttons EXAMPLES:: @@ -2310,9 +2321,10 @@ # def html_menu(self): - """ - OUTPUT: - - returns the html for the menus of the worksheet + r""" + OUTPUT: + + - string -- the html for the menus of the worksheet EXAMPLES:: @@ -2330,13 +2342,18 @@ doc_worksheet = self.is_doc_worksheet()) def html_worksheet_body(self, do_print, publish=False): - """ - INPUT: + r""" + INPUT: + + - publish - a boolean stating whether the worksheet is published + - do_print - a boolean OUTPUT: - - returns the html for the File menu of the worksheet + + + - string -- the html for the File menu of the worksheet EXAMPLES:: @@ -4020,11 +4037,16 @@ def format_completions_as_html(cell_id, completions): """ INPUT: + + - cell_id - id for the cell of the completions + - completions - list of completions in row-major order OUTPUT: - - html for the completions formatted in rows and columns + + + - string -- html for the completions formatted in rows and columns """ if len(completions) == 0: return '' diff -r 832b46058006 -r 6b319da23983 sage/server/simple/twist.py --- a/sage/server/simple/twist.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/simple/twist.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,5 +1,5 @@ r""" -Simple Sage API +Simple Sage Server API This module provides a very simple API for interacting with a Sage session over HTTP. It runs as part of the notebook server. diff -r 832b46058006 -r 6b319da23983 sage/server/support.py --- a/sage/server/support.py Fri Aug 14 18:37:05 2009 -0700 +++ b/sage/server/support.py Mon Aug 10 06:52:10 2009 -0700 @@ -1,9 +1,11 @@ """ -Support for the Notebook (introspection and setup) +Support for Notebook Introspection and Setup AUTHORS: - William Stein (much of this code is from IPython). + +- Nick Alexander """ import inspect @@ -70,7 +72,10 @@ ###################################################################### def help(obj): """ - Display help on s. + Display HTML help for ``obj``, a Python object, module, etc. This + help is often more extensive than that given by 'obj?'. This + function does not return a value --- it prints HTML as a side + effect. .. note:: @@ -79,12 +84,7 @@ INPUT: - - - ``s`` - Python object, module, etc. - - - OUTPUT: prints out help about s; it's often more more extensive - than foo? + - ``obj`` - a Python object, module, etc. TESTS:: @@ -122,7 +122,20 @@ def completions(s, globs, format=False, width=90, system="None"): """ - Return a list of completions in the context of globs. + Return a list of completions in the given context. + + INPUT: + + - ``globs`` - a string:object dictionary; context in which to + search for completions, e.g., :func:`globals()` + + - ``format`` - a bool (default: False); whether to tabulate the + list + + - ``width`` - an int; character width of the table + + - ``system`` - a string (default: 'None'); system prefix for the + completions """ if system not in ['sage', 'python']: prepend = system + '.' @@ -176,9 +189,24 @@ def docstring(obj_name, globs, system='sage'): r""" - Format ``obj_name``'s docstring for printing in Sage + Format an object's docstring to process and display in the Sage notebook. + INPUT: + + - ``obj_name`` - a string; a name of an object + + - ``globs`` - a string:object dictionary; a context in which to + evaluate ``obj_name`` + + - ``system`` - a string (default: 'sage'); the system to which to + confine the search + + OUTPUT: + + - a string containing the object's file, type, definition, and + docstring or a message stating the object is not defined + AUTHORS: - William Stein: partly taken from IPython for use in Sage @@ -215,8 +243,24 @@ def source_code(s, globs, system='sage'): r""" - Format obj's source code for printing in Sage notebook. + Format an object's source code to process and display in the the + Sage notebook. + INPUT: + + - ``s`` - a string; a name of an object + + - ``globs`` - a string:object dictionary; a context in which to + evaluate ``s`` + + - ``system`` - a string (default: 'sage'); the system to which to + confine the search + + OUTPUT: + + - a string containing the object's file, starting line number, and + source code + AUTHORS: - William Stein: partly taken from IPython for use in Sage @@ -340,17 +384,26 @@ def syseval(system, cmd, dir=None): """ + Evaluate an input with a "system" object that can evaluate inputs + (e.g., python, gap). + INPUT: - system -- an object with an eval method that takes as input - a cmd (a string), and two dictionaries: - sage_globals and locals. - dir -- an optional directory to change to before - calling system.eval. + + - ``system`` - an object with an eval method that takes an input + + - ``cmd`` - a string input + + - ``sage_globals`` - a string:object dictionary + + - dir - a string (default: None); an optional directory to change + to before calling :func:`system.eval` OUTPUT: - The output of system.eval is returned. + + - :func:`system.eval`'s output - EXAMPLES: + EXAMPLES:: + sage: from sage.misc.python import python sage: sage.server.support.syseval(python, '2+4/3') 3 @@ -379,22 +432,17 @@ def cython_import(filename, verbose=False, compile_message=False, use_cache=False, create_local_c_file=True): """ + Compile a file containing Cython code, then import and return the + module. Raises an ``ImportError`` if anything goes wrong. + INPUT: - - - ``filename`` - name of a file that contains cython - code - + - ``filename`` - a string; name of a file that contains Cython + code OUTPUT: - - - ``module`` - the module that contains the compiled - cython code. - - - Raises an ``ImportError`` exception if anything goes - wrong. + - the module that contains the compiled Cython code. """ name, build_dir = sage.misc.cython.cython(filename, verbose=verbose, compile_message=compile_message, @@ -407,18 +455,18 @@ def cython_import_all(filename, globals, verbose=False, compile_message=False, use_cache=False, create_local_c_file=True): """ + Imports all non-private (i.e., not beginning with an underscore) + attributes of the specified Cython module into the given context. + This is similar to:: + + from module import * + + Raises an ``ImportError`` exception if anything goes wrong. + INPUT: - - - ``filename`` - name of a file that contains cython - code - - - OUTPUT: changes globals using the attributes of the Cython module - that do not begin with an underscore. - - Raises an ``ImportError`` exception if anything goes - wrong. + - ``filename`` - a string; name of a file that contains Cython + code """ m = cython_import(filename, verbose=verbose, compile_message=compile_message, use_cache=use_cache,