# HG changeset patch
# User Travis Scrimshaw
# Date 1359729772 28800
# Node ID 74c57728b420890f6d222faa4bcb72390f5055b6
# Parent 4459b99e1ab35725eb1dbaf268eb11b7b6b08957
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 @@ verify that it is listed as a newly defi
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 @@ Next we reset the session, verify this,
[]
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 @@ Indeed $w$ is now defined again.::
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
"""
@@ 76,12 +77,13 @@ state_at_init = None
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::
@@ 90,8 +92,8 @@ def init(state=None):
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,21 +106,24 @@ def init(state=None):
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)::
@@ 132,7 +137,7 @@ def _is_new_var(x, v, hidden):
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)
@@ 161,14 +166,15 @@ def show_identifiers(hidden=False):
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()
@@ 176,7 +182,7 @@ def show_identifiers(hidden=False):
[]
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
@@ 184,14 +190,14 @@ def show_identifiers(hidden=False):
['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()
@@ 212,41 +218,49 @@ def save_session(name='sage_session', ve
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.
+  ``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.
+  ``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
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()
@@ 256,7 +270,8 @@ def save_session(name='sage_session', ve
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)
@@ 264,7 +279,7 @@ def save_session(name='sage_session', ve
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)
@@ 313,8 +328,10 @@ def load_session(name='sage_session', ve
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::
@@ 323,7 +340,9 @@ def load_session(name='sage_session', ve
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)
@@ 332,7 +351,8 @@ def load_session(name='sage_session', ve
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):
@@ 363,10 +383,10 @@ def attach(*files):
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
@@ 397,7 +417,7 @@ def attach(*files):
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::
@@ 431,3 +451,4 @@ def attach(*files):
import preparser
for filename in files:
preparser.load(filename, globals(), attach=True)
+