passagemath-objects 10.6.41__cp314-cp314t-macosx_13_0_arm64.whl

sage/misc/sage_ostools.pyx

@@ -0,0 +1,323 @@
+# sage_setup: distribution = sagemath-objects
+"""
+Miscellaneous operating system functions
+"""
+
+IF UNAME_SYSNAME == "Linux" or UNAME_SYSNAME == "Darwin":
+
+    from posix.unistd cimport dup, dup2, close
+
+    from cpython.exc cimport PyErr_SetFromErrno
+
+ELSE:
+
+    def dup(x):
+        return -1
+
+    def dup2(x, y):
+        return -1
+
+    def close():
+        return
+
+    def PyErr_SetFromErrno(x):
+        return
+
+import os
+import contextlib
+
+
+def have_program(program, path=None) -> bool:
+    """
+    Return ``True`` if a ``program`` executable is found in the path
+    given by ``path``.
+
+    INPUT:
+
+    - ``program`` -- string, the name of the program to check
+
+    - ``path`` -- string or ``None``. Paths to search for ``program``,
+      separated by ``os.pathsep``. If ``None``, use the :envvar:`PATH`
+      environment variable.
+
+    OUTPUT: boolean
+
+    EXAMPLES::
+
+        sage: from sage.misc.sage_ostools import have_program
+        sage: have_program('ls')
+        True
+        sage: have_program('there_is_not_a_program_with_this_name')
+        False
+        sage: have_program('sh', '/bin')
+        True
+        sage: have_program('sage', '/there_is_not_a_path_with_this_name')
+        False
+        sage: have_program('there_is_not_a_program_with_this_name', "/bin")
+        False
+    """
+    if path is None:
+        path = os.environ.get('PATH', "")
+    for p in path.split(os.pathsep):
+        try:
+            if os.access(os.path.join(p, program), os.X_OK):
+                return True
+        except OSError:
+            pass
+    return False
+
+
+@contextlib.contextmanager
+def restore_cwd(chdir=None):
+    """
+    Context manager that restores the original working directory upon exiting.
+
+    INPUT:
+
+    - ``chdir`` -- optionally change directories to the given directory
+      upon entering the context manager
+
+    EXAMPLES::
+
+        sage: from sage.misc.sage_ostools import restore_cwd
+        sage: import tempfile
+        sage: orig_cwd = os.getcwd()
+        sage: with tempfile.TemporaryDirectory() as d:
+        ....:     with restore_cwd(d):
+        ....:         print(os.getcwd() == orig_cwd)
+        False
+        sage: os.getcwd() == orig_cwd
+        True
+    """
+    orig_cwd = os.getcwd()
+    if chdir is not None:
+        os.chdir(chdir)
+    try:
+        yield
+    finally:
+        os.chdir(orig_cwd)
+
+
+cdef file_and_fd(x, int* fd):
+    """
+    If ``x`` is a file, return ``x`` and set ``*fd`` to its file
+    descriptor. If ``x`` is an integer, return ``None`` and set
+    ``*fd`` to ``x``. Otherwise, set ``*fd = -1`` and raise a
+    :exc:`TypeError`.
+    """
+    fd[0] = -1
+    try:
+        m = x.fileno
+    except AttributeError:
+        try:
+            fd[0] = x
+        except Exception:  # Some objects raise bizarre exceptions when calling int()
+            raise TypeError(f"{x} must be a Python file or an integer")
+        return None
+    fd[0] = m()
+    return x
+
+
+cdef class redirection:
+    r"""
+    Context to implement redirection of files, analogous to the
+    ``>file`` or ``1>&2`` syntax in POSIX shells.
+
+    Unlike the ``redirect_stdout`` and ``redirect_stderr`` contexts in
+    the Python 3.4 standard library, this acts on the OS level, not on
+    the Python level. This implies that it only works for true files,
+    not duck-type file objects such as ``StringIO``.
+
+    INPUT:
+
+    - ``source`` -- the file to be redirected
+
+    - ``dest`` -- where the source file should be redirected to
+
+    - ``close`` -- boolean (default: ``True``); whether to close the
+      destination file upon exiting the context. This is only supported
+      if ``dest`` is a Python file.
+
+    The ``source`` and ``dest`` arguments can be either Python files
+    or file descriptors.
+
+    EXAMPLES::
+
+        sage: from sage.misc.sage_ostools import redirection
+        sage: fn = tmp_filename()
+
+    ::
+
+        sage: with redirection(sys.stdout, open(fn, 'w')):
+        ....:     print("hello world!")
+        sage: with open(fn) as f:
+        ....:     _ = sys.stdout.write(f.read())
+        hello world!
+
+    We can do the same using a file descriptor as source::
+
+        sage: fd = sys.stdout.fileno()
+        sage: with redirection(fd, open(fn, 'wb')):
+        ....:     _ = os.write(fd, b"hello world!\n")
+        sage: with open(fn) as f:
+        ....:     _ = sys.stdout.write(f.read())
+        hello world!
+
+    The converse also works::
+
+        sage: with open(fn, 'w') as f:
+        ....:     _ = f.write("This goes to the file\n")
+        ....:     with redirection(f, sys.stdout, close=False):
+        ....:         _ = f.write("This goes to stdout\n")
+        ....:     _ = f.write("This goes to the file again\n")
+        This goes to stdout
+        sage: with open(fn) as f:
+        ....:     _ = sys.stdout.write(f.read())
+        This goes to the file
+        This goes to the file again
+
+    The same :class:`redirection` instance can be reused multiple times,
+    provided that ``close=False``::
+
+        sage: f = open(fn, 'w+')
+        sage: r = redirection(sys.stdout, f, close=False)
+        sage: with r:
+        ....:     print("Line 1")
+        sage: with r:
+        ....:     print("Line 2")
+        sage: with f:
+        ....:     _ = f.seek(0)
+        ....:     _ = sys.stdout.write(f.read())
+        Line 1
+        Line 2
+
+    The redirection also works for subprocesses::
+
+        sage: import subprocess
+        sage: with redirection(sys.stdout, open(fn, 'w')):
+        ....:     _ = subprocess.call(["echo", "hello world"])
+        sage: with open(fn) as f:
+        ....:     _ = sys.stdout.write(f.read())
+        hello world
+
+    TESTS::
+
+        sage: import io
+        sage: redirection(sys.stdout, io.StringIO())
+        Traceback (most recent call last):
+        ...
+        io.UnsupportedOperation: fileno
+
+    The redirection is removed and the destination file is closed even
+    in the case of errors::
+
+        sage: f = open(os.devnull, 'w')
+        sage: with redirection(sys.stdout, f):
+        ....:     raise KeyboardInterrupt
+        Traceback (most recent call last):
+        ...
+        KeyboardInterrupt
+        sage: f.closed
+        True
+
+    Reusing a :class:`redirection` instance with ``close=True``::
+
+        sage: f = open(fn, 'w+')
+        sage: r = redirection(sys.stdout, f, close=True)
+        sage: with r:
+        ....:     print("Line 1")
+        sage: with r:
+        ....:     print("Line 2")
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid destination file
+
+    Using ``close=True`` on a non-file::
+
+        sage: redirection(sys.stdout, 0, close=True)
+        Traceback (most recent call last):
+        ...
+        ValueError: close=True requires a Python destination file
+
+    Passing invalid file descriptors::
+
+        sage: with redirection(-123, open(os.devnull, 'w')):
+        ....:     pass
+        Traceback (most recent call last):
+        ...
+        OSError: [Errno 9] Bad file descriptor
+        sage: with redirection(sys.stdout, -123):
+        ....:     pass
+        Traceback (most recent call last):
+        ...
+        OSError: [Errno 9] Bad file descriptor
+
+    Nesting the same :class:`redirection` object is not allowed::
+
+        sage: with redirection(sys.stdout, open(os.devnull, 'w')) as r:
+        ....:     with r:
+        ....:         pass
+        Traceback (most recent call last):
+        ...
+        ValueError: source already redirected
+    """
+    cdef readonly source_file, dest_file
+    cdef readonly int source_fd, dest_fd, dup_source_fd
+    cdef bint close_dest
+
+    def __cinit__(self):
+        self.source_fd = -1
+        self.dest_fd = -1
+        self.dup_source_fd = -1
+
+    def __init__(self, source, dest, close=None):
+        self.source_file = file_and_fd(source, &self.source_fd)
+        self.dest_file = file_and_fd(dest, &self.dest_fd)
+
+        if self.dest_file is None:
+            if close:
+                raise ValueError("close=True requires a Python destination file")
+        elif close is None:
+            close = True
+        self.close_dest = close
+
+    cdef int flush(self) except -1:
+        for f in (self.source_file, self.dest_file):
+            if f is not None:
+                f.flush()
+
+    def __enter__(self):
+        # Basic sanity checks
+        if self.source_fd == -1:
+            raise ValueError("invalid source file")
+        if self.dest_fd == -1:
+            raise ValueError("invalid destination file")
+        if self.dup_source_fd != -1:
+            raise ValueError("source already redirected")
+
+        self.flush()
+
+        dupsrc = dup(self.source_fd)
+        if dupsrc == -1:
+            PyErr_SetFromErrno(OSError)
+        fd = dup2(self.dest_fd, self.source_fd)
+        if fd == -1:
+            try:
+                PyErr_SetFromErrno(OSError)
+            finally:
+                close(dupsrc)
+        self.dup_source_fd = dupsrc
+        return self
+
+    def __exit__(self, *args):
+        try:
+            self.flush()
+        finally:
+            fd = dup2(self.dup_source_fd, self.source_fd)
+            if fd == -1:
+                PyErr_SetFromErrno(OSError)
+            close(self.dup_source_fd)
+            self.dup_source_fd = -1
+            if self.close_dest:
+                self.dest_file.close()
+                self.dest_fd = -1

sage/misc/sage_timeit.py

@@ -0,0 +1,276 @@
+# sage_setup: distribution = sagemath-objects
+"""
+Accurate timing information for Sage commands
+
+This is an implementation of nice timeit functionality, like the
+``%timeit`` magic command in IPython.  To use it, use the ``timeit``
+command. This command then calls :func:`sage_timeit`, which you can
+find below.
+
+EXAMPLES::
+
+    sage: timeit('1+1')    # random output
+    625 loops, best of 3: 314 ns per loop
+
+AUTHOR:
+
+    -- William Stein, based on code by Fernando Perez included in IPython
+"""
+
+import os
+
+
+class SageTimeitResult:
+    r"""
+    Represent the statistics of a timeit() command.
+
+    Prints as a string so that it can be easily returned to a user.
+
+    INPUT:
+
+    - ``stats`` -- tuple of length 5 containing the following information:
+
+        - integer, number of loops
+        - integer, repeat number
+        - Python integer, number of digits to print
+        - number, best timing result
+        - str, time unit
+
+    EXAMPLES::
+
+        sage: from sage.misc.sage_timeit import SageTimeitResult
+        sage: SageTimeitResult( (3, 5, int(8), pi, 'ms') )                              # needs sage.symbolic
+        3 loops, best of 5: 3.1415927 ms per loop
+
+    ::
+
+        sage: units = [u"s", u"ms", u"μs", u"ns"]
+        sage: scaling = [1, 1e3, 1e6, 1e9]
+        sage: number = 7
+        sage: repeat = 13
+        sage: precision = int(5)
+        sage: best = pi / 10 ^ 9                                                        # needs sage.symbolic
+        sage: order = 3
+        sage: stats = (number, repeat, precision, best * scaling[order], units[order])  # needs sage.symbolic
+        sage: SageTimeitResult(stats)                                                   # needs sage.symbolic
+        7 loops, best of 13: 3.1416 ns per loop
+
+    If the third argument is not a Python integer, a :exc:`TypeError` is raised::
+
+        sage: SageTimeitResult( (1, 2, 3, 4, 's') )
+        <repr(<sage.misc.sage_timeit.SageTimeitResult at 0x...>) failed: TypeError: * wants int>
+    """
+    def __init__(self, stats, series=None):
+        r"""
+        Construction of a timing result.
+
+        See documentation of ``SageTimeitResult`` for more details and
+        examples.
+
+        EXAMPLES::
+
+            sage: from sage.misc.sage_timeit import SageTimeitResult
+            sage: SageTimeitResult( (3, 5, int(8), pi, 'ms') )                          # needs sage.symbolic
+            3 loops, best of 5: 3.1415927 ms per loop
+            sage: s = SageTimeitResult( (3, 5, int(8), pi, 'ms'), [1.0,1.1,0.5])        # needs sage.symbolic
+            sage: s.series                                                              # needs sage.symbolic
+            [1.00000000000000, 1.10000000000000, 0.500000000000000]
+        """
+        self.stats = stats
+        self.series = series if not None else []
+
+    def __repr__(self):
+        r"""
+        String representation.
+
+        EXAMPLES::
+
+            sage: from sage.misc.sage_timeit import SageTimeitResult
+            sage: stats = (1, 2, int(3), pi, 'ns')                                      # needs sage.symbolic
+            sage: SageTimeitResult(stats)           #indirect doctest                   # needs sage.symbolic
+            1 loop, best of 2: 3.14 ns per loop
+        """
+        if self.stats[0] > 1:
+            s = "%d loops, best of %d: %.*g %s per loop" % self.stats
+        else:
+            s = "%d loop, best of %d: %.*g %s per loop" % self.stats
+
+        if isinstance(s, str):
+            return s
+        return s.encode("utf-8")
+
+
+def sage_timeit(stmt, globals_dict=None, preparse=None, number=0, repeat=3, precision=3, seconds=False):
+    """nodetex
+    Accurately measure the wall time required to execute ``stmt``.
+
+    INPUT:
+
+    - ``stmt`` -- a text string
+
+    - ``globals_dict`` -- dictionary or ``None`` (default). Evaluate
+      ``stmt`` in the context of the globals dictionary. If not set,
+      the current ``globals()`` dictionary is used.
+
+    - ``preparse`` -- (default: use globals preparser default) if
+      ``True`` preparse ``stmt`` using the Sage preparser
+
+    - ``number`` -- integer; (default: 0); number of loops
+
+    - ``repeat`` -- integer; (default: 3); number of repetition
+
+    - ``precision`` -- integer; (default: 3); precision of output time
+
+    - ``seconds`` -- boolean (default: ``False``); whether to just
+      return time in seconds
+
+    OUTPUT:
+
+    An instance of ``SageTimeitResult`` unless the optional parameter
+    ``seconds=True`` is passed. In that case, the elapsed time in
+    seconds is returned as a floating-point number.
+
+    EXAMPLES::
+
+        sage: from sage.misc.sage_timeit import sage_timeit
+        sage: sage_timeit('3^100000', globals(), preparse=True, number=50)      # random output
+        '50 loops, best of 3: 1.97 ms per loop'
+        sage: sage_timeit('3^100000', globals(), preparse=False, number=50)     # random output
+        '50 loops, best of 3: 67.1 ns per loop'
+        sage: a = 10
+        sage: sage_timeit('a^2', globals(), number=50)                            # random output
+        '50 loops, best of 3: 4.26 us per loop'
+
+    If you only want to see the timing and not have access to additional
+    information, just use the ``timeit`` object::
+
+        sage: timeit('10^2', number=50)
+        50 loops, best of 3: ... per loop
+
+    Using sage_timeit gives you more information though::
+
+        sage: s = sage_timeit('10^2', globals(), repeat=1000)
+        sage: len(s.series)
+        1000
+        sage: mean(s.series)   # random output                                          # needs sage.modules
+        3.1298141479492283e-07
+        sage: min(s.series)    # random output
+        2.9258728027343752e-07
+        sage: t = stats.TimeSeries(s.series)                                            # needs numpy sage.modules
+        sage: t.scale(10^6).plot_histogram(bins=20,figsize=[12,6], ymax=2)              # needs numpy sage.modules sage.plot
+        Graphics object consisting of 20 graphics primitives
+
+
+    The input expression can contain newlines (but doctests cannot, so
+    we use ``os.linesep`` here)::
+
+        sage: from sage.misc.sage_timeit import sage_timeit
+        sage: from os import linesep as CR
+        sage: # sage_timeit(r'a = 2\\nb=131\\nfactor(a^b-1)')
+        sage: sage_timeit('a = 2' + CR + 'b=131' + CR + 'factor(a^b-1)',                # needs sage.libs.pari
+        ....:             globals(), number=10)
+        10 loops, best of 3: ... per loop
+
+    Test to make sure that ``timeit`` behaves well with output::
+
+        sage: timeit("print('Hi')", number=50)
+        50 loops, best of 3: ... per loop
+
+    If you want a machine-readable output, use the ``seconds=True`` option::
+
+        sage: timeit("print('Hi')", seconds=True)   # random output
+        1.42555236816e-06
+        sage: t = timeit("print('Hi')", seconds=True)
+        sage: t     #r random output
+        3.6010742187499999e-07
+
+    TESTS:
+
+    Make sure that garbage collection is re-enabled after an exception
+    occurs in timeit::
+
+        sage: def f(): raise ValueError
+        sage: import gc
+        sage: gc.isenabled()
+        True
+        sage: timeit("f()")
+        Traceback (most recent call last):
+        ...
+        ValueError
+        sage: gc.isenabled()
+        True
+    """
+    import math
+    import timeit as timeit_
+
+    import sage.repl.interpreter as interpreter
+    import sage.repl.preparse as preparser
+
+    number = int(number)
+    repeat = int(repeat)
+    precision = int(precision)
+    if preparse is None:
+        preparse = interpreter._do_preparse
+    if preparse:
+        stmt = preparser.preparse(stmt)
+    if stmt == "":
+        return ''
+
+    units = ["s", "ms", "μs", "ns"]
+    scaling = [1, 1e3, 1e6, 1e9]
+
+    timer = timeit_.Timer()
+
+    # this code has tight coupling to the inner workings of timeit.Timer,
+    # but is there a better way to achieve that the code stmt has access
+    # to the shell namespace?
+
+    src = timeit_.template.format(stmt=timeit_.reindent(stmt, 8),
+                                  setup='pass', init='')
+    code = compile(src, '<magic-timeit>', 'exec')
+    ns = {}
+    if not globals_dict:
+        globals_dict = globals()
+    exec(code, globals_dict, ns)
+    timer.inner = ns["inner"]
+
+
+    import sys
+    f = sys.stdout
+
+    try:
+        null = open(os.devnull, 'w')
+    except Exception:
+        null = None
+
+    try:
+        if null is not None:
+            sys.stdout = null
+
+        if number == 0:
+            # determine number so that 0.2 <= total time < 2.0
+            number = 1
+            for i in range(1, 5):
+                number *= 5
+                if timer.timeit(number) >= 0.2:
+                    break
+
+        series = [s / number for s in timer.repeat(repeat, number)]
+        best = min(series)
+
+    finally:
+        if null is not None:
+            sys.stdout.close()
+            sys.stdout = f
+        import gc
+        gc.enable()
+
+    if seconds:
+        return best
+
+    if best > 0.0:
+        order = min(-int(math.floor(math.log10(best)) // 3), 3)
+    else:
+        order = 3
+    stats = (number, repeat, precision, best * scaling[order], units[order])
+    return SageTimeitResult(stats, series=series)