Ticket #13715: trac13715.patch

File trac13715.patch, 9.2 KB (added by jdemeyer, 7 years ago)
  • doc/en/reference/misc.rst

    # HG changeset patch
    # User Dan Drake <ddrake@member.ams.org>
    # Date 1353617968 28800
    # Node ID 1bfb4e4d03edf62120dd99b2bfd6bde66c0ebeb8
    # Parent  05fb6d50fb47ebbde41519de5ca05a559eb4d90d
    documentation for attach() should mention load_attach_path()
    
    diff --git a/doc/en/reference/misc.rst b/doc/en/reference/misc.rst
    a b  
    5353   sage/misc/sage_unittest
    5454   sage/misc/randstate
    5555   sage/misc/cython
     56   sage/misc/session
     57
  • sage/misc/preparser.py

    diff --git a/sage/misc/preparser.py b/sage/misc/preparser.py
    a b  
    14331433
    14341434def reset_load_attach_path():
    14351435    """
    1436     Resets the current search path for loading and attaching files.
    1437    
     1436    Resets the current search path for :func:`load` and
     1437    :meth:`~sage.misc.session.attach`.
     1438
    14381439    The default path is '.' plus any paths specified in the environment
    14391440    variable `SAGE_LOAD_ATTACH_PATH`.
    1440    
     1441
    14411442    EXAMPLES::
    1442    
     1443
    14431444        sage: load_attach_path()
    14441445        ['.']
    14451446        sage: t_dir = tmp_dir()
     
    14481449        True
    14491450        sage: reset_load_attach_path(); load_attach_path()
    14501451        ['.']
    1451    
     1452
    14521453    At startup, Sage adds colon-separated paths in the environment
    14531454    variable ``SAGE_LOAD_ATTACH_PATH``::
    14541455
     
    15051506    EXAMPLES:
    15061507
    15071508    Note that .py files are *not* preparsed::
    1508    
     1509
    15091510        sage: t=tmp_filename(ext='.py'); open(t,'w').write("print 'hi',2/3; z=-2/9")
    15101511        sage: sage.misc.preparser.load(t,globals())
    15111512        hi 0
     
    15131514        -1
    15141515
    15151516    A .sage file *is* preparsed::
    1516    
     1517
    15171518        sage: t=tmp_filename(ext='.sage'); open(t,'w').write("print 'hi',2/3; s=-2/7")
    15181519        sage: sage.misc.preparser.load(t,globals())
    15191520        hi 2/3
     
    15211522        -2/7
    15221523
    15231524    Cython files are *not* preparsed::
    1524    
     1525
    15251526        sage: t=tmp_filename(ext='.pyx'); open(t,'w').write("print 'hi',2/3; z=-2/9")
    15261527        sage: z=0; sage.misc.preparser.load(t,globals())
    15271528        hi 0
     
    15481549        sage: sage.misc.preparser.load('http://wstein.org/loadtest.py', globals())  # optional - internet
    15491550        hi from the net
    15501551
    1551     We can load files using secure http (https):: 
     1552    We can load files using secure http (https)::
    15521553
    1553         sage: sage.misc.preparser.load('https://github.com/jasongrout/minimum_rank/raw/minimum_rank_1_0_0/minrank.py', globals())  # optional - internet 
     1554        sage: sage.misc.preparser.load('https://github.com/jasongrout/minimum_rank/raw/minimum_rank_1_0_0/minrank.py', globals())  # optional - internet
    15541555
    15551556    We attach a file::
    15561557
     
    16521653            # code snippets. Use preparse_file_named to make
    16531654            # the file name appear in the traceback as well.
    16541655            # See Trac 11812.
    1655             from sage.misc.interpreter import preparse_file_named         
     1656            from sage.misc.interpreter import preparse_file_named
    16561657            execfile(preparse_file_named(fpath), globals)
    16571658        else:
    16581659            # Preparse in memory only for speed.
     
    16761677
    16771678def load_attach_mode(load_debug=None, attach_debug=None):
    16781679    """
    1679     Get or modify the current debug mode for loading and attaching
    1680     .sage files.
     1680    Get or modify the current debug mode for the behavior of
     1681    :func:`load` and :meth:`~sage.misc.session.attach` on ``.sage``
     1682    files.
    16811683
    1682     In debug mode, loaded or attached .sage files are preparsed
    1683     through a file to make their tracebacks more informative.
    1684     If not in debug mode, then .sage files are preparsed
    1685     in memory only for performance.
     1684    In debug mode, loaded or attached ``.sage`` files are preparsed
     1685    through a file to make their tracebacks more informative. If not in
     1686    debug mode, then ``.sage`` files are preparsed in memory only for
     1687    performance.
    16861688
    16871689    At startup, debug mode is ``True`` for attaching and ``False``
    16881690    for loading.
    1689    
     1691
    16901692    INPUT:
    16911693
    16921694    - ``load_debug`` - boolean or (the default) ``None``;
     
    17001702
    17011703    - if all input values are ``None``, returns a tuple
    17021704      giving the current modes for loading and attaching.
    1703    
     1705
    17041706    EXAMPLES::
    17051707
    17061708        sage: load_attach_mode()
     
    17251727
    17261728def load_attach_path(path=None, replace=False):
    17271729    """
    1728     Get or modify the current search path for loading and attaching
    1729     files.
     1730    Get or modify the current search path for :func:`load` and
     1731    :meth:`~sage.misc.session.attach`.
    17301732
    17311733    INPUT:
    17321734
     
    17591761        sage: attach('test.py')
    17601762        111
    17611763        sage: attached_files() == [fullpath]
    1762         True       
     1764        True
    17631765        sage: sage.misc.reset.reset_attached(); reset_load_attach_path()
    17641766        sage: load_attach_path() == ['.']
    17651767        True
     
    18701872   
    18711873def attached_files():
    18721874    """
    1873     Returns a list of all files attached to the current session.
     1875    Returns a list of all files attached to the current session with
     1876    :meth:`~sage.misc.session.attach`.
    18741877
    18751878    OUTPUT:
    18761879
     
    18901893
    18911894def detach(filename):
    18921895    """
    1893     Detaches a file, if it was attached with the attach command.
     1896    Detaches a file, if it was attached with
     1897    :meth:`~sage.misc.session.attach`.
    18941898
    18951899    INPUT:
    18961900
  • sage/misc/session.pyx

    diff --git a/sage/misc/session.pyx b/sage/misc/session.pyx
    a b  
    356356    """
    357357    Attach a file or files to a running instance of Sage and also load
    358358    that file.
    359    
     359
     360    USAGE:
     361
     362    ``attach file1 ...`` - space-separated list of ``.py``, ``.pyx``,
     363    and ``.sage`` files, or ``attach('file1', 'file2')`` - filenames as
     364    strings, given as arguments to :func:`attach`.
     365
     366    :meth:`~sage.misc.preparser.load` is the same as :func:`attach`, but doesn't
     367    automatically reload a file when it changes.
     368
    360369    .. note::
    361370
    362371       In addition to ``attach('foo.sage')``, from the sage prompt
    363372       you can also just type ``attach "foo.sage"``.  However this
    364373       second common usage is not part of the Python language.
    365    
    366     ``load`` is the same as attach, but doesn't automatically reload a
    367     file when it changes.
    368    
     374
     375    EFFECT:
     376
     377    Each file is read in and added to an internal list of watched files.
     378    The meaning of reading in a file depends on the file type:
     379
     380    -  ``.py`` files are read in with no preparsing (so, e.g., ``2^3`` is 2
     381       bit-xor 3);
     382
     383    -  ``.sage`` files are preparsed, then the result is read in;
     384
     385    - ``.pyx`` files are *not* preparsed, but rather are compiled to a
     386       module ``m`` and then ``from m import *`` is executed.
     387
     388    The contents of the file are then loaded, which means they are read
     389    into the running Sage session. For example, if ``foo.sage`` contains
     390    ``x=5``, after attaching ``foo.sage`` the variable ``x`` will be set
     391    to 5. Moreover, any time you change ``foo.sage``, before you execute
     392    a command, the attached file will be re-read automatically (with no
     393    intervention on your part).
     394
     395    EXAMPLES:
     396
    369397    You attach a file, e.g., ``foo.sage`` or ``foo.py`` or
    370398    ``foo.pyx``, to a running Sage session by typing::
    371    
     399
    372400        sage: attach foo.sage   # or foo.py   or foo.pyx or even a URL to such a file (not tested)
    373401
    374402    or::
    375    
     403
    376404        sage: attach('foo.sage')  # not tested
    377405
    378406    Here we test attaching multiple files at once::
    379    
     407
    380408        sage: sage.misc.reset.reset_attached()
    381409        sage: t1 = tmp_filename(ext='.py')
    382410        sage: open(t1,'w').write("print 'hello world'")
     
    388416        sage: set(attached_files()) == set([t1,t2])
    389417        True
    390418
    391     The contents of the file are then loaded, which means they are
    392     read into the running Sage session. For example, if ``foo.sage``
    393     contains ``x=5``, after attaching ``foo.sage`` the variable ``x``
    394     will be set to 5. Moreover, any time you change ``foo.sage``,
    395     before you execute a command, the attached file will be re-read
    396     automatically (with no intervention on your part).
    397    
    398     USAGE: ``attach file1 ...`` - space-separated list of .py, .pyx,
    399     and .sage files.
    400    
    401     EFFECT: Each file is read in and added to an internal list of
    402     watched files. The meaning of reading a file in depends on the file
    403     type:
    404    
    405    
    406     -  read in with no preparsing (so, e.g., ``23`` is 2
    407        bit-xor 3),
    408    
    409     -  preparsed then the result is read in
    410    
    411     -  *not* preparsed. Compiled to a module ``m`` then
    412        ``from m import *`` is executed.
    413    
    414    
    415     Type ``attached_files()`` for a list of all currently
    416     attached files.
     419    .. SEEALSO::
    417420
    418     Use ``detach(...)`` to instruct Sage to remove a file from the internal
    419     list watched files.
     421        - :meth:`~sage.misc.preparser.attached_files` returns a list of
     422          all currently attached files.
    420423
    421     .. note::
     424        - :meth:`~sage.misc.preparser.detach` instructs Sage to remove a
     425          file from the internal list of watched files.
    422426
    423         ``attach`` is exactly the same as load, except it keeps track of
    424         the loaded file and automatically reloads it when it changes.
     427        - :meth:`~sage.misc.preparser.load_attach_path` allows you to
     428          get or modify the current search path for loading and attaching
     429          files.
    425430    """
    426431    import preparser
    427432    for filename in files: