passagemath-repl 10.5.1__py3-none-any.whl

sage/repl/attach.py

@@ -0,0 +1,625 @@
+# sage_setup: distribution = sagemath-repl
+r"""
+Keep track of attached files
+
+TESTS::
+
+    sage: attach('http://wstein.org/loadtest.py')
+    Traceback (most recent call last):
+    ...
+    NotImplementedError: you cannot attach a URL
+
+Check that no file clutter is produced::
+
+    sage: dir = tmp_dir()
+    sage: src = os.path.join(dir, 'foobar.sage')
+    sage: with open(src, 'w') as f:
+    ....:     _ = f.write('print("<output from attached file>")\n')
+    sage: attach(src)
+    <output from attached file>
+    sage: os.listdir(dir)
+    ['foobar.sage']
+    sage: detach(src)
+
+In debug mode backtraces contain code snippets. We need to manually
+print the traceback because the python doctest module has special
+support for exceptions and does not match them
+character-by-character::
+
+    sage: import traceback
+    sage: with open(src, 'w') as f:
+    ....:     _ = f.write('# first line\n')
+    ....:     _ = f.write('# second line\n')
+    ....:     _ = f.write('raise ValueError("third")   # this should appear in the source snippet\n')
+    ....:     _ = f.write('# fourth line\n')
+
+    sage: load_attach_mode(attach_debug=False)
+    sage: try:
+    ....:     attach(src)
+    ....: except Exception:
+    ....:     traceback.print_exc(file=sys.stdout)
+    Traceback (most recent call last):
+    ...
+        exec(preparse_file(f.read()) + "\n", globals)
+      File "<string>", line 3, in <module>
+    ValueError: third
+    sage: detach(src)
+
+    sage: load_attach_mode(attach_debug=True)
+    sage: try:
+    ....:     attach(src)
+    ....: except Exception:
+    ....:     traceback.print_exc(file=sys.stdout)
+    Traceback (most recent call last):
+    ...
+        exec(code, globals)
+      File ".../foobar...sage.py", line ..., in <module>
+        raise ValueError("third")   # this should appear in the source snippet...
+    ValueError: third
+    sage: detach(src)
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2013 Volker Braun <vbraun.name@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from IPython.core.getipython import get_ipython
+
+from sage.repl.load import load, load_wrap
+import sage.repl.inputhook
+import sage.env
+
+# The attached files as a dict of {Path object:mtime}
+attached = {}
+
+
+load_debug_mode = False
+attach_debug_mode = True
+
+
+def load_attach_mode(load_debug=None, attach_debug=None):
+    """
+    Get or modify the current debug mode for the behavior of
+    :func:`load` and :func:`attach` on ``.sage`` files.
+
+    In debug mode, loaded or attached ``.sage`` files are preparsed
+    through a file to make their tracebacks more informative. If not
+    in debug mode, then ``.sage`` files are preparsed in memory only
+    for performance.
+
+    At startup, debug mode is ``True`` for attaching and ``False``
+    for loading.
+
+    .. NOTE::
+
+        This function should really be deprecated and code executed
+        from memory should raise proper tracebacks.
+
+    INPUT:
+
+    - ``load_debug`` -- boolean or ``None`` (default); if not
+      ``None``, then set a new value for the debug mode for loading
+      files
+
+    - ``attach_debug`` -- boolean or ``None`` (default); same as
+      ``load_debug``, but for attaching files
+
+    OUTPUT:
+
+    If all input values are ``None``, returns a tuple giving the
+    current modes for loading and attaching.
+
+    EXAMPLES::
+
+        sage: load_attach_mode()
+        (False, True)
+        sage: load_attach_mode(attach_debug=False)
+        sage: load_attach_mode()
+        (False, False)
+        sage: load_attach_mode(load_debug=True)
+        sage: load_attach_mode()
+        (True, False)
+        sage: load_attach_mode(load_debug=False, attach_debug=True)
+    """
+    global load_debug_mode, attach_debug_mode
+    if load_debug is None and attach_debug is None:
+        return (load_debug_mode, attach_debug_mode)
+    if load_debug is not None:
+        load_debug_mode = load_debug
+    if attach_debug is not None:
+        attach_debug_mode = attach_debug
+
+
+search_paths: list[Path] = []
+
+
+def load_attach_path(path=None, replace=False):
+    """
+    Get or modify the current search path for :func:`load` and
+    :func:`attach`.
+
+    INPUT:
+
+    - ``path`` -- string or list of strings (default: ``None``);
+      path(s) to append to or replace the current path
+
+    - ``replace`` -- boolean (default: ``False``); if ``path`` is not
+      ``None``, whether to *replace* the search path instead of
+      *appending* to it
+
+    OUTPUT: none or a *reference* to the current search paths
+
+    EXAMPLES:
+
+    First, we extend the example given in :func:`load`'s docstring::
+
+        sage: sage.repl.attach.reset(); reset_load_attach_path()
+        sage: load_attach_path()
+        [PosixPath('.')]
+        sage: t_dir = tmp_dir()
+        sage: fullpath = os.path.join(t_dir, 'test.py')
+        sage: with open(fullpath, 'w') as f:
+        ....:     _ = f.write("print(37 * 3)")
+
+    We put a new, empty directory on the attach path for testing
+    (otherwise this will load ``test.py`` from the current working
+    directory if that happens to exist)::
+
+        sage: import tempfile
+        sage: with tempfile.TemporaryDirectory() as d:
+        ....:     load_attach_path(d, replace=True)
+        ....:     attach('test.py')
+        Traceback (most recent call last):
+        ...
+        OSError: did not find file 'test.py' to load or attach
+        sage: load_attach_path(t_dir)
+        sage: attach('test.py')
+        111
+        sage: af = attached_files(); len(af)
+        1
+        sage: af == [fullpath]
+        True
+        sage: from pathlib import Path
+        sage: sage.repl.attach.reset(); reset_load_attach_path()
+        sage: load_attach_path() == [Path('.')]
+        True
+        sage: with tempfile.TemporaryDirectory() as d:
+        ....:     load_attach_path(d, replace=True)
+        ....:     load('test.py')
+        Traceback (most recent call last):
+        ...
+        OSError: did not find file 'test.py' to load or attach
+
+    The function returns a reference to the path list::
+
+        sage: reset_load_attach_path(); load_attach_path()
+        [PosixPath('.')]
+        sage: load_attach_path('/path/to/my/sage/scripts'); load_attach_path()
+        [PosixPath('.'), PosixPath('/path/to/my/sage/scripts')]
+        sage: load_attach_path(['good', 'bad', 'ugly'], replace=True)
+        sage: load_attach_path()
+        [PosixPath('good'), PosixPath('bad'), PosixPath('ugly')]
+        sage: p = load_attach_path(); p.pop()
+        PosixPath('ugly')
+        sage: p[0] = 'weird'; load_attach_path()
+        ['weird', PosixPath('bad')]
+        sage: reset_load_attach_path(); load_attach_path()
+        [PosixPath('.')]
+    """
+    global search_paths
+    if path is None:
+        return search_paths
+
+    if not isinstance(path, list):
+        path = [Path(path)]
+    if replace:
+        search_paths = [Path(p) for p in path]
+    else:
+        for p in path:
+            if not p:
+                continue
+            as_path = Path(p)
+            if as_path not in search_paths:
+                search_paths.append(as_path)
+
+
+def reset_load_attach_path():
+    """
+    Reset the current search path for :func:`load` and :func:`attach`.
+
+    The default path is ``'.'`` plus any paths specified in the
+    environment variable ``SAGE_LOAD_ATTACH_PATH``.
+
+    EXAMPLES::
+
+        sage: load_attach_path()
+        [PosixPath('.')]
+        sage: t_dir = tmp_dir()
+        sage: load_attach_path(t_dir)
+        sage: from pathlib import Path
+        sage: Path(t_dir) in load_attach_path()
+        True
+        sage: reset_load_attach_path(); load_attach_path()
+        [PosixPath('.')]
+
+    At startup, Sage adds colon-separated paths in the environment
+    variable ``SAGE_LOAD_ATTACH_PATH``::
+
+        sage: reset_load_attach_path(); load_attach_path()
+        [PosixPath('.')]
+        sage: os.environ['SAGE_LOAD_ATTACH_PATH'] = '/veni/vidi:vici:'
+        sage: from importlib import reload
+        sage: reload(sage.repl.attach)    # Simulate startup
+        <module 'sage.repl.attach' from '...'>
+        sage: load_attach_path()
+        [PosixPath('.'), PosixPath('/veni/vidi'), PosixPath('vici')]
+        sage: del os.environ['SAGE_LOAD_ATTACH_PATH']
+        sage: reload(sage.repl.preparse)    # Simulate startup
+        <module 'sage.repl.preparse' from '...'>
+        sage: reset_load_attach_path(); load_attach_path()
+        [PosixPath('.')]
+    """
+    global search_paths
+    search_paths = [Path()]
+    for path in os.environ.get('SAGE_LOAD_ATTACH_PATH', '').split(':'):
+        load_attach_path(path=path)
+
+
+# Set up the initial search path for loading and attaching files.  A
+# user can modify the path with the function load_attach_path.
+reset_load_attach_path()
+
+
+def attach(*files):
+    """
+    Attach a file or files to a running instance of Sage and also load
+    that file.
+
+    .. NOTE::
+
+        Attaching files uses the Python inputhook, which will conflict
+        with other inputhook users. This generally includes GUI main loop
+        integrations, for example tkinter. So you can only use tkinter or
+        attach, but not both at the same time.
+
+    INPUT:
+
+    - ``files`` -- list of filenames (strings) to attach
+
+    OUTPUT:
+
+    Each file is read in and added to an internal list of watched files.
+    The meaning of reading in a file depends on the file type:
+
+    - ``.py`` files are read in with no preparsing (so, e.g., ``2^3`` is 2
+      bit-xor 3);
+
+    - ``.sage`` files are preparsed, then the result is read in;
+
+    - ``.pyx`` files are *not* preparsed, but rather are compiled to a
+      module ``m`` and then ``from m import *`` is executed.
+
+    The contents of the file are then loaded, which means they are read
+    into the running Sage session. For example, if ``foo.sage`` contains
+    ``x=5``, after attaching ``foo.sage`` the variable ``x`` will be set
+    to 5. Moreover, any time you change ``foo.sage``, before you execute
+    a command, the attached file will be re-read automatically (with no
+    intervention on your part).
+
+    .. SEEALSO::
+
+        :meth:`~sage.repl.load.load` is the same as :func:`attach`, but
+        does not automatically reload a file when it changes.
+
+    EXAMPLES:
+
+    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')  # not tested
+
+    Here we test attaching multiple files at once::
+
+        sage: sage.repl.attach.reset()
+        sage: t1 = tmp_filename(ext='.py')
+        sage: with open(t1,'w') as f: _ = f.write("print('hello world')")
+        sage: t2 = tmp_filename(ext='.py')
+        sage: with open(t2,'w') as f: _ = f.write("print('hi there xxx')")
+        sage: attach(t1, t2)
+        hello world
+        hi there xxx
+        sage: af = attached_files(); len(af)
+        2
+        sage: t1 in af and t2 in af
+        True
+
+    .. SEEALSO::
+
+        - :meth:`attached_files` returns a list of
+          all currently attached files.
+
+        - :meth:`detach` instructs Sage to remove a
+          file from the internal list of watched files.
+
+        - :meth:`load_attach_path` allows you to
+          get or modify the current search path for loading and attaching
+          files.
+    """
+    try:
+        ipy = get_ipython()
+    except NameError:
+        ipy = None
+    global attached
+    for filename in files:
+        if ipy:
+            code = load_wrap(filename, attach=True)
+            ipy.run_cell(code)
+        else:
+            load(filename, globals(), attach=True)
+
+
+def add_attached_file(filename):
+    """
+    Add to the list of attached files.
+
+    This is a callback to be used from
+    :func:`~sage.repl.load.load` after evaluating the attached
+    file the first time.
+
+    INPUT:
+
+    - ``filename`` -- string (the fully qualified file name)
+      or :class:`Path` object
+
+    EXAMPLES::
+
+        sage: import sage.repl.attach as af
+        sage: af.reset()
+        sage: t = tmp_filename(ext='.py')
+        sage: af.add_attached_file(t)
+        sage: af.attached_files()
+        ['/.../tmp_....py']
+        sage: af.detach(t)
+        sage: af.attached_files()
+        []
+    """
+    sage.repl.inputhook.install()
+    fpath = Path(filename).absolute()
+    attached[fpath] = fpath.stat().st_mtime
+
+
+def attached_files() -> list:
+    """
+    Return a list of all files attached to the current session with
+    :meth:`attach`.
+
+    OUTPUT: the filenames in a sorted list of strings
+
+    EXAMPLES::
+
+        sage: sage.repl.attach.reset()
+        sage: t = tmp_filename(ext='.py')
+        sage: with open(t,'w') as f: _ = f.write("print('hello world')")
+        sage: attach(t)
+        hello world
+        sage: af = attached_files(); af
+        ['/....py']
+        sage: af == [t]
+        True
+    """
+    global attached
+    return sorted(str(f) for f in attached)
+
+
+def detach(filename):
+    """
+    Detach a file.
+
+    This is the counterpart to :meth:`attach`.
+
+    INPUT:
+
+    - ``filename`` -- string, a list of strings or a tuple of strings
+      or a :class:`Path`, a list of :class:`Path` or a tuple of :class:`Path`
+
+    EXAMPLES::
+
+        sage: sage.repl.attach.reset()
+        sage: t = tmp_filename(ext='.py')
+        sage: with open(t,'w') as f: _ = f.write("print('hello world')")
+        sage: attach(t)
+        hello world
+        sage: af = attached_files(); len(af)
+        1
+        sage: af == [t]
+        True
+        sage: detach(t)
+        sage: attached_files()
+        []
+
+        sage: sage.repl.attach.reset(); reset_load_attach_path()
+        sage: load_attach_path()
+        [PosixPath('.')]
+        sage: t_dir = tmp_dir()
+        sage: fullpath = os.path.join(t_dir, 'test.py')
+        sage: with open(fullpath, 'w') as f: _ = f.write("print(37 * 3)")
+        sage: load_attach_path(t_dir, replace=True)
+        sage: attach('test.py')
+        111
+        sage: af = attached_files(); len(af)
+        1
+        sage: af == [os.path.normpath(fullpath)]
+        True
+        sage: detach('test.py')
+        sage: attached_files()
+        []
+        sage: attach('test.py')
+        111
+        sage: fullpath = os.path.join(t_dir, 'test2.py')
+        sage: with open(fullpath, 'w') as f: _ = f.write("print(3)")
+        sage: attach('test2.py')
+        3
+        sage: detach(attached_files())
+        sage: attached_files()
+        []
+
+    TESTS::
+
+        sage: detach('/dev/null/foobar.sage')
+        Traceback (most recent call last):
+        ...
+        ValueError: file '/dev/null/foobar.sage' is not attached, see attached_files()
+    """
+    if isinstance(filename, str):
+        filelist = [Path(filename)]
+    else:
+        filelist = [Path(x) for x in filename]
+
+    global attached
+    for filename in filelist:
+        fpath = filename.expanduser()
+        if not fpath.is_absolute():
+            for path in load_attach_path():
+                fpath = path.expanduser() / filename
+                fpath = fpath.absolute()
+                if fpath in attached:
+                    break
+        abs_fpath = fpath.absolute()
+        if fpath in attached:
+            attached.pop(fpath)
+        elif abs_fpath in attached:
+            attached.pop(abs_fpath)
+        else:
+            raise ValueError("file '{0}' is not attached, see attached_files()".format(filename))
+    if not attached:
+        sage.repl.inputhook.uninstall()
+
+
+def reset():
+    """
+    Remove all the attached files from the list of attached files.
+
+    EXAMPLES::
+
+        sage: sage.repl.attach.reset()
+        sage: t = tmp_filename(ext='.py')
+        sage: with open(t,'w') as f: _ = f.write("print('hello world')")
+        sage: attach(t)
+        hello world
+        sage: af = attached_files(); len(af)
+        1
+        sage: af == [t]
+        True
+        sage: sage.repl.attach.reset()
+        sage: attached_files()
+        []
+    """
+    global attached
+    attached = {}
+
+
+def modified_file_iterator():
+    """
+    Iterate over the changed files.
+
+    As a side effect the stored time stamps are updated with the
+    actual time stamps. So if you iterate over the attached files in
+    order to reload them and you hit an error then the subsequent
+    files are not marked as read.
+
+    Files that are in the process of being saved are excluded.
+
+    EXAMPLES::
+
+        sage: sage.repl.attach.reset()
+        sage: t = tmp_filename(ext='.py')
+        sage: attach(t)
+        sage: from sage.repl.attach import modified_file_iterator
+        sage: list(modified_file_iterator())
+        []
+        sage: sleep(1)   # filesystem mtime granularity
+        sage: with open(t, 'w') as f: _ = f.write('1')
+        sage: list(modified_file_iterator())
+        [(PosixPath('/.../tmp_....py'), time.struct_time(...))]
+    """
+    global attached
+    modified = {}
+    for filename in list(attached):
+        old_tm = attached[filename]
+        if not filename.exists():
+            print('### detaching file {0} because it does not exist (deleted?) ###'.format(filename))
+            detach(filename)
+            continue
+        new_tm = filename.stat().st_mtime
+        if new_tm > old_tm:
+            modified[filename] = new_tm
+
+    if not modified:
+        return
+    time.sleep(0.1)  # sleep 100ms to give the editor time to finish saving
+
+    for filename in list(modified):
+        old_tm = modified[filename]
+        new_tm = filename.stat().st_mtime
+        if new_tm == old_tm:
+            # file was modified but did not change in the last 100ms
+            attached[filename] = new_tm
+            yield filename, time.gmtime(new_tm)
+
+
+def reload_attached_files_if_modified():
+    r"""
+    Reload attached files that have been modified.
+
+    This is the internal implementation of the attach mechanism.
+
+    EXAMPLES::
+
+        sage: sage.repl.attach.reset()
+        sage: from sage.repl.interpreter import get_test_shell
+        sage: shell = get_test_shell()
+        sage: tmp = tmp_filename(ext='.py')
+        sage: with open(tmp, 'w') as f: _ = f.write('a = 2\n')
+        sage: shell.run_cell('attach({0})'.format(repr(tmp)))
+        sage: shell.run_cell('a')
+        2
+        sage: sleep(1)   # filesystem mtime granularity
+        sage: with open(tmp, 'w') as f: _ = f.write('a = 3\n')
+
+    Note that the doctests are never really at the command prompt
+    where the automatic reload is triggered. So we have to do it
+    manually::
+
+        sage: shell.run_cell('from sage.repl.attach import reload_attached_files_if_modified')
+        sage: shell.run_cell('reload_attached_files_if_modified()')
+        ### reloading attached file tmp_....py modified at ... ###
+
+        sage: shell.run_cell('a')
+        3
+        sage: shell.run_cell('detach({0})'.format(repr(tmp)))
+        sage: shell.run_cell('attached_files()')
+        []
+        sage: shell.quit()
+    """
+    ip = get_ipython()
+    for filename, mtime in modified_file_iterator():
+        basename = filename.name
+        timestr = time.strftime('%T', mtime)
+        notice = '### reloading attached file {0} modified at {1} ###'.format(basename, timestr)
+        if ip:
+            print(notice)
+            code = load_wrap(filename, attach=True)
+            ip.run_cell(code)
+        else:
+            print(notice)
+            load(filename, globals(), attach=True)