Ticket #13715: trac_13715reviewts.2.patch
File trac_13715reviewts.2.patch, 12.5 KB (added by , 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 b 1 """1 r""" 2 2 Loading and saving sessions and listing all variables 3 3 4 4 EXAMPLES: 5 5 6 We reset the current session, then define a rational number $2/3$, and6 We reset the current session, then define a rational number ``2/3``, and 7 7 verify that it is listed as a newly defined variable:: 8 8 9 9 sage: reset() … … 12 12 sage: show_identifiers() 13 13 ['w'] 14 14 15 We next save this session. We are using a file in SAGE_TMP. We do this 16 \emph{for testing} only  please do not do this, when you want to 17 save your session permanently, since SAGE_TMP will be removed when 18 leaving Sage!:: 15 We next save this session. We are using a file in ``SAGE_TMP``. We do this 16 *for testing* only  please do not do this, when you want to save your 17 session permanently, since ``SAGE_TMP`` will be removed when leaving Sage! 18 19 :: 19 20 20 21 sage: save_session(os.path.join(SAGE_TMP, 'session')) 21 22 22 This saves a dictionary with $w$as one of the keys::23 This saves a dictionary with ``w`` as one of the keys:: 23 24 24 25 sage: z = load(os.path.join(SAGE_TMP, 'session')) 25 26 sage: z.keys() … … 34 35 [] 35 36 sage: load_session(os.path.join(SAGE_TMP, 'session')) 36 37 37 Indeed $w$is now defined again.::38 Indeed ``w`` is now defined again.:: 38 39 39 40 sage: show_identifiers() 40 41 ['w'] … … 42 43 2/3 43 44 44 45 It is not needed to clean up the file created in the above code, since it 45 resides in the directory SAGE_TMP.46 resides in the directory ``SAGE_TMP``. 46 47 47 48 AUTHOR: 48 49 49 50  William Stein 50 51 51 52 """ 52 53 … … 68 69 from misc import embedded 69 70 from sage.structure.sage_object import load, save 70 71 71 # This modulescope variables is used to save the 72 # This modulescope variables is used to save the 72 73 # global state of the sage environment at the moment 73 74 # before the user starts typing or running code. 74 75 … … 76 77 77 78 def init(state=None): 78 79 """ 79 Initialize some dictionaries needed by the show_identifiers, save_session,80 and load_sessionfunctions.80 Initialize some dictionaries needed by the :func:`show_identifiers`, 81 :func:`save_session`, and :func:`load_session` functions. 81 82 82 83 INPUT: 83 84  ``state``  a dictionary or None; if None the locals() of the caller is used. 84 85  ``state``  a dictionary or ``None``; if ``None`` the :func:`locals()` 86 of the caller is used. 85 87 86 88 EXAMPLES:: 87 89 88 90 sage: reset() 89 91 sage: w = 10 90 92 sage: show_identifiers() 91 93 ['w'] 92 94 93 When we call init()below it reinitializes the internal table, so94 the ` w` we just defined doesn't count as a new identifier::95 95 When we call :func:`init()` below it reinitializes the internal table, so 96 the ``w`` we just defined doesn't count as a new identifier:: 97 96 98 sage: sage.misc.session.init() 97 99 sage: show_identifiers() 98 100 [] … … 104 106 105 107 def _is_new_var(x, v, hidden): 106 108 """ 107 Return whether or not the variable named ` x` with value `v` is considered108 newly defined in the current session.109 Return whether or not the variable named ``x`` with value ``v`` is 110 considered newly defined in the current session. 109 111 110 112 INPUT: 111 112  `x`  string 113 114  `v`  object 115 116  ``hidden``  bool (if True, always return False on variables that start with _) 117 113 114  ``x``  string 115 116  ``v``  object 117 118  ``hidden``  bool; if ``True``, always return ``False`` on variables 119 that start with ``_``) 120 118 121 OUTPUT: 119 bool120 122 121 EXAMPLES:: 123 A bool 124 125 EXAMPLES: 126 122 127 We reset the session, then check whether the builtin factor function 123 128 is newly defined (it isn't):: 124 129 125 130 sage: reset() 126 131 sage: sage.misc.session._is_new_var('factor', factor, True) 127 132 False 128 133 129 134 We then redefine factor, and find that it is newly defined:: 130 135 131 136 sage: factor = 10 132 137 sage: sage.misc.session._is_new_var('factor', factor, True) 133 138 True 134 139 135 We define a new variable 'blue', and test::136 140 We define a new variable ``'blue'``, and test:: 141 137 142 sage: blue = 10 138 143 sage: sage.misc.session._is_new_var('blue', blue, True) 139 144 True 140 145 sage: sage.misc.session._is_new_var('_blue', blue, True) 141 146 True 142 147 sage: sage.misc.session._is_new_var('_blue', blue, False) 143 False 148 False 144 149 """ 145 150 # We ignore all _ variable names unless hidden is True 146 151 if not hidden and x.startswith('_'): … … 161 166 162 167 INPUT: 163 168 164  `hidden`  bool (default: False); if True, also return identifiers165 166 169  ``hidden``  bool (Default: ``False``); If ``True``, also return 170 identifiers that start with an underscore. 171 167 172 OUTPUT: 168 169  ``list``  alist of variable names173 174 A list of variable names 170 175 171 176 EXAMPLES: 177 172 178 We reset the state of all variables, and see that none are defined:: 173 179 174 180 sage: reset() 175 181 sage: show_identifiers() 176 182 [] 177 183 178 184 We then define two variables, one which overwrites the default factor 179 function; both are shown by \code{show_identifiers()}::180 185 function; both are shown by :func:`show_identifiers()`:: 186 181 187 sage: a = 10 182 188 sage: factor = 20 183 189 sage: show_identifiers() 184 190 ['a', 'factor'] 185 191 186 192 To get the actual value of a variable from the list, use the 187 \code{globals()}function.::188 193 :func:`globals()` function.:: 194 189 195 sage: globals()['factor'] 190 196 20 191 197 192 By default \code{show_identifiers()}only returns variables that198 By default :func:`show_identifiers()` only returns variables that 193 199 don't start with an underscore. There is an option hidden that 194 allows one to list those as well .::195 200 allows one to list those as well:: 201 196 202 sage: _hello = 10 197 203 sage: show_identifiers() 198 204 ['a', 'factor'] … … 201 207 202 208 Many of the hidden variables are part of the IPython command history, at 203 209 least in command line mode.:: 204 210 205 211 sage: show_identifiers(hidden=True) # random output 206 212 ['__', '_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'] 207 213 """ … … 212 218 r""" 213 219 Save all variables that can be saved to the given filename. The 214 220 variables will be saved to a dictionary, which can be loaded using 215 load(name) or load_session.221 ``load(name)`` or :func:`load_session`. 216 222 217 NOTES: 218 1. Function and anything else that can't be pickled is not 219 saved. This failure is silent unless you set \code{verbose=True}. 223 .. NOTE:: 220 224 221 2. In the Sage notebook the session is saved both to the current 222 working cell and to the DATA directory. 225 1. Function and anything else that can't be pickled is not 226 saved. This failure is silent unless you set 227 ``verbose=True``. 223 228 224 3. One can still make sessions that can't be reloaded. E.g., define 225 a class with 226 class Foo: pass 227 and make an instance with 228 f = Foo() 229 Then save_session followed by quit and load_session fails. 230 I doubt there is any good way to deal with this. Fortunately, 231 one can simply reevaluate the code to define Foo, and suddenly 232 load_session works fine. 233 229 2. In the Sage notebook the session is saved both to the current 230 working cell and to the ``DATA`` directory. 231 232 3. One can still make sessions that can't be reloaded. E.g., define 233 a class with:: 234 235 class Foo: pass 236 237 and make an instance with:: 238 239 f = Foo() 240 241 Then :func:`save_session` followed by ``quit`` and 242 :func:`load_session` fails. I doubt there is any good way to 243 deal with this. Fortunately, one can simply reevaluate the 244 code to define ``Foo``, and suddenly :func:`load_session` 245 works fine. 246 234 247 INPUT: 235 236  ``name``  string (default: 'sage_session') name of sobj to save237 the session to.238 248 239  ``verbose``  bool (default: False) if True, print info about 240 why certain variables can't be saved. 249  ``name``  string (default: 'sage_session') name of ``sobj`` 250 to save the session to. 251 252  ``verbose``  bool (default: ``False``) if ``True``, print 253 info about why certain variables can't be saved. 241 254 242 255 OUTPUT: 243 244  creates a file256 257  Creates a file and returns silently. 245 258 246 259 EXAMPLES: 247 260 248 For testing, we use a temporary file ,that will be removed as soon261 For testing, we use a temporary file that will be removed as soon 249 262 as Sage is left. Of course, for permanently saving your session, 250 you should choose a permanent file. :: 251 263 you should choose a permanent file. 264 265 :: 266 252 267 sage: a = 5 253 268 sage: tmp_f = tmp_filename() 254 269 sage: save_session(tmp_f) … … 257 272 sage: print a 258 273 5 259 274 260 We illustrate what happens when one of the variables is a function .::275 We illustrate what happens when one of the variables is a function:: 261 276 262 277 sage: f = lambda x : x^2 263 278 sage: save_session(tmp_f) 264 279 sage: save_session(tmp_f, verbose=True) 265 280 Saving... 266 281 Not saving f: f is a function, method, class or type 267 ... 282 ... 268 283 269 Something similar happens for cythondefined functions .::270 284 Something similar happens for cythondefined functions:: 285 271 286 sage: g = cython_lambda('double x', 'x*x + 1.5') 272 287 sage: save_session(tmp_f, verbose=True) 273 288 Not saving g: g is a function, method, class or type … … 314 329 don't necessarily loose all your current work when you use this 315 330 command. 316 331 317 NOTES: In the Sage notebook the session name is searched for both 318 in the current working cell and the DATA directory. 332 .. NOTE:: 333 334 In the Sage notebook the session name is searched for both 335 in the current working cell and the ``DATA`` directory. 319 336 320 337 EXAMPLES:: 321 338 322 339 sage: a = 5 323 340 sage: f = lambda x: x^2 324 341 325 For testing, we use a temporary file, that will be removed as soon 342 For testing, we use a temporary file, that will be removed as soon 326 343 as Sage is left. Of course, for permanently saving your session, 327 you should choose a permanent file.:: 328 344 you should choose a permanent file. 345 346 :: 347 329 348 sage: tmp_f = tmp_filename() 330 349 sage: save_session(tmp_f) 331 350 sage: del a; del f … … 333 352 sage: print a 334 353 5 335 354 336 Note that f does not come back, since it is a function, hence couldn't be saved:: 337 355 Note that ``f`` does not come back, since it is a function, hence 356 couldn't be saved:: 357 338 358 sage: print f 339 359 Traceback (most recent call last): 340 360 ... 341 361 NameError: name 'f' is not defined 342 362 """ 343 363 state = caller_locals() 344 364 345 365 if embedded(): 346 366 if not os.path.exists(name): 347 367 nm = '../../data/' + name … … 364 384 and ``.sage`` files, or ``attach('file1', 'file2')``  filenames as 365 385 strings, given as arguments to :func:`attach`. 366 386 367 :meth:`~sage.misc.preparser.load` is the same as :func:`attach`, but doesn't368 automatically reload a file when it changes.387 :meth:`~sage.misc.preparser.load` is the same as :func:`attach`, but 388 doesn't automatically reload a file when it changes. 369 389 370 .. note::390 .. NOTE:: 371 391 372 392 In addition to ``attach('foo.sage')``, from the sage prompt 373 393 you can also just type ``attach "foo.sage"``. However this … … 398 418 You attach a file, e.g., ``foo.sage`` or ``foo.py`` or 399 419 ``foo.pyx``, to a running Sage session by typing:: 400 420 401 sage: attach foo.sage # or foo.py 421 sage: attach foo.sage # or foo.py or foo.pyx or even a URL to such a file (not tested) 402 422 403 423 or:: 404 424