Parsing docstrings#
This module contains functions and classes that parse docstrings.
AUTHORS:
David Roe (2012-03-27) – initial version, based on Robert Bradshaw’s code.
Jeroen Demeyer(2014-08-28) – much improved handling of tolerances using interval arithmetic (trac ticket #16889).
- class sage.doctest.parsing.MarkedOutput#
Bases:
str
A subclass of string with context for whether another string matches it.
EXAMPLES:
sage: from sage.doctest.parsing import MarkedOutput sage: s = MarkedOutput("abc") sage: s.rel_tol 0 sage: s.update(rel_tol = .05) 'abc' sage: s.rel_tol 0.0500000000000000 sage: MarkedOutput("56 µs") '56 µs'
- update(**kwds)#
EXAMPLES:
sage: from sage.doctest.parsing import MarkedOutput sage: s = MarkedOutput("0.0007401") sage: s.update(abs_tol = .0000001) '0.0007401' sage: s.rel_tol 0 sage: s.abs_tol 1.00000000000000e-7
- class sage.doctest.parsing.OriginalSource(example)#
Bases:
object
Context swapping out the pre-parsed source with the original for better reporting.
EXAMPLES:
sage: from sage.doctest.sources import FileDocTestSource sage: from sage.doctest.control import DocTestDefaults sage: from sage.env import SAGE_SRC sage: import os sage: filename = os.path.join(SAGE_SRC,'sage','doctest','forker.py') sage: FDS = FileDocTestSource(filename,DocTestDefaults()) sage: doctests, extras = FDS.create_doctests(globals()) sage: ex = doctests[0].examples[0] sage: ex.sage_source 'doctest_var = 42; doctest_var^2\n' sage: ex.source 'doctest_var = Integer(42); doctest_var**Integer(2)\n' sage: from sage.doctest.parsing import OriginalSource sage: with OriginalSource(ex): ....: ex.source 'doctest_var = 42; doctest_var^2\n'
- sage.doctest.parsing.RIFtol(*args)#
Create an element of the real interval field used for doctest tolerances.
It allows large numbers like 1e1000, it parses strings with spaces like
RIF(" - 1 ")
out of the box and it carries a lot of precision. The latter is useful for testing libraries using arbitrary precision but not guaranteed rounding such as PARI. We use 1044 bits of precision, which should be good to deal with tolerances on numbers computed with 1024 bits of precision.The interval approach also means that we do not need to worry about rounding errors and it is also very natural to see a number with tolerance as an interval.
EXAMPLES:
sage: from sage.doctest.parsing import RIFtol sage: RIFtol(-1, 1) 0.? sage: RIFtol(" - 1 ") -1 sage: RIFtol("1e1000") 1.00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000?e1000
- class sage.doctest.parsing.SageDocTestParser(optional_tags=(), long=False)#
Bases:
doctest.DocTestParser
A version of the standard doctest parser which handles Sage’s custom options and tolerances in floating point arithmetic.
- parse(string, *args)#
A Sage specialization of
doctest.DocTestParser
.INPUT:
string
– the string to parse.name
– optional string giving the name identifying string, to be used in error messages.
OUTPUT:
A list consisting of strings and
doctest.Example
instances. There will be at least one string between successive examples (exactly one unless or long or optional tests are removed), and it will begin and end with a string.
EXAMPLES:
sage: from sage.doctest.parsing import SageDocTestParser sage: DTP = SageDocTestParser(('sage','magma','guava')) sage: example = 'Explanatory text::\n\n sage: E = magma("EllipticCurve([1, 1, 1, -10, -10])") # optional: magma\n\nLater text' sage: parsed = DTP.parse(example) sage: parsed[0] 'Explanatory text::\n\n' sage: parsed[1].sage_source 'E = magma("EllipticCurve([1, 1, 1, -10, -10])") # optional: magma\n' sage: parsed[2] '\nLater text'
If the doctest parser is not created to accept a given optional argument, the corresponding examples will just be removed:
sage: DTP2 = SageDocTestParser(('sage',)) sage: parsed2 = DTP2.parse(example) sage: parsed2 ['Explanatory text::\n\n', '\nLater text']
You can mark doctests as having a particular tolerance:
sage: example2 = 'sage: gamma(1.6) # tol 2.0e-11\n0.893515349287690' sage: ex = DTP.parse(example2)[1] sage: ex.sage_source 'gamma(1.6) # tol 2.0e-11\n' sage: ex.want '0.893515349287690\n' sage: type(ex.want) <class 'sage.doctest.parsing.MarkedOutput'> sage: ex.want.tol 2.000000000000000000...?e-11
You can use continuation lines:
sage: s = "sage: for i in range(4):\n....: print(i)\n....:\n" sage: ex = DTP2.parse(s)[1] sage: ex.source 'for i in range(Integer(4)):\n print(i)\n'
Sage currently accepts backslashes as indicating that the end of the current line should be joined to the next line. This feature allows for breaking large integers over multiple lines but is not standard for Python doctesting. It’s not guaranteed to persist, but works in Sage 5.5:
sage: n = 1234\ ....: 5678 sage: print(n) 12345678 sage: type(n) <class 'sage.rings.integer.Integer'>
It also works without the line continuation:
sage: m = 8765\ 4321 sage: print(m) 87654321
Test that trac ticket #26575 is resolved:
sage: example3 = 'sage: Zp(5,4,print_mode="digits")(5)\n...00010' sage: parsed3 = DTP.parse(example3) sage: dte = parsed3[1] sage: dte.sage_source 'Zp(5,4,print_mode="digits")(5)\n' sage: dte.want '...00010\n'
- class sage.doctest.parsing.SageOutputChecker#
Bases:
doctest.OutputChecker
A modification of the doctest OutputChecker that can check relative and absolute tolerance of answers.
EXAMPLES:
sage: from sage.doctest.parsing import SageOutputChecker, MarkedOutput, SageDocTestParser sage: import doctest sage: optflag = doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS sage: DTP = SageDocTestParser(('sage','magma','guava')) sage: OC = SageOutputChecker() sage: example2 = 'sage: gamma(1.6) # tol 2.0e-11\n0.893515349287690' sage: ex = DTP.parse(example2)[1] sage: ex.sage_source 'gamma(1.6) # tol 2.0e-11\n' sage: ex.want '0.893515349287690\n' sage: type(ex.want) <class 'sage.doctest.parsing.MarkedOutput'> sage: ex.want.tol 2.000000000000000000...?e-11 sage: OC.check_output(ex.want, '0.893515349287690', optflag) True sage: OC.check_output(ex.want, '0.8935153492877', optflag) True sage: OC.check_output(ex.want, '0', optflag) False sage: OC.check_output(ex.want, 'x + 0.8935153492877', optflag) False
- add_tolerance(wantval, want)#
Enlarge the real interval element
wantval
according to the tolerance options inwant
.INPUT:
wantval
– a real interval elementwant
– aMarkedOutput
describing the tolerance
OUTPUT:
an interval element containing
wantval
EXAMPLES:
sage: from sage.doctest.parsing import MarkedOutput, SageOutputChecker sage: OC = SageOutputChecker() sage: want_tol = MarkedOutput().update(tol=0.0001) sage: want_abs = MarkedOutput().update(abs_tol=0.0001) sage: want_rel = MarkedOutput().update(rel_tol=0.0001) sage: OC.add_tolerance(RIF(pi.n(64)), want_tol).endpoints() (3.14127849432443, 3.14190681285516) sage: OC.add_tolerance(RIF(pi.n(64)), want_abs).endpoints() (3.14149265358979, 3.14169265358980) sage: OC.add_tolerance(RIF(pi.n(64)), want_rel).endpoints() (3.14127849432443, 3.14190681285516) sage: OC.add_tolerance(RIF(1e1000), want_tol) 1.000?e1000 sage: OC.add_tolerance(RIF(1e1000), want_abs) 1.000000000000000?e1000 sage: OC.add_tolerance(RIF(1e1000), want_rel) 1.000?e1000 sage: OC.add_tolerance(0, want_tol) 0.000? sage: OC.add_tolerance(0, want_abs) 0.000? sage: OC.add_tolerance(0, want_rel) 0
- check_output(want, got, optionflags)#
Checks to see if the output matches the desired output.
If
want
is aMarkedOutput
instance, takes into account the desired tolerance.INPUT:
want
– a string orMarkedOutput
got
– a stringoptionflags
– an integer, passed down todoctest.OutputChecker
OUTPUT:
boolean, whether
got
matcheswant
up to the specified tolerance.
EXAMPLES:
sage: from sage.doctest.parsing import MarkedOutput, SageOutputChecker sage: import doctest sage: optflag = doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS sage: rndstr = MarkedOutput("I'm wrong!").update(random=True) sage: tentol = MarkedOutput("10.0").update(tol=.1) sage: tenabs = MarkedOutput("10.0").update(abs_tol=.1) sage: tenrel = MarkedOutput("10.0").update(rel_tol=.1) sage: zerotol = MarkedOutput("0.0").update(tol=.1) sage: zeroabs = MarkedOutput("0.0").update(abs_tol=.1) sage: zerorel = MarkedOutput("0.0").update(rel_tol=.1) sage: zero = "0.0" sage: nf = "9.5" sage: ten = "10.05" sage: eps = "-0.05" sage: OC = SageOutputChecker()
sage: OC.check_output(rndstr,nf,optflag) True sage: OC.check_output(tentol,nf,optflag) True sage: OC.check_output(tentol,ten,optflag) True sage: OC.check_output(tentol,zero,optflag) False sage: OC.check_output(tenabs,nf,optflag) False sage: OC.check_output(tenabs,ten,optflag) True sage: OC.check_output(tenabs,zero,optflag) False sage: OC.check_output(tenrel,nf,optflag) True sage: OC.check_output(tenrel,ten,optflag) True sage: OC.check_output(tenrel,zero,optflag) False sage: OC.check_output(zerotol,zero,optflag) True sage: OC.check_output(zerotol,eps,optflag) True sage: OC.check_output(zerotol,ten,optflag) False sage: OC.check_output(zeroabs,zero,optflag) True sage: OC.check_output(zeroabs,eps,optflag) True sage: OC.check_output(zeroabs,ten,optflag) False sage: OC.check_output(zerorel,zero,optflag) True sage: OC.check_output(zerorel,eps,optflag) False sage: OC.check_output(zerorel,ten,optflag) False
More explicit tolerance checks:
sage: _ = x # rel tol 1e10 sage: raise RuntimeError # rel tol 1e10 Traceback (most recent call last): ... RuntimeError sage: 1 # abs tol 2 -0.5 sage: print("0.9999") # rel tol 1e-4 1.0 sage: print("1.00001") # abs tol 1e-5 1.0 sage: 0 # rel tol 1 1
Spaces before numbers or between the sign and number are ignored:
sage: print("[ - 1, 2]") # abs tol 1e-10 [-1,2]
Tolerance on Python 3 for string results with unicode prefix:
sage: a = 'Cyrano'; a 'Cyrano' sage: b = ['Fermat', 'Euler']; b ['Fermat', 'Euler'] sage: c = 'you'; c 'you'
This illustrates that trac ticket #33588 is fixed:
sage: from sage.doctest.parsing import SageOutputChecker, SageDocTestParser sage: import doctest sage: optflag = doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS sage: DTP = SageDocTestParser(('sage','magma','guava')) sage: OC = SageOutputChecker() sage: example = "sage: 1.3090169943749475 # tol 1e-8\n1.3090169943749475" sage: ex = DTP.parse(example)[1] sage: OC.check_output(ex.want, '1.3090169943749475', optflag) True sage: OC.check_output(ex.want, 'ANYTHING1.3090169943749475', optflag) False sage: OC.check_output(ex.want, 'Long-step dual simplex will be used\n1.3090169943749475', optflag) True
- do_fixup(want, got)#
Performs few changes to the strings
want
andgot
.For example, remove warnings to be ignored.
INPUT:
want
– a string orMarkedOutput
got
– a string
OUTPUT:
A tuple:
bool,
True
when some fixup were performed andFalse
otherwisestring, edited wanted string
string, edited got string
Note
Currently, the code only possibly changes the string
got
while keepingwant
invariant. We keep open the possibility of adding a regular expression which would also change thewant
string. This is whywant
is an input and an output of the method even if currently kept invariant.EXAMPLES:
sage: from sage.doctest.parsing import SageOutputChecker sage: OC = SageOutputChecker() sage: OC.do_fixup('1.3090169943749475','1.3090169943749475') (False, '1.3090169943749475', '1.3090169943749475') sage: OC.do_fixup('1.3090169943749475','ANYTHING1.3090169943749475') (False, '1.3090169943749475', 'ANYTHING1.3090169943749475') sage: OC.do_fixup('1.3090169943749475','Long-step dual simplex will be used\n1.3090169943749475') (True, '1.3090169943749475', '\n1.3090169943749475')
When
want
is an instance of classMarkedOutput
:sage: from sage.doctest.parsing import SageOutputChecker, SageDocTestParser sage: import doctest sage: optflag = doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS sage: DTP = SageDocTestParser(('sage','magma','guava')) sage: OC = SageOutputChecker() sage: example = "sage: 1.3090169943749475\n1.3090169943749475" sage: ex = DTP.parse(example)[1] sage: ex.want '1.3090169943749475\n' sage: OC.do_fixup(ex.want,'1.3090169943749475') (False, '1.3090169943749475\n', '1.3090169943749475') sage: OC.do_fixup(ex.want,'ANYTHING1.3090169943749475') (False, '1.3090169943749475\n', 'ANYTHING1.3090169943749475') sage: OC.do_fixup(ex.want,'Long-step dual simplex will be used\n1.3090169943749475') (True, '1.3090169943749475\n', '\n1.3090169943749475')
- human_readable_escape_sequences(string)#
Make ANSI escape sequences human readable.
EXAMPLES:
sage: print('This is \x1b[1mbold\x1b[0m text') This is <CSI-1m>bold<CSI-0m> text
- output_difference(example, got, optionflags)#
Report on the differences between the desired result and what was actually obtained.
If
want
is aMarkedOutput
instance, takes into account the desired tolerance.INPUT:
example
– adoctest.Example
instancegot
– a stringoptionflags
– an integer, passed down todoctest.OutputChecker
OUTPUT:
a string, describing how
got
fails to matchexample.want
EXAMPLES:
sage: from sage.doctest.parsing import MarkedOutput, SageOutputChecker sage: import doctest sage: optflag = doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS sage: tentol = doctest.Example('',MarkedOutput("10.0\n").update(tol=.1)) sage: tenabs = doctest.Example('',MarkedOutput("10.0\n").update(abs_tol=.1)) sage: tenrel = doctest.Example('',MarkedOutput("10.0\n").update(rel_tol=.1)) sage: zerotol = doctest.Example('',MarkedOutput("0.0\n").update(tol=.1)) sage: zeroabs = doctest.Example('',MarkedOutput("0.0\n").update(abs_tol=.1)) sage: zerorel = doctest.Example('',MarkedOutput("0.0\n").update(rel_tol=.1)) sage: tlist = doctest.Example('',MarkedOutput("[10.0, 10.0, 10.0, 10.0, 10.0, 10.0]\n").update(abs_tol=0.987)) sage: zero = "0.0" sage: nf = "9.5" sage: ten = "10.05" sage: eps = "-0.05" sage: L = "[9.9, 8.7, 10.3, 11.2, 10.8, 10.0]" sage: OC = SageOutputChecker()
sage: print(OC.output_difference(tenabs,nf,optflag)) Expected: 10.0 Got: 9.5 Tolerance exceeded: 10.0 vs 9.5, tolerance 5e-1 > 1e-1 sage: print(OC.output_difference(tentol,zero,optflag)) Expected: 10.0 Got: 0.0 Tolerance exceeded: 10.0 vs 0.0, tolerance 1e0 > 1e-1 sage: print(OC.output_difference(tentol,eps,optflag)) Expected: 10.0 Got: -0.05 Tolerance exceeded: 10.0 vs -0.05, tolerance 2e0 > 1e-1 sage: print(OC.output_difference(tlist,L,optflag)) Expected: [10.0, 10.0, 10.0, 10.0, 10.0, 10.0] Got: [9.9, 8.7, 10.3, 11.2, 10.8, 10.0] Tolerance exceeded in 2 of 6: 10.0 vs 8.7, tolerance 2e0 > 9.87e-1 10.0 vs 11.2, tolerance 2e0 > 9.87e-1
- sage.doctest.parsing.get_source(example)#
Return the source with the leading ‘sage: ‘ stripped off.
EXAMPLES:
sage: from sage.doctest.parsing import get_source sage: from sage.doctest.sources import DictAsObject sage: example = DictAsObject({}) sage: example.sage_source = "2 + 2" sage: example.source = "sage: 2 + 2" sage: get_source(example) '2 + 2' sage: example = DictAsObject({}) sage: example.source = "3 + 3" sage: get_source(example) '3 + 3'
- sage.doctest.parsing.make_marked_output(s, D)#
Auxiliary function for pickling.
EXAMPLES:
sage: from sage.doctest.parsing import make_marked_output sage: s = make_marked_output("0.0007401", {'abs_tol':.0000001}) sage: s '0.0007401' sage: s.abs_tol 1.00000000000000e-7
- sage.doctest.parsing.parse_optional_tags(string)#
Return a set consisting of the optional tags from the following set that occur in a comment on the first line of the input string.
‘long time’
‘not implemented’
‘not tested’
‘known bug’
‘py2’
‘arb216’
‘arb218’
‘optional: PKG_NAME’ – the set will just contain ‘PKG_NAME’
EXAMPLES:
sage: from sage.doctest.parsing import parse_optional_tags sage: parse_optional_tags("sage: magma('2 + 2')# optional: magma") {'magma'} sage: parse_optional_tags("sage: #optional -- mypkg") {'mypkg'} sage: parse_optional_tags("sage: print(1) # parentheses are optional here") set() sage: parse_optional_tags("sage: print(1) # optional") {''} sage: sorted(list(parse_optional_tags("sage: #optional -- foo bar, baz"))) ['bar', 'foo'] sage: parse_optional_tags("sage: #optional -- foo.bar, baz") {'foo.bar'} sage: sorted(list(parse_optional_tags(" sage: factor(10^(10^10) + 1) # LoNg TiME, NoT TeSTED; OptioNAL -- P4cka9e"))) ['long time', 'not tested', 'p4cka9e'] sage: parse_optional_tags(" sage: raise RuntimeError # known bug") {'bug'} sage: sorted(list(parse_optional_tags(" sage: determine_meaning_of_life() # long time, not implemented"))) ['long time', 'not implemented']
We don’t parse inside strings:
sage: parse_optional_tags(" sage: print(' # long time')") set() sage: parse_optional_tags(" sage: print(' # long time') # not tested") {'not tested'}
UTF-8 works:
sage: parse_optional_tags("'ěščřžýáíéďĎ'") set()
- sage.doctest.parsing.parse_tolerance(source, want)#
Return a version of
want
marked up with the tolerance tags specified insource
.INPUT:
source
– a string, the source of a doctestwant
– a string, the desired output of the doctest
OUTPUT:
want
if there are no tolerance tags specified; aMarkedOutput
version otherwise.
EXAMPLES:
sage: from sage.doctest.parsing import parse_tolerance sage: marked = parse_tolerance("sage: s.update(abs_tol = .0000001)", "") sage: type(marked) <class 'str'> sage: marked = parse_tolerance("sage: s.update(tol = 0.1); s.rel_tol # abs tol 0.01 ", "") sage: marked.tol 0 sage: marked.rel_tol 0 sage: marked.abs_tol 0.010000000000000000000...?
- sage.doctest.parsing.pre_hash(s)#
Prepends a string with its length.
EXAMPLES:
sage: from sage.doctest.parsing import pre_hash sage: pre_hash("abc") '3:abc'
- sage.doctest.parsing.reduce_hex(fingerprints)#
Return a symmetric function of the arguments as hex strings.
The arguments should be 32 character strings consisting of hex digits: 0-9 and a-f.
EXAMPLES:
sage: from sage.doctest.parsing import reduce_hex sage: reduce_hex(["abc", "12399aedf"]) '0000000000000000000000012399a463' sage: reduce_hex(["12399aedf","abc"]) '0000000000000000000000012399a463'