# HG changeset patch
# User Travis Scrimshaw
# 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/sage/misc/session.pyx
+++ b/sage/misc/session.pyx
@@ 1,9 +1,9 @@
"""
+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()
@@ 12,14 +12,15 @@
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()
@@ 34,7 +35,7 @@
[]
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']
@@ 42,11 +43,11 @@
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
"""
@@ 68,7 +69,7 @@
from misc import embedded
from sage.structure.sage_object import load, save
# This modulescope variables is used to save the
+# This modulescope variables is used to save the
# global state of the sage environment at the moment
# before the user starts typing or running code.
@@ 76,23 +77,24 @@
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()
[]
@@ 104,43 +106,46 @@
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('_'):
@@ 161,38 +166,39 @@
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']
@@ 201,7 +207,7 @@
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']
"""
@@ 212,43 +218,52 @@
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 reevaluate 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 reevaluate 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)
@@ 257,17 +272,17 @@
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 cythondefined functions.::

+ Something similar happens for cythondefined 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
@@ 314,18 +329,22 @@
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
@@ 333,15 +352,16 @@
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
@@ 364,10 +384,10 @@
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
@@ 398,7 +418,7 @@
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::