# Ticket #13715: trac_13715-review-ts.2.patch

File trac_13715-review-ts.2.patch, 12.5 KB (added by ddrake, 9 years ago)
• ## sage/misc/session.pyx

# HG changeset patch
# User Travis Scrimshaw <tscrim@ucdavis.edu>
# Date 1359729772 28800
# Node ID 32b3a9297b8d743b6da3e4f99a0a00f268cbfa2e
# Parent  32a6cc48adb91adeecb461ec3bc36956cf898c6d
Review patch for #13715 which cleans up the rest of the doc in session.pyx.

diff --git a/sage/misc/session.pyx b/sage/misc/session.pyx
 a """ r""" Loading and saving sessions and listing all variables EXAMPLES: We reset the current session, then define a rational number $2/3$, and We reset the current session, then define a rational number 2/3, and verify that it is listed as a newly defined variable:: sage: reset() sage: show_identifiers() ['w'] We next save this session. We are using a file in SAGE_TMP. We do this \emph{for testing} only --- please do not do this, when you want to save your session permanently, since SAGE_TMP will be removed when leaving Sage!:: We next save this session. We are using a file in SAGE_TMP. We do this *for testing* only --- please do not do this, when you want to save your session permanently, since SAGE_TMP will be removed when leaving Sage! :: sage: save_session(os.path.join(SAGE_TMP, 'session')) This saves a dictionary with $w$ as one of the keys:: This saves a dictionary with w as one of the keys:: sage: z = load(os.path.join(SAGE_TMP, 'session')) sage: z.keys() [] sage: load_session(os.path.join(SAGE_TMP, 'session')) Indeed $w$ is now defined again.:: Indeed w is now defined again.:: sage: show_identifiers() ['w'] 2/3 It is not needed to clean up the file created in the above code, since it resides in the directory SAGE_TMP. resides in the directory SAGE_TMP. AUTHOR: - William Stein - William Stein """ from misc import embedded from sage.structure.sage_object import load, save # This module-scope variables is used to save the # This module-scope variables is used to save the # global state of the sage environment at the moment # before the user starts typing or running code. def init(state=None): """ Initialize some dictionaries needed by the show_identifiers, save_session, and load_session functions. Initialize some dictionaries needed by the :func:show_identifiers, :func:save_session, and :func:load_session functions. INPUT: - state -- a dictionary or None; if None the locals() of the caller is used. - state -- a dictionary or None; if None the :func:locals() of the caller is used. EXAMPLES:: sage: reset() sage: w = 10 sage: show_identifiers() ['w'] When we call init() below it reinitializes the internal table, so the w we just defined doesn't count as a new identifier:: When we call :func:init() below it reinitializes the internal table, so the w we just defined doesn't count as a new identifier:: sage: sage.misc.session.init() sage: show_identifiers() [] def _is_new_var(x, v, hidden): """ Return whether or not the variable named x with value v is considered newly defined in the current session. Return whether or not the variable named x with value v is considered newly defined in the current session. INPUT: - x -- string - v -- object - hidden -- bool (if True, always return False on variables that start with _) - x -- string - v -- object - hidden -- bool; if True, always return False on variables that start with _) OUTPUT: bool EXAMPLES:: A bool EXAMPLES: We reset the session, then check whether the builtin factor function is newly defined (it isn't):: sage: reset() sage: sage.misc.session._is_new_var('factor', factor, True) False We then redefine factor, and find that it is newly defined:: sage: factor = 10 sage: sage.misc.session._is_new_var('factor', factor, True) True We define a new variable 'blue', and test:: We define a new variable 'blue', and test:: sage: blue = 10 sage: sage.misc.session._is_new_var('blue', blue, True) True sage: sage.misc.session._is_new_var('_blue', blue, True) True sage: sage.misc.session._is_new_var('_blue', blue, False) False False """ # We ignore all _ variable names unless hidden is True if not hidden and x.startswith('_'): INPUT: - hidden -- bool (default: False); if True, also return identifiers that start with an underscore. - hidden -- bool (Default: False); If True, also return identifiers that start with an underscore. OUTPUT: - list -- a list of variable names A list of variable names EXAMPLES: We reset the state of all variables, and see that none are defined:: sage: reset() sage: show_identifiers() [] We then define two variables, one which overwrites the default factor function; both are shown by \code{show_identifiers()}:: function; both are shown by :func:show_identifiers():: sage: a = 10 sage: factor = 20 sage: show_identifiers() ['a', 'factor'] To get the actual value of a variable from the list, use the \code{globals()} function.:: :func:globals() function.:: sage: globals()['factor'] 20 By default \code{show_identifiers()} only returns variables that By default :func:show_identifiers() only returns variables that don't start with an underscore.  There is an option hidden that allows one to list those as well.:: allows one to list those as well:: sage: _hello = 10 sage: show_identifiers() ['a', 'factor'] Many of the hidden variables are part of the IPython command history, at least in command line mode.:: sage: show_identifiers(hidden=True)        # random output ['__', '_i', '_6', '_4', '_3', '_1', '_ii', '__doc__', '__builtins__', '___', '_9', '__name__', '_', 'a', '_i12', '_i14', 'factor', '__file__', '_hello', '_i13', '_i11', '_i10', '_i15', '_i5', '_13', '_10', '_iii', '_i9', '_i8', '_i7', '_i6', '_i4', '_i3', '_i2', '_i1', '_init_cmdline', '_14'] """ r""" Save all variables that can be saved to the given filename.  The variables will be saved to a dictionary, which can be loaded using load(name) or load_session. load(name) or :func:load_session. NOTES: 1. Function and anything else that can't be pickled is not saved.  This failure is silent unless you set \code{verbose=True}. .. NOTE:: 2. In the Sage notebook the session is saved both to the current working cell and to the DATA directory. 1. Function and anything else that can't be pickled is not saved. This failure is silent unless you set verbose=True. 3. One can still make sessions that can't be reloaded.  E.g., define a class with class Foo: pass and make an instance with f = Foo() Then save_session followed by quit and load_session fails. I doubt there is any good way to deal with this.  Fortunately, one can simply re-evaluate the code to define Foo, and suddenly load_session works fine. 2. In the Sage notebook the session is saved both to the current working cell and to the DATA directory. 3. One can still make sessions that can't be reloaded.  E.g., define a class with:: class Foo: pass and make an instance with:: f = Foo() Then :func:save_session followed by quit and :func:load_session fails. I doubt there is any good way to deal with this. Fortunately, one can simply re-evaluate the code to define Foo, and suddenly :func:load_session works fine. INPUT: - name -- string (default: 'sage_session') name of sobj to save the session to. - verbose -- bool (default: False) if True, print info about why certain variables can't be saved. - name -- string (default: 'sage_session') name of sobj to save the session to. - verbose -- bool (default: False) if True, print info about why certain variables can't be saved. OUTPUT: - creates a file - Creates a file and returns silently. EXAMPLES: For testing, we use a temporary file, that will be removed as soon For testing, we use a temporary file that will be removed as soon as Sage is left. Of course, for permanently saving your session, you should choose a permanent file. :: you should choose a permanent file. :: sage: a = 5 sage: tmp_f = tmp_filename() sage: save_session(tmp_f) sage: print a 5 We illustrate what happens when one of the variables is a function.:: We illustrate what happens when one of the variables is a function:: sage: f = lambda x : x^2 sage: save_session(tmp_f) sage: save_session(tmp_f, verbose=True) Saving... Not saving f: f is a function, method, class or type ... ... Something similar happens for cython-defined functions.:: Something similar happens for cython-defined functions:: sage: g = cython_lambda('double x', 'x*x + 1.5') sage: save_session(tmp_f, verbose=True) Not saving g: g is a function, method, class or type don't necessarily loose all your current work when you use this command. NOTES: In the Sage notebook the session name is searched for both in the current working cell and the DATA directory. .. NOTE:: In the Sage notebook the session name is searched for both in the current working cell and the DATA directory. EXAMPLES:: sage: a = 5 sage: f = lambda x: x^2 For testing, we use a temporary file, that will be removed as soon For testing, we use a temporary file, that will be removed as soon as Sage is left. Of course, for permanently saving your session, you should choose a permanent file.:: you should choose a permanent file. :: sage: tmp_f = tmp_filename() sage: save_session(tmp_f) sage: del a; del f sage: print a 5 Note that f does not come back, since it is a function, hence couldn't be saved:: Note that f does not come back, since it is a function, hence couldn't be saved:: sage: print f Traceback (most recent call last): ... NameError: name 'f' is not defined """ state = caller_locals() if embedded(): if not os.path.exists(name): nm = '../../data/' + name and .sage files, or attach('file1', 'file2') - filenames as strings, given as arguments to :func:attach. :meth:~sage.misc.preparser.load is the same as :func:attach, but doesn't automatically reload a file when it changes. :meth:~sage.misc.preparser.load is the same as :func:attach, but doesn't automatically reload a file when it changes. .. note:: .. NOTE:: In addition to attach('foo.sage'), from the sage prompt you can also just type attach "foo.sage".  However this You attach a file, e.g., foo.sage or foo.py or foo.pyx, to a running Sage session by typing:: sage: attach foo.sage   # or foo.py   or foo.pyx or even a URL to such a file (not tested) sage: attach foo.sage   # or foo.py or foo.pyx or even a URL to such a file (not tested) or::