### Navigation

- index
- modules |
- previous |
- Sage's Doctesting Framework »

# 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)

  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

  TESTS:

      sage: TestSuite(qname).run()

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'}

  TESTS:

      sage: TestSuite(D).run()

  `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`

  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(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 occuring in `self` but not in `other`.

  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)

  Auxilliary 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'}

### Navigation

- index
- modules |
- previous |
- Sage's Doctesting Framework »