passagemath-objects 10.6.44__cp314-cp314t-macosx_13_0_arm64.whl

sage/misc/test_nested_class.py

@@ -0,0 +1,228 @@
+# sage_setup: distribution = sagemath-objects
+"""
+Test for nested class Parent
+
+This file contains a discussion, examples, and tests about nested
+classes and parents. It is kept in a separate file to avoid import
+loops.
+
+EXAMPLES:
+
+Currently pickling fails for parents using nested classes (typically
+for categories), but deriving only from Parent::
+
+    sage: from sage.misc.test_nested_class import TestParent1, TestParent2, TestParent3, TestParent4
+    sage: P = TestParent1()
+    sage: TestSuite(P).run()
+    Failure ...
+    The following tests failed: _test_elements, _test_pickling
+
+They actually need to be in the NestedClassMetaclass. However, due to
+a technical detail, this is currently not directly supported::
+
+    sage: P = TestParent2()
+    Traceback (most recent call last):
+    ...
+    TypeError: metaclass conflict: the metaclass of a derived class must be a (non-strict) subclass of the metaclasses of all its bases
+    sage: TestSuite(P).run()  # not tested
+
+Instead, the easiest is to inherit from UniqueRepresentation, which is
+what you want to do anyway most of the time::
+
+    sage: P = TestParent3()
+    sage: TestSuite(P).run()
+
+This is what all Sage's parents using categories currently do. An
+alternative is to use ClasscallMetaclass as metaclass::
+
+    sage: P = TestParent4()
+    sage: TestSuite(P).run()
+"""
+# *****************************************************************************
+#  Copyright (C) 2009 Nicolas M. Thiery <nthiery at users.sf.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  http://www.gnu.org/licenses/
+# ******************************************************************************
+
+__all__ = []  # Don't document any parents
+
+from sage.structure.parent import Parent
+from sage.structure.element_wrapper import ElementWrapper
+from sage.structure.unique_representation import UniqueRepresentation
+from sage.misc.classcall_metaclass import ClasscallMetaclass
+from sage.misc.nested_class import NestedClassMetaclass
+
+
+class TestParent1(Parent):
+    def __init__(self):
+        """
+        EXAMPLES::
+
+            sage: sage.misc.test_nested_class.TestParent1()
+            <sage.misc.test_nested_class.TestParent1_with_category object at ...>
+        """
+        from sage.categories.sets_cat import Sets
+        Parent.__init__(self, category=Sets())
+
+    class Element(ElementWrapper):
+        pass
+
+
+class TestParent2(Parent, metaclass=NestedClassMetaclass):
+    def __init__(self):
+        """
+        EXAMPLES::
+
+            sage: sage.misc.test_nested_class.TestParent2()
+            Traceback (most recent call last):
+            ...
+            TypeError: metaclass conflict: the metaclass of a derived class must be a (non-strict) subclass of the metaclasses of all its bases
+        """
+        from sage.categories.sets_cat import Sets
+        Parent.__init__(self, category=Sets())
+
+    class Element(ElementWrapper):
+        pass
+
+
+class TestParent3(UniqueRepresentation, Parent):
+
+    def __init__(self):
+        """
+        EXAMPLES::
+
+            sage: sage.misc.test_nested_class.TestParent3()
+            <sage.misc.test_nested_class.TestParent3_with_category object at ...>
+        """
+        from sage.categories.sets_cat import Sets
+        Parent.__init__(self, category=Sets())
+
+    class Element(ElementWrapper):
+        pass
+
+
+class TestParent4(Parent, metaclass=ClasscallMetaclass):
+    def __init__(self):
+        """
+        EXAMPLES::
+
+            sage: sage.misc.test_nested_class.TestParent4()
+            <sage.misc.test_nested_class.TestParent4_with_category object at ...>
+        """
+        from sage.categories.sets_cat import Sets
+        Parent.__init__(self, category=Sets())
+
+    def __eq__(self, other):
+        """
+        EXAMPLES::
+
+            sage: from sage.misc.test_nested_class import TestParent4
+            sage: TestParent4() == TestParent4()
+            True
+        """
+        return self.__class__ == other.__class__
+
+    def __ne__(self, other):
+        """
+        EXAMPLES::
+
+            sage: from sage.misc.test_nested_class import TestParent4
+            sage: TestParent4() != TestParent4()
+            False
+        """
+        return self.__class__ != other.__class__
+
+    def __hash__(self):
+        """
+        Return the hash of ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.misc.test_nested_class import TestParent4
+            sage: hash(TestParent4()) == hash(TestParent4())
+            True
+        """
+        return hash(8960522744683456048)
+
+    class Element(ElementWrapper):
+        pass
+
+
+# Class for tests:
+class B:
+    """
+    A normal external class.
+    """
+    pass
+
+
+class ABB:
+    class B:
+        """
+        This class is broken and cannot be pickled.
+        A warning is emitted during compilation.
+        """
+        pass
+
+
+class ABL:
+    """
+    There is no problem here.
+    """
+    B = B
+
+
+class ALB:
+    """
+    There is a nested class just below. Which can't be properly sphinxed.
+    """
+    class C:
+        """
+        Internal C class.
+
+        Thanks to the links below this class is pickled ok.
+        But it is sphinxed wrong: It is typeset as a link to an outer class.
+        """
+        pass
+
+
+C = ALB.C
+
+
+class ABBMeta(metaclass=NestedClassMetaclass):
+    class B:
+        """
+        B interne
+        """
+        pass
+
+
+class ABLMeta(metaclass=NestedClassMetaclass):
+    B = B
+
+
+class ALBMeta(metaclass=NestedClassMetaclass):
+    """
+    There is a nested class just below which is properly sphinxed.
+    """
+    class CMeta:
+        """
+        B interne
+        """
+        pass
+
+
+CMeta = ALBMeta.CMeta
+
+
+class TestNestedParent(UniqueRepresentation, Parent):
+    """
+    This is a dummy for testing source inspection of nested classes.
+
+    See the test in ``sage.misc.sageinspect.sage_getsourcelines``.
+    """
+
+    class Element:
+        "This is a dummy element class"
+        pass

sage/misc/timing.py

@@ -0,0 +1,264 @@
+# pyright: strict
+# sage_setup: distribution = sagemath-objects
+r"""
+Timing functions
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2006 William Stein <wstein@gmail.com>
+#                     2006 Gonzalo Tornaria
+#                     2008 Martin Albrecht
+#                     2009 Mike Hansen
+#                     2018 Frédéric Chapoton
+#
+# 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 time
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    from weakref import ReferenceType
+
+    from sage.interfaces.expect import Expect
+
+
+@overload
+def cputime(t: float = 0, subprocesses: bool = False) -> float: ...
+@overload
+def cputime(t: GlobalCputime, subprocesses: bool) -> GlobalCputime: ...
+
+
+def cputime(
+    t: float | GlobalCputime = 0, subprocesses: bool = False
+) -> float | GlobalCputime:
+    """
+    Return the time in CPU seconds since Sage started, or with
+    optional argument ``t``, return the time since ``t``. This is how
+    much time Sage has spent using the CPU (to be precise, the sum of the system
+    and user CPU times of the process).  If ``subprocesses=False``
+    this does not count time spent in subprocesses spawned by Sage
+    (e.g., Gap, Singular, etc.). If ``subprocesses=True`` this
+    function tries to take all subprocesses with a working
+    ``cputime()`` implementation into account.
+
+    INPUT:
+
+    - ``t`` -- (optional) time in CPU seconds, if ``t`` is a result
+      from an earlier call with ``subprocesses=True``, then
+      ``subprocesses=True`` is assumed.
+
+    - ``subprocesses`` -- boolean (default: ``False``); include subprocesses
+
+    OUTPUT:
+
+    - ``float`` -- time in CPU seconds if ``subprocesses=False``
+
+    - :class:`GlobalCputime` -- object which holds CPU times of
+      subprocesses otherwise
+
+    EXAMPLES::
+
+        sage: t = cputime()
+        sage: F = gp.factor(2^199-1)                                                    # needs sage.libs.pari
+        sage: cputime(t)            # somewhat random
+        0.010999000000000092
+
+        sage: t = cputime(subprocesses=True)
+        sage: F = gp.factor(2^199-1)                                                    # needs sage.libs.pari
+        sage: cputime(t)            # somewhat random
+        0.091999
+
+        sage: w = walltime()
+        sage: F = gp.factor(2^199-1)                                                    # needs sage.libs.pari
+        sage: walltime(w)           # somewhat random
+        0.58425593376159668
+
+    .. NOTE::
+
+        Even with ``subprocesses=True`` there is no guarantee that the
+        CPU time is reported correctly because subprocesses can be
+        started and terminated at any given time.
+    """
+    try:
+        import resource  # type: ignore
+    except ImportError:
+        # The module 'resource' is removed in Pyodide to browser limitations.
+        if isinstance(t, GlobalCputime):
+            t = float(t)
+        return walltime(t)
+
+    if isinstance(t, GlobalCputime):
+        subprocesses = True
+
+    if not subprocesses:
+        try:
+            t = float(t)
+        except TypeError:
+            t = 0.0
+        return time.process_time() - t
+
+    try:
+        from sage.interfaces.quit import expect_objects
+    except ImportError:
+        expect_objects = ()
+
+    if t == 0:
+        ret = GlobalCputime(cputime())
+        for reference in expect_objects:
+            process = reference()
+            if process and process.is_running():
+                try:
+                    ct = process.cputime()
+                    ret.total += ct
+                    ret.interfaces[reference] = ct
+                except NotImplementedError:
+                    pass
+        return ret
+
+    if not isinstance(t, GlobalCputime):
+        t = GlobalCputime(t)
+    ret = GlobalCputime(cputime() - t.local)
+    for reference in expect_objects:
+        process = reference()
+        if process and process.is_running():
+            try:
+                ct = process.cputime() - t.interfaces.get(reference, 0.0)
+                ret.total += ct
+                ret.interfaces[reference] = ct
+            except NotImplementedError:
+                pass
+    return ret
+
+
+class GlobalCputime:
+    """
+    Container for CPU times of subprocesses.
+
+    AUTHOR:
+
+    - Martin Albrecht - (2008-12): initial version
+
+    EXAMPLES:
+
+    Objects of this type are returned if ``subprocesses=True`` is
+    passed to :func:`cputime`::
+
+        sage: cputime(subprocesses=True)        # indirect doctest, output random
+        0.2347431
+
+    We can use it to keep track of the CPU time spent in Singular for
+    example::
+
+        sage: t = cputime(subprocesses=True)
+        sage: P = PolynomialRing(QQ,7,'x')
+        sage: I = sage.rings.ideal.Katsura(P)                                           # needs sage.libs.singular
+        sage: gb = I.groebner_basis()  # calls Singular                                 # needs sage.libs.singular
+        sage: cputime(subprocesses=True) - t    # output random
+        0.462987
+
+    For further processing we can then convert this container to a
+    float::
+
+        sage: t = cputime(subprocesses=True)
+        sage: float(t)                          # output somewhat random
+        2.1088339999999999
+
+    .. SEEALSO::
+
+      :func:`cputime`
+    """
+
+    def __init__(self, t: float) -> None:
+        """
+        Create a new CPU time object which also keeps track of
+        subprocesses.
+
+        EXAMPLES::
+
+            sage: from sage.misc.timing import GlobalCputime
+            sage: ct = GlobalCputime(0.0); ct
+            0.0...
+        """
+        self.total: float = t
+        self.local: float = t
+        self.interfaces: dict[ReferenceType[Expect], float] = {}
+
+    def __repr__(self) -> str:
+        """
+        EXAMPLES::
+
+            sage: cputime(subprocesses=True)    # indirect doctest, output random
+            0.2347431
+        """
+        return str(self.total)
+
+    def __add__(self, other: GlobalCputime | float) -> GlobalCputime:
+        """
+        EXAMPLES::
+
+            sage: t = cputime(subprocesses=True)
+            sage: P = PolynomialRing(QQ,7,'x')
+            sage: I = sage.rings.ideal.Katsura(P)                                       # needs sage.libs.singular
+            sage: gb = I.groebner_basis()  # calls Singular                             # needs sage.libs.singular
+            sage: cputime(subprocesses=True) + t # output random
+            2.798708
+        """
+        if not isinstance(other, GlobalCputime):
+            other = GlobalCputime(other)
+        ret = GlobalCputime(self.total + other.total)
+        return ret
+
+    def __sub__(self, other: GlobalCputime | float) -> GlobalCputime:
+        """
+        EXAMPLES::
+
+            sage: t = cputime(subprocesses=True)
+            sage: P = PolynomialRing(QQ,7,'x')
+            sage: I = sage.rings.ideal.Katsura(P)                                       # needs sage.libs.singular
+            sage: gb = I.groebner_basis()  # calls Singular                             # needs sage.libs.singular
+            sage: cputime(subprocesses=True) - t # output random
+            0.462987
+        """
+        if not isinstance(other, GlobalCputime):
+            other = GlobalCputime(other)
+        ret = GlobalCputime(self.total - other.total)
+        return ret
+
+    def __float__(self) -> float:
+        """
+        EXAMPLES::
+
+            sage: t = cputime(subprocesses=True)
+            sage: float(t)                          # output somewhat random
+            2.1088339999999999
+        """
+        return float(self.total)
+
+
+def walltime(t: float = 0) -> float:
+    """
+    Return the wall time in second, or with optional argument ``t``, return
+    the wall time since time ``t``. "Wall time" means the time on a wall
+    clock, i.e., the actual time.
+
+    INPUT:
+
+    - ``t`` -- (optional) float, time in CPU seconds
+
+    OUTPUT: ``float`` -- time in seconds
+
+    EXAMPLES::
+
+        sage: w = walltime()
+        sage: F = factor(2^199-1)                                                       # needs sage.libs.pari
+        sage: walltime(w)   # somewhat random
+        0.8823847770690918
+    """
+    return time.time() - t

sage/misc/unknown.py

@@ -0,0 +1,222 @@
+# sage_setup: distribution = sagemath-objects
+"""
+The Unknown truth value
+
+The ``Unknown`` object is used in Sage in several places as return value
+in addition to ``True`` and ``False``, in order to signal uncertainty
+about or inability to compute the result. ``Unknown`` can be identified
+using ``is``, or by catching :exc:`UnknownError` from a boolean operation.
+
+.. WARNING::
+
+    Calling ``bool()`` with ``Unknown`` as argument will throw an
+    :exc:`UnknownError`. This also means that in the following cases,
+    ``and``, ``not``, and ``or`` fail or return a somewhat wrong value::
+
+        sage: not Unknown         # should return Unknown
+        Traceback (most recent call last):
+        ...
+        UnknownError: Unknown does not evaluate in boolean context
+        sage: Unknown and False   # should return False
+        Traceback (most recent call last):
+        ...
+        UnknownError: Unknown does not evaluate in boolean context
+        sage: Unknown or False    # should return Unknown
+        Traceback (most recent call last):
+        ...
+        UnknownError: Unknown does not evaluate in boolean context
+
+EXAMPLES::
+
+    sage: def func(n):
+    ....:     if n > 0:
+    ....:         return True
+    ....:     elif n < 0:
+    ....:         return False
+    ....:     else:
+    ....:         return Unknown
+
+Using direct identification::
+
+    sage: for n in [-3, 0, 12]:
+    ....:    res = func(n)
+    ....:    if res is True:
+    ....:        print("n={} is positive".format(n))
+    ....:    elif res is False:
+    ....:        print("n={} is negative".format(n))
+    ....:    else:
+    ....:        print("n={} is neither positive nor negative".format(n))
+    n=-3 is negative
+    n=0 is neither positive nor negative
+    n=12 is positive
+
+Using :exc:`UnknownError`::
+
+    sage: for n in [-3, 0, 12]:
+    ....:    try:
+    ....:        if func(n):
+    ....:            print("n={} is positive".format(n))
+    ....:        else:
+    ....:            print("n={} is negative".format(n))
+    ....:    except UnknownError:
+    ....:        print("n={} is neither positive nor negative".format(n))
+    n=-3 is negative
+    n=0 is neither positive nor negative
+    n=12 is positive
+
+AUTHORS:
+
+- Florent Hivert (2010): initial version.
+- Ralf Stephan, Vincent Delecroix (2018-2020): redesign
+"""
+# ****************************************************************************
+#       Copyright (C) 2010 Florent Hivert <florent.hivert at lri.fr>
+#                     2018-2020 Ralf Stefan
+#                     2018-2020 Vincent Delecroix <20100.delecroix@gmail.com>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  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 sage.structure.unique_representation import UniqueRepresentation
+from sage.structure.richcmp import richcmp_method, rich_to_bool
+
+
+class UnknownError(TypeError):
+    """
+    Raised whenever :class:`Unknown` is used in a boolean operation.
+
+    EXAMPLES::
+
+        sage: not Unknown
+        Traceback (most recent call last):
+        ...
+        UnknownError: Unknown does not evaluate in boolean context
+    """
+    pass
+
+
+@richcmp_method
+class UnknownClass(UniqueRepresentation):
+    """
+    The Unknown truth value.
+
+    The ``Unknown`` object is used in Sage in several places as return value
+    in addition to ``True`` and ``False``, in order to signal uncertainty
+    about or inability to compute the result. ``Unknown`` can be identified
+    using ``is``, or by catching :exc:`UnknownError` from a boolean
+    operation.
+
+    .. WARNING::
+
+        Calling ``bool()`` with ``Unknown`` as argument will throw an
+        :exc:`UnknownError`. This also means that applying ``and``, ``not``,
+        and ``or`` to ``Unknown`` might fail.
+
+    TESTS::
+
+        sage: TestSuite(Unknown).run()
+    """
+    def __repr__(self):
+        """
+        TESTS::
+
+            sage: Unknown
+            Unknown
+        """
+        return "Unknown"
+
+    def __bool__(self):
+        """
+        When evaluated in a boolean context ``Unknown`` raises a :exc:`UnknownError`.
+
+        EXAMPLES::
+
+            sage: bool(Unknown)
+            Traceback (most recent call last):
+            ...
+            UnknownError: Unknown does not evaluate in boolean context
+            sage: not Unknown
+            Traceback (most recent call last):
+            ...
+            UnknownError: Unknown does not evaluate in boolean context
+        """
+        raise UnknownError('Unknown does not evaluate in boolean context')
+
+    def __and__(self, other):
+        """
+        The ``&`` logical operation.
+
+        EXAMPLES::
+
+            sage: Unknown & False
+            False
+            sage: Unknown & Unknown
+            Unknown
+            sage: Unknown & True
+            Unknown
+
+            sage: Unknown.__or__(3)
+            NotImplemented
+        """
+        if other is False:
+            return False
+        elif other is True or other is Unknown:
+            return self
+        else:
+            return NotImplemented
+
+    def __or__(self, other):
+        """
+        The ``|`` logical connector.
+
+        EXAMPLES::
+
+            sage: Unknown | False
+            Unknown
+            sage: Unknown | Unknown
+            Unknown
+            sage: Unknown | True
+            True
+
+            sage: Unknown.__or__(3)
+            NotImplemented
+        """
+        if other is True:
+            return True
+        elif other is False or other is Unknown:
+            return self
+        else:
+            return NotImplemented
+
+    def __richcmp__(self, other, op):
+        """
+        Comparison of truth value.
+
+        EXAMPLES::
+
+            sage: l = [False, Unknown, True]
+            sage: for a in l: print([a < b for b in l])
+            [False, True, True]
+            [False, False, True]
+            [False, False, False]
+
+            sage: for a in l: print([a <= b for b in l])
+            [True, True, True]
+            [False, True, True]
+            [False, False, True]
+        """
+        if other is self:
+            return rich_to_bool(op, 0)
+        if not isinstance(other, bool):
+            return NotImplemented
+        if other:
+            return rich_to_bool(op, -1)
+        else:
+            return rich_to_bool(op, +1)
+
+
+Unknown = UnknownClass()