Ticket #13715: trac_13715-review-ts.patch

File trac_13715-review-ts.patch, 11.2 KB (added by tscrim, 6 years ago)
  • sage/misc/session.pyx

    # HG changeset patch
    # User Travis Scrimshaw <tscrim@ucdavis.edu>
    # 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 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()
    verify that it is listed as a newly defi 
    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()
    Next we reset the session, verify this,  
    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']
    Indeed $w$ is now defined again.:: 
    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
    state_at_init = None 
    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:
    8384   
    84         - ``state`` -- a dictionary or None; if None the locals() of the caller is used.
     85    - ``state`` -- a dictionary or ``None``; if ``None`` the :func:`locals()`
     86      of the caller is used.
    8587
    8688    EXAMPLES::
    8789   
    def init(state=None): 
    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    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::
    9597   
    9698        sage: sage.misc.session.init()
    9799        sage: show_identifiers()
    def init(state=None): 
    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)::
    124129   
    def _is_new_var(x, v, hidden): 
    132137        sage: sage.misc.session._is_new_var('factor', factor, True)
    133138        True
    134139
    135     We define a new variable 'blue', and test::
     140    We define a new variable ``'blue'``, and test::
    136141   
    137142        sage: blue = 10
    138143        sage: sage.misc.session._is_new_var('blue', blue, True)
    def show_identifiers(hidden=False): 
    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::
    173179   
    174180        sage: reset()
    def show_identifiers(hidden=False): 
    176182        []
    177183
    178184    We then define two variables, one which overwrites the default factor
    179     function; both are shown by \code{show_identifiers()}::
     185    function; both are shown by :func:`show_identifiers()`::
    180186   
    181187        sage: a = 10
    182188        sage: factor = 20
    def show_identifiers(hidden=False): 
    184190        ['a', 'factor']
    185191
    186192    To get the actual value of a variable from the list, use the
    187     \code{globals()} function.::
     193    :func:`globals()` function.::
    188194   
    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.::
     200    allows one to list those as well::
    195201   
    196202        sage: _hello = 10
    197203        sage: show_identifiers()
    def save_session(name='sage_session', ve 
    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 ``verbose=True``.
    223227
    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.
     228        2. In the Sage notebook the session is saved both to the current
     229           working cell and to the ``DATA`` directory.
     230
     231        3. One can still make sessions that can't be reloaded.  E.g., define
     232           a class with::
     233
     234               class Foo: pass
     235
     236           and make an instance with::
     237
     238               f = Foo()
     239
     240           Then :func:`save_session` followed by ``quit`` and
     241           :func:`load_session` fails.   I doubt there is any good way to deal
     242           with this.  Fortunately, one can simply re-evaluate the code to
     243           define ``Foo``, and suddenly :func:`load_session` works fine.
    233244   
    234245    INPUT:
    235246       
    236         - ``name`` -- string (default: 'sage_session') name of sobj to save
    237           the session to.
     247    - ``name`` -- string (default: 'sage_session') name of ``sobj`` to save
     248      the session to.
    238249
    239         - ``verbose`` -- bool (default: False) if True, print info about
    240           why certain variables can't be saved.
     250    - ``verbose`` -- bool (default: ``False``) if ``True``, print info about
     251      why certain variables can't be saved.
    241252
    242253    OUTPUT:
    243254   
    244         - creates a file
     255    Creates a file and returns silently
    245256
    246257    EXAMPLES:
     258
    247259    For testing, we use a temporary file, that will be removed as soon
    248260    as Sage is left. Of course, for permanently saving your session,
    249     you should choose a permanent file.::
     261    you should choose a permanent file.
     262
     263    ::
    250264   
    251265        sage: a = 5
    252266        sage: tmp_f = tmp_filename()
    def save_session(name='sage_session', ve 
    256270        sage: print a
    257271        5
    258272
    259     We illustrate what happens when one of the variables is a function.::
     273    We illustrate what happens when one of the variables is a function::
     274
    260275        sage: f = lambda x : x^2
    261276        sage: save_session(tmp_f)
    262277        sage: save_session(tmp_f, verbose=True)
    def save_session(name='sage_session', ve 
    264279        Not saving f: f is a function, method, class or type
    265280        ...
    266281
    267     Something similar happens for cython-defined functions.::
     282    Something similar happens for cython-defined functions::
    268283   
    269284        sage: g = cython_lambda('double x', 'x*x + 1.5')
    270285        sage: save_session('tmp_f', verbose=True)
    def load_session(name='sage_session', ve 
    313328    don't necessarily loose all your current work when you use this
    314329    command.
    315330
    316     NOTES: In the Sage notebook the session name is searched for both
    317     in the current working cell and the DATA directory.
     331    .. NOTE::
     332
     333        In the Sage notebook the session name is searched for both
     334        in the current working cell and the ``DATA`` directory.
    318335
    319336    EXAMPLES::
    320337   
    def load_session(name='sage_session', ve 
    323340
    324341    For testing, we use a temporary file, that will be removed as soon
    325342    as Sage is left. Of course, for permanently saving your session,
    326     you should choose a permanent file.::
     343    you should choose a permanent file.
     344
     345    ::
    327346   
    328347        sage: tmp_f = tmp_filename()
    329348        sage: save_session(tmp_f)
    def load_session(name='sage_session', ve 
    332351        sage: print a
    333352        5
    334353
    335     Note that f does not come back, since it is a function, hence couldn't be saved::
     354    Note that ``f`` does not come back, since it is a function, hence
     355    couldn't be saved::
    336356   
    337357        sage: print f
    338358        Traceback (most recent call last):
    def attach(*files): 
    363383    and ``.sage`` files, or ``attach('file1', 'file2')`` - filenames as
    364384    strings, given as arguments to :func:`attach`.
    365385
    366     :meth:`~sage.misc.preparser.load` is the same as :func:`attach`, but doesn't
    367     automatically reload a file when it changes.
     386    :meth:`~sage.misc.preparser.load` is the same as :func:`attach`, but
     387    doesn't automatically reload a file when it changes.
    368388
    369     .. note::
     389    .. NOTE::
    370390
    371391       In addition to ``attach('foo.sage')``, from the sage prompt
    372392       you can also just type ``attach "foo.sage"``.  However this
    def attach(*files): 
    397417    You attach a file, e.g., ``foo.sage`` or ``foo.py`` or
    398418    ``foo.pyx``, to a running Sage session by typing::
    399419
    400         sage: attach foo.sage   # or foo.py   or foo.pyx or even a URL to such a file (not tested)
     420        sage: attach foo.sage   # or foo.py or foo.pyx or even a URL to such a file (not tested)
    401421
    402422    or::
    403423
    def attach(*files): 
    431451    import preparser
    432452    for filename in files:
    433453        preparser.load(filename, globals(), attach=True)
     454