Ticket #6840: trac_6840-notebook-documentation-v4.patch
File trac_6840-notebook-documentation-v4.patch, 167.1 KB (added by , 13 years ago) |
---|
-
doc/en/reference/notebook.rst
# HG changeset patch # User Mitesh Patel <qed777@gmail.com> # 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 b 11 11 sage/server/notebook/worksheet 12 12 sage/server/notebook/twist 13 13 14 sage/server/notebook/interact 14 15 sage/server/notebook/js 15 16 sage/server/notebook/config 16 17 sage/server/notebook/css 18 sage/server/notebook/docHTMLProcessor 19 sage/server/notebook/template 17 20 21 sage/server/misc 18 22 sage/server/support 19 23 sage/server/introspect 20 24 -
sage/server/introspect.py
diff -r 832b46058006 -r 6b319da23983 sage/server/introspect.py
a b 1 1 """ 2 Sage Notebook :Introspection2 Sage Notebook Introspection 3 3 4 """ 5 6 """ 4 7 TODO: - add support for grabbing source code from Pyrex functions 5 8 (even if not perfect is better than nothing). - PNG or MathML 6 9 output format for docstring -
sage/server/misc.py
diff -r 832b46058006 -r 6b319da23983 sage/server/misc.py
a b 1 1 """ 2 Misc code useful for the notebook2 Miscellaneous Notebook Functions 3 3 """ 4 4 5 5 ############################################################################# … … 19 19 web browser to a certain URL. 20 20 21 21 INPUT: 22 address -- a computer address23 port -- a port number24 secure -- bool (default: False); whether to put HTTP or HTTPS25 path -- path after the port.26 22 27 EXAMPLES: 23 - ``address`` -- a string; a computer address or name 24 25 - ``port`` -- an int; a port number 26 27 - ``secure`` -- a bool (default: False); whether to prefix the URL 28 with 'http' or 'https' 29 30 - ``path`` -- a string; the URL's path following the port. 31 32 EXAMPLES:: 33 28 34 sage: sage.server.misc.print_open_msg('localhost', 8000, True) 29 35 **************************************************** 30 36 * * … … 72 78 import socket 73 79 def find_next_available_port(start, max_tries=100, verbose=False): 74 80 """ 75 Find the next port that is available to be used, where available means that76 current ly trying to connect to it gives a 'Connection refused'77 error message.81 Find for the next available port, that is, a port for which a 82 current connection attempt returns a 'Connection refused' error 83 message. If no port is found, raise a RuntimError exception. 78 84 79 85 INPUT: 80 start -- integer; a port number to start scanning for a new port at 81 max_tries -- integer (default: 100); how many ports to try 82 verbose -- bool (default: True); whether or not to print out info about scanning results. 86 87 - ``start`` - an int; the starting port number for the scan 88 89 - ``max_tries`` - an int (default: 100); how many ports to scan 90 91 - ``verbose`` - a bool (default: True); whether to print information 92 about the scan 83 93 84 94 OUTPUT: 85 an integer, or if no port is found, raises a RuntimError exception86 95 87 EXAMPLES: 96 - an int - the port number 97 98 EXAMPLES:: 99 88 100 sage: sage.server.misc.find_next_available_port(9000, verbose=False) # random output -- depends on network 89 101 9002 90 102 """ -
sage/server/notebook/avatars.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/avatars.py
a b 28 28 OUTPUT: 29 29 string -- 'invalid_user', 'admin', 'user' 30 30 31 EXAMPLES: 31 EXAMPLES:: 32 32 33 sage: import sage.server.notebook.twist 33 34 sage: import sage.server.notebook.avatars as avatars 34 35 sage: avatars.user_type(avatars.FailedLogin('fake')) -
sage/server/notebook/cell.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/cell.py
a b 251 251 252 252 def plain_text(self, prompts=False): 253 253 """ 254 Returns a plain text version of self. 255 254 256 EXAMPLES:: 255 257 256 258 sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) … … 261 263 262 264 def edit_text(self): 263 265 """ 266 Returns the text to be displayed in the Edit window. 267 264 268 EXAMPLES:: 265 269 266 270 sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) … … 271 275 272 276 def id(self): 273 277 """ 278 Returns self's id. 279 280 OUTPUT: 281 282 - int -- self's id. 283 274 284 EXAMPLES:: 275 285 276 286 sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) … … 281 291 282 292 def is_auto_cell(self): 283 293 """ 294 Returns true if self is automatically evaluated. 295 284 296 EXAMPLES:: 285 297 286 298 sage: C = sage.server.notebook.cell.TextCell(0, '2+3', None) … … 291 303 292 304 def __cmp__(self, right): 293 305 """ 306 Compares cells by `id`. 307 294 308 EXAMPLES:: 295 309 296 310 sage: C1 = sage.server.notebook.cell.TextCell(0, '2+3', None) … … 339 353 340 354 def set_asap(self, asap): 341 355 """ 356 Set whether this cell is evaluated as soon as possible. 357 342 358 EXAMPLES:: 343 359 344 360 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) … … 568 584 mainly because there is no good way to distinguish content (e.g., 569 585 images in the current directory) that goes into the interactive 570 586 template and content that would go here. 587 588 EXAMPLES:: 589 590 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 591 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 592 sage: W = nb.create_new_worksheet('Test', 'sage') 593 sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) 594 sage: C.evaluate() 595 sage: W.check_comp(wait=9999) 596 ('d', Cell 0; in=plot(sin(x),0,5), out= 597 <html><font color='black'><img src='cell://sage0.png'></font></html> 598 <BLANKLINE> 599 ) 600 sage: C.update_html_output() 601 sage: C.output_html() 602 '<img src="/home/sage/0/cells/0/sage0.png?...">' 571 603 """ 572 604 if self.is_interactive_cell(): 573 605 self.__out_html = "" … … 702 734 703 735 def __cmp__(self, right): 704 736 """ 737 Compares cells by their `id`s. 738 705 739 EXAMPLES:: 706 740 707 741 sage: C1 = sage.server.notebook.cell.Cell(0, '2+3', '5', None) … … 718 752 719 753 def __repr__(self): 720 754 """ 755 Returns a string representation of self. 756 721 757 EXAMPLES:: 722 758 723 759 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None); C … … 755 791 return 70 756 792 757 793 def plain_text(self, ncols=0, prompts=True, max_out=None): 758 """794 r""" 759 795 Returns the plain text version of self. 760 761 TODO: Add more comprehensive doctests. 796 797 EXAMPLES:: 798 799 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) 800 sage: len(C.plain_text()) 801 11 762 802 """ 763 803 if ncols == 0: 764 804 ncols = self.word_wrap_cols() … … 831 871 832 872 def edit_text(self, ncols=0, prompts=False, max_out=None): 833 873 r""" 874 Returns the text displayed in the Edit window. 875 834 876 EXAMPLES:: 835 877 836 878 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) … … 986 1028 987 1029 def is_interacting(self): 988 1030 """ 989 Returns True 1031 Returns True if this cell is currently interacting with the user. 1032 1033 EXAMPLES:: 1034 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1035 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1036 sage: W = nb.create_new_worksheet('Test', 'sage') 1037 sage: C = W.new_cell_after(0, "@interact\ndef f(a=slider(0,10,1,5):\n print a^2") 1038 sage: C.is_interacting() 1039 False 990 1040 """ 991 1041 return hasattr(self, 'interact') 992 1042 993 1043 def stop_interacting(self): 994 1044 """ 995 1045 Stops interaction with user. 1046 1047 TODO: Add doctests for :meth: `stop_interacting`. 1048 996 1049 """ 997 1050 if self.is_interacting(): 998 1051 del self.interact … … 1224 1277 self.__in = new_text 1225 1278 1226 1279 def set_output_text(self, output, html, sage=None): 1280 r""" 1281 Sets the output text for self. 1282 1283 EXAMPLES:: 1284 1285 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) 1286 sage: len(C.plain_text()) 1287 11 1288 sage: C.set_output_text('10', '10') 1289 sage: len(C.plain_text()) 1290 12 1291 """ 1227 1292 if output.count('<?__SAGE__TEXT>') > 1: 1228 1293 html = '<h3><font color="red">WARNING: multiple @interacts in one cell disabled (not yet implemented).</font></h3>' 1229 1294 output = '' … … 1279 1344 return None 1280 1345 1281 1346 def output_html(self): 1347 """ 1348 Returns the HTML for self's output. 1349 1350 EXAMPLES:: 1351 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) 1352 sage: C.output_html() 1353 '' 1354 sage: C.set_output_text('5', '<strong>5</strong>') 1355 sage: C.output_html() 1356 '<strong>5</strong>' 1357 """ 1282 1358 try: 1283 1359 return self.__out_html 1284 1360 except AttributeError: 1285 1361 self.__out_html = '' 1286 1362 return '' 1287 1363 1288 def process_cell_urls(self, x): 1364 def process_cell_urls(self, urls): 1365 """ 1366 Processes urls of the form 'cell://.*?' by replacing the 1367 protocol with the path to self and appending self's version 1368 number. 1369 1370 INPUT: 1371 1372 - ``urls`` - a string 1373 1374 EXAMPLES:: 1375 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1376 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1377 sage: W = nb.create_new_worksheet('Test', 'sage') 1378 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) 1379 sage: C.process_cell_urls('"cell://foobar"') 1380 '/home/sage/0/cells/0/foobar?0"' 1381 """ 1289 1382 end = '?%d"'%self.version() 1290 1383 begin = self.url_to_self() 1291 for s in re_cell.findall( x) + re_cell_2.findall(x):1292 x = x.replace(s,begin + s[7:-1] + end)1293 return x1384 for s in re_cell.findall(urls) + re_cell_2.findall(urls): 1385 urls = urls.replace(s,begin + s[7:-1] + end) 1386 return urls 1294 1387 1295 1388 def output_text(self, ncols=0, html=True, raw=False, allow_interact=True): 1389 """ 1390 Returns the text for self's output. 1391 1392 INPUT: 1393 1394 - ``ncols`` - maximum number of columns 1395 1396 - ``html`` - boolean stating whether to output html 1397 1398 - ``raw`` - boolean stating whether to output raw text 1399 (takes precedence over html) 1400 1401 - ``allow_interact`` - boolean stating whether to allow interaction 1402 1403 EXAMPLE:: 1404 1405 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1406 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1407 sage: W = nb.create_new_worksheet('Test', 'sage') 1408 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) 1409 sage: C.output_text() 1410 '<pre class="shrunk">5</pre>' 1411 sage: C.output_text(html=False) 1412 '<pre class="shrunk">5</pre>' 1413 sage: C.output_text(raw=True) 1414 '5' 1415 """ 1296 1416 if allow_interact and hasattr(self, '_interact_output'): 1297 1417 # Get the input template 1298 1418 z = self.output_text(ncols, html, raw, allow_interact=False) … … 1337 1457 return s.strip('\n') 1338 1458 1339 1459 def parse_html(self, s, ncols): 1460 """ 1461 Parse HTML for output. 1462 1463 INPUT: 1464 1465 - ``s`` - the input string containing HTML 1466 1467 - ``ncols`` - maximum number of columns 1468 1469 EXAMPLES:: 1470 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1471 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1472 sage: W = nb.create_new_worksheet('Test', 'sage') 1473 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) 1474 sage: C.parse_html('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">\n<html><head></head><body>Test</body></html>', 80) 1475 '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0...Test</body>' 1476 """ 1340 1477 def format(x): 1341 1478 return word_wrap(escape(x), ncols=ncols) 1342 1479 … … 1442 1579 ``verbose`` is not easily accessible now -- if you need to 1443 1580 debug, you have to edit this file, changing its value to True, 1444 1581 and run 'sage -b'. 1582 1583 EXAMPLES:: 1584 1585 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1586 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1587 sage: W = nb.create_new_worksheet('Test', 'sage') 1588 sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) 1589 sage: C.introspect() 1590 False 1591 sage: C.evaluate(username='sage') 1592 sage: W.check_comp(9999) 1593 ('d', Cell 0; in=sage?, out=) 1594 sage: C.set_introspect_html('foobar') 1595 sage: C.introspect_html() 1596 '<div class="docstring"><pre>foobar</pre></div>' 1597 sage: C.set_introspect_html('`foobar`') 1598 sage: C.introspect_html() 1599 '<div class="docstring">\n \n <p><span class="math">foobar</span></p>\n\n\n</div>' 1445 1600 """ 1446 1601 if html == "" or completing: 1447 1602 self.__introspect_html = html … … 1599 1754 return 1600 1755 1601 1756 def introspect_html(self): 1757 """ 1758 Returns html for introspection. 1759 1760 EXAMPLES:: 1761 1762 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1763 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1764 sage: W = nb.create_new_worksheet('Test', 'sage') 1765 sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) 1766 sage: C.introspect() 1767 False 1768 sage: C.evaluate(username='sage') 1769 sage: W.check_comp(9999) 1770 ('d', Cell 0; in=sage?, out=) 1771 sage: C.introspect_html() 1772 u'<div class="docstring">...</pre></div>' 1773 """ 1602 1774 if not self.introspect(): 1603 1775 return '' 1604 1776 try: … … 1609 1781 1610 1782 def introspect(self): 1611 1783 """ 1612 TODO: Figure out what the __introspect method is for and write a 1613 better doctest. 1784 Returns self's introspection text. 1614 1785 1615 1786 EXAMPLES:: 1616 1617 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) 1787 1788 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1789 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1790 sage: W = nb.create_new_worksheet('Test', 'sage') 1791 sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) 1618 1792 sage: C.introspect() 1619 1793 False 1620 sage: C.set_introspect("a", "b") 1794 sage: C.evaluate(username='sage') 1795 sage: W.check_comp(9999) 1796 ('d', Cell 0; in=sage?, out=) 1621 1797 sage: C.introspect() 1622 [' a', 'b']1798 ['sage?', ''] 1623 1799 """ 1624 1800 try: 1625 1801 return self.__introspect … … 1628 1804 1629 1805 def unset_introspect(self): 1630 1806 """ 1631 TODO: Figure out what the __introspect method is for and write a 1632 better doctest. 1807 Unsets self's introspection text. 1633 1808 1634 1809 EXAMPLES:: 1635 1636 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', None) 1637 sage: C.set_introspect("a", "b") 1810 1811 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1812 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1813 sage: W = nb.create_new_worksheet('Test', 'sage') 1814 sage: C = sage.server.notebook.cell.Cell(0, 'sage?', '', W) 1638 1815 sage: C.introspect() 1639 ['a', 'b'] 1816 False 1817 sage: C.evaluate(username='sage') 1818 sage: W.check_comp(9999) 1819 ('d', Cell 0; in=sage?, out=) 1820 sage: C.introspect() 1821 ['sage?', ''] 1640 1822 sage: C.unset_introspect() 1641 1823 sage: C.introspect() 1642 1824 False … … 1645 1827 1646 1828 def set_introspect(self, before_prompt, after_prompt): 1647 1829 """ 1648 TODO: Figure out what the __introspect method is for and write a 1649 better doctest. 1830 Set self's introspection text. 1650 1831 1651 1832 EXAMPLES:: 1652 1833 … … 1670 1851 [before_cursor, after_cursor] of strings. 1671 1852 1672 1853 1673 EXAMPLES: We create a notebook, worksheet, and cell and evaluate it 1854 EXAMPLES: 1855 1856 We create a notebook, worksheet, and cell and evaluate it 1674 1857 in order to compute `3^5`:: 1675 1858 1676 1859 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 1753 1936 This is a hack and needs to be improved. The problem is how to get 1754 1937 the documentation html to display nicely between the example cells. 1755 1938 The type setting (jsMath formatting) needs attention too. 1939 1940 TODO: Remove this hack ( :meth: `doc_html` ) 1756 1941 """ 1757 1942 self.evaluate() 1758 1943 if wrap is None: … … 1773 1958 return s 1774 1959 1775 1960 def html(self, wrap=None, div_wrap=True, do_print=False): 1961 r""" 1962 Returns the html for self. 1963 1964 INPUT: 1965 1966 - ``wrap`` - a boolean stating whether to wrap lines. Defaults to 1967 configuration if not given, 1968 1969 - ``div_wrap`` - a boolean stating whether to wrap ``div``s. 1970 1971 - ``do_print`` - a boolean stating whether the HTML is for 1972 print or not. 1973 1974 EXAMPLES:: 1975 1976 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1977 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1978 sage: W = nb.create_new_worksheet('Test', 'sage') 1979 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) 1980 sage: C.html() 1981 '\n\n<div id="cell_outer_0" cl...</div>' 1982 """ 1776 1983 if do_print: 1777 1984 wrap = 68 1778 1985 div_wrap = 68 … … 1910 2117 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1911 2118 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1912 2119 sage: W = nb.create_new_worksheet('Test', 'sage') 1913 sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', ", W)2120 sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) 1914 2121 sage: C.evaluate() 1915 2122 sage: W.check_comp(wait=9999) 1916 2123 ('d', Cell 0; in=plot(sin(x),0,5), out= … … 1937 2144 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1938 2145 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 1939 2146 sage: W = nb.create_new_worksheet('Test', 'sage') 1940 sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', ", W)2147 sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) 1941 2148 sage: C.evaluate() 1942 2149 sage: W.check_comp(wait=9999) 1943 2150 ('d', Cell 0; in=plot(sin(x),0,5), out= … … 1960 2167 1961 2168 1962 2169 def files_html(self, out): 2170 """ 2171 Returns html to display the files in self's directory. 2172 2173 INPUT: 2174 2175 - ``out`` - string to exclude files. 2176 Format: To exclude bar, foo, ...`'cell://bar cell://foo ...'` 2177 2178 EXAMPLES:: 2179 2180 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 2181 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 2182 sage: W = nb.create_new_worksheet('Test', 'sage') 2183 sage: C = sage.server.notebook.cell.Cell(0, 'plot(sin(x),0,5)', '', W) 2184 sage: C.evaluate() 2185 sage: W.check_comp(wait=9999) 2186 ('d', Cell 0; in=plot(sin(x),0,5), out= 2187 <html><font color='black'><img src='cell://sage0.png'></font></html> 2188 <BLANKLINE> 2189 ) 2190 sage: C.files_html('') 2191 '<img src="/home/sage/0/cells/0/sage0.png?...">' 2192 """ 1963 2193 import time 1964 2194 D = self.files() 1965 2195 D.sort() … … 2027 2257 return images + files 2028 2258 2029 2259 def html_out(self, ncols=0, do_print=False): 2260 r""" 2261 Returns the html for self's output. 2262 2263 INPUT: 2264 2265 - ``do_print`` - a boolean stating whether to output html 2266 for print 2267 2268 - ``ncols`` - the number of columns 2269 2270 EXAMPLES:: 2271 2272 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 2273 sage: nb.add_user('sage','sage','sage@sagemath.org',force=True) 2274 sage: W = nb.create_new_worksheet('Test', 'sage') 2275 sage: C = sage.server.notebook.cell.Cell(0, '2+3', '5', W) 2276 sage: C.html_out() 2277 '\n...<table class="cell_output_box">...</table>' 2278 """ 2030 2279 if do_print and self.cell_output_type() == 'hidden': 2031 2280 return '<pre>\n</pre>' 2032 2281 -
sage/server/notebook/config.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/config.py
a b 1 1 """ 2 Customization of theNotebook Keybindings2 Notebook Keybindings 3 3 4 4 This module is responsible for setting the keyboard bindings for the notebook. 5 5 """ -
sage/server/notebook/css.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/css.py
a b 1 1 """nodoctest 2 Sage Notebook CSS 2 Notebook Stylesheets (CSS) 3 3 """ 4 4 5 5 -
sage/server/notebook/docHTMLProcessor.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/docHTMLProcessor.py
a b 4 4 Processes Sage documentation into notebook worksheet format with 5 5 evaluatable examples. 6 6 7 This takes in any HTML document, i.e. Sage documentation, and returns7 This takes in any HTML document, i.e., Sage documentation, and returns 8 8 it in the editable format (like the notebook edit window). It also 9 returns a string representing the csslink for the document. The SGML10 parser is setup to return only the body of the htmldocumentation page9 returns a string representing the CSS link for the document. The SGML 10 parser is setup to return only the body of the HTML documentation page 11 11 and to re-format Sage examples and type-setting. 12 12 13 13 Note: This extension of sgmllib.SGMLParser was partly inspired by Mark 14 14 Pilgrim's 'Dive Into Python' examples. 15 15 16 16 Author: 17 -- Dorian Raymer (2006): first version 18 -- William Stein (2007-06-10): rewrite to work with twisted Sage notebook 19 -- Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation 17 18 - Dorian Raymer (2006): first version 19 20 - William Stein (2007-06-10): rewrite to work with twisted Sage notebook 21 22 - Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation 20 23 """ 21 24 ############################################################################# 22 25 # Copyright (C) 2007 William Stein <wstein@gmail.com> and Dorian Raimer … … 32 35 class SphinxHTMLProcessor(SGMLParser): 33 36 def reset(self): 34 37 """ 35 This function is called by SGMLParser.__init__ so all necessary things36 are initialized here.38 Initialize necessary variables. Called by 39 :meth:`SGMLParser.__init__`. 37 40 38 EXAMPLES: 41 EXAMPLES:: 42 39 43 sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor 40 44 sage: d = SphinxHTMLProcessor() 41 45 sage: d.bodyQ … … 64 68 65 69 def process_doc_html(self, doc_in): 66 70 """ 67 process_doc_html is the only function that needs to be called68 externally. docin should be a properly marked up html file.71 Returns processed HTML input as HTML output. This is the only 72 method that needs to be called externally. 69 73 70 self.feed() is a 71 SGMLParser method and starts everything off; Most of the 72 functions here are extensions to SGMLParser, and may never 73 actually be visibly called here. 74 """ 74 INPUT: 75 76 - ``doc_in`` - a string containing properly formed HTML 77 78 OUTPUT: 79 80 - a string; the processed HTML 81 """ 82 # self.feed() is a SGMLParser method and starts everything 83 # off; Most of the functions here are extensions to 84 # SGMLParser, and may never actually be visibly called here. 75 85 self.feed(doc_in) #SGMLParser call 76 86 self.close() #SGMLParser call 77 87 self.hand_off_temp_pieces('to_doc_pieces') … … 81 91 82 92 def hand_off_temp_pieces(self, piece_type): 83 93 """ 84 To separate documentation content from sage examples, 85 everything is split into one of two cell types. This function 86 is called to put the current self.temp_pieces into 87 self.all_pieces. 94 To separate the documentation's content from the Sage 95 examples, everything is split into one of two cell types. 96 This method puts the current ``self.temp_pieces`` into 97 ``self.all_pieces``. 98 99 INPUT: 100 101 - ``piece_type`` - a string; indicates the type of and how to 102 process the current ``self.temp_pieces`` 88 103 """ 89 104 pieces = "".join(self.temp_pieces) 90 105 pieces = pieces.lstrip() … … 100 115 101 116 def get_cellcount(self): 102 117 """ 103 Returns the current cell count and increments it 104 by one. 118 Return the current cell count and increment it by one. 105 119 106 EXAMPLES: 120 OUTPUT: 121 122 - an int 123 124 EXAMPLES:: 125 107 126 sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor 108 127 sage: d = SphinxHTMLProcessor() 109 128 sage: d.get_cellcount() … … 116 135 117 136 def process_cell_input_output(self, cell_piece): 118 137 """ 119 All class='highlight' div's contain code examples. 120 Some examples are models of how the function works; 121 those begin with INPUT: or something. 122 The rest of the examples should have sage:input and 123 output. If the example is a model, it is made into a 124 div class='usage_model' so it can be stylized. 125 If it is actual input/output, the input is separated 126 from the output according to the Notebook edit format. 138 Process and return a ``cell_piece``. 139 140 All divs with CSS class="highlight" contain code examples. 141 They include 142 143 - Models of how the function works. These begin with, e.g., 144 'INPUT:' and are re-styled as divs with 145 class="usage_model". 146 147 - Actual Sage input and ouput. These begin with 'sage:'. 148 The input and output are separated according to the 149 Notebook edit format. 150 151 INPUT: 152 153 - ``cell_piece`` - a string; a cell piece 154 155 OUTPUT: 156 157 - a string; the processed cell piece 127 158 """ 128 159 if cell_piece[:5] != 'sage:' and cell_piece[:12] != '>'*3: 129 160 piece = '<div class="highlight"><pre>' … … 215 246 ## 216 247 def start_body(self, attrs): 217 248 """ 218 This just sets self.bodyQ to True once we've hit thebody tag.249 Set ``self.bodyQ`` to True upon finding the opening body tag. 219 250 220 EXAMPLES: 251 INPUT: 252 253 - ``attrs`` - a string:string dictionary containing the 254 element's attributes 255 256 EXAMPLES:: 257 221 258 sage: from sage.server.notebook.docHTMLProcessor import SphinxHTMLProcessor 222 259 sage: d = SphinxHTMLProcessor() 223 260 sage: d.bodyQ -
sage/server/notebook/interact.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/interact.py
a b 6 6 ############################################################################# 7 7 8 8 r""" 9 Interact Sage functions in the notebook9 Interact Functions in the Notebook 10 10 11 This module implements a interact decorator for function inthe Sage11 This module implements an :func:`interact` function decorator for the Sage 12 12 notebook. 13 13 14 14 AUTHORS: 15 -- William Stein (2008-03-02): version 1.0 at Sage/Enthought Days 8 in Texas 16 -- Jason Grout (2008-03): discussion and first few prototypes 17 -- Jason Grout (2008-05): input_grid control 15 16 - William Stein (2008-03-02): version 1.0 at Sage/Enthought Days 17 8 in Texas 18 19 - Jason Grout (2008-03): discussion and first few prototypes 20 21 - Jason Grout (2008-05): :class:`input_grid` control 18 22 """ 19 23 20 24 """ … … 158 162 159 163 def reset_state(): 160 164 """ 161 Reset the interactstate of this sage process.165 Reset the :func:`interact` state of this sage process. 162 166 163 EXAMPLES: 167 EXAMPLES:: 168 164 169 sage: sage.server.notebook.interact.state # random output 165 170 {1: {'function': <function g at 0x72aaab0>, 'variables': {'m': 3, 'n': 5}, 'adapt': {1: <bound method Slider._adaptor of Slider Interact Control: n [1--|1|---10].>, 2: <bound method Slider._adaptor of Slider Interact Control: m [1--|1|---10].>}}} 166 171 sage: from sage.server.notebook.interact import reset_state … … 180 185 e.g., makes sure the control always produces int's. 181 186 182 187 OUTPUT: 183 integer184 188 185 EXAMPLES: 189 - an integer 190 191 EXAMPLES:: 192 186 193 sage: sage.server.notebook.interact.new_adapt_number() # random output -- depends on when called 187 194 1 188 195 """ … … 193 200 194 201 def html(s): 195 202 """ 196 Render the input string s in a form that tells the notebook 197 to display it in the HTML portion of the output. 203 Print the input string ``s`` in a form that tells the notebook to 204 display it in the HTML portion of the output. This function has 205 no return value. 198 206 199 207 INPUT: 200 s -- a string201 208 202 OUTPUT: 203 string -- html format 209 - ``s`` - a string 204 210 205 EXAMPLES: 211 EXAMPLES:: 212 206 213 sage: sage.server.notebook.interact.html('hello') 207 214 <html>hello</html> 208 215 """ … … 213 220 Return the HTML representation of a jQuery slider. 214 221 215 222 INPUT: 216 id -- string -- the DOM id of the slider (better be unique) 217 values -- 'null' or javascript string containing array of values on slider 218 callback-- javascript that is executed whenever the slider is done moving 219 steps -- number of steps from minimum to maximum value. 220 default -- (default: 0) the default position of the slider 221 margin -- (default: 0) size of margin to insert around the slider 223 224 - ``id`` - a string; the DOM id of the slider (better be unique) 225 226 - ``values`` - a string; 'null' or JavaScript string containing 227 array of values on slider 228 229 - ``callback`` - a string; JavaScript that is executed whenever 230 the slider is done moving 231 232 - ``steps`` - an integer; number of steps from minimum to maximum 233 value. 234 235 - ``default`` - an integer (default: 0); the default position of 236 the slider 237 238 - ``margin`` - an integer (default: 0); size of margin to insert 239 around the slider 240 241 OUTPUT: 242 243 - a string - HTML format 222 244 223 245 EXAMPLES: 224 We create a jQuery HTML slider. If you do the following in the notebook 225 you should obtain a slider that when moved pops up a window showing its 226 current position. 246 247 We create a jQuery HTML slider. If you do the following in the 248 notebook you should obtain a slider that when moved pops up a 249 window showing its current position:: 250 227 251 sage: from sage.server.notebook.interact import html_slider, html 228 252 sage: html(html_slider('slider-007', 'null', 'alert(position)', steps=5, default=2, margin=5)) 229 253 <html>...</html> … … 257 281 Return the HTML representation of a jQuery range slider. 258 282 259 283 INPUT: 260 id -- string -- the DOM id of the slider (better be unique) 261 values -- 'null' or javascript string containing array of values on slider 262 callback-- javascript that is executed whenever the slider is done moving 263 steps -- number of steps from minimum to maximum value. 264 default_l -- (default: 0) the default position of the left edge of the slider 265 default_r -- (default: 1) the default position of the right edge of the slider 266 margin -- (default: 0) size of margin to insert around the slider 284 285 - ``id`` - a string; the DOM id of the slider (better be unique) 286 287 - ``values`` - a string; 'null' or JavaScript string containing 288 array of values on slider 289 290 - ``callback`` - a string; JavaScript that is executed whenever 291 the slider is done moving 292 293 - ``steps`` - an integer; number of steps from minimum to maximum 294 value. 295 296 - ``default_l`` - an integer (default: 0); the default position of 297 the left edge of the slider 298 299 - ``default_r`` - an integer (default: 1); the default position of 300 the right edge of the slider 301 302 - ``margin`` - an integer (default: 0); size of margin to insert 303 around the slider 304 305 OUTPUT: 306 307 - a string - HTML format 267 308 268 309 EXAMPLES: 269 We create a jQuery range slider. If you do the following in the notebook 270 you should obtain a slider that when moved pops up a window showing its 271 current position. 310 311 We create a jQuery range slider. If you do the following in the 312 notebook you should obtain a slider that when moved pops up a 313 window showing its current position:: 314 272 315 sage: from sage.server.notebook.interact import html_rangeslider, html 273 316 sage: html(html_rangeslider('slider-007', 'null', 'alert(pos[0]+", "+pos[1])', steps=5, default_l=2, default_r=3, margin=5)) 274 317 <html>...</html> … … 324 367 Return HTML representation of a jQuery color selector. 325 368 326 369 INPUT: 327 id -- integer; the id of the html div element that this selector should have 328 change -- javascript code to execute when the color selector changes. 329 default -- string (default: '000000'); default color as a 6-character 330 HTML hex string. 370 371 - ``id`` - an integer; the id of the HTML div element that this 372 selector should have 373 374 - ``change`` - a string; JavaScript code to execute when the color 375 selector changes. 376 377 - ``default`` - a string (default: ``'000000'``); default color as 378 a 6-character HTML hex string. 331 379 332 380 OUTPUT: 333 string -- HTML that creates the slider.334 381 335 EXAMPLES: 382 - a string - HTML that creates the slider. 383 384 EXAMPLES:: 385 336 386 sage: sage.server.notebook.interact.html_color_selector(0, 'alert("changed")', '', default='0afcac') 337 387 '<table>...' 338 388 """ … … 366 416 Returns an empty label for this element. This should be 367 417 overridden for subclasses that need a label. 368 418 369 EXAMPLES: 419 OUTPUT: 420 421 - a string 422 423 EXAMPLES:: 424 370 425 sage: from sage.server.notebook.interact import UpdateButton, InteractElement 371 426 sage: b = UpdateButton(1) 372 427 sage: isinstance(b, InteractElement) … … 378 433 379 434 def set_canvas(self, canvas): 380 435 """ 381 Sets the InteractCanvas on which this element appears. This382 method is primarily called in the constructor for383 InteractCanvas.436 Sets the :class:`InteractCanvas` on which this element appears. 437 This method is primarily called in the constructor for 438 :class:`InteractCanvas`. 384 439 385 EXAMPLES: 440 EXAMPLES:: 441 386 442 sage: from sage.server.notebook.interact import InputBox, InteractCanvas 387 443 sage: B = InputBox('x',2) 388 444 sage: canvas1 = InteractCanvas([B], 3) … … 398 454 399 455 def canvas(self): 400 456 """ 401 Returns the InteractCanvas associated to this element. If no402 canvas has been set (via the set_canvas method), then this403 will returna ValueError.457 Returns the :class:`InteractCanvas` associated to this element. If 458 no canvas has been set (via the :meth:`set_canvas` method), then 459 raise a ValueError. 404 460 405 EXAMPLES: 461 EXAMPLES:: 462 406 463 sage: from sage.server.notebook.interact import InputBox, InteractCanvas 407 464 sage: B = InputBox('x',2) 408 465 sage: canvas1 = InteractCanvas([B], 3) … … 420 477 class InteractControl(InteractElement): 421 478 def __init__(self, var, default_value, label=None): 422 479 """ 423 Abstract base class for interactcontrols. These are controls424 that are used in a specific interact. They have internal425 state information about the specific function being interact d,480 Abstract base class for :func:`interact` controls. These are controls 481 that are used in a specific :func:`interact`. They have internal 482 state information about the specific function being interacted, 426 483 etc. 427 484 428 485 INPUT: 429 var -- string; name of variable that this control interacts430 default_value -- the default value of the variable431 corresponding to this control.432 label -- string (default: None) label of this control; if None433 then defaults to var.434 486 435 EXAMPLES: 487 - ``var`` - a string; name of variable that this control 488 interacts 489 490 - ``default_value`` - the default value of the variable 491 corresponding to this control. 492 493 - ``label`` - a string (default: None); label for this 494 control; if None then defaults to ``var``. 495 496 EXAMPLES:: 497 436 498 sage: from sage.server.notebook.interact import InteractControl 437 499 sage: InteractControl('x', default_value=5) 438 500 A InteractControl (abstract base class) … … 450 512 451 513 def __repr__(self): 452 514 """ 453 String representation of interactcontrol.515 String representation of :func:`interact` control. 454 516 455 EXAMPLES: 517 OUTPUT: 518 519 - a string 520 521 EXAMPLES:: 522 456 523 sage: from sage.server.notebook.interact import InteractControl 457 524 sage: InteractControl('x', default_value=5).__repr__() 458 525 'A InteractControl (abstract base class)' … … 461 528 462 529 def value_js(self): 463 530 """ 464 Java script that when evaluated gives the current value of this531 JavaScript that when evaluated gives the current value of this 465 532 control. This should be redefined in a derived class. 466 533 467 534 OUTPUT: 468 string -- defaults to NULL -- this should be redefined.469 535 470 EXAMPLES: 536 - a string - defaults to 'NULL' - this should be redefined. 537 538 EXAMPLES:: 539 471 540 sage: sage.server.notebook.interact.InteractControl('x', default_value=5).value_js() 472 541 'NULL' 473 542 """ … … 475 544 476 545 def label(self): 477 546 """ 478 Return the text label of this interactcontrol.547 Return the text label of this :func:`interact` control. 479 548 480 EXAMPLES: 549 OUTPUT: 550 551 - a string 552 553 EXAMPLES:: 554 481 555 sage: from sage.server.notebook.interact import InteractControl 482 556 sage: InteractControl('x', default_value=5, label='the x value').label() 483 557 'the x value' … … 487 561 def default_value(self): 488 562 """ 489 563 Return the default value of the variable corresponding to this 490 interactcontrol.564 :func:`interact` control. 491 565 492 566 OUTPUT: 493 object494 567 495 EXAMPLES: 568 - an object 569 570 EXAMPLES:: 571 496 572 sage: from sage.server.notebook.interact import InteractControl 497 573 sage: InteractControl('x', 19/3).default_value() 498 574 19/3 … … 502 578 def html_escaped_default_value(self): 503 579 """ 504 580 Returns the HTML escaped default value of the variable 505 corresponding to this interactcontrol. Note that any506 HTML that uses quotes around this should use double 507 quotes andnot single quotes.581 corresponding to this :func:`interact` control. Note that any 582 HTML that uses quotes around this should use double quotes and 583 not single quotes. 508 584 509 EXAMPLES: 585 OUTPUT: 586 587 - a string 588 589 EXAMPLES:: 590 510 591 sage: from sage.server.notebook.interact import InteractControl 511 592 sage: InteractControl('x', '"cool"').html_escaped_default_value() 512 593 '"cool"' … … 528 609 called to adapt the values of this control to Python. 529 610 530 611 OUTPUT: 531 an integer532 612 533 EXAMPLES: 613 - an integer 614 615 EXAMPLES:: 616 534 617 sage: from sage.server.notebook.interact import InteractControl 535 618 sage: InteractControl('x', 19/3).adapt_number() # random -- depends on call order 536 619 2 … … 543 626 by this control. 544 627 545 628 INPUT: 546 value -- the string the user typed in 547 globs -- the globals interpreter variables, e.g., 548 globals(), which is useful for evaling value. 629 630 - ``value`` - the string the user typed in 631 632 - ``globs`` - a string:object dictionary; the globals 633 interpreter variables, e.g., :func:`globals`, which is 634 useful for evaling value. 549 635 550 636 OUTPUT: 551 object552 637 553 EXAMPLES: 638 - an object 639 640 EXAMPLES:: 641 554 642 sage: sage.server.notebook.interact.InteractControl('x', 1)._adaptor('2/3', globals()) 555 643 2/3 556 644 """ … … 558 646 559 647 def interact(self, *args): 560 648 """ 561 Return a string that when evaluated in Java script calls the562 javascript interactfunction with appropriate inputs for649 Return a string that when evaluated in JavaScript calls the 650 JavaScript :func:`interact` function with appropriate inputs for 563 651 this control. 564 652 565 653 This method will check to see if there is a canvas attached to … … 569 657 automatically update. 570 658 571 659 OUTPUT: 572 string -- that is meant to be evaluated in Javascript573 660 574 EXAMPLES: 661 - a string - that is meant to be evaluated in JavaScript 662 663 EXAMPLES:: 664 575 665 sage: sage.server.notebook.interact.InteractControl('x', 1).interact() 576 666 'interact(..., "sage.server.notebook.interact.update(..., \\"x\\", ..., sage.server.notebook.interact.standard_b64decode(\\""+encode64(NULL)+"\\"), globals());sage.server.notebook.interact.recompute(0)")' 577 667 """ … … 599 689 Return the name of the variable that this control interacts. 600 690 601 691 OUTPUT: 602 string -- name of a variable as a string.603 692 604 EXAMPLES: 693 - a string - name of a variable as a string. 694 695 EXAMPLES:: 696 605 697 sage: sage.server.notebook.interact.InteractControl('theta', 1).var() 606 698 'theta' 607 699 """ … … 609 701 610 702 def cell_id(self): 611 703 """ 612 Return the id of the cell that contains this interactcontrol.704 Return the id of the cell that contains this :func:`interact` control. 613 705 614 706 OUTPUT: 615 integer -- id of cell that this control interacts 707 708 - an integer - id of cell that this control interacts 616 709 617 710 EXAMPLES: 618 The output below should equal the ID of the current cell. 711 712 The output below should equal the id of the current cell:: 713 619 714 sage: sage.server.notebook.interact.InteractControl('theta', 1).cell_id() 620 715 0 621 716 """ … … 624 719 class InputBox(InteractControl): 625 720 def __init__(self, var, default_value, label=None, type=None, width = 80): 626 721 """ 627 An input box interactcontrol.722 An input box :func:`interact` control. 628 723 629 InputBox(var, default_value, label, type)724 EXAMPLES:: 630 725 631 EXAMPLES:632 726 sage: sage.server.notebook.interact.InputBox('theta', 1, 'theta') 633 727 An InputBox interactive control with theta=1 and label 'theta' 634 728 sage: sage.server.notebook.interact.InputBox('theta', 1, 'theta', int) … … 640 734 641 735 def __repr__(self): 642 736 """ 643 String representation of an InputBoxinteractive control.737 String representation of an :class:`InputBox` interactive control. 644 738 645 EXAMPLES: 739 OUTPUT: 740 741 - a string 742 743 EXAMPLES:: 744 646 745 sage: sage.server.notebook.interact.InputBox('theta', 1).__repr__() 647 746 "An InputBox interactive control with theta=1 and label 'theta'" 648 747 """ … … 655 754 element selected by this control. 656 755 657 756 INPUT: 658 value -- text entered by user 659 globs -- the globals interpreter variables (not used here). 757 758 - ``value`` - text entered by user 759 760 - ``globs`` - a string:object dictionary; the :func:`globals` 761 interpreter variables (not used here). 660 762 661 763 OUTPUT: 662 object663 764 664 EXAMPLES: 765 - an object 766 767 EXAMPLES:: 768 665 769 sage: sage.server.notebook.interact.InputBox('theta', Color('red'), type=Color)._adaptor('#aaaaaa',globals()) 666 770 RGB color (0.6640625, 0.6640625, 0.6640625) 667 771 """ … … 676 780 677 781 def value_js(self): 678 782 """ 679 Return javascript string that will give the value of this783 Return JavaScript string that will give the value of this 680 784 control element. 681 785 682 786 OUTPUT: 683 string -- javascript684 787 685 EXAMPLES: 788 - a string - JavaScript 789 790 EXAMPLES:: 791 686 792 sage: sage.server.notebook.interact.InputBox('theta', 1).value_js() 687 793 'this.value' 688 794 """ … … 696 802 Render this control as a string. 697 803 698 804 OUTPUT: 699 string -- html format700 805 701 EXAMPLES: 806 - a string - HTML format 807 808 EXAMPLES:: 809 702 810 sage: sage.server.notebook.interact.InputBox('theta', 1).render() 703 811 '<input type=\'text\' value="1" size=80 onchange=\'interact(0, "sage.server.notebook.interact.update(0, \\"theta\\", ..., sage.server.notebook.interact.standard_b64decode(\\""+encode64(this.value)+"\\"), globals());sage.server.notebook.interact.recompute(0)")\'></input>' 704 812 """ … … 715 823 class ColorInput(InputBox): 716 824 def value_js(self, n): 717 825 """ 718 Return javascript that evaluates to value of this control. 826 Return JavaScript that evaluates to value of this control. 827 If ``n`` is 0 return code for evaluation by the actual color 828 control. If ``n`` is 1, return code for the text area that 829 displays the current color. 719 830 720 831 INPUT: 721 n -- integer, either 0 or 1.722 832 723 If n is 0 return code for evaluation by the actual color control. 724 If n is 1, return code for the text area that displays the current color. 833 - ``n`` - integer, either 0 or 1. 725 834 726 EXAMPLES: 835 OUTPUT: 836 837 - a string 838 839 EXAMPLES:: 840 727 841 sage: C = sage.server.notebook.interact.ColorInput('c', Color('red')) 728 842 sage: C.value_js(0) 729 843 'color' … … 737 851 738 852 def render(self): 739 853 """ 740 Render this color input box to html.854 Render this color input box to HTML. 741 855 742 EXAMPLES: 856 OUTPUT: 857 858 - a string - HTML format 859 860 EXAMPLES:: 861 743 862 sage: sage.server.notebook.interact.ColorInput('c', Color('red')).render() 744 863 '<table>...' 745 864 """ … … 754 873 """ 755 874 A grid interact control. 756 875 757 INPUT 758 var -- the variable 759 rows -- the number of rows 760 columns -- the number of columns 761 default_value -- if this is a scalar, it is put in every 762 cell; if it is a list, it is filled into the cells row by 763 row; if it is a nested list, then it is filled into the 764 cells according to the nesting structure. 765 label -- the label for the control 766 to_value -- a function which is applied to the nested list 767 from user input when assigning the variable 768 width -- the width of the input boxes 876 INPUT: 769 877 770 EXAMPLES: 878 - ``var`` - an object; the variable 879 880 - ``rows`` - an integer; the number of rows 881 882 - ``columns`` - an integer; the number of columns 883 884 - ``default_value`` - an object; if this is a scalar, it is 885 put in every cell; if it is a list, it is filled into the 886 cells row by row; if it is a nested list, then it is filled 887 into the cells according to the nesting structure. 888 889 - ``label`` - a string; the label for the control 890 891 - ``to_value`` - a function applied to the nested list from 892 user input when assigning the variable 893 894 - ``width`` - an integer; the width of the input boxes 895 896 EXAMPLES:: 897 771 898 sage: sage.server.notebook.interact.InputGrid('M', 2,2, default_value = 0, label='M') 772 899 A 2 x 2 InputGrid interactive control with M=[[0, 0], [0, 0]] and label 'M' 773 900 sage: sage.server.notebook.interact.InputGrid('M', 2,2, default_value = [[1,2],[3,4]], label='M') … … 795 922 796 923 def __repr__(self): 797 924 """ 798 String representation of an InputGridinteractive control.925 String representation of an :class:`InputGrid` interactive control. 799 926 800 EXAMPLES: 927 OUTPUT: 928 929 - a string 930 931 EXAMPLES:: 932 801 933 sage: sage.server.notebook.interact.InputGrid('M', 2,2).__repr__() 802 934 "A 2 x 2 InputGrid interactive control with M=[[None, None], [None, None]] and label 'M'" 803 935 """ … … 812 944 element selected by this control. 813 945 814 946 INPUT: 815 value -- text entered by user 816 globs -- the globals interpreter variables (not used here). 947 948 - ``value`` - text entered by user 949 950 - ``globs`` - a string:object dictionary; the :func:`globals` 951 interpreter variables (not used here). 817 952 818 953 OUTPUT: 819 object820 954 821 EXAMPLES: 955 - an object 956 957 EXAMPLES:: 958 822 959 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()) 823 960 (4, 5, 6) 824 961 """ … … 827 964 828 965 def value_js(self): 829 966 """ 830 Return javascript string that will give the value of this967 Return JavaScript string that will give the value of this 831 968 control element. 832 969 833 970 OUTPUT: 834 string -- javascript835 971 836 EXAMPLES: 972 - string - JavaScript 973 974 EXAMPLES:: 975 837 976 sage: sage.server.notebook.interact.InputGrid('M', 2,2).value_js() 838 977 ' "[["+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("],[")+"]]" ' 839 978 """ … … 848 987 Render this control as a string. 849 988 850 989 OUTPUT: 851 string -- html format852 990 853 EXAMPLES: 991 - string - HTML format 992 993 EXAMPLES:: 994 854 995 sage: sage.server.notebook.interact.InputGrid('M', 1,2).render() 855 996 '<table><tr><td><input type=\'text\' value=\'None\' ... 856 997 … … 874 1015 A drop down menu or a button bar that when pressed sets a 875 1016 variable to a given value. 876 1017 877 Selector(var, values, label=None, nrows=None, ncols=None)1018 INPUT: 878 1019 879 INPUT: 880 var -- string; variable name 881 values-- list; button values 882 label -- string (default: None) label off to the left for this button group 883 default -- integer (default: 0) position of default value in values list. 884 nrows -- integer (default: None) number of rows 885 ncols -- integer (default: None) number of columns 886 width -- integer (default: None) width of all the buttons 887 buttons -- bool (default: False) if True use buttons instead of dropdown 1020 - ``var`` - a string; variable name 888 1021 889 EXAMPLES: 1022 - ``values`` - a list; button values 1023 1024 - ``label`` - a string (default: None); label off to the left 1025 for this button group 1026 1027 - ``default`` - an integer (default: 0); position of default 1028 value in values list. 1029 1030 - ``nrows`` - an integer (default: None); number of rows 1031 1032 - ``ncols`` - an integer (default: None); number of columns 1033 1034 - ``width`` - an integer (default: None); width of all the 1035 buttons 1036 1037 - ``buttons`` - a bool (default: False); if True use buttons 1038 instead of dropdown 1039 1040 EXAMPLES:: 1041 890 1042 sage: sage.server.notebook.interact.Selector('x', [1..5], 'alpha', default=2) 891 1043 Selector with 5 options for variable 'x' 892 1044 sage: sage.server.notebook.interact.Selector('x', [1..4], 'alpha', default=2, nrows=2, ncols=2, width=10, buttons=True) … … 937 1089 938 1090 def __repr__(self): 939 1091 """ 940 String representation of a Selectorinteractive control.1092 String representation of a :class:`Selector` interactive control. 941 1093 942 EXAMPLES: 1094 OUTPUT: 1095 1096 - a string 1097 1098 EXAMPLES:: 1099 943 1100 sage: sage.server.notebook.interact.Selector('x', [1..5]).__repr__() 944 1101 "Selector with 5 options for variable 'x'" 945 1102 """ … … 947 1104 948 1105 def _adaptor(self, value, globs): 949 1106 """ 950 Adapt value of button or menu selection. 951 952 The button value is just an integer, and this function adapts 953 it to be the value that we associate with that button. 1107 Adapt value of button or menu selection. The button value is 1108 just an integer, and this function adapts it to be the value 1109 that we associate with that button. 954 1110 955 1111 INPUT: 956 value -- value sent in via javascript 957 globs -- the globals interpreter variables (not used here). 1112 1113 - ``value` - an integer; value sent in via JavaScript 1114 1115 - ``globs`` - a string:object dictionary; the :func:`globals` 1116 interpreter variables (not used here). 958 1117 959 1118 OUTPUT: 960 object961 1119 962 EXAMPLES: 1120 - an object 1121 1122 EXAMPLES:: 1123 963 1124 sage: S = sage.server.notebook.interact.Selector('x', ['first',x^3+5]) 964 1125 sage: S._adaptor(0,globals()) 965 1126 'first' … … 970 1131 971 1132 def use_buttons(self): 972 1133 """ 973 Whether or not to use buttons instead of a drop 974 down menu forthis select list.1134 Whether or not to use buttons instead of a drop down menu for 1135 this select list. 975 1136 976 1137 OUTPUT: 977 bool978 1138 979 EXAMPLES: 1139 - a bool 1140 1141 EXAMPLES:: 1142 980 1143 sage: sage.server.notebook.interact.Selector('x', [1..5]).use_buttons() 981 1144 False 982 1145 sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).use_buttons() … … 986 1149 987 1150 def value_js(self): 988 1151 """ 989 Return javascript string that will give the value of this1152 Return JavaScript string that will give the value of this 990 1153 control element. 991 1154 992 1155 OUTPUT: 993 string -- javascript994 1156 995 EXAMPLES: 1157 - a string - JavaScript 1158 1159 EXAMPLES:: 1160 996 1161 sage: sage.server.notebook.interact.Selector('x', [1..5]).value_js() 997 1162 'this.options[this.selectedIndex].value' 998 1163 sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).value_js() … … 1009 1174 Render this control as a string. 1010 1175 1011 1176 OUTPUT: 1012 string -- html format1013 1177 1014 EXAMPLES: 1178 - a string - HTML format 1179 1180 EXAMPLES:: 1181 1015 1182 sage: sage.server.notebook.interact.Selector('x', [1..5]).render() 1016 1183 '<select...</select>' 1017 1184 sage: sage.server.notebook.interact.Selector('x', [1..5], buttons=True).render() … … 1066 1233 class SliderGeneric(InteractControl): 1067 1234 def __init__(self, var, values, default_value, label=None, display_value=True): 1068 1235 """ 1069 An abstract slider interact control that takes on the given list of1070 values.1236 An abstract slider :func:`interact` control that takes on the 1237 given list of values. 1071 1238 1072 1239 INPUT: 1073 var -- string; name of variable being interactd1074 values -- list; a list of the values that the slider will take on1075 default_value -- default valueoif slider.1076 label -- alternative label to the left of the slider,1077 instead of the variable.1078 display_value -- boolean, whether to display the current value1079 on the slider1080 1240 1081 EXAMPLES: 1241 - ``var`` - a string; name of variable being interacted 1242 1243 - ``values`` - a list; a list of the values that the slider 1244 will take on 1245 1246 - ``default_value`` - an object; default value of the slider. 1247 1248 - ``label`` - a string; alternative label to the left of the 1249 slider, instead of the variable. 1250 1251 - ``display_value`` - a bool; whether to display the current 1252 value on the slider 1253 1254 EXAMPLES:: 1255 1082 1256 sage: sage.server.notebook.interact.SliderGeneric('x', [1..5], 2, 'alpha') 1083 1257 Abstract Slider Interact Control: alpha [1--|2|---5] 1084 1258 """ … … 1090 1264 """ 1091 1265 Return string representation of this slider control. 1092 1266 1093 EXAMPLES: 1267 OUTPUT: 1268 1269 - a string 1270 1271 EXAMPLES:: 1272 1094 1273 sage: sage.server.notebook.interact.SliderGeneric('x', [1..5], 2, 'alpha').__repr__() 1095 1274 'Abstract Slider Interact Control: alpha [1--|2|---5]' 1096 1275 """ … … 1103 1282 Return list of values the slider acts on. 1104 1283 1105 1284 OUTPUT: 1106 list 1285 1286 - a list 1107 1287 1108 EXAMPLES: 1288 EXAMPLES:: 1289 1109 1290 sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').values() 1110 1291 [1, 2, 3, 4, 5] 1111 1292 """ … … 1116 1297 Returns whether to display the value on the slider. 1117 1298 1118 1299 OUTPUT: 1119 boolean 1300 1301 - a bool 1120 1302 1121 EXAMPLES: 1303 EXAMPLES:: 1304 1122 1305 sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').display_value() 1123 1306 True 1124 1307 """ … … 1126 1309 1127 1310 def values_js(self): 1128 1311 """ 1129 Returns Javascript array representation of values or null if display_value is False 1312 Returns JavaScript array representation of values or 'null' if 1313 display_value=False 1130 1314 1131 1315 OUTPUT: 1132 string 1316 1317 - a string 1133 1318 1134 EXAMPLES: 1319 EXAMPLES:: 1320 1135 1321 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').values_js() 1136 1322 '["1","2","3","4","5"]' 1137 1323 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha', False).values_js() … … 1152 1338 class Slider(SliderGeneric): 1153 1339 def __init__(self, var, values, default_position, label=None, display_value=True): 1154 1340 """ 1155 A slider interactcontrol that takes on the given list of1341 A slider :func:`interact` control that takes on the given list of 1156 1342 values. 1157 1343 1158 1344 INPUT: 1159 var -- string; name of variable being interactd1160 values -- list; a list of the values that the slider will take on1161 default_position -- int; default location that the slider is set to.1162 label -- alternative label to the left of the slider,1163 instead of the variable.1164 display_value -- boolean, whether to display the current value right1165 of the slider1166 1345 1167 EXAMPLES: 1346 - ``var`` - a string; name of variable being interacted 1347 1348 - ``values`` - a list; a list of the values that the slider 1349 will take on 1350 1351 - ``default_position`` - an integer; default location that the 1352 slider is set to. 1353 1354 - ``label`` - a string; alternative label to the left of the 1355 slider, instead of the variable. 1356 1357 - ``display_value`` - a bool, whether to display the current 1358 value right of the slider 1359 1360 EXAMPLES:: 1361 1168 1362 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha') 1169 1363 Slider Interact Control: alpha [1--|3|---5] 1170 1364 """ … … 1175 1369 """ 1176 1370 Return string representation of this slider control. 1177 1371 1178 EXAMPLES: 1372 OUTPUT: 1373 1374 - a string 1375 1376 EXAMPLES:: 1377 1179 1378 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').__repr__() 1180 1379 'Slider Interact Control: alpha [1--|3|---5]' 1181 1380 """ … … 1187 1386 """ 1188 1387 Return the default position (as an integer) of the slider. 1189 1388 1190 EXAMPLES: 1389 OUTPUT: 1390 1391 - an integer 1392 1393 EXAMPLES:: 1394 1191 1395 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').default_position() 1192 1396 2 1193 1397 """ … … 1195 1399 1196 1400 def value_js(self): 1197 1401 """ 1198 Return javascript string that will give the1199 value of thiscontrol element.1402 Return JavaScript string that will give the value of this 1403 control element. 1200 1404 1201 1405 OUTPUT: 1202 string -- javascript1203 1406 1204 EXAMPLES: 1407 - a string - JavaScript 1408 1409 EXAMPLES:: 1410 1205 1411 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').value_js() 1206 1412 'position' 1207 1413 """ … … 1213 1419 element selected by this control. 1214 1420 1215 1421 INPUT: 1216 position -- position of the slider 1217 globs -- the globals interpreter variables (not used here). 1422 1423 - ``position`` - an object; position of the slider 1424 1425 - ``globs`` - a string:object dictionary; the :func:`globals` 1426 interpreter variables (not used here). 1218 1427 1219 1428 OUTPUT: 1220 object1221 1429 1222 EXAMPLES: 1430 - an object 1431 1432 EXAMPLES:: 1433 1223 1434 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha')._adaptor(2,globals()) 1224 1435 3 1225 1436 """ … … 1233 1444 Render this control as an HTML string. 1234 1445 1235 1446 OUTPUT: 1236 string -- html format1237 1447 1238 EXAMPLES: 1448 - a string - HTML format 1449 1450 EXAMPLES:: 1451 1239 1452 sage: sage.server.notebook.interact.Slider('x', [1..5], 2, 'alpha').render() 1240 1453 '<table>...<div ...var values = ["1","2","3","4","5"];...' 1241 1454 … … 1251 1464 class RangeSlider(SliderGeneric): 1252 1465 def __init__(self, var, values, default_position, label=None, display_value=True): 1253 1466 """ 1254 A range slider interact control that takes on the given list of1255 values.1467 A range slider :func:`interact` control that takes on the given 1468 list of values. 1256 1469 1257 1470 INPUT: 1258 var -- string; name of variable being interactd1259 values -- list; a list of the values that the slider will take on1260 default_position -- (int,int); default location that the slider is set to.1261 label -- alternative label to the left of the slider,1262 instead of the variable.1263 display_value -- boolean, whether to display the current value below1264 the slider1265 1471 1266 EXAMPLES: 1472 - ``var`` - a string; name of variable being interacted 1473 1474 - ``values`` - a list; a list of the values that the slider 1475 will take on 1476 1477 - ``default_position`` - an integer 2-tuple; default location 1478 that the slider is set to. 1479 1480 - ``label`` - a string; alternative label to the left of the 1481 slider, instead of the variable. 1482 1483 - ``display_value`` - a bool, whether to display the current 1484 value below the slider 1485 1486 EXAMPLES:: 1487 1267 1488 sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha') 1268 1489 Range Slider Interact Control: alpha [1--|3==4|---5] 1269 1490 """ … … 1274 1495 """ 1275 1496 Return string representation of this slider control. 1276 1497 1277 EXAMPLES: 1498 OUTPUT: 1499 1500 - a string 1501 1502 EXAMPLES:: 1503 1278 1504 sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').__repr__() 1279 1505 'Range Slider Interact Control: alpha [1--|3==4|---5]' 1280 1506 """ … … 1286 1512 """ 1287 1513 Return the default position (as an integer) of the slider. 1288 1514 1289 EXAMPLES: 1515 OUTPUT: 1516 1517 - an integer 2-tuple 1518 1519 EXAMPLES:: 1520 1290 1521 sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').default_position() 1291 1522 (2, 3) 1292 1523 """ … … 1294 1525 1295 1526 def value_js(self): 1296 1527 """ 1297 Return javascript string that will give the1298 value of thiscontrol element.1528 Return JavaScript string that will give the value of this 1529 control element. 1299 1530 1300 1531 OUTPUT: 1301 string -- javascript1302 1532 1303 EXAMPLES: 1533 - a string - JavaScript 1534 1535 EXAMPLES:: 1536 1304 1537 sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').value_js() 1305 1538 "pos[0]+' '+pos[1]" 1306 1539 """ … … 1312 1545 element selected by this control. 1313 1546 1314 1547 INPUT: 1315 position -- position of the slider 1316 globs -- the globals interpreter variables (not used here). 1548 1549 - ``position`` - an object; position of the slider 1550 1551 - ``globs` - a string:object dictionary; the :func:`globals` 1552 interpreter variables (not used here). 1317 1553 1318 1554 OUTPUT: 1319 object1320 1555 1321 EXAMPLES: 1556 - an object 1557 1558 EXAMPLES:: 1559 1322 1560 sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha')._adaptor("2 3",globals()) 1323 1561 (3, 4) 1324 1562 """ … … 1332 1570 Render this control as an HTML string. 1333 1571 1334 1572 OUTPUT: 1335 string -- html format1336 1573 1337 EXAMPLES: 1574 - string - HTML format 1575 1576 EXAMPLES:: 1577 1338 1578 sage: sage.server.notebook.interact.RangeSlider('x', [1..5], (2,3), 'alpha').render() 1339 1579 '<table>...<div ...var values = ["1","2","3","4","5"];...' 1340 1580 … … 1351 1591 class TextControl(InteractControl): 1352 1592 def __init__(self, var, data): 1353 1593 """ 1354 A text field interactcontrol1594 A text field :func:`interact` control 1355 1595 1356 1596 INPUT: 1357 data -- the HTML value of the text field1358 1597 1359 EXAMPLES: 1598 - ``data`` - a string; the HTML value of the text field 1599 1600 EXAMPLES:: 1601 1360 1602 sage: sage.server.notebook.interact.TextControl('x', 'something') 1361 1603 Text Interact Control: something 1362 1604 """ … … 1367 1609 """ 1368 1610 Return string representation of this control. 1369 1611 1370 EXAMPLES: 1612 OUTPUT: 1613 1614 - a string 1615 1616 EXAMPLES:: 1617 1371 1618 sage: sage.server.notebook.interact.TextControl('x', 'something').__repr__() 1372 1619 'Text Interact Control: something' 1373 1620 """ … … 1378 1625 Render this control as an HTML string. 1379 1626 1380 1627 OUTPUT: 1381 string -- html format1382 1628 1383 EXAMPLES: 1629 - a string - HTML format 1630 1631 EXAMPLES:: 1632 1384 1633 sage: sage.server.notebook.interact.TextControl('x', 'something').render() 1385 1634 '<div ...>something</div>' 1386 1635 """ … … 1390 1639 class InteractCanvas: 1391 1640 def __init__(self, controls, id, **options): 1392 1641 """ 1393 Base class for interact canvases. This is where all the controls1394 along with the output of the interactd function are laid out1395 a nd rendered.1642 Base class for :func:`interact` canvases. This is where all 1643 the controls along with the output of the interacted function 1644 are laid out and rendered. 1396 1645 1397 1646 INPUT: 1398 controls -- a list of InteractControl instances. 1399 id -- the id of the cell that contains this InteractCanvas. 1400 options -- any additional keyword arguments (for example, auto_update=False) 1647 1648 - ``controls`` - a list of :class:`InteractControl` instances. 1649 1650 - ``id`` - an integer; the id of the cell that contains this 1651 InteractCanvas. 1652 1653 - ``options`` - any additional keyword arguments (for example, 1654 auto_update=False) 1401 1655 1402 EXAMPLES: 1656 EXAMPLES:: 1657 1403 1658 sage: B = sage.server.notebook.interact.InputBox('x',2) 1404 1659 sage: sage.server.notebook.interact.InteractCanvas([B], 3) 1405 1660 Interactive canvas in cell 3 with 1 controls … … 1415 1670 """ 1416 1671 Print representation of an interactive canvas. 1417 1672 1418 EXAMPLES: 1673 OUTPUT: 1674 1675 - a string 1676 1677 EXAMPLES:: 1678 1419 1679 sage: B = sage.server.notebook.interact.InputBox('x',2) 1420 1680 sage: sage.server.notebook.interact.InteractCanvas([B], 3).__repr__() 1421 1681 'Interactive canvas in cell 3 with 1 controls' … … 1424 1684 self.__cell_id, len(self.__controls)) 1425 1685 1426 1686 def is_auto_update(self): 1427 """1687 r""" 1428 1688 Returns True if any change of the values for the controls on 1429 this canvas should cause an update. If auto_update=Falsewas1689 this canvas should cause an update. If `auto_update=False` was 1430 1690 not specified in the constructor for this canvas, then this 1431 1691 will default to True. 1432 1692 1433 EXAMPLES: 1693 OUTPUT: 1694 1695 - a bool 1696 1697 EXAMPLES:: 1698 1434 1699 sage: B = sage.server.notebook.interact.InputBox('x',2) 1435 1700 sage: canvas = sage.server.notebook.interact.InteractCanvas([B], 3) 1436 1701 sage: canvas.is_auto_update() … … 1442 1707 return self.__options.get('auto_update', True) 1443 1708 1444 1709 def cell_id(self): 1445 """1446 Returns the cell id associated to this InteractCanvas.1710 r""" 1711 Returns the cell id associated to this :class:`InteractCanvas`. 1447 1712 1448 EXAMPLES: 1713 OUTPUT: 1714 1715 - an integer 1716 1717 EXAMPLES:: 1718 1449 1719 sage: B = sage.server.notebook.interact.InputBox('x',2) 1450 1720 sage: canvas = sage.server.notebook.interact.InteractCanvas([B], 3) 1451 1721 sage: canvas.cell_id() … … 1455 1725 1456 1726 def controls(self): 1457 1727 """ 1458 Return list of controls in this canvas.1728 Return a list of controls in this canvas. 1459 1729 1460 WARNING: Returns a reference to a mutable list.1730 OUTPUT: 1461 1731 1462 EXAMPLES: 1732 - list of controls 1733 1734 .. note:: Returns a reference to a mutable list. 1735 1736 EXAMPLES:: 1737 1463 1738 sage: B = sage.server.notebook.interact.InputBox('x',2) 1464 1739 sage: sage.server.notebook.interact.InteractCanvas([B], 3).controls() 1465 1740 [An InputBox interactive control with x=2 and label 'x'] … … 1470 1745 """ 1471 1746 Return the cell id that contains this interactive canvas. 1472 1747 1473 EXAMPLES: 1748 OUTPUT: 1749 1750 - an integer 1751 1752 EXAMPLES:: 1753 1474 1754 sage: B = sage.server.notebook.interact.InputBox('x',2) 1475 1755 sage: sage.server.notebook.interact.InteractCanvas([B], 3).cell_id() 1476 1756 3 … … 1479 1759 1480 1760 def render_output(self): 1481 1761 """ 1482 Render in text (html) form the output portion of the interact canvas. 1762 Render in text (HTML) form the output portion of the 1763 :func:`interact` canvas. 1483 1764 1484 1765 The output contains two special tags, <?TEXT> and <?HTML>, 1485 which get replaced at runtime by the text and htmlparts1766 which get replaced at runtime by the text and HTML parts 1486 1767 of the output of running the function. 1487 1768 1488 1769 OUTPUT: 1489 string -- html1490 1770 1491 EXAMPLES: 1771 - a string - HTML format 1772 1773 EXAMPLES:: 1774 1492 1775 sage: B = sage.server.notebook.interact.InputBox('x',2) 1493 1776 sage: sage.server.notebook.interact.InteractCanvas([B], 3).render_output() 1494 1777 "<div ...</div>" … … 1501 1784 1502 1785 def render_controls(self): 1503 1786 """ 1504 Render in text ( html) form all the input controls.1787 Render in text (HTML) form all the input controls. 1505 1788 1506 1789 OUTPUT: 1507 string -- html1508 1790 1509 EXAMPLES: 1791 - a string - HTML format 1792 1793 EXAMPLES:: 1794 1510 1795 sage: B = sage.server.notebook.interact.InputBox('x',2) 1511 1796 sage: sage.server.notebook.interact.InteractCanvas([B], 3).render_controls() 1512 1797 '<table>...' … … 1523 1808 def wrap_in_outside_frame(self, inside): 1524 1809 """ 1525 1810 Return the entire HTML for the interactive canvas, obtained by 1526 wrapping all the inside htmlof the canvas in a div and a1811 wrapping all the inside HTML of the canvas in a div and a 1527 1812 table. 1528 1813 1529 1814 INPUT: 1530 inside -- string (of HTML) 1815 1816 - ``inside`` - a string; HTML 1531 1817 1532 1818 OUTPUT: 1533 string of HTML 1819 1820 - a string - HTML format 1534 1821 1535 EXAMPLES: 1822 EXAMPLES:: 1823 1536 1824 sage: B = sage.server.notebook.interact.InputBox('x',2) 1537 1825 sage: sage.server.notebook.interact.InteractCanvas([B], 3).wrap_in_outside_frame('<!--inside-->') 1538 1826 "<!--notruncate--><div padding=6 id='div-interact-3'> ...</div>\n " … … 1553 1841 1554 1842 def render(self): 1555 1843 """ 1556 Render in text ( html) the entire interactcanvas.1844 Render in text (HTML) the entire :func:`interact` canvas. 1557 1845 1558 1846 OUTPUT: 1559 string -- html 1847 1848 - string - HTML format 1560 1849 1561 EXAMPLES: 1850 EXAMPLES:: 1851 1562 1852 sage: B = sage.server.notebook.interact.InputBox('x',2) 1563 1853 sage: sage.server.notebook.interact.InteractCanvas([B], 3).render() 1564 1854 '<!--notruncate--><div padding=6 id=\'div-interact-3\'> ...</div>\n ' … … 1570 1860 class JavascriptCodeButton(InteractElement): 1571 1861 def __init__(self, label, code): 1572 1862 """ 1573 This interactelement displays a button which when clicked1574 executes Java script code in the notebook.1863 This :func:`interact` element displays a button which when clicked 1864 executes JavaScript code in the notebook. 1575 1865 1576 EXAMPLES: 1866 EXAMPLES:: 1867 1577 1868 sage: b = sage.server.notebook.interact.JavascriptCodeButton('Push me', 'alert("2")') 1578 1869 """ 1579 1870 self.__label = label … … 1584 1875 r""" 1585 1876 Returns the HTML to display this button. 1586 1877 1587 EXAMPLES: 1878 OUTPUT: 1879 1880 - a string - HTML format 1881 1882 EXAMPLES:: 1883 1588 1884 sage: b = sage.server.notebook.interact.JavascriptCodeButton('Push me', 'alert("2")') 1589 1885 sage: b.render() 1590 1886 '<input type="button" value="Push me" onclick=\'alert("2")\'>\n' … … 1595 1891 class UpdateButton(JavascriptCodeButton): 1596 1892 def __init__(self, cell_id): 1597 1893 r""" 1598 This interactelement creates a button which when clicked1599 causes the interact function in the cell cell_idto be1894 This :func:`interact` element creates a button which when clicked 1895 causes the :func:`interact` function in the cell ``cell_id`` to be 1600 1896 recomputed with the current values of the variables. 1601 1897 1602 EXAMPLES: 1898 INPUT: 1899 1900 - ``cell_id`` - an integer; the ambient cell's id 1901 1902 EXAMPLES:: 1903 1603 1904 sage: b = sage.server.notebook.interact.UpdateButton(0) 1604 1905 sage: b.render() 1605 1906 '<input type="button" value="Update" onclick=\'interact(0, "sage.server.notebook.interact.recompute(0)")\'>\n' … … 1612 1913 r""" 1613 1914 Use interact as a decorator to create interactive Sage notebook 1614 1915 cells with sliders, text boxes, radio buttons, check boxes, and 1615 color selectors. Simply put @interacton the line before a1916 color selectors. Simply put ``@interact`` on the line before a 1616 1917 function definition in a cell by itself, and choose appropriate 1617 1918 defaults for the variable names to determine the types of 1618 1919 controls (see tables below). 1619 1920 1620 1921 INPUT: 1621 f -- a Python function 1922 1923 - ``f`` - a Python function 1622 1924 1623 1925 EXAMPLES: 1926 1624 1927 In each example below we use a single underscore for the function 1625 name. You can use \emph{any}name you want; it does not have to1928 name. You can use *any* name you want; it does not have to 1626 1929 be an underscore. 1627 1930 1628 1931 We create an interact control with two inputs, a text input for 1629 the variable $a$ and a $y$ slider that runs through the range of 1630 integers from $0$ to $19$. 1932 the variable ``a`` and a ``y`` slider that runs through the range of 1933 integers from `0` to `19`. 1934 1935 :: 1936 1631 1937 sage: @interact 1632 1938 ... def _(a=5, y=(0..20)): print a + y 1633 1939 ... 1634 1940 <html>... 1635 1941 1636 Draw a plot interacting with the ``continuous'' variable $a$. By1942 Draw a plot interacting with the "continuous" variable ``a``. By 1637 1943 default continuous variables have exactly 50 possibilities. 1944 1945 :: 1946 1638 1947 sage: @interact 1639 1948 ... def _(a=(0,2)): 1640 1949 ... show(plot(sin(x*(1+a*x)), (x,0,6)), figsize=4) 1641 1950 <html>... 1642 1951 1643 1952 Interact a variable in steps of 1 (we also use an unnamed 1644 function): 1953 function):: 1954 1645 1955 sage: @interact 1646 1956 ... def _(n=(10,100,1)): 1647 1957 ... show(factor(x^n - 1)) 1648 1958 <html>... 1649 1959 1650 Interact two variables: 1960 Interact two variables:: 1961 1651 1962 sage: @interact 1652 1963 ... def _(a=(1,4), b=(0,10)): 1653 1964 ... show(plot(sin(a*x+b), (x,0,6)), figsize=3) 1654 1965 <html>... 1655 1966 1656 Place a block of text among the controls: 1967 Place a block of text among the controls:: 1968 1657 1969 sage: @interact 1658 1970 ... def _(t1=text_control("Factors an integer."), n="1"): 1659 1971 ... print factor(Integer(n)) 1660 1972 <html>... 1661 1973 1662 1974 You do not have to use interact as a decorators; you can also 1663 simply write \code{interact(f)} where f is any Python function 1664 that you have defined, though this is frowned on. E.g., f can 1665 also be a library function as long as it is written in Python: 1975 simply write ``interact(f)`` where ``f`` is any Python function 1976 that you have defined, though this is frowned upon. E.g., ``f`` 1977 can also be a library function as long as it is written in 1978 Python:: 1666 1979 1667 1980 sage: interact(matrix) # put ZZ, 2,2,[1..4] in boxes... 1668 1981 <html>... 1669 1982 1670 1983 If your the time to evaluate your function takes awhile, you may 1671 1984 not want to have it reevaluated every time the inputs change. In 1672 order to prevent this, you can add a keyword 1673 \code{auto_update=False} to your function to prevent it from 1674 updating whenever the values are changed. This will cause a 1675 button labeled 'Update' to appear which you can click on to 1676 re-evaluate your function. 1985 order to prevent this, you can add a keyword ``auto_update=False`` to 1986 your function to prevent it from updating whenever the values are 1987 changed. This will cause a button labeled 'Update' to appear 1988 which you can click on to re-evaluate your function. 1989 1990 :: 1677 1991 1678 1992 sage: @interact 1679 1993 ... def _(n=(10,100,1), auto_update=False): … … 1681 1995 <html>... 1682 1996 1683 1997 DEFAULTS: 1998 1684 1999 Defaults for the variables of the input function determine 1685 interactive controls. The standard controls are \code{input_box},1686 \code{slider}, \code{range_slider}, \code{checkbox}, \code{selector},1687 \code{input_grid}. There is also a color selector and text control2000 interactive controls. The standard controls are ``input_box``, 2001 ``slider``, ``range_slider``, ``checkbox``, ``selector``, and 2002 ``input_grid``. There is also a color selector and text control 1688 2003 (see defaults below). 2004 1689 2005 1690 \begin{itemize} 1691 \item u = input_box(default=None, label=None, type=None) 1692 -- input box with given default; use type=str to 1693 get input as an arbitrary string 1694 \item u = slider(vmin, vmax=None,step_size=1,default=None,label=None) 1695 -- slider with given list of possible values; vmin can be a list 1696 \item u = range_slider(vmin, vmax=None,step_size=1,default=None,label=None) 1697 -- range slider with given list of possible values; 1698 vmin can be a list 1699 \item u = checkbox(default=True, label=None) 1700 -- a checkbox 1701 \item u = selector(values, label=None, nrows=None, ncols=None, buttons=False) 1702 -- a dropdown menu or buttons (get buttons if nrows, 1703 ncols, or buttons is set, otherwise a dropdown menu) 1704 \item u = input_grid(nrows, ncols, default=None, label=None, 1705 to_value=lambda x:x, width=4) 1706 -- an editable grid of objects (a matrix or array) 1707 \item u = text_control(value='') 1708 -- a block of text 1709 \end{itemize} 2006 * ``u = input_box(default=None, label=None, type=None)`` - 2007 input box with given ``default``; use ``type=str`` to get 2008 input as an arbitrary string 2009 2010 2011 * ``u = slider(vmin, vmax=None, step_size=1, default=None, 2012 label=None)`` - slider with given list of possible values; 2013 ``vmin`` can be a list 2014 2015 2016 * ``u = range_slider(vmin, vmax=None, step_size=1, 2017 default=None, label=None)`` - range slider with given list 2018 of possible values; ``vmin`` can be a list 2019 2020 2021 * ``u = checkbox(default=True, label=None)`` - a checkbox 2022 2023 2024 * ``u = selector(values, label=None, nrows=None, ncols=None, 2025 buttons=False)`` - a dropdown menu or buttons (get buttons 2026 if ``nrows``, ``ncols``, or ``buttons`` is set, otherwise a 2027 dropdown menu) 2028 2029 2030 * ``u = input_grid(nrows, ncols, default=None, label=None, 2031 to_value=lambda x:x, width=4)`` - an editable grid of 2032 objects (a matrix or array) 2033 2034 2035 * ``u = text_control(value='')`` - a block of text 2036 1710 2037 1711 2038 You can create a color selector by setting the default value for a 1712 variable to Color(...).2039 variable to ``Color(...)``. 1713 2040 1714 2041 There are also some convenient defaults that allow you to make 1715 2042 controls automatically without having to explicitly specify them. 1716 E.g., you can make $x$ a continuous slider of values between $u$1717 and $v$ by just writing \code{x=(u,v)}in the argument list of2043 E.g., you can make ``x`` a continuous slider of values between ``u`` 2044 and ``v`` by just writing ``x=(u,v)`` in the argument list of 1718 2045 your function. These are all just convenient shortcuts for 1719 2046 creating the controls listed above. 1720 2047 1721 \begin{itemize} 1722 \item u -- blank input_box field 1723 \item u = element -- input_box with default=element, if element not below. 1724 \item u = (umin,umax) -- continuous slider (really 100 steps) 1725 \item u = (umin,umax,du)-- slider with step size du 1726 \item u = list -- buttons if len(list) at most 5; otherwise, drop down 1727 \item u = generator -- a slider (up to 10000 steps) 1728 \item u = bool -- a checkbox 1729 \item u = Color('blue') -- a 2d RGB color selector; returns Color object 1730 \item u = (default, v) -- v as above, with given default value 1731 \item u = (label, v) -- v as above, with given label (a string) 1732 \item u = matrix -- an input_grid with to_value set to matrix.parent() 1733 and default values given by the matrix 1734 \end{itemize} 2048 * ``u`` - blank input_box field 1735 2049 1736 WARNING: Suppose you would like to make a interactive with a 1737 default rgb color of (1,0,0), so the function would have signature 1738 \code{f(color=(1,0,0))}. Unfortunately, the above shortcuts reinterpret 1739 the (1,0,0) as a discrete slider with step size 0 between 1 and 0. 1740 Instead you should do the following: 1741 sage: @interact 1742 ... def _(v = input_box((1,0,0))): 1743 ... show(plot(sin,color=v)) 1744 <html>... 2050 * ``u = element`` - input_box with ``default=element``, if 2051 element not below. 2052 2053 * ``u = (umin,umax)`` - continuous slider (really `100` steps) 2054 2055 * ``u = (umin,umax,du)`` - slider with step size ``du`` 2056 2057 * ``u = list`` - buttons if ``len(list)`` at most `5`; 2058 otherwise, drop down 2059 2060 * ``u = generator`` - a slider (up to `10000` steps) 2061 2062 * ``u = bool`` - a checkbox 2063 2064 * ``u = Color('blue')`` - a 2D RGB color selector; returns 2065 ``Color`` object 2066 2067 * ``u = (default, v)`` - ``v`` as above, with given 2068 ``default`` value 2069 2070 * ``u = (label, v)`` - ``v`` as above, with given ``label`` 2071 (a string) 2072 2073 * ``u = matrix`` - an ``input_grid`` with ``to_value`` set to 2074 ``matrix.parent()`` and default values given by the matrix 2075 2076 .. note:: 2077 2078 Suppose you would like to make a interactive with a default 2079 RGB color of ``(1,0,0)``, so the function would have signature 2080 ``f(color=(1,0,0))``. Unfortunately, the above shortcuts 2081 reinterpret the ``(1,0,0)`` as a discrete slider with step 2082 size 0 between 1 and 0. Instead you should do the 2083 following:: 2084 2085 sage: @interact 2086 ... def _(v = input_box((1,0,0))): 2087 ... show(plot(sin,color=v)) 2088 <html>... 1745 2089 1746 2090 MORE EXAMPLES: 1747 We give an input box that allows one to enter completely arbitrary strings. 2091 2092 We give an input box that allows one to enter completely arbitrary 2093 strings:: 2094 1748 2095 sage: @interact 1749 2096 ... def _(a=input_box('sage', label="Enter your name", type=str)): 1750 2097 ... print "Hello there %s"%a.capitalize() 1751 2098 <html>... 1752 2099 1753 The scope of variables that you control via interact are local to 1754 the scope of the function being interacted with. However, by using 1755 the global Python keyword, you can still modify global variables 1756 as follows: 2100 The scope of variables that you control via :func:`interact` are local 2101 to the scope of the function being interacted with. However, by 2102 using the ``global`` Python keyword, you can still modify global 2103 variables as follows:: 2104 1757 2105 sage: xyz = 10 1758 2106 sage: @interact 1759 2107 ... def _(a=('xyz',5)): … … 1761 2109 ... xyz = a 1762 2110 <html>... 1763 2111 1764 If you enter the above you obtain an interactcanvas. Entering1765 values in the box , changes the global variable xyz.2112 If you enter the above you obtain an :func:`interact` canvas. Entering 2113 values in the box changes the global variable ``xyz``:: 1766 2114 1767 2115 sage: @interact 1768 2116 ... def _(title=["A Plot Demo", "Something silly", "something tricky"], a=input_box(sin(x*sin(x*sin(x))), 'function'), … … 1772 2120 ... show(plot(a, -zoom*pi,zoom*pi, color=clr, thickness=thickness, plot_points=plot_points)) 1773 2121 <html>... 1774 2122 1775 We give defaults and name the variables: 2123 We give defaults and name the variables:: 2124 1776 2125 sage: @interact 1777 2126 ... def _(a=('first', (1,4)), b=(0,10)): 1778 2127 ... show(plot(sin(a*x+sin(b*x)), (x,0,6)), figsize=3) 1779 2128 <html>... 1780 2129 1781 Another example involving labels and defaults, and the 1782 slider command. 2130 Another example involving labels, defaults, and the slider 2131 command:: 2132 1783 2133 sage: @interact 1784 2134 ... def _(a = slider(1, 4, default=2, label='Multiplier'), 1785 2135 ... b = slider(0, 10, default=0, label='Phase Variable')): 1786 2136 ... show(plot(sin(a*x+b), (x,0,6)), figsize=4) 1787 2137 <html>... 1788 2138 1789 An example where the range slider control is useful. 2139 An example where the range slider control is useful:: 2140 1790 2141 sage: @interact 1791 2142 ... def _(b = range_slider(-20, 20, 1, default=(-19,3), label='Range')): 1792 2143 ... plot(sin(x)/x, b[0], b[1]).show(xmin=b[0],xmax=b[1]) 1793 2144 <html>... 1794 2145 1795 An example using checkboxes, obtained by making the default values bools. 2146 An example using checkboxes, obtained by making the default values 2147 bools:: 2148 1796 2149 sage: @interact 1797 2150 ... def _(axes=('Show axes', True), square=False): 1798 2151 ... show(plot(sin, -5,5), axes=axes, aspect_ratio = (1 if square else None)) 1799 2152 <html>... 1800 2153 1801 An example generating a random walk that uses a checkbox control to determine 1802 whether points are placed at each step: 2154 An example generating a random walk that uses a checkbox control 2155 to determine whether points are placed at each step:: 2156 1803 2157 sage: @interact 1804 2158 ... def foo(pts = checkbox(True, "points"), n = (50,(10..100))): 1805 2159 ... s = 0; v = [(0,0)] … … 1811 2165 ... show(L) 1812 2166 <html>... 1813 2167 1814 You can rotate and zoom into 3D graphics while 1815 interacting with a variable. 2168 You can rotate and zoom into 3D graphics while interacting with a 2169 variable:: 2170 1816 2171 sage: @interact 1817 2172 ... def _(a=(0,1)): 1818 2173 ... x,y = var('x,y') 1819 2174 ... show(plot3d(sin(x*cos(y*a)), (x,0,5), (y,0,5)), figsize=4) 1820 2175 <html>... 1821 2176 1822 A random polygon: 2177 A random polygon:: 2178 1823 2179 sage: pts = [(random(), random()) for _ in xrange(20)] 1824 2180 sage: @interact 1825 2181 ... def _(n = (4..len(pts)), c=Color('purple') ): … … 1827 2183 ... show(G, figsize=5, xmin=0, ymin=0) 1828 2184 <html>... 1829 2185 1830 Two "sinks" displayed simultaneously via a contour plot and a 3d 1831 interactive plot: 2186 Two "sinks" displayed simultaneously via a contour plot and a 3D 2187 interactive plot:: 2188 1832 2189 sage: @interact 1833 2190 ... def _(q1=(-1,(-3,3)), q2=(-2,(-3,3))): 1834 2191 ... x,y = var('x,y') … … 1838 2195 ... show(plot3d(f, (x,-2,2), (y,-2,2)), figsize=4) 1839 2196 <html>... 1840 2197 1841 This is similar to above, but you can select the color map from a dropdown menu: 2198 This is similar to above, but you can select the color map from a 2199 dropdown menu:: 2200 1842 2201 sage: @interact 1843 2202 ... def _(q1=(-1,(-3,3)), q2=(-2,(-3,3)), 1844 2203 ... cmap=['autumn', 'bone', 'cool', 'copper', 'gray', 'hot', 'hsv', … … 1849 2208 ... show(C, figsize=3, aspect_ratio=1) 1850 2209 <html>... 1851 2210 1852 A quadratic roots etch-a-sketch: 2211 A quadratic roots etch-a-sketch:: 2212 1853 2213 sage: v = [] 1854 2214 sage: html('<h2>Quadratic Root Etch-a-sketch</h2>') 1855 2215 <html><font color='black'><h2>Quadratic Root Etch-a-sketch</h2></font></html> … … 1863 2223 ... show(line(v, rgbcolor='purple') + point(P, pointsize=200)) 1864 2224 <html>... 1865 2225 1866 In the following example, we only generate data for a given n 1867 once, so that as one varies p the data doesn't not randomly 1868 change. We do this by simply caching the results for each n 1869 in a dictionary. 2226 In the following example, we only generate data for a given ``n`` 2227 once, so that as one varies ``p`` the data does not randomly change. 2228 We do this by simply caching the results for each ``n`` in a 2229 dictionary.:: 2230 1870 2231 sage: data = {} 1871 2232 sage: @interact 1872 2233 ... def _(n=(500,(100,5000,1)), p=(1,(0.1,10))): … … 1876 2237 ... show(points([(x^p,y^p) for x,y in data[n]], rgbcolor='black'), xmin=0, ymin=0, axes=False) 1877 2238 <html>... 1878 2239 1879 A conchoid: 2240 A conchoid:: 2241 1880 2242 sage: @interact 1881 2243 ... def _(k=(1.2,(1.1,2)), k_2=(1.2,(1.1,2)), a=(1.5,(1.1,2))): 1882 2244 ... u, v = var('u,v') … … 1884 2246 ... show(parametric_plot3d(f, (u,0,6*pi), (v,0,2*pi), plot_points=[40,40], texture=(0,0.5,0))) 1885 2247 <html>... 1886 2248 1887 An input grid: 2249 An input grid:: 2250 1888 2251 sage: @interact 1889 2252 ... def _(A=matrix(QQ,3,3,range(9)), v=matrix(QQ,3,1,range(3))): 1890 2253 ... try: … … 1937 2300 class control: 1938 2301 def __init__(self, label=None): 1939 2302 """ 1940 An interactive control object used with the interactcommand.2303 An interactive control object used with the :func:`interact` command. 1941 2304 This is the abstract base class. 1942 2305 1943 2306 INPUTS: 1944 label -- a string 2307 2308 - ``label`` - a string 1945 2309 1946 EXAMPLES: 2310 EXAMPLES:: 2311 1947 2312 sage: sage.server.notebook.interact.control('a control') 1948 2313 Interative control 'a control' (abstract base class) 1949 2314 """ … … 1951 2316 1952 2317 def __repr__(self): 1953 2318 """ 1954 Return string representation of this control. 1955 (It justmentions the label and that this is an abstract base class.)2319 Return string representation of this control. (It just 2320 mentions the label and that this is an abstract base class.) 1956 2321 1957 EXAMPLES: 2322 OUTPUT: 2323 2324 - a string 2325 2326 EXAMPLES:: 2327 1958 2328 sage: sage.server.notebook.interact.control('a control').__repr__() 1959 2329 "Interative control 'a control' (abstract base class)" 1960 2330 """ … … 1965 2335 Return the label of this control. 1966 2336 1967 2337 OUTPUT: 1968 a string 1969 1970 EXAMPLES: 2338 2339 - a string 2340 2341 EXAMPLES:: 2342 1971 2343 sage: sage.server.notebook.interact.control('a control').label() 1972 2344 'a control' 1973 2345 sage: selector([1,2,7], 'alpha').label() … … 1980 2352 Set the label of this control. 1981 2353 1982 2354 INPUT: 1983 label -- a string 2355 2356 - ``label`` - a string 1984 2357 1985 EXAMPLES: 2358 EXAMPLES:: 2359 1986 2360 sage: C = sage.server.notebook.interact.control('a control') 1987 2361 sage: C.set_label('sage'); C 1988 2362 Interative control 'sage' (abstract base class) … … 1993 2367 def __init__(self, default=None, label=None, type=None, width = 80): 1994 2368 r""" 1995 2369 An input box interactive control. Use this in conjunction 1996 with the interact command. 1997 1998 \code{input_box(default=None, label=None, type=None)} 2370 with the :func:`interact` command. 1999 2371 2000 2372 INPUT: 2001 default -- object; the default put in this input box 2002 label -- the label rendered to the left of the box. 2003 type -- coerce inputs to this; this doesn't have to be 2004 an actual type, since anything callable will do. 2005 width -- width of text box in characters 2373 2374 - ``default`` - an object; the default put in this input box 2375 2376 - ``label`` - a string; the label rendered to the left of the 2377 box. 2378 2379 - ``type`` - a type; coerce inputs to this; this doesn't 2380 have to be an actual type, since anything callable will do. 2381 2382 - ``width`` - an integer; width of text box in characters 2006 2383 2007 EXAMPLES: 2384 EXAMPLES:: 2385 2008 2386 sage: input_box("2+2", 'expression') 2009 2387 Interact input box labeled 'expression' with default value '2+2' 2010 2388 sage: input_box('sage', label="Enter your name", type=str) … … 2019 2397 """ 2020 2398 Return print representation of this input box. 2021 2399 2022 EXAMPLES: 2400 OUTPUT: 2401 2402 - a string 2403 2404 EXAMPLES:: 2405 2023 2406 sage: input_box("2+2", 'expression').__repr__() 2024 2407 "Interact input box labeled 'expression' with default value '2+2'" 2025 2408 """ … … 2029 2412 """ 2030 2413 Return the default value of this input box. 2031 2414 2032 EXAMPLES: 2415 OUTPUT: 2416 2417 - an object 2418 2419 EXAMPLES:: 2420 2033 2421 sage: input_box('2+2', 'Expression').default() 2034 2422 '2+2' 2035 2423 sage: input_box(x^2 + 1, 'Expression').default() … … 2042 2430 def type(self): 2043 2431 """ 2044 2432 Return the type that elements of this input box are coerced to 2045 or None if they are not coerced (they have whatever type they2046 evaluate to).2433 or None if they are not coerced (they have whatever type 2434 they evaluate to). 2047 2435 2048 EXAMPLES: 2436 OUTPUT: 2437 2438 - a type 2439 2440 EXAMPLES:: 2441 2049 2442 sage: input_box("2+2", 'expression', type=int).type() 2050 2443 <type 'int'> 2051 2444 sage: input_box("2+2", 'expression').type() is None … … 2055 2448 2056 2449 def render(self, var): 2057 2450 r""" 2058 Return rendering of this input box as an InputBox to be used2059 for an interact canvas. Basically this specializes this2060 input to be used for a specific function and variable.2451 Return rendering of this input box as an :class:`InputBox` to be 2452 used for an :func:`interact` canvas. Basically this specializes 2453 this input to be used for a specific function and variable. 2061 2454 2062 2455 INPUT: 2063 var -- a string (variable; one of the variable names input to f) 2456 2457 - ``var`` - a string (variable; one of the variable names 2458 input to ``f``) 2064 2459 2065 2460 OUTPUT: 2066 InputBox -- an InputBox object.2067 2461 2068 EXAMPLES: 2462 - an :class:`InputBox` instance 2463 2464 EXAMPLES:: 2465 2069 2466 sage: input_box("2+2", 'Exp').render('x') 2070 2467 An InputBox interactive control with x='2+2' and label 'Exp' 2071 2468 """ … … 2079 2476 def __init__(self, nrows, ncols, default=None, label=None, to_value=lambda x: x, width=4): 2080 2477 r""" 2081 2478 An input grid interactive control. Use this in conjunction 2082 with the interactcommand.2479 with the :func:`interact` command. 2083 2480 2084 2481 INPUT: 2085 nrows -- integer 2086 ncols -- integer 2087 default -- object; the default put in this input box 2088 label -- the label rendered to the left of the box. 2089 to_value -- the grid output (list of rows) is sent through 2090 this function. This may reformat the data or 2091 coerce the type. 2092 width -- size of each input box in characters 2482 2483 - ``nrows`` - an integer 2484 2485 - ``ncols`` - an integer 2486 2487 - ``default`` - an object; the default put in this input box 2488 2489 - ``label`` - a string; the label rendered to the left of the 2490 box. 2491 2492 - ``to_value`` - a list; the grid output (list of rows) is 2493 sent through this function. This may reformat the data or 2494 coerce the type. 2495 2496 - ``width`` - an integer; size of each input box in characters 2093 2497 2094 2498 NOTEBOOK EXAMPLE: 2499 2095 2500 @interact 2096 2501 def _(m = input_grid(2,2, default = [[1,7],[3,4]], 2097 2502 label='M=', to_value=matrix), … … 2103 2508 except: 2104 2509 html('There is no solution to $$%s x=%s$$'%(latex(m), latex(v))) 2105 2510 2511 EXAMPLES:: 2106 2512 2107 EXAMPLES:2108 2513 sage: input_grid(2,2, default = 0, label='M') 2109 2514 Interact 2 x 2 input grid control labeled M with default value 0 2110 2515 sage: input_grid(2,2, default = [[1,2],[3,4]], label='M') … … 2126 2531 """ 2127 2532 Return print representation of this input box. 2128 2533 2129 EXAMPLES: 2534 OUTPUT: 2535 2536 - a string 2537 2538 EXAMPLES:: 2539 2130 2540 sage: input_grid(2,2, label='M').__repr__() 2131 2541 'Interact 2 x 2 input grid control labeled M with default value None' 2132 2542 … … 2140 2550 """ 2141 2551 Return the default value of this input grid. 2142 2552 2143 EXAMPLES: 2553 OUTPUT: 2554 2555 - an object 2556 2557 EXAMPLES:: 2558 2144 2559 sage: input_grid(2,2, default=1).default() 2145 2560 1 2146 2561 """ … … 2149 2564 2150 2565 def render(self, var): 2151 2566 r""" 2152 Return rendering of this input grid as an InputGrid to be used2153 for an interact canvas. Basically this specializes this2154 input to be used for a specific function and variable.2567 Return rendering of this input grid as an :class:`InputGrid` to be 2568 used for an :func:`interact` canvas. Basically this specializes 2569 this input to be used for a specific function and variable. 2155 2570 2156 2571 INPUT: 2157 var -- a string (variable; one of the variable names input to f) 2572 2573 - ``var`` - a string (variable; one of the variable names 2574 input to ``f``) 2158 2575 2159 2576 OUTPUT: 2160 InputGrid -- an InputGrid object.2161 2577 2162 EXAMPLES: 2578 - an :class:`InputGrid` instance. 2579 2580 EXAMPLES:: 2581 2163 2582 sage: input_grid(2,2).render('x') 2164 2583 A 2 x 2 InputGrid interactive control with x=[[None, None], [None, None]] and label 'x' 2165 2584 … … 2171 2590 class checkbox(input_box): 2172 2591 def __init__(self, default=True, label=None): 2173 2592 """ 2174 A checkbox interactive control. Use this in conj ecture2175 with the interactcommand.2593 A checkbox interactive control. Use this in conjunction with 2594 the :func:`interact` command. 2176 2595 2177 2596 INPUT: 2178 default -- bool (default: True); whether box should be checked or not2179 label -- str or None (default: None) text label rendered to the left of the box2180 2597 2181 EXAMPLES: 2598 - ``default`` - a bool (default: True); whether box should be 2599 checked or not 2600 2601 - ``label`` - a string (default: None) text label rendered to 2602 the left of the box 2603 2604 EXAMPLES:: 2605 2182 2606 sage: checkbox(False, "Points") 2183 2607 Interact checkbox labeled 'Points' with default value False 2184 2608 sage: checkbox(True, "Points") … … 2194 2618 """ 2195 2619 Print representation of this checkbox. 2196 2620 2197 EXAMPLES: 2621 OUTPUT: 2622 2623 - a string 2624 2625 EXAMPLES:: 2626 2198 2627 sage: checkbox(True, "Points").__repr__() 2199 2628 "Interact checkbox labeled 'Points' with default value True" 2200 2629 """ … … 2248 2677 Returns list of values that this slider takes on, in order. 2249 2678 2250 2679 OUTPUT: 2251 list -- list of values2252 2680 2253 WARNING: This is a reference to a mutable list.2681 - a list 2254 2682 2255 EXAMPLES: 2683 .. note:: This is a reference to a mutable list. 2684 2685 EXAMPLES:: 2686 2256 2687 sage: sage.server.notebook.interact.slider(1,10,1/2).values() 2257 2688 [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] 2258 2689 """ … … 2263 2694 Returns whether to display the value on the slider. 2264 2695 2265 2696 OUTPUT: 2266 boolean 2697 2698 - a bool 2267 2699 2268 EXAMPLES: 2700 EXAMPLES:: 2701 2269 2702 sage.server.notebook.interact.slider_generic(1,10,1/2).display_value() 2270 2703 True 2271 2704 """ … … 2276 2709 def __init__(self, vmin, vmax=None, step_size=None, default=None, label=None, display_value=True): 2277 2710 r""" 2278 2711 An interactive slider control, which can be used in conjunction 2279 with the interact command. 2280 2281 \code{slider(vmin, vmax=None, step_size=1, default=None, label=None)} 2712 with the :func:`interact` command. 2282 2713 2283 2714 INPUT: 2284 vmin -- object or number2285 vmax -- object or None; if None then vmin must be a list, and the slider2286 then varies over elements of the list.2287 step_size -- integer (default: 1)2288 default -- object or None; default value is ``closest'' in vmin or range2289 to this default.2290 label -- string2291 display_value -- boolean, whether to display the current value to the right2292 of the slider2293 2715 2294 EXAMPLES: 2295 We specify both vmin and vmax. We make the default 3, but 2296 since 3 isn't one of 3/17-th spaced values between 2 and 5, 2297 52/17 is instead chosen as the default (it is closest). 2716 - ``vmin`` - an object 2717 2718 - ``vmax`` - an object (default: None); if None then ``vmin`` 2719 must be a list, and the slider then varies over elements of 2720 the list. 2721 2722 - ``step_size`` - an integer (default: 1) 2723 2724 - ``default`` - an object (default: None); default value is 2725 "closest" in ``vmin`` or range to this default. 2726 2727 - ``label`` - a string 2728 2729 - ``display_value`` - a bool, whether to display the current 2730 value to the right of the slider 2731 2732 EXAMPLES:: 2733 2734 We specify both ``vmin`` and ``vmax``. We make the default 2735 `3`, but since `3` isn't one of `3/17`-th spaced values 2736 between `2` and `5`, `52/17` is instead chosen as the 2737 default (it is closest):: 2738 2298 2739 sage: slider(2, 5, 3/17, 3, 'alpha') 2299 2740 Slider: alpha [2--|52/17|---5] 2300 2741 2301 Here we give a list: 2742 Here we give a list:: 2743 2302 2744 sage: slider([1..10], None, None, 3, 'alpha') 2303 2745 Slider: alpha [1--|3|---10] 2304 2746 2305 The elements of the list can be anything: 2747 The elements of the list can be anything:: 2748 2306 2749 sage: slider([1, 'x', 'abc', 2/3], None, None, 'x', 'alpha') 2307 2750 Slider: alpha [1--|x|---2/3] 2308 2751 """ … … 2329 2772 """ 2330 2773 Return string representation of this slider. 2331 2774 2332 EXAMPLES: 2775 OUTPUT: 2776 2777 - a string 2778 2779 EXAMPLES:: 2780 2333 2781 sage: slider(2, 5, 1/5, 3, 'alpha').__repr__() 2334 2782 'Slider: alpha [2--|3|---5]' 2335 2783 """ … … 2343 2791 Return default index into the list of values. 2344 2792 2345 2793 OUTPUT: 2346 int2347 2794 2348 EXAMPLES: 2795 - an integer 2796 2797 EXAMPLES:: 2798 2349 2799 sage: slider(2, 5, 1/2, 3, 'alpha').default_index() 2350 2800 2 2351 2801 """ … … 2353 2803 2354 2804 def render(self, var): 2355 2805 """ 2356 Render the interactcontrol for the given function and2806 Render the :func:`interact` control for the given function and 2357 2807 variable. 2358 2808 2359 2809 INPUT: 2360 var -- string; variable name2361 2810 2362 EXAMPLES: 2811 - ``var`` - a string; variable name 2812 2813 OUTPUT: 2814 2815 - a :class:`Slider` instance 2816 2817 EXAMPLES:: 2818 2363 2819 sage: S = slider(0, 10, 1, default=3, label='theta'); S 2364 2820 Slider: theta [0--|3|---10] 2365 2821 sage: S.render('x') … … 2375 2831 def __init__(self, vmin, vmax=None, step_size=None, default=None, label=None, display_value=True): 2376 2832 r""" 2377 2833 An interactive range slider control, which can be used in conjunction 2378 with the interactcommand.2834 with the :func:`interact` command. 2379 2835 2380 \code{range_slider(vmin, vmax=None, step_size=1, default=None, label=None)}2381 2382 2836 INPUT: 2383 vmin -- object or number2384 vmax -- object or None; if None then vmin must be a list, and the slider2385 then varies over elements of the list.2386 step_size -- integer (default: 1)2387 default -- (object, object) or None; default range is ``closest'' in vmin or range2388 to this default.2389 label -- string2390 display_value -- boolean, whether to display the current value below2391 the slider2392 2837 2393 EXAMPLES: 2394 We specify both vmin and vmax. We make the default (3,4) but 2395 since neither is one of 3/17-th spaced values between 2 and 5, 2396 the closest values: 52/17 and 67/17, are instead chosen as the 2397 default. 2838 - ``vmin`` - an object 2839 2840 - ``vmax`` - object or None; if None then ``vmin`` must be a 2841 list, and the slider then varies over elements of the list. 2842 2843 - ``step_size`` - integer (default: 1) 2844 2845 - ``default`` - a 2-tuple of objects (default: None); default 2846 range is "closest" in ``vmin`` or range to this default. 2847 2848 - ``label`` - a string 2849 2850 - ``display_value`` - a bool, whether to display the current 2851 value below the slider 2852 2853 EXAMPLES:: 2854 2855 We specify both ``vmin`` and ``vmax``. We make the default 2856 `(3,4)` but since neither is one of `3/17`-th spaced 2857 values between `2` and `5`, the closest values: `52/17` 2858 and `67/17`, are instead chosen as the default:: 2859 2398 2860 sage: range_slider(2, 5, 3/17, (3,4), 'alpha') 2399 2861 Range Slider: alpha [2--|52/17==67/17|---5] 2400 2862 2401 Here we give a list: 2863 Here we give a list:: 2864 2402 2865 sage: range_slider([1..10], None, None, (3,7), 'alpha') 2403 2866 Range Slider: alpha [1--|3==7|---10] 2404 2867 """ … … 2430 2893 """ 2431 2894 Return string representation of this slider. 2432 2895 2433 EXAMPLES: 2896 OUTPUT: 2897 2898 - a string 2899 2900 EXAMPLES:: 2901 2434 2902 sage: range_slider(2, 5, 1/5, (3,4), 'alpha').__repr__() 2435 2903 'Range Slider: alpha [2--|3==4|---5]' 2436 2904 """ … … 2443 2911 Return default index into the list of values. 2444 2912 2445 2913 OUTPUT: 2446 (int, int)2447 2914 2448 EXAMPLES: 2915 - an integer 2-tuple 2916 2917 EXAMPLES:: 2918 2449 2919 sage: range_slider(2, 5, 1/2, (3,4), 'alpha').default_index() 2450 2920 (2, 4) 2451 2921 """ … … 2453 2923 2454 2924 def render(self, var): 2455 2925 """ 2456 Render the interactcontrol for the given function and2926 Render the :func:`interact` control for the given function and 2457 2927 variable. 2458 2928 2459 2929 INPUT: 2460 var -- string; variable name2461 2930 2462 EXAMPLES: 2931 - ``var`` - string; variable name 2932 2933 OUTPUT: 2934 2935 - a :class:`RangeSlider` instance 2936 2937 EXAMPLES:: 2938 2463 2939 sage: S = range_slider(0, 10, 1, default=(3,7), label='theta'); S 2464 2940 Range Slider: theta [0--|3==7|---10] 2465 2941 sage: S.render('x') … … 2477 2953 r""" 2478 2954 A drop down menu or a button bar that when pressed sets a 2479 2955 variable to a given value. Use this in conjunction with the 2480 interact command. 2481 2482 \code{selector(values, label=None, nrows=None, ncols=None, buttons=False)} 2956 :func:`interact` command. 2483 2957 2484 2958 We use the same command to create either a drop down menu or 2485 2959 selector bar of buttons, since conceptually the two controls 2486 do exactly the same thing - -they only look different. If2487 either nrows or ncols is given, then you get a buttons instead2488 of a drop down menu.2960 do exactly the same thing - they only look different. If 2961 either ``nrows`` or ``ncols`` is given, then you get a buttons 2962 instead of a drop down menu. 2489 2963 2490 2964 INPUT: 2491 values -- [val0, val1, val2, ...] or2492 [(val0, lbl0), (val1,lbl1), ...] where all labels must be2493 given or given as None.2494 label -- (default: None); if given, this label is placed to2495 the left of the entire button group2496 default -- object (default: 0) default value in values list2497 nrows -- (default: None); if given determines the number2498 of rows of buttons; if given buttons option below is set to True2499 ncols -- (default: None); if given determines the number2500 of columns of buttons; if given buttons option below is set to True2501 width -- (default: None); if given, all buttons are the same2502 width, equal to this in html ex units's.2503 buttons -- (default: False); if True, use buttons2504 2965 2505 EXAMPLES: 2966 - ``values`` - [val0, val1, val2, ...] or [(val0, lbl0), 2967 (val1,lbl1), ...] where all labels must be given or given as 2968 None. 2969 2970 - ``label`` - a string (default: None); if given, this label 2971 is placed to the left of the entire button group 2972 2973 - ``default`` - an object (default: 0); default value in values 2974 list 2975 2976 - ``nrows`` - an integer (default: None); if given determines 2977 the number of rows of buttons; if given buttons option below 2978 is set to True 2979 2980 - ``ncols`` - an integer (default: None); if given determines 2981 the number of columns of buttons; if given buttons option 2982 below is set to True 2983 2984 - ``width`` - an integer (default: None); if given, all 2985 buttons are the same width, equal to this in HTML ex 2986 units's. 2987 2988 - ``buttons`` - a bool (default: False); if True, use buttons 2989 2990 EXAMPLES:: 2991 2506 2992 sage: selector([1..5]) 2507 2993 Drop down menu with 5 options 2508 2994 sage: selector([1,2,7], default=2) … … 2516 3002 sage: selector([1,2,7], buttons=True) 2517 3003 Button bar with 3 buttons 2518 3004 2519 We create an interactive that involves computing charpolys of matrices over various rings: 3005 We create an :func:`interact` that involves computing charpolys of 3006 matrices over various rings:: 3007 2520 3008 sage: @interact 2521 3009 ... def _(R=selector([ZZ,QQ,GF(17),RDF,RR]), n=(1..10)): 2522 3010 ... M = random_matrix(R, n) … … 2526 3014 ... print f 2527 3015 <html>... 2528 3016 2529 Here we create a drop-down 3017 Here we create a drop-down:: 3018 2530 3019 sage: @interact 2531 3020 ... def _(a=selector([(2,'second'), (3,'third')])): 2532 3021 ... print a … … 2553 3042 """ 2554 3043 Return print representation of this button. 2555 3044 2556 EXAMPLES: 3045 OUTPUT: 3046 3047 - a string 3048 3049 EXAMPLES:: 3050 2557 3051 sage: selector([1,2,7], default=2).__repr__() 2558 3052 'Drop down menu with 3 options' 2559 3053 """ … … 2568 3062 selector can take on. 2569 3063 2570 3064 OUTPUT: 2571 list2572 3065 2573 EXAMPLES: 3066 - a list 3067 3068 EXAMPLES:: 3069 2574 3070 sage: selector([1..5]).values() 2575 3071 [1, 2, 3, 4, 5] 2576 3072 sage: selector([(5,'fifth'), (8,'eight')]).values() … … 2583 3079 Return the default choice for this control. 2584 3080 2585 3081 OUTPUT: 2586 int -- an integer, with 0 corresponding to the first choice.2587 3082 2588 EXAMPLES: 3083 - an integer, with 0 corresponding to the first choice. 3084 3085 EXAMPLES:: 3086 2589 3087 sage: selector([1,2,7], default=2).default() 2590 3088 1 2591 3089 """ … … 2593 3091 2594 3092 def render(self, var): 2595 3093 r""" 2596 Return rendering of this button as a Button instance to be2597 used for an interact canvas.3094 Return rendering of this button as a :class:`Selector` 3095 instance to be used for an :func:`interact` canvas. 2598 3096 2599 3097 INPUT: 2600 var -- a string (variable; one of the variable names input to f) 3098 3099 - ``var`` - a string (variable; one of the variable names 3100 input to ``f``) 2601 3101 2602 3102 OUTPUT: 2603 Button -- a Button instance2604 3103 2605 EXAMPLES: 3104 - a :class:`Selector` instance 3105 3106 EXAMPLES:: 3107 2606 3108 sage: selector([1..5]).render('alpha') 2607 3109 Selector with 5 options for variable 'alpha' 2608 3110 """ … … 2614 3116 class text_control(control): 2615 3117 def __init__(self, value=''): 2616 3118 """ 2617 Text that can be inserted among other interactcontrols.3119 Text that can be inserted among other :func:`interact` controls. 2618 3120 2619 3121 INPUT: 2620 value -- HTML for the control2621 3122 2622 EXAMPLES: 3123 - ``value`` - HTML for the control 3124 3125 EXAMPLES:: 3126 2623 3127 sage: text_control('something') 2624 3128 Text field: something 2625 3129 """ … … 2630 3134 """ 2631 3135 Return print representation of this control. 2632 3136 2633 EXAMPLES: 3137 OUTPUT: 3138 3139 - a string 3140 3141 EXAMPLES:: 3142 2634 3143 sage: text_control('something') 2635 3144 Text field: something 2636 3145 """ … … 2641 3150 Return rendering of the text field 2642 3151 2643 3152 INPUT: 2644 var -- a string (variable; one of the variable names input to f) 3153 3154 - ``var`` - a string (variable; one of the variable names 3155 input to ``f``) 2645 3156 2646 3157 OUTPUT: 2647 TextControl -- a TextControl instance 3158 3159 - a :class:`TextControl` instance 2648 3160 """ 2649 3161 return TextControl(var, self.__default) 2650 3162 … … 2655 3167 value of the variable. 2656 3168 2657 3169 INPUT: 2658 default -- the default value for v given by the function; see 2659 the documentation to interact? for details. 3170 3171 - ``default`` - the default value for ``v`` given by the function; 3172 see the documentation to :func:`interact` for details. 2660 3173 2661 3174 OUTPUT: 2662 a interact control2663 3175 2664 EXAMPLES: 3176 - an :func:`interact` control 3177 3178 EXAMPLES:: 3179 2665 3180 sage: sage.server.notebook.interact.automatic_control('') 2666 3181 Interact input box labeled None with default value '' 2667 3182 sage: sage.server.notebook.interact.automatic_control(15) … … 2737 3252 Given an iterator v, return first n elements it produces as a list. 2738 3253 2739 3254 INPUT: 2740 v -- an iterator 2741 n -- an integer 3255 3256 - ``v`` - an iterator 3257 3258 - ``n`` - an integer 2742 3259 2743 3260 OUTPUT: 2744 list2745 3261 2746 EXAMPLES: 3262 - a list 3263 3264 EXAMPLES:: 3265 2747 3266 sage: sage.server.notebook.interact.list_of_first_n(Primes(), 10) 2748 3267 [2, 3, 5, 7, 11, 13, 17, 19, 23, 29] 2749 3268 sage: sage.server.notebook.interact.list_of_first_n((1..5), 10) … … 2764 3283 2765 3284 2766 3285 def update(cell_id, var, adapt, value, globs): 2767 """3286 r""" 2768 3287 Called when updating the positions of an interactive control. 2769 3288 Note that this just causes the values of the variables to be 2770 3289 updated; it does not reevaluate the function with the new values. 2771 3290 2772 3291 INPUT: 2773 cell_id -- the id of a interact cell 2774 var -- a variable associated to that cell 2775 adapt -- the number of the adapt function 2776 value -- new value of the control 2777 globs -- global variables. 3292 3293 - ``cell_id`` - an integer; the id of an :func:`interact` cell 3294 3295 - ``var`` - an object; a variable associated to that cell 3296 3297 - ``adapt`` - in integer; the number of the adapt function 3298 3299 - ``value`` - an object; new value of the control 3300 3301 - ``globs`` - global variables. 2778 3302 2779 3303 EXAMPLES: 3304 2780 3305 The following outputs __SAGE_INTERACT_RESTART__ to indicate that 2781 not all the state of the interrupt canvas has been setup yet (this 2782 setup happens when javascript calls certain functions). 3306 not all the state of the :func:`interact` canvas has been set up yet 3307 (this setup happens when JavaScript calls certain functions):: 3308 2783 3309 sage: sage.server.notebook.interact.update(0, 'a', 0, '5', globals()) 2784 3310 __SAGE_INTERACT_RESTART__ 2785 3311 """ … … 2795 3321 2796 3322 def recompute(cell_id): 2797 3323 """ 2798 Evaluates the interactfunction associated to the cell2799 cell_id. This typically gets called after a call to2800 sage.server.notebook.interact.update.3324 Evaluates the :func:`interact` function associated to the cell 3325 ``cell_id``. This typically gets called after a call to 3326 :func:`update`. 2801 3327 3328 INPUT: 3329 3330 - ``cell_id`` - an integer 3331 2802 3332 EXAMPLES: 3333 2803 3334 The following outputs __SAGE_INTERACT_RESTART__ to indicate that 2804 not all the state of the interrupt canvas has been setup yet (this 2805 setup happens when javascript calls certain functions). 3335 not all the state of the :func:`interact` canvas has been set up yet 3336 (this setup happens when JavaScript calls certain functions):: 3337 2806 3338 sage: sage.server.notebook.interact.recompute(10) 2807 3339 __SAGE_INTERACT_RESTART__ 2808 3340 -
sage/server/notebook/js.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/js.py
a b 1 1 r"""nodoctest 2 Java script (AJAX) Component of \sage Notebook2 JavaScript (AJAX) Components of the Notebook 3 3 4 4 AUTHORS: 5 5 -
sage/server/notebook/notebook.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/notebook.py
a b 182 182 Create the default users for a notebook. 183 183 184 184 INPUT: 185 186 185 187 186 - ``passwd`` - a string 188 187 189 190 188 EXAMPLES:: 191 189 192 190 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 213 211 214 212 def user_exists(self, username): 215 213 """ 216 Return whether or not a user exists given a username.214 Return whether a user with the given ``username`` exists. 217 215 216 INPUT: 217 218 - ``username`` - a string 219 220 OUTPUT: 221 222 - a bool 223 218 224 EXAMPLES:: 219 225 220 226 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 233 239 234 240 def users(self): 235 241 """ 236 Return dictionary of users in a notebook.242 Return a dictionary of users in a notebook. 237 243 244 OUTPUT: 245 246 - a string:User instance dictionary 247 238 248 EXAMPLES:: 239 249 240 250 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 251 261 252 262 def user(self, username): 253 263 """ 254 Return an instance of the User class given the usernameof a user264 Return an instance of the User class given the ``username`` of a user 255 265 in a notebook. 256 266 267 INPUT: 268 269 - ``username`` - a string 270 271 OUTPUT: 272 273 - an instance of User 274 257 275 EXAMPLES:: 258 276 259 277 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 284 302 285 303 def create_user_with_same_password(self, user, other_user): 286 304 r""" 305 Change the password of ``user`` to that of ``other_user``. 306 287 307 INPUT: 288 308 289 290 309 - ``user`` - a string 291 310 292 311 - ``other_user`` - a string 293 312 294 295 OUTPUT: Changes password of ``user`` to that of296 ``other_user``.297 298 313 EXAMPLES:: 299 314 300 315 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 315 330 316 331 def user_is_admin(self, user): 317 332 """ 333 Return true if ``user`` is an admin. 334 335 INPUT: 336 337 - ``user`` - an instance of User 338 339 OUTPUT: 340 341 - a bool 342 318 343 EXAMPLES:: 319 344 320 345 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 321 sage: nb.add_user('Administrator', 'password', ", 'admin', True)322 sage: nb.add_user('RegularUser', 'password', ", 'user', True)346 sage: nb.add_user('Administrator', 'password', '', 'admin', True) 347 sage: nb.add_user('RegularUser', 'password', '', 'user', True) 323 348 sage: nb.user_is_admin('Administrator') 324 349 True 325 350 sage: nb.user_is_admin('RegularUser') … … 329 354 330 355 def user_is_guest(self, username): 331 356 """ 357 Return true if ``username`` is a guest. 358 359 INPUT: 360 361 - ``username`` - a string 362 363 OUTPUT: 364 365 - a bool 366 332 367 EXAMPLES:: 333 368 334 369 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 346 381 347 382 def user_list(self): 348 383 """ 349 Return list of user objects.384 Return a list of user objects. 350 385 386 OUTPUT: 387 388 - a list of User instances 389 351 390 EXAMPLES:: 352 391 353 392 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 360 399 361 400 def usernames(self): 362 401 """ 363 Return list of usernames.402 Return a list of usernames. 364 403 404 OUTPUT: 405 406 - a list of strings 407 365 408 EXAMPLES:: 366 409 367 410 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 375 418 376 419 def valid_login_names(self): 377 420 """ 378 Return list of users that can be signedin.421 Return a list of users that can log in. 379 422 423 OUTPUT: 424 425 - a list of strings 426 380 427 EXAMPLES:: 381 428 382 429 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 384 431 Creating default users. 385 432 sage: nb.valid_login_names() 386 433 ['admin'] 387 sage: nb.add_user('Mark', 'password', ", force=True)388 sage: nb.add_user('Sarah', 'password', ", force=True)389 sage: nb.add_user('David', 'password', ", force=True)434 sage: nb.add_user('Mark', 'password', '', force=True) 435 sage: nb.add_user('Sarah', 'password', '', force=True) 436 sage: nb.add_user('David', 'password', '', force=True) 390 437 sage: sorted(nb.valid_login_names()) 391 438 ['David', 'Mark', 'Sarah', 'admin'] 392 439 """ 393 440 return [x for x in self.usernames() if not x in ['guest', '_sage_', 'pub']] 394 441 395 442 def default_user(self): 396 """ 397 Return a default login name that the user will see when confronted 398 with the Sage notebook login page. 443 r""" 444 Return a default login name that the user will see when 445 confronted with the Sage notebook login page. Currently, this 446 returns 'admin' if that is the *only* user. Otherwise it 447 returns an empty string (''). 399 448 400 OUTPUT: string 401 402 Currently this returns 'admin' if that is the *only* user. 403 Otherwise it returns the string ". 449 OUTPUT: 450 451 - a string - the default username. 404 452 405 453 EXAMPLES:: 406 454 … … 409 457 Creating default users. 410 458 sage: nb.default_user() 411 459 'admin' 412 sage: nb.add_user('AnotherUser', 'password', ", force=True)460 sage: nb.add_user('AnotherUser', 'password', '', force=True) 413 461 sage: nb.default_user() 414 462 '' 415 463 """ … … 420 468 421 469 def set_accounts(self, value): 422 470 r""" 423 Changes ``__accounts`` to ``value``471 Set the attribute ``__accounts`` to ``value``. 424 472 473 INPUT: 474 475 - ``value`` - a bool 476 425 477 EXAMPLES:: 426 478 427 479 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 438 490 439 491 def get_accounts(self): 440 492 r""" 441 Return ``__accounts`` 493 Return ``__accounts``. 442 494 495 OUTPUT: 496 497 - a bool 498 443 499 EXAMPLES:: 444 500 445 501 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 457 513 458 514 def add_user(self, username, password, email, account_type="user", force=False): 459 515 """ 516 Add a user with the given credentials. 517 460 518 INPUT: 461 462 519 463 520 - ``username`` - the username 464 521 465 522 - ``password`` - the password 466 523 467 524 - ``email`` - the email address 468 525 469 - ``account_type`` - one of 'user', 'admin', or 470 'guest' 526 - ``account_type`` - one of 'user', 'admin', or 'guest' 471 527 472 - ``force`` - bool528 - ``force`` - a bool (default: False) 473 529 474 475 If the method get_accounts return False then user can only be 476 added if force=True 477 530 If the method :meth:`get_accounts` returns False then user can 531 only be added if ``force`` is True. 532 478 533 EXAMPLES:: 479 534 480 535 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 481 sage: nb.add_user('Mark', 'password', ", force=True)536 sage: nb.add_user('Mark', 'password', '', force=True) 482 537 sage: nb.user('Mark') 483 538 Mark 484 539 sage: nb.add_user('Sarah', 'password', ") … … 500 555 501 556 def change_password(self, username, password): 502 557 """ 558 Change a user's password. 559 503 560 INPUT: 504 561 562 - ``username`` - a string, the username 505 563 506 - ``username`` - the username 507 508 - ``password`` - the password to change the user's 509 password to 510 564 - ``password`` - a string, the user's new password 511 565 512 566 EXAMPLES:: 513 567 514 568 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 515 sage: nb.add_user('Mark', 'password', ", force=True)569 sage: nb.add_user('Mark', 'password', '', force=True) 516 570 sage: nb.user('Mark').password() 517 571 'aajfMKNH1hTm2' 518 572 sage: nb.change_password('Mark', 'different_password') … … 523 577 524 578 def del_user(self, username): 525 579 """ 526 Delete s the given user580 Delete the given user. 527 581 582 INPUT: 583 584 - ``username`` - a string 585 528 586 EXAMPLES:: 529 587 530 588 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 531 sage: nb.add_user('Mark', 'password', ", force=True)589 sage: nb.add_user('Mark', 'password', '', force=True) 532 590 sage: nb.user('Mark') 533 591 Mark 534 592 sage: nb.del_user('Mark') … … 542 600 543 601 def passwords(self): 544 602 """ 545 Return theusername:password dictionary.603 Return a username:password dictionary. 546 604 605 OUTPUT: 606 607 - a string:string dictionary 608 547 609 EXAMPLES:: 548 610 549 611 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 550 612 sage: nb.create_default_users('password') 551 613 Creating default users. 552 sage: nb.add_user('Mark', 'password', ", force=True)614 sage: nb.add_user('Mark', 'password', '', force=True) 553 615 sage: list(sorted(nb.passwords().iteritems())) 554 616 [('Mark', 'aajfMKNH1hTm2'), ('_sage_', 'aaQSqAReePlq6'), ('admin', 'aajfMKNH1hTm2'), ('guest', 'aaQSqAReePlq6'), ('pub', 'aaQSqAReePlq6')] 555 617 """ … … 557 619 558 620 def user_conf(self, username): 559 621 """ 560 Return a user's configuration .622 Return a user's configuration object. 561 623 624 OUTPUT: 625 626 - an instance of Configuration. 627 562 628 EXAMPLES:: 563 629 564 630 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 581 647 ########################################################## 582 648 def _initialize_worksheet(self, src, W): 583 649 r""" 584 ``src`` and ``W`` are worksheets and 585 ``W`` is brand new. 650 Initialize a new worksheet from a source worksheet. 651 652 INPUT: 653 654 - ``src`` - a Worksheet instance; the source 655 656 - ``W`` - a new Worksheet instance; the target 586 657 """ 587 658 # Copy over images and other files 588 659 data = src.data_directory() … … 595 666 596 667 def publish_worksheet(self, worksheet, username): 597 668 r""" 598 Publish the given worksheet. 669 Publish a user's worksheet. This creates a new worksheet in 670 the 'pub' directory with the same contents as ``worksheet``. 599 671 600 This creates a new worksheet in the ``pub`` directory 601 with the same contents as ``worksheet``. 602 672 INPUT: 673 674 - ``worksheet`` - an instance of Worksheet 675 676 - ``username`` - a string 677 678 OUTPUT: 679 680 - a new or existing published instance of Worksheet 681 603 682 EXAMPLES:: 604 683 605 684 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 606 sage: nb.add_user('Mark','password', ",force=True)685 sage: nb.add_user('Mark','password','',force=True) 607 686 sage: W = nb.new_worksheet_with_title_from_text('First steps', owner='Mark') 608 687 sage: nb.worksheet_names() 609 688 ['Mark/0'] … … 691 770 def delete_worksheet(self, filename): 692 771 """ 693 772 Delete the given worksheet and remove its name from the worksheet 694 list. 773 list. Raise a KeyError, if it is missing. 774 775 INPUT: 776 777 - ``filename`` - a string 695 778 """ 696 779 if not (filename in self.__worksheets.keys()): 697 780 print self.__worksheets.keys() … … 715 798 716 799 INPUT: 717 800 718 719 801 - ``username`` - a string 720 802 721 722 803 This empties the trash for the given user and cleans up all files 723 804 associated with the worksheets that are in the trash. 724 805 … … 745 826 """ 746 827 Return a list of all the names of worksheets in this notebook. 747 828 748 OUTPUT: list of strings. 829 OUTPUT: 830 831 - a list of strings. 749 832 750 833 EXAMPLES: We make a new notebook with two users and two worksheets, 751 834 then list their names:: … … 764 847 765 848 def migrate_old(self): 766 849 """ 767 Migrate all old worksheets, i.e., ones with no owner, to 768 ``/pub``. 850 Migrate all old worksheets, i.e., those with no owner, to 851 ``/pub``. Currently, this always raises a 852 NotImplementedError. 769 853 """ 770 854 raise NotImplementedError 771 855 for w in self.__worksheets.itervalues(): … … 927 1011 ########################################################## 928 1012 def export_worksheet(self, worksheet_filename, output_filename, verbose=True): 929 1013 """ 930 Export a worksheet with given directory filenmae to 931 output_filename. 1014 Export a worksheet, creating a sws file on the file system. 932 1015 933 1016 INPUT: 934 1017 1018 - ``worksheet_filename`` - a string 935 1019 936 - `` worksheet_filename`` -string1020 - ``output_filename`` - a string 937 1021 938 - ``output_filename`` - string 939 940 - ``verbose`` - bool (default: True) if True print 941 some the tar command used to extract the sws file. 942 943 944 OUTPUT: creates a file on the filesystem 1022 - ``verbose`` - a bool (default: True); if True, print the tar 1023 command used to create the sws file. 945 1024 """ 946 1025 W = self.get_worksheet_with_filename(worksheet_filename) 947 1026 W.save() … … 968 1047 969 1048 def import_worksheet(self, filename, owner): 970 1049 r""" 971 Upload the worksheet with name ``filename`` and make it 972 have the given owner. 1050 Import a worksheet with the given ``filename`` and set its 1051 ``owner``. If the file extension is not txt or sws, raise a 1052 ValueError. 973 1053 974 1054 INPUT: 975 1055 976 977 1056 - ``filename`` - a string 978 1057 979 1058 - ``owner`` - a string 980 1059 981 982 1060 OUTPUT: 983 1061 984 985 - ``worksheet`` - a newly created worksheet 986 1062 - ``worksheet`` - a newly created Worksheet instance 987 1063 988 1064 EXAMPLES: We create a notebook and import a plain text worksheet 989 1065 into it. … … 1024 1100 1025 1101 INPUT: 1026 1102 1103 - ``filename`` - a string; a filename that ends in .txt 1027 1104 1028 - `` filename`` - string; a filename that ends in .txt1105 - ``owner`` - a string; the imported worksheet's owner 1029 1106 1030 - ``owner`` - string; who will own this worksheet when 1031 imported 1032 1033 1034 OUTPUT: a new worksheet 1107 OUTPUT: 1108 1109 - a new instance of Worksheet 1035 1110 1036 1111 EXAMPLES: We write a plain text worksheet to a file and import it 1037 1112 using this function. … … 1055 1130 def _import_worksheet_sws(self, filename, owner, verbose=True): 1056 1131 r""" 1057 1132 Import an sws format worksheet into this notebook as a new 1058 worksheet. 1133 worksheet. If the worksheet cannot be read, raise a 1134 ValueError. 1059 1135 1060 1136 INPUT: 1061 1137 1062 1063 - ``filename`` - string; a filename that ends in .sws; 1138 - ``filename`` - a string; a filename that ends in .sws; 1064 1139 internally it must be a tar'd bz2'd file. 1065 1140 1066 - ``owner`` -string1141 - ``owner`` - a string 1067 1142 1068 - ``verbose`` - bool (default: True) if True print1069 some thetar command used to extract the sws file.1143 - ``verbose`` - a bool (default: True) if True print some the 1144 tar command used to extract the sws file. 1070 1145 1071 1072 OUTPUT: a new worksheet 1146 OUTPUT: 1147 1148 - a new Worksheet instance 1073 1149 1074 1150 EXAMPLES: We create a notebook, then make a worksheet from a plain 1075 1151 text file first. … … 1096 1172 sage: nb._import_worksheet_sws('tmp.sws', 'admin', verbose=False) 1097 1173 [Cell 0; in=2+3, out=] 1098 1174 1099 Ye p, it's there now (as admin/2)::1175 Yes, it's there now (as admin/2):: 1100 1176 1101 1177 sage: nb.worksheet_names() 1102 1178 ['admin/0', 'admin/2'] … … 1167 1243 1168 1244 def plain_text_worksheet_html(self, filename, prompts=True): 1169 1245 """ 1170 Outputs html containing the plain text version of a worksheet1246 Return HTML containing the plain text version of a worksheet. 1171 1247 1172 1248 INPUT: 1173 - ``filename`` - filename of a worksheet 1174 - ``prompts`` - boolean 1249 1250 - ``filename`` - a string; filename of a worksheet 1251 1252 - ``prompts`` - a bool (default: True); whether to format the 1253 text for inclusion in docstrings 1175 1254 1176 1255 OUTPUT: 1177 - A string containing the html for the plain text version 1256 1257 - a string - the worksheet's HTML representation 1178 1258 """ 1179 1259 worksheet = self.get_worksheet_with_filename(filename) 1180 1260 text = escape(worksheet.plain_text(prompts = prompts)) … … 1193 1273 1194 1274 def DIR(self): 1195 1275 """ 1196 Return the absolute path to the directory that contains the Sage 1197 Notebook directory. 1276 Return the absolute path to the parent of this Notebook 1277 instance's home directory. 1278 1279 OUTPUT: 1280 1281 - a string 1198 1282 """ 1199 1283 P = os.path.abspath('%s/..'%self.__dir) 1200 1284 if not os.path.exists(P): … … 1309 1393 return s 1310 1394 1311 1395 def worksheet_html(self, filename, do_print=False): 1312 """1313 Return s the HTML for theworksheet.1396 r""" 1397 Return the HTML for a given worksheet. 1314 1398 1315 1399 INPUT: 1316 - ``username`` - a string 1317 - ``worksheet`` - an instance of Worksheet 1400 1401 - ``filename`` - a string; the worksheet's filename 1402 1403 - ``do_print`` - a bool (default: False); whether this is a 1404 printed worksheet 1318 1405 1319 1406 OUTPUT: 1320 - a string containing the HTML 1407 1408 - a string - the worksheet rendered as HTML 1321 1409 1322 1410 EXAMPLES:: 1323 1411 … … 1359 1447 # Revision history for a worksheet 1360 1448 ########################################################## 1361 1449 def html_worksheet_revision_list(self, username, worksheet): 1362 """1363 Return s theHTML for the revision list of a worksheet.1450 r""" 1451 Return HTML for the revision list of a worksheet. 1364 1452 1365 1453 INPUT: 1454 1366 1455 - ``username`` - a string 1456 1367 1457 - ``worksheet`` - an instance of Worksheet 1368 1458 1369 1459 OUTPUT: 1370 - a string containing the HTML 1460 1461 - a string - the HTML for the revision list 1371 1462 1372 1463 EXAMPLES:: 1373 1464 … … 1389 1480 1390 1481 1391 1482 def html_specific_revision(self, username, ws, rev): 1392 """1393 Return s the HTML for a revision of theworksheet.1483 r""" 1484 Return the HTML for a specific revision of a worksheet. 1394 1485 1395 1486 INPUT: 1487 1396 1488 - ``username`` - a string 1489 1397 1490 - ``ws`` - an instance of Worksheet 1491 1398 1492 - ``rev`` - a string containing the key of the revision 1399 1493 1400 1494 OUTPUT: 1401 - a string containing the HTML 1495 1496 - a string - the revision rendered as HTML 1402 1497 """ 1403 1498 t = time.time() - float(rev[:-4]) 1404 1499 time_ago = worksheet.convert_seconds_to_meaningful_time_span(t) … … 1434 1529 1435 1530 1436 1531 def html_share(self, worksheet, username): 1437 """1438 Return s the HTML for the sharepage of a worksheet.1532 r""" 1533 Return the HTML for the "share" page of a worksheet. 1439 1534 1440 1535 INPUT: 1536 1441 1537 - ``username`` - a string 1538 1442 1539 - ``worksheet`` - an instance of Worksheet 1443 1540 1444 1541 OUTPUT: 1445 - a string containing the HTML 1542 1543 - string - the share page's HTML representation 1446 1544 1447 1545 EXAMPLES:: 1448 1546 … … 1466 1564 1467 1565 1468 1566 def html_download_or_delete_datafile(self, ws, username, filename): 1469 """1470 Return sthe HTML for the download or delete datafile page.1567 r""" 1568 Return the HTML for the download or delete datafile page. 1471 1569 1472 1570 INPUT: 1571 1473 1572 - ``username`` - a string 1573 1474 1574 - ``ws`` - an instance of Worksheet 1475 - ``filename`` - the name of the file 1575 1576 - ``filename`` - a string; the name of the file 1476 1577 1477 1578 OUTPUT: 1478 - a string containing the HTML 1579 1580 - a string - the page rendered as HTML 1479 1581 1480 1582 EXAMPLES:: 1481 1583 … … 1554 1656 1555 1657 def get_worksheet_with_filename(self, filename): 1556 1658 """ 1557 Get the worksheet with given filename. If there is no such1558 worksheet, raise a ``KeyError``.1659 Get the worksheet with the given filename. If there is no 1660 such worksheet, raise a ``KeyError``. 1559 1661 1560 INPUT: string OUTPUT: a worksheet or KeyError 1662 INPUT: 1663 1664 - ``filename`` - a string 1665 1666 OUTPUT: 1667 1668 - a Worksheet instance 1561 1669 """ 1562 1670 if self.__worksheets.has_key(filename): 1563 1671 return self.__worksheets[filename] … … 1613 1721 # HTML -- generate most html related to the whole notebook page 1614 1722 ########################################################### 1615 1723 def html_debug_window(self): 1616 """1617 Return s the HTML for the debug window1724 r""" 1725 Return the HTML for the debug window. 1618 1726 1619 1727 OUTPUT: 1620 - the HTML for the debug window 1728 1729 - a string - the debug window rendered as HTML 1621 1730 1622 1731 EXAMPLES:: 1623 1732 1624 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1625 sage: print(nb.html_debug_window()) 1626 <div class='debug_window'> 1627 <div class='debug_output'><pre id='debug_output'></pre></div> 1628 <textarea rows=5 id='debug_input' class='debug_input' 1629 onKeyPress='return debug_keypress(event);' 1630 onFocus='debug_focus();' onBlur='debug_blur();'></textarea> 1631 </div> 1733 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) 1734 sage: nb.html_debug_window() 1735 "\n<div class='debug_window'>...</div>" 1632 1736 """ 1633 1737 return template("notebook/debug_window.html") 1634 1738 1635 1739 1636 1740 def html_plain_text_window(self, worksheet, username): 1637 """1638 Return s a window that displays a plain text version of the1639 worksheet1640 1741 r""" 1742 Return HTML for the window that displays a plain text version 1743 of the worksheet. 1744 1641 1745 INPUT: 1642 - ``worksheet`` - a worksheet 1643 - ``username`` - name of the user 1746 1747 - ``worksheet`` - a Worksheet instance 1748 1749 - ``username`` - a string 1644 1750 1645 1751 OUTPUT: 1646 - a window that displays a plain text version of the 1647 worksheet1648 1752 1753 - a string - the plain text window rendered as HTML 1754 1649 1755 EXAMPLES:: 1650 1756 1651 1757 sage: nb = sage.server.notebook.notebook.Notebook(tmp_dir()) … … 1666 1772 1667 1773 def html_edit_window(self, worksheet, username): 1668 1774 r""" 1669 Return a window for editing ``worksheet``.1775 Return HTML for a window for editing ``worksheet``. 1670 1776 1671 1777 INPUT: 1778 1672 1779 - ``username`` - a string containing the username 1780 1673 1781 - ``worksheet`` - a Worksheet instance 1674 1782 1675 1783 OUTPUT: 1676 - html for a window for editing ``worksheet``. 1784 1785 - a string - the editing window's HTML representation 1677 1786 1678 1787 EXAMPLES:: 1679 1788 … … 1695 1804 sage_jsmath_macros = sage_jsmath_macros) 1696 1805 1697 1806 def html_beforepublish_window(self, worksheet, username): 1698 """1699 Return the html code for a page dedicated to worksheet publishing1700 prior to the publication ofthe given worksheet.1807 r""" 1808 Return HTML for the warning and decision page displayed prior 1809 to publishing the given worksheet. 1701 1810 1702 1811 INPUT: 1703 - ``worksheet`` - instance of Worksheet 1704 - ``username`` - string 1812 1813 - ``worksheet`` - an instance of Worksheet 1814 1815 - ``username`` - a string 1816 1817 OUTPUT: 1818 1819 - a string - the pre-publication page rendered as HTML 1705 1820 1706 1821 EXAMPLES:: 1707 1822 … … 1728 1843 sage_jsmath_macros = sage_jsmath_macros) 1729 1844 1730 1845 def html_afterpublish_window(self, worksheet, username, url, dtime): 1731 """ 1732 Return the html code for a page dedicated to worksheet publishing 1733 after the publication of the given worksheet. 1846 r""" 1847 Return HTML for a given worksheet's post-publication page. 1734 1848 1735 1849 INPUT: 1736 - ``worksheet`` - instance of Worksheet 1737 - ``username`` - string 1738 - ``url`` - a string representing the url of the published worksheet 1739 - ``dtime`` - instance of time.struct_time representing the publishing time 1850 1851 - ``worksheet`` - an instance of Worksheet 1852 1853 - ``username`` - a string 1854 1855 - ``url`` - a string representing the URL of the published 1856 worksheet 1857 1858 - ``dtime`` - an instance of time.struct_time representing the 1859 publishing time 1860 1861 OUTPUT: 1862 1863 - a string - the post-publication page rendered as HTML 1864 1740 1865 """ 1741 1866 from time import strftime 1742 1867 time = strftime("%B %d, %Y %I:%M %p", dtime) … … 1750 1875 sage_jsmath_macros = sage_jsmath_macros) 1751 1876 1752 1877 def html_upload_data_window(self, ws, username): 1753 """1754 Return s the html for the "Upload Data" window1878 r""" 1879 Return HTML for the "Upload Data" window. 1755 1880 1756 1881 INPUT: 1757 - ``worksheet`` - instance of Worksheet 1758 - ``username`` - string 1882 1883 - ``worksheet`` - an instance of Worksheet 1884 1885 - ``username`` - a string 1886 1887 OUTPUT: 1888 1889 - a string - the HTML representation of the data upload window 1759 1890 1760 1891 EXAMPLES:: 1761 1892 … … 1773 1904 1774 1905 1775 1906 def html(self, worksheet_filename=None, username='guest', show_debug=False, admin=False): 1776 """1777 Return s the html for index page of a worksheet.1907 r""" 1908 Return the HTML for a worksheet's index page. 1778 1909 1779 1910 INPUT: 1780 - ``worksheet_filename`` - a string 1781 - ``username`` - a string 1782 - ``show_debug`` - a boolean 1783 - ``admin`` - a boolean 1911 1912 - ``worksheet_filename`` - a string (default: None) 1913 1914 - ``username`` - a string (default: 'guest') 1915 1916 - ``show_debug`` - a bool (default: False) 1917 1918 - ``admin`` - a bool (default: False) 1919 1920 OUTPUT: 1921 1922 - a string - the worksheet rendered as HTML 1784 1923 1785 1924 EXAMPLES:: 1786 1925 … … 1820 1959 1821 1960 1822 1961 def html_worksheet_settings(self, ws, username): 1823 """1824 Return s the html for the setings page of the worksheet.1962 r""" 1963 Return the HTML for a worksheet's settings page. 1825 1964 1826 1965 INPUT: 1827 - ``ws`` - instance of Worksheet 1828 - ``username`` - string 1966 1967 - ``ws`` - an instance of Worksheet 1968 1969 - ``username`` - a string 1970 1971 OUTPUT: 1972 1973 - a string - HTML representation of the settings page 1829 1974 1830 1975 EXAMPLES:: 1831 1976 … … 1856 2001 return s 1857 2002 1858 2003 def html_doc(self, username): 1859 """1860 Return s the html for the documentation pages.2004 r""" 2005 Return the HTML for the a documentation page. 1861 2006 1862 2007 INPUT: 1863 - ``worksheet_filename`` - a string2008 1864 2009 - ``username`` - a string 1865 - ``show_debug`` - a boolean 1866 - ``admin`` - a boolean 2010 2011 OUTPUT: 2012 2013 - a string - the doc page rendered as HTML 1867 2014 1868 2015 EXAMPLES:: 1869 2016 … … 1883 2030 1884 2031 def load_notebook(dir, address=None, port=None, secure=None): 1885 2032 """ 1886 Load the notebook from the given directory, or create one in that1887 directoryif one isn't already there.2033 Load and return a notebook from a given directory. Create a new 2034 one in that directory, if one isn't already there. 1888 2035 1889 2036 INPUT: 1890 2037 1891 1892 2038 - ``dir`` - a string that defines a directory name 1893 2039 1894 - ``address`` - the address that the notebook server 1895 will listen on 2040 - ``address`` - the address the server listens at 1896 2041 1897 2042 - ``port`` - the port the server listens on 1898 2043 1899 - ``secure`` - whether or not the notebook is secure 2044 - ``secure`` - whether the notebook is secure 2045 2046 OUTPUT: 2047 2048 - a Notebook instance 1900 2049 """ 1901 2050 sobj = '%s/nb.sobj'%dir 1902 2051 nb = None … … 1937 2086 1938 2087 def make_path_relative(dir): 1939 2088 r""" 1940 If easy, replace the absolute path ``dir`` by a 1941 relative one. 2089 Replace an absolute path with a relative path, if possible. 2090 Otherwise, return the given path. 2091 2092 INPUT: 2093 2094 - ``dir`` - a string containing, e.g., a directory name 2095 2096 OUTPUT: 2097 2098 - a string 1942 2099 """ 1943 2100 base, file = os.path.split(dir) 1944 2101 if os.path.exists(file): … … 1954 2111 1955 2112 def sort_worksheet_list(v, sort, reverse): 1956 2113 """ 2114 Sort a given list on a given key, in a given order. 2115 1957 2116 INPUT: 1958 2117 2118 - ``sort`` - a string; 'last_edited', 'owner', 'rating', or 'name' 1959 2119 1960 - ``sort`` - 'last_edited', 'owner', 'rating', or1961 'name' 1962 1963 - ``reverse`` - if True, reverse the order of the 1964 sort.2120 - ``reverse`` - a bool; if True, reverse the order of the sort. 2121 2122 OUTPUT: 2123 2124 - the sorted list 1965 2125 """ 1966 2126 f = None 1967 2127 if sort == 'last_edited': -
sage/server/notebook/sage_email.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/sage_email.py
a b 6 6 email server or anything else, since Sage already includes by default 7 7 a sophisticated email server (which is part of Twisted). 8 8 9 EXAMPLES: 9 EXAMPLES:: 10 10 11 sage: email('xxxsageuser@gmail.com', 'The calculation finished!') # not tested 11 12 Child process ... is sending email to xxxsageuser@gmail.com 12 13 … … 32 33 OUTPUT: 33 34 string 34 35 35 EXAMPLES: 36 EXAMPLES:: 37 36 38 sage: sage.server.notebook.sage_email.default_email_address() 37 39 '...@...' 38 40 """ … … 64 66 be a problem, but might be useful for certain 65 67 users. 66 68 67 EXAMPLES: 69 EXAMPLES:: 70 68 71 sage: email('xxxsageuser@gmail.com', 'The calculation finished!') # not tested 69 72 Child process ... is sending email to xxxsageuser@gmail.com 70 73 -
sage/server/notebook/sagetex.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/sagetex.py
a b 8 8 9 9 THIS IS ONLY A PROOF-of-CONCEPT. 10 10 11 EXAMPLES: 11 EXAMPLES:: 12 12 13 sage: sagetex('foo.tex') # not tested 13 14 [pops up web browser with live version of foo.tex.] 14 15 """ -
sage/server/notebook/template.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/template.py
a b 1 1 # -*- coding: utf-8 -*- 2 2 """ 3 HTML templating for the notebook3 HTML Templating for the Notebook 4 4 5 5 AUTHORS: 6 -- Bobby Moretti (2007-07-18): initial version 7 -- Timothy Clemans and Mike Hansen (2008-10-27): major update 6 7 - Bobby Moretti (2007-07-18): initial version 8 9 - Timothy Clemans and Mike Hansen (2008-10-27): major update 8 10 9 11 """ 10 12 ############################################################################# … … 22 24 23 25 def contained_in(container): 24 26 """ 25 Returns a function which takes in an environment, context, and value 26 and returns True if that value is in the container and False 27 otherwise. This is registered and used as a test in the templates. 27 Given a container, returns a function which takes an environment, 28 context, and value and returns True if that value is in the 29 container and False otherwise. This is registered and used as a 30 test in the templates. 28 31 29 EXAMPLES: 32 INPUT:: 33 34 - ``container`` - a container, e.g., a list or dictionary 35 36 EXAMPLES:: 37 30 38 sage: from sage.server.notebook.template import contained_in 31 39 sage: f = contained_in([1,2,3]) 32 40 sage: f(None, None, 2) … … 48 56 49 57 def template(filename, **user_context): 50 58 """ 51 Returns a rendered template as a string. 59 Returns HTML, CSS, etc., for a template file rendered in the given 60 context. 52 61 53 62 INPUT: 54 filename -- the filename of the template relative to55 $SAGE_ROOT/devel/sage/sage/server/notebook/templates56 63 57 EXAMPLES: 64 - ``filename`` - a string; the filename of the template relative 65 to $SAGE_ROOT/devel/sage/sage/server/notebook/templates 66 67 - ``user_context`` - a dictionary; the context in which to evaluate 68 the file's template variables 69 70 OUTPUT: 71 72 - a string - the rendered HTML, CSS, etc. 73 74 EXAMPLES:: 75 58 76 sage: from sage.server.notebook.template import template 59 77 sage: s = template('yes_no.html'); type(s) 60 78 <type 'str'> -
sage/server/notebook/twist.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/twist.py
a b 134 134 Returns an HTMLResponse object whose 'Content-Type' header has been set 135 135 to 'text/html; charset=utf-8 136 136 137 EXAMPLES: 137 EXAMPLES:: 138 138 139 sage: from sage.server.notebook.twist import HTMLResponse 139 140 sage: response = HTMLResponse(stream='<html><head><title>Test</title></head><body>Test</body></html>') 140 141 sage: response.headers -
sage/server/notebook/user.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/user.py
a b 63 63 64 64 def username(self): 65 65 """ 66 EXAMPLES: 66 EXAMPLES:: 67 67 68 sage: from sage.server.notebook.user import User 68 69 sage: User('andrew', 'tEir&tiwk!', 'andrew@matrixstuff.com', 'user').username() 69 70 'andrew' … … 79 80 80 81 def conf(self): 81 82 """ 82 EXAMPLES: 83 EXAMPLES:: 84 83 85 sage: from sage.server.notebook.user import User 84 86 sage: config = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin').conf(); config 85 87 Configuration: {} … … 102 104 103 105 def password(self): 104 106 """ 105 EXAMPLES: 107 EXAMPLES:: 108 106 109 sage: from sage.server.notebook.user import User 107 110 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 108 111 sage: user.password() … … 112 115 113 116 def set_password(self, password): 114 117 """ 115 EXAMPLES: 118 EXAMPLES:: 119 116 120 sage: from sage.server.notebook.user import User 117 121 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 118 122 sage: old = user.password() … … 127 131 128 132 def set_hashed_password(self, password): 129 133 """ 130 EXAMPLES: 134 EXAMPLES:: 135 131 136 sage: from sage.server.notebook.user import User 132 137 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 133 138 sage: user.set_hashed_password('Crrc!') … … 138 143 139 144 def get_email(self): 140 145 """ 141 EXAMPLES: 146 EXAMPLES:: 147 142 148 sage: from sage.server.notebook.user import User 143 149 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 144 150 sage: user.get_email() … … 148 154 149 155 def set_email(self, email): 150 156 """ 151 EXAMPLES: 157 EXAMPLES:: 158 152 159 sage: from sage.server.notebook.user import User 153 160 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 154 161 sage: user.get_email() … … 161 168 162 169 def set_email_confirmation(self, value): 163 170 """ 164 EXAMPLES: 171 EXAMPLES:: 172 165 173 sage: from sage.server.notebook.user import User 166 174 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 167 175 sage: user.is_email_confirmed() … … 178 186 179 187 def is_email_confirmed(self): 180 188 """ 181 EXAMPLES: 189 EXAMPLES:: 190 182 191 sage: from sage.server.notebook.user import User 183 192 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 184 193 sage: user.is_email_confirmed() … … 192 201 193 202 def password_is(self, password): 194 203 """ 195 EXAMPLES: 204 EXAMPLES:: 205 196 206 sage: from sage.server.notebook.user import User 197 207 sage: user = User('bob', 'Aisfa!!', 'bob@sagemath.net', 'admin') 198 208 sage: user.password_is('ecc') … … 206 216 207 217 def account_type(self): 208 218 """ 209 EXAMPLES: 219 EXAMPLES:: 220 210 221 sage: from sage.server.notebook.user import User 211 222 sage: User('A', account_type='admin').account_type() 212 223 'admin' … … 221 232 222 233 def is_admin(self): 223 234 """ 224 EXAMPLES: 235 EXAMPLES:: 236 225 237 sage: from sage.server.notebook.user import User 226 238 sage: User('A', account_type='admin').is_admin() 227 239 True … … 232 244 233 245 def is_guest(self): 234 246 """ 235 EXAMPLES: 247 EXAMPLES:: 248 236 249 sage: from sage.server.notebook.user import User 237 250 sage: User('A', account_type='guest').is_guest() 238 251 True -
sage/server/notebook/worksheet.py
diff -r 832b46058006 -r 6b319da23983 sage/server/notebook/worksheet.py
a b 1236 1236 OUTPUT: 1237 1237 1238 1238 1239 - ``string`` - a string of HTML as a bunch of table1239 - ``string`` -- a string of HTML as a bunch of table 1240 1240 rows. 1241 1241 1242 1242 … … 2097 2097 - ``text`` - a string 2098 2098 2099 2099 - ``ignore_ids`` - bool (default: False); if True 2100 ignore all the id's in the code block.2100 ignore all the id's in the {{{}}} code block. 2101 2101 2102 2102 2103 2103 EXAMPLES: We create a new test notebook and a worksheet. … … 2212 2212 ########################################################## 2213 2213 def html(self, include_title=True, do_print=False, 2214 2214 confirm_before_leave=False, read_only=False): 2215 """ 2216 INPUT: 2215 r""" 2216 INPUT: 2217 2218 2217 2219 - publish - a boolean stating whether the worksheet is published 2220 2218 2221 - do_print - a boolean 2219 2222 2220 2223 OUTPUT: 2221 - returns the html for the worksheet 2224 2225 2226 - string -- the html for the worksheet 2222 2227 2223 2228 EXAMPLES:: 2224 2229 … … 2275 2280 def html_save_discard_buttons(self): 2276 2281 r""" 2277 2282 OUTPUT: 2278 - returns the html for the save, discard, etc. buttons 2283 2284 - string -- the html for the save, discard, etc. buttons 2279 2285 2280 2286 EXAMPLES:: 2281 2287 … … 2289 2295 def html_share_publish_buttons(self, select=None, backwards=False): 2290 2296 r""" 2291 2297 INPUT: 2298 2299 2292 2300 - select - a boolean 2301 2293 2302 - backwards - a boolean 2294 2303 2295 2304 OUTPUT: 2296 - returns the html for the share, publish, etc. buttons 2305 2306 2307 - string -- the html for the share, publish, etc. buttons 2297 2308 2298 2309 EXAMPLES:: 2299 2310 … … 2310 2321 # <option title="Configure this worksheet" value="worksheet_settings();">Worksheet settings</option> 2311 2322 2312 2323 def html_menu(self): 2313 """ 2314 OUTPUT: 2315 - returns the html for the menus of the worksheet 2324 r""" 2325 OUTPUT: 2326 2327 - string -- the html for the menus of the worksheet 2316 2328 2317 2329 EXAMPLES:: 2318 2330 … … 2330 2342 doc_worksheet = self.is_doc_worksheet()) 2331 2343 2332 2344 def html_worksheet_body(self, do_print, publish=False): 2333 """ 2334 INPUT: 2345 r""" 2346 INPUT: 2347 2348 2335 2349 - publish - a boolean stating whether the worksheet is published 2350 2336 2351 - do_print - a boolean 2337 2352 2338 2353 OUTPUT: 2339 - returns the html for the File menu of the worksheet 2354 2355 2356 - string -- the html for the File menu of the worksheet 2340 2357 2341 2358 EXAMPLES:: 2342 2359 … … 4020 4037 def format_completions_as_html(cell_id, completions): 4021 4038 """ 4022 4039 INPUT: 4040 4041 4023 4042 - cell_id - id for the cell of the completions 4043 4024 4044 - completions - list of completions in row-major order 4025 4045 4026 4046 OUTPUT: 4027 - html for the completions formatted in rows and columns 4047 4048 4049 - string -- html for the completions formatted in rows and columns 4028 4050 """ 4029 4051 if len(completions) == 0: 4030 4052 return '' -
sage/server/simple/twist.py
diff -r 832b46058006 -r 6b319da23983 sage/server/simple/twist.py
a b 1 1 r""" 2 Simple Sage API2 Simple Sage Server API 3 3 4 4 This module provides a very simple API for interacting with a Sage session 5 5 over HTTP. It runs as part of the notebook server. -
sage/server/support.py
diff -r 832b46058006 -r 6b319da23983 sage/server/support.py
a b 1 1 """ 2 Support for the Notebook (introspection and setup)2 Support for Notebook Introspection and Setup 3 3 4 4 AUTHORS: 5 5 6 6 - William Stein (much of this code is from IPython). 7 8 - Nick Alexander 7 9 """ 8 10 9 11 import inspect … … 70 72 ###################################################################### 71 73 def help(obj): 72 74 """ 73 Display help on s. 75 Display HTML help for ``obj``, a Python object, module, etc. This 76 help is often more extensive than that given by 'obj?'. This 77 function does not return a value --- it prints HTML as a side 78 effect. 74 79 75 80 .. note:: 76 81 … … 79 84 80 85 INPUT: 81 86 82 83 - ``s`` - Python object, module, etc. 84 85 86 OUTPUT: prints out help about s; it's often more more extensive 87 than foo? 87 - ``obj`` - a Python object, module, etc. 88 88 89 89 TESTS:: 90 90 … … 122 122 123 123 def completions(s, globs, format=False, width=90, system="None"): 124 124 """ 125 Return a list of completions in the context of globs. 125 Return a list of completions in the given context. 126 127 INPUT: 128 129 - ``globs`` - a string:object dictionary; context in which to 130 search for completions, e.g., :func:`globals()` 131 132 - ``format`` - a bool (default: False); whether to tabulate the 133 list 134 135 - ``width`` - an int; character width of the table 136 137 - ``system`` - a string (default: 'None'); system prefix for the 138 completions 126 139 """ 127 140 if system not in ['sage', 'python']: 128 141 prepend = system + '.' … … 176 189 177 190 def docstring(obj_name, globs, system='sage'): 178 191 r""" 179 Format ``obj_name``'s docstring for printing inSage192 Format an object's docstring to process and display in the Sage 180 193 notebook. 181 194 195 INPUT: 196 197 - ``obj_name`` - a string; a name of an object 198 199 - ``globs`` - a string:object dictionary; a context in which to 200 evaluate ``obj_name`` 201 202 - ``system`` - a string (default: 'sage'); the system to which to 203 confine the search 204 205 OUTPUT: 206 207 - a string containing the object's file, type, definition, and 208 docstring or a message stating the object is not defined 209 182 210 AUTHORS: 183 211 184 212 - William Stein: partly taken from IPython for use in Sage … … 215 243 216 244 def source_code(s, globs, system='sage'): 217 245 r""" 218 Format obj's source code for printing in Sage notebook. 246 Format an object's source code to process and display in the the 247 Sage notebook. 219 248 249 INPUT: 250 251 - ``s`` - a string; a name of an object 252 253 - ``globs`` - a string:object dictionary; a context in which to 254 evaluate ``s`` 255 256 - ``system`` - a string (default: 'sage'); the system to which to 257 confine the search 258 259 OUTPUT: 260 261 - a string containing the object's file, starting line number, and 262 source code 263 220 264 AUTHORS: 221 265 222 266 - William Stein: partly taken from IPython for use in Sage … … 340 384 341 385 def syseval(system, cmd, dir=None): 342 386 """ 387 Evaluate an input with a "system" object that can evaluate inputs 388 (e.g., python, gap). 389 343 390 INPUT: 344 system -- an object with an eval method that takes as input 345 a cmd (a string), and two dictionaries: 346 sage_globals and locals. 347 dir -- an optional directory to change to before 348 calling system.eval. 391 392 - ``system`` - an object with an eval method that takes an input 393 394 - ``cmd`` - a string input 395 396 - ``sage_globals`` - a string:object dictionary 397 398 - dir - a string (default: None); an optional directory to change 399 to before calling :func:`system.eval` 349 400 350 401 OUTPUT: 351 The output of system.eval is returned. 402 403 - :func:`system.eval`'s output 352 404 353 EXAMPLES: 405 EXAMPLES:: 406 354 407 sage: from sage.misc.python import python 355 408 sage: sage.server.support.syseval(python, '2+4/3') 356 409 3 … … 379 432 def cython_import(filename, verbose=False, compile_message=False, 380 433 use_cache=False, create_local_c_file=True): 381 434 """ 435 Compile a file containing Cython code, then import and return the 436 module. Raises an ``ImportError`` if anything goes wrong. 437 382 438 INPUT: 383 439 384 385 - ``filename`` - name of a file that contains cython 386 code 387 440 - ``filename`` - a string; name of a file that contains Cython 441 code 388 442 389 443 OUTPUT: 390 444 391 392 - ``module`` - the module that contains the compiled 393 cython code. 394 395 396 Raises an ``ImportError`` exception if anything goes 397 wrong. 445 - the module that contains the compiled Cython code. 398 446 """ 399 447 name, build_dir = sage.misc.cython.cython(filename, verbose=verbose, 400 448 compile_message=compile_message, … … 407 455 def cython_import_all(filename, globals, verbose=False, compile_message=False, 408 456 use_cache=False, create_local_c_file=True): 409 457 """ 458 Imports all non-private (i.e., not beginning with an underscore) 459 attributes of the specified Cython module into the given context. 460 This is similar to:: 461 462 from module import * 463 464 Raises an ``ImportError`` exception if anything goes wrong. 465 410 466 INPUT: 411 467 412 413 - ``filename`` - name of a file that contains cython 414 code 415 416 417 OUTPUT: changes globals using the attributes of the Cython module 418 that do not begin with an underscore. 419 420 Raises an ``ImportError`` exception if anything goes 421 wrong. 468 - ``filename`` - a string; name of a file that contains Cython 469 code 422 470 """ 423 471 m = cython_import(filename, verbose=verbose, compile_message=compile_message, 424 472 use_cache=use_cache,