Utility functions¶
This module contains various utility functions and classes used in doctesting.
AUTHORS:
David Roe (2012-03-27) – initial version, based on Robert Bradshaw’s code.
-
class
sage.doctest.util.
NestedName
(base)¶ Bases:
object
Class used to construct fully qualified names based on indentation level.
EXAMPLES:
sage: from sage.doctest.util import NestedName sage: qname = NestedName('sage.categories.algebras') sage: qname[0] = 'Algebras'; qname sage.categories.algebras.Algebras sage: qname[4] = '__contains__'; qname sage.categories.algebras.Algebras.__contains__ sage: qname[4] = 'ParentMethods' sage: qname[8] = 'from_base_ring'; qname sage.categories.algebras.Algebras.ParentMethods.from_base_ring
-
class
sage.doctest.util.
RecordingDict
(*args, **kwds)¶ Bases:
dict
This dictionary is used for tracking the dependencies of an example.
This feature allows examples in different doctests to be grouped for better timing data. It’s obtained by recording whenever anything is set or retrieved from this dictionary.
EXAMPLES:
sage: from sage.doctest.util import RecordingDict sage: D = RecordingDict(test=17) sage: D.got set() sage: D['test'] 17 sage: D.got {'test'} sage: D.set set() sage: D['a'] = 1 sage: D['a'] 1 sage: D.set {'a'} sage: D.got {'test'}
-
copy
()¶ Note that set and got are not copied.
EXAMPLES:
sage: from sage.doctest.util import RecordingDict sage: D = RecordingDict(d = 42) sage: D['a'] = 4 sage: D.set {'a'} sage: E = D.copy() sage: E.set set() sage: sorted(E.keys()) ['a', 'd']
-
get
(name, default=None)¶ EXAMPLES:
sage: from sage.doctest.util import RecordingDict sage: D = RecordingDict(d = 42) sage: D.get('d') 42 sage: D.got {'d'} sage: D.get('not_here') sage: sorted(list(D.got)) ['d', 'not_here']
-
start
()¶ We track which variables have been set or retrieved. This function initializes these lists to be empty.
EXAMPLES:
sage: from sage.doctest.util import RecordingDict sage: D = RecordingDict(d = 42) sage: D.set set() sage: D['a'] = 4 sage: D.set {'a'} sage: D.start(); D.set set()
-
-
class
sage.doctest.util.
Timer
¶ Bases:
object
A simple timer.
EXAMPLES:
sage: from sage.doctest.util import Timer sage: Timer() {} sage: TestSuite(Timer()).run()
-
annotate
(object)¶ Annotates the given object with the cputime and walltime stored in this timer.
EXAMPLES:
sage: from sage.doctest.util import Timer sage: Timer().start().annotate(EllipticCurve) sage: EllipticCurve.cputime # random 2.817255 sage: EllipticCurve.walltime # random 1332649288.410404
-
start
()¶ Start the timer.
Can be called multiple times to reset the timer.
EXAMPLES:
sage: from sage.doctest.util import Timer sage: Timer().start() {'cputime': ..., 'walltime': ...}
-
stop
()¶ Stops the timer, recording the time that has passed since it was started.
EXAMPLES:
sage: from sage.doctest.util import Timer sage: import time sage: timer = Timer().start() sage: time.sleep(float(0.5)) sage: timer.stop() {'cputime': ..., 'walltime': ...}
-
-
sage.doctest.util.
count_noun
(number, noun, plural=None, pad_number=False, pad_noun=False)¶ EXAMPLES:
sage: from sage.doctest.util import count_noun sage: count_noun(1, "apple") '1 apple' sage: count_noun(1, "apple", pad_noun=True) '1 apple ' sage: count_noun(1, "apple", pad_number=3) ' 1 apple' sage: count_noun(2, "orange") '2 oranges' sage: count_noun(3, "peach", "peaches") '3 peaches' sage: count_noun(1, "peach", plural="peaches", pad_noun=True) '1 peach '
-
sage.doctest.util.
dict_difference
(self, other)¶ Return a dict with all key-value pairs occurring in
self
but not inother
.EXAMPLES:
sage: from sage.doctest.util import dict_difference sage: d1 = {1: 'a', 2: 'b', 3: 'c'} sage: d2 = {1: 'a', 2: 'x', 4: 'c'} sage: dict_difference(d2, d1) {2: 'x', 4: 'c'}
sage: from sage.doctest.control import DocTestDefaults sage: D1 = DocTestDefaults() sage: D2 = DocTestDefaults(foobar="hello", timeout=100) sage: dict_difference(D2.__dict__, D1.__dict__) {'foobar': 'hello', 'timeout': 100}
-
sage.doctest.util.
make_recording_dict
(D, st, gt)¶ Auxiliary function for pickling.
EXAMPLES:
sage: from sage.doctest.util import make_recording_dict sage: D = make_recording_dict({'a':4,'d':42},set([]),set(['not_here'])) sage: sorted(D.items()) [('a', 4), ('d', 42)] sage: D.got {'not_here'}