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

File trac_13715-review-ts.2.patch, 12.5 KB (added by ddrake, 6 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 """
     1r"""
    22Loading and saving sessions and listing all variables
    33
    44EXAMPLES:
    55
    6 We reset the current session, then define a rational number $2/3$, and
     6We reset the current session, then define a rational number ``2/3``, and
    77verify that it is listed as a newly defined variable::
    88
    99    sage: reset()
     
    1212    sage: show_identifiers()
    1313    ['w']
    1414
    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!::
     15We 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
     17session permanently, since ``SAGE_TMP`` will be removed when leaving Sage!
     18
     19::
    1920
    2021    sage: save_session(os.path.join(SAGE_TMP, 'session'))
    2122
    22 This saves a dictionary with $w$ as one of the keys::
     23This saves a dictionary with ``w`` as one of the keys::
    2324
    2425    sage: z = load(os.path.join(SAGE_TMP, 'session'))
    2526    sage: z.keys()
     
    3435    []
    3536    sage: load_session(os.path.join(SAGE_TMP, 'session'))
    3637
    37 Indeed $w$ is now defined again.::
     38Indeed ``w`` is now defined again.::
    3839
    3940    sage: show_identifiers()
    4041    ['w']
     
    4243    2/3
    4344
    4445It is not needed to clean up the file created in the above code, since it
    45 resides in the directory SAGE_TMP.
     46resides in the directory ``SAGE_TMP``.
    4647
    4748AUTHOR:
    4849
    49      - William Stein
     50- William Stein
    5051
    5152"""
    5253
     
    6869from misc import embedded
    6970from sage.structure.sage_object import load, save
    7071
    71 # This module-scope variables is used to save the 
     72# This module-scope variables is used to save the
    7273# global state of the sage environment at the moment
    7374# before the user starts typing or running code.
    7475
     
    7677
    7778def init(state=None):
    7879    """
    79     Initialize some dictionaries needed by the show_identifiers, save_session,
    80     and load_session functions.
     80    Initialize some dictionaries needed by the :func:`show_identifiers`,
     81    :func:`save_session`, and :func:`load_session` functions.
    8182
    8283    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.
    8587
    8688    EXAMPLES::
    87    
     89
    8890        sage: reset()
    8991        sage: w = 10
    9092        sage: show_identifiers()
    9193        ['w']
    9294
    93     When we call init() below it reinitializes the internal table, so
    94     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
    9698        sage: sage.misc.session.init()
    9799        sage: show_identifiers()
    98100        []
     
    104106
    105107def _is_new_var(x, v, hidden):
    106108    """
    107     Return whether or not the variable named `x` with value `v` is considered
    108     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.
    109111
    110112    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
    118121    OUTPUT:
    119         bool
    120122
    121     EXAMPLES::
     123    A bool
     124
     125    EXAMPLES:
     126
    122127    We reset the session, then check whether the builtin factor function
    123128    is newly defined (it isn't)::
    124    
     129
    125130        sage: reset()
    126131        sage: sage.misc.session._is_new_var('factor', factor, True)
    127132        False
    128133
    129134    We then redefine factor, and find that it is newly defined::
    130    
     135
    131136        sage: factor = 10
    132137        sage: sage.misc.session._is_new_var('factor', factor, True)
    133138        True
    134139
    135     We define a new variable 'blue', and test::
    136    
     140    We define a new variable ``'blue'``, and test::
     141
    137142        sage: blue = 10
    138143        sage: sage.misc.session._is_new_var('blue', blue, True)
    139144        True
    140145        sage: sage.misc.session._is_new_var('_blue', blue, True)
    141146        True
    142147        sage: sage.misc.session._is_new_var('_blue', blue, False)
    143         False   
     148        False
    144149    """
    145150    # We ignore all _ variable names unless hidden is True
    146151    if not hidden and x.startswith('_'):
     
    161166
    162167    INPUT:
    163168
    164         - `hidden` -- bool (default: False); if True, also return identifiers
    165           that start with an underscore.
    166          
     169    - ``hidden`` -- bool (Default: ``False``); If ``True``, also return
     170      identifiers that start with an underscore.
     171
    167172    OUTPUT:
    168    
    169         - ``list`` -- a list of variable names
     173
     174    A list of variable names
    170175
    171176    EXAMPLES:
     177
    172178    We reset the state of all variables, and see that none are defined::
    173    
     179
    174180        sage: reset()
    175181        sage: show_identifiers()
    176182        []
    177183
    178184    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
    181187        sage: a = 10
    182188        sage: factor = 20
    183189        sage: show_identifiers()
    184190        ['a', 'factor']
    185191
    186192    To get the actual value of a variable from the list, use the
    187     \code{globals()} function.::
    188    
     193    :func:`globals()` function.::
     194
    189195        sage: globals()['factor']
    190196        20
    191197
    192     By default \code{show_identifiers()} only returns variables that
     198    By default :func:`show_identifiers()` only returns variables that
    193199    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
    196202        sage: _hello = 10
    197203        sage: show_identifiers()
    198204        ['a', 'factor']
     
    201207
    202208    Many of the hidden variables are part of the IPython command history, at
    203209    least in command line mode.::
    204    
     210
    205211        sage: show_identifiers(hidden=True)        # random output
    206212        ['__', '_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']
    207213    """
     
    212218    r"""
    213219    Save all variables that can be saved to the given filename.  The
    214220    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`.
    216222
    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::
    220224
    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``.
    223228
    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 re-evaluate 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 re-evaluate the
     244          code to define ``Foo``, and suddenly :func:`load_session`
     245          works fine.
     246
    234247    INPUT:
    235        
    236         - ``name`` -- string (default: 'sage_session') name of sobj to save
    237           the session to.
    238248
    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.
    241254
    242255    OUTPUT:
    243    
    244         - creates a file
     256
     257        - Creates a file and returns silently.
    245258
    246259    EXAMPLES:
    247260
    248     For testing, we use a temporary file, that will be removed as soon
     261    For testing, we use a temporary file that will be removed as soon
    249262    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
    252267        sage: a = 5
    253268        sage: tmp_f = tmp_filename()
    254269        sage: save_session(tmp_f)
     
    257272        sage: print a
    258273        5
    259274
    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::
    261276
    262277        sage: f = lambda x : x^2
    263278        sage: save_session(tmp_f)
    264279        sage: save_session(tmp_f, verbose=True)
    265280        Saving...
    266281        Not saving f: f is a function, method, class or type
    267         ... 
     282        ...
    268283
    269     Something similar happens for cython-defined functions.::
    270    
     284    Something similar happens for cython-defined functions::
     285
    271286        sage: g = cython_lambda('double x', 'x*x + 1.5')
    272287        sage: save_session(tmp_f, verbose=True)
    273288        Not saving g: g is a function, method, class or type
     
    314329    don't necessarily loose all your current work when you use this
    315330    command.
    316331
    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.
    319336
    320337    EXAMPLES::
    321    
     338
    322339        sage: a = 5
    323340        sage: f = lambda x: x^2
    324341
    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
    326343    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
    329348        sage: tmp_f = tmp_filename()
    330349        sage: save_session(tmp_f)
    331350        sage: del a; del f
     
    333352        sage: print a
    334353        5
    335354
    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
    338358        sage: print f
    339359        Traceback (most recent call last):
    340360        ...
    341361        NameError: name 'f' is not defined
    342362    """
    343363    state = caller_locals()
    344    
     364
    345365    if embedded():
    346366        if not os.path.exists(name):
    347367            nm = '../../data/' + name
     
    364384    and ``.sage`` files, or ``attach('file1', 'file2')`` - filenames as
    365385    strings, given as arguments to :func:`attach`.
    366386
    367     :meth:`~sage.misc.preparser.load` is the same as :func:`attach`, but doesn't
    368     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.
    369389
    370     .. note::
     390    .. NOTE::
    371391
    372392       In addition to ``attach('foo.sage')``, from the sage prompt
    373393       you can also just type ``attach "foo.sage"``.  However this
     
    398418    You attach a file, e.g., ``foo.sage`` or ``foo.py`` or
    399419    ``foo.pyx``, to a running Sage session by typing::
    400420
    401         sage: attach foo.sage   # or foo.py   or foo.pyx or even a URL to such a file (not tested)
     421        sage: attach foo.sage   # or foo.py or foo.pyx or even a URL to such a file (not tested)
    402422
    403423    or::
    404424