This repository has been archived by the owner on Jan 30, 2023. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 7
/
sources.py
1634 lines (1380 loc) · 60.8 KB
/
sources.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
"""
Classes for sources of doctests
This module defines various classes for sources from which doctests
originate, such as files, functions or database entries.
AUTHORS:
- David Roe (2012-03-27) -- initial version, based on Robert Bradshaw's code.
"""
# ****************************************************************************
# Copyright (C) 2012 David Roe <roed.math@gmail.com>
# Robert Bradshaw <robertwb@gmail.com>
# William Stein <wstein@gmail.com>
#
# Distributed under the terms of the GNU General Public License (GPL)
#
# https://www.gnu.org/licenses/
# ****************************************************************************
import os
import sys
import re
import random
import doctest
from sage.cpython.string import bytes_to_str
from sage.repl.load import load
from sage.misc.lazy_attribute import lazy_attribute
from sage.misc.package_dir import is_package_or_sage_namespace_package_dir
from .parsing import SageDocTestParser
from .util import NestedName
from sage.structure.dynamic_class import dynamic_class
from sage.env import SAGE_SRC, SAGE_LIB
# Python file parsing
triple_quotes = re.compile(r"\s*[rRuU]*((''')|(\"\"\"))")
name_regex = re.compile(r".*\s(\w+)([(].*)?:")
# LaTeX file parsing
begin_verb = re.compile(r"\s*\\begin{verbatim}")
end_verb = re.compile(r"\s*\\end{verbatim}\s*(%link)?")
begin_lstli = re.compile(r"\s*\\begin{lstlisting}")
end_lstli = re.compile(r"\s*\\end{lstlisting}\s*(%link)?")
skip = re.compile(r".*%skip.*")
# ReST file parsing
link_all = re.compile(r"^\s*\.\.\s+linkall\s*$")
double_colon = re.compile(r"^(\s*).*::\s*$")
code_block = re.compile(r"^(\s*)[.][.]\s*code-block\s*::.*$")
whitespace = re.compile(r"\s*")
bitness_marker = re.compile('#.*(32|64)-bit')
bitness_value = '64' if sys.maxsize > (1 << 32) else '32'
# For neutralizing doctests
find_prompt = re.compile(r"^(\s*)(>>>|sage:)(.*)")
# For testing that enough doctests are created
sagestart = re.compile(r"^\s*(>>> |sage: )\s*[^#\s]")
untested = re.compile("(not implemented|not tested)")
# For parsing a PEP 0263 encoding declaration
pep_0263 = re.compile(br'^[ \t\v]*#.*?coding[:=]\s*([-\w.]+)')
# Source line number in warning output
doctest_line_number = re.compile(r"^\s*doctest:[0-9]")
def get_basename(path):
"""
This function returns the basename of the given path, e.g. sage.doctest.sources or doc.ru.tutorial.tour_advanced
EXAMPLES::
sage: from sage.doctest.sources import get_basename
sage: from sage.env import SAGE_SRC
sage: import os
sage: get_basename(os.path.join(SAGE_SRC,'sage','doctest','sources.py'))
'sage.doctest.sources'
"""
if path is None:
return None
if not os.path.exists(path):
return path
path = os.path.abspath(path)
root = os.path.dirname(path)
# If the file is in the sage library, we can use our knowledge of
# the directory structure
dev = SAGE_SRC
sp = SAGE_LIB
if path.startswith(dev):
# there will be a branch name
i = path.find(os.path.sep, len(dev))
if i == -1:
# this source is the whole library....
return path
root = path[:i]
elif path.startswith(sp):
root = path[:len(sp)]
else:
# If this file is in some python package we can see how deep
# it goes.
while is_package_or_sage_namespace_package_dir(root):
root = os.path.dirname(root)
fully_qualified_path = os.path.splitext(path[len(root) + 1:])[0]
if os.path.split(path)[1] == '__init__.py':
fully_qualified_path = fully_qualified_path[:-9]
return fully_qualified_path.replace(os.path.sep, '.')
class DocTestSource():
"""
This class provides a common base class for different sources of doctests.
INPUT:
- ``options`` -- a :class:`sage.doctest.control.DocTestDefaults`
instance or equivalent.
"""
def __init__(self, options):
"""
Initialization.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: TestSuite(FDS).run()
"""
self.options = options
def __eq__(self, other):
"""
Comparison is just by comparison of attributes.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: DD = DocTestDefaults()
sage: FDS = FileDocTestSource(filename,DD)
sage: FDS2 = FileDocTestSource(filename,DD)
sage: FDS == FDS2
True
"""
if type(self) != type(other):
return False
return self.__dict__ == other.__dict__
def __ne__(self, other):
"""
Test for non-equality.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: DD = DocTestDefaults()
sage: FDS = FileDocTestSource(filename,DD)
sage: FDS2 = FileDocTestSource(filename,DD)
sage: FDS != FDS2
False
"""
return not (self == other)
def _process_doc(self, doctests, doc, namespace, start):
"""
Appends doctests defined in ``doc`` to the list ``doctests``.
This function is called when a docstring block is completed
(either by ending a triple quoted string in a Python file,
unindenting from a comment block in a ReST file, or ending a
verbatim or lstlisting environment in a LaTeX file).
INPUT:
- ``doctests`` -- a running list of doctests to which the new
test(s) will be appended.
- ``doc`` -- a list of lines of a docstring, each including
the trailing newline.
- ``namespace`` -- a dictionary or
:class:`sage.doctest.util.RecordingDict`, used in the
creation of new :class:`doctest.DocTest` s.
- ``start`` -- an integer, giving the line number of the start
of this docstring in the larger file.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.doctest.parsing import SageDocTestParser
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','util.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: doctests, _ = FDS.create_doctests({})
sage: manual_doctests = []
sage: for dt in doctests:
....: FDS.qualified_name = dt.name
....: FDS._process_doc(manual_doctests, dt.docstring, {}, dt.lineno-1)
sage: doctests == manual_doctests
True
"""
docstring = "".join(doc)
new_doctests = self.parse_docstring(docstring, namespace, start)
sig_on_count_doc_doctest = "sig_on_count() # check sig_on/off pairings (virtual doctest)\n"
for dt in new_doctests:
if len(dt.examples) > 0 and not (hasattr(dt.examples[-1],'sage_source')
and dt.examples[-1].sage_source == sig_on_count_doc_doctest):
# Line number refers to the end of the docstring
sigon = doctest.Example(sig_on_count_doc_doctest, "0\n", lineno=docstring.count("\n"))
sigon.sage_source = sig_on_count_doc_doctest
dt.examples.append(sigon)
doctests.append(dt)
def _create_doctests(self, namespace, tab_okay=None):
"""
Creates a list of doctests defined in this source.
This function collects functionality common to file and string
sources, and is called by
:meth:`FileDocTestSource.create_doctests`.
INPUT:
- ``namespace`` -- a dictionary or
:class:`sage.doctest.util.RecordingDict`, used in the
creation of new :class:`doctest.DocTest` s.
- ``tab_okay`` -- whether tabs are allowed in this source.
OUTPUT:
- ``doctests`` -- a list of doctests defined by this source
- ``extras`` -- a dictionary with ``extras['tab']`` either
False or a list of linenumbers on which tabs appear.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.doctest.util import NestedName
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: FDS.qualified_name = NestedName('sage.doctest.sources')
sage: doctests, extras = FDS._create_doctests({})
sage: len(doctests)
41
sage: extras['tab']
False
sage: extras['line_number']
False
"""
if tab_okay is None:
tab_okay = isinstance(self,TexSource)
self._init()
self.line_shift = 0
self.parser = SageDocTestParser(self.options.optional,
self.options.long)
self.linking = False
doctests = []
in_docstring = False
unparsed_doc = False
doc = []
start = None
tab_locations = []
contains_line_number = False
for lineno, line in self:
if doctest_line_number.search(line) is not None:
contains_line_number = True
if "\t" in line:
tab_locations.append(str(lineno+1))
if "SAGE_DOCTEST_ALLOW_TABS" in line:
tab_okay = True
just_finished = False
if in_docstring:
if self.ending_docstring(line):
in_docstring = False
just_finished = True
self._process_doc(doctests, doc, namespace, start)
unparsed_doc = False
else:
bitness = bitness_marker.search(line)
if bitness:
if bitness.groups()[0] != bitness_value:
self.line_shift += 1
continue
else:
line = line[:bitness.start()] + "\n"
if self.line_shift and sagestart.match(line):
# We insert blank lines to make up for the removed lines
doc.extend(["\n"]*self.line_shift)
self.line_shift = 0
doc.append(line)
unparsed_doc = True
if not in_docstring and (not just_finished or self.start_finish_can_overlap):
# to get line numbers in linked docstrings correct we
# append a blank line to the doc list.
doc.append("\n")
if not line.strip():
continue
if self.starting_docstring(line):
in_docstring = True
if self.linking:
# If there's already a doctest, we overwrite it.
if len(doctests) > 0:
doctests.pop()
if start is None:
start = lineno
doc = []
else:
self.line_shift = 0
start = lineno
doc = []
# In ReST files we can end the file without decreasing the indentation level.
if unparsed_doc:
self._process_doc(doctests, doc, namespace, start)
extras = dict(tab=not tab_okay and tab_locations,
line_number=contains_line_number,
optionals=self.parser.optionals)
if self.options.randorder is not None and self.options.randorder is not False:
# we want to randomize even when self.randorder = 0
random.seed(self.options.randorder)
randomized = []
while doctests:
i = random.randint(0, len(doctests) - 1)
randomized.append(doctests.pop(i))
return randomized, extras
else:
return doctests, extras
class StringDocTestSource(DocTestSource):
r"""
This class creates doctests from a string.
INPUT:
- ``basename`` -- string such as 'sage.doctests.sources', going
into the names of created doctests and examples.
- ``source`` -- a string, giving the source code to be parsed for
doctests.
- ``options`` -- a :class:`sage.doctest.control.DocTestDefaults`
or equivalent.
- ``printpath`` -- a string, to be used in place of a filename
when doctest failures are displayed.
- ``lineno_shift`` -- an integer (default: 0) by which to shift
the line numbers of all doctests defined in this string.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import StringDocTestSource, PythonSource
sage: from sage.structure.dynamic_class import dynamic_class
sage: s = "'''\n sage: 2 + 2\n 4\n'''"
sage: PythonStringSource = dynamic_class('PythonStringSource',(StringDocTestSource, PythonSource))
sage: PSS = PythonStringSource('<runtime>', s, DocTestDefaults(), 'runtime')
sage: dt, extras = PSS.create_doctests({})
sage: len(dt)
1
sage: extras['tab']
[]
sage: extras['line_number']
False
sage: s = "'''\n\tsage: 2 + 2\n\t4\n'''"
sage: PSS = PythonStringSource('<runtime>', s, DocTestDefaults(), 'runtime')
sage: dt, extras = PSS.create_doctests({})
sage: extras['tab']
['2', '3']
sage: s = "'''\n sage: import warnings; warnings.warn('foo')\n doctest:1: UserWarning: foo \n'''"
sage: PSS = PythonStringSource('<runtime>', s, DocTestDefaults(), 'runtime')
sage: dt, extras = PSS.create_doctests({})
sage: extras['line_number']
True
"""
def __init__(self, basename, source, options, printpath, lineno_shift=0):
r"""
Initialization
TESTS::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import StringDocTestSource, PythonSource
sage: from sage.structure.dynamic_class import dynamic_class
sage: s = "'''\n sage: 2 + 2\n 4\n'''"
sage: PythonStringSource = dynamic_class('PythonStringSource',(StringDocTestSource, PythonSource))
sage: PSS = PythonStringSource('<runtime>', s, DocTestDefaults(), 'runtime')
sage: TestSuite(PSS).run()
"""
self.qualified_name = NestedName(basename)
self.printpath = printpath
self.source = source
self.lineno_shift = lineno_shift
DocTestSource.__init__(self, options)
def __iter__(self):
r"""
Iterating over this source yields pairs ``(lineno, line)``.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import StringDocTestSource, PythonSource
sage: from sage.structure.dynamic_class import dynamic_class
sage: s = "'''\n sage: 2 + 2\n 4\n'''"
sage: PythonStringSource = dynamic_class('PythonStringSource',(StringDocTestSource, PythonSource))
sage: PSS = PythonStringSource('<runtime>', s, DocTestDefaults(), 'runtime')
sage: for n, line in PSS:
....: print("{} {}".format(n, line))
0 '''
1 sage: 2 + 2
2 4
3 '''
"""
for lineno, line in enumerate(self.source.split('\n')):
yield lineno + self.lineno_shift, line + '\n'
def create_doctests(self, namespace):
r"""
Creates doctests from this string.
INPUT:
- ``namespace`` -- a dictionary or :class:`sage.doctest.util.RecordingDict`.
OUTPUT:
- ``doctests`` -- a list of doctests defined by this string
- ``tab_locations`` -- either False or a list of linenumbers
on which tabs appear.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import StringDocTestSource, PythonSource
sage: from sage.structure.dynamic_class import dynamic_class
sage: s = "'''\n sage: 2 + 2\n 4\n'''"
sage: PythonStringSource = dynamic_class('PythonStringSource',(StringDocTestSource, PythonSource))
sage: PSS = PythonStringSource('<runtime>', s, DocTestDefaults(), 'runtime')
sage: dt, tabs = PSS.create_doctests({})
sage: for t in dt:
....: print("{} {}".format(t.name, t.examples[0].sage_source))
<runtime> 2 + 2
"""
return self._create_doctests(namespace)
class FileDocTestSource(DocTestSource):
"""
This class creates doctests from a file.
INPUT:
- ``path`` -- string, the filename
- ``options`` -- a :class:`sage.doctest.control.DocTestDefaults`
instance or equivalent.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: FDS.basename
'sage.doctest.sources'
TESTS::
sage: TestSuite(FDS).run()
::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: filename = tmp_filename(ext=".txtt")
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
Traceback (most recent call last):
...
ValueError: unknown extension for the file to test (=...txtt),
valid extensions are: .py, .pyx, .pxd, .pxi, .sage, .spyx, .tex, .rst, .rst.txt
"""
def __init__(self, path, options):
"""
Initialization.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults(randorder=0))
sage: FDS.options.randorder
0
"""
self.path = path
DocTestSource.__init__(self, options)
if path.endswith('.rst.txt'):
ext = '.rst.txt'
else:
base, ext = os.path.splitext(path)
valid_code_ext = ('.py', '.pyx', '.pxd', '.pxi', '.sage', '.spyx')
if ext in valid_code_ext:
self.__class__ = dynamic_class('PythonFileSource',(FileDocTestSource,PythonSource))
self.encoding = "utf-8"
elif ext == '.tex':
self.__class__ = dynamic_class('TexFileSource',(FileDocTestSource,TexSource))
self.encoding = "utf-8"
elif ext == '.rst' or ext == '.rst.txt':
self.__class__ = dynamic_class('RestFileSource',(FileDocTestSource,RestSource))
self.encoding = "utf-8"
else:
valid_ext = ", ".join(valid_code_ext + ('.tex', '.rst', '.rst.txt'))
raise ValueError("unknown extension for the file to test (={}),"
" valid extensions are: {}".format(path, valid_ext))
def __iter__(self):
r"""
Iterating over this source yields pairs ``(lineno, line)``.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: filename = tmp_filename(ext=".py")
sage: s = "'''\n sage: 2 + 2\n 4\n'''"
sage: with open(filename, 'w') as f:
....: _ = f.write(s)
sage: FDS = FileDocTestSource(filename, DocTestDefaults())
sage: for n, line in FDS:
....: print("{} {}".format(n, line))
0 '''
1 sage: 2 + 2
2 4
3 '''
The encoding is "utf-8" by default::
sage: FDS.encoding
'utf-8'
We create a file with a Latin-1 encoding without declaring it::
sage: s = b"'''\nRegardons le polyn\xF4me...\n'''\n"
sage: with open(filename, 'wb') as f:
....: _ = f.write(s)
sage: FDS = FileDocTestSource(filename, DocTestDefaults())
sage: L = list(FDS)
Traceback (most recent call last):
...
UnicodeDecodeError: 'utf...8' codec can...t decode byte 0xf4 in position 18: invalid continuation byte
This works if we add a PEP 0263 encoding declaration::
sage: s = b"#!/usr/bin/env python\n# -*- coding: latin-1 -*-\n" + s
sage: with open(filename, 'wb') as f:
....: _ = f.write(s)
sage: FDS = FileDocTestSource(filename, DocTestDefaults())
sage: L = list(FDS)
sage: FDS.encoding
'latin-1'
"""
with open(self.path, 'rb') as source:
for lineno, line in enumerate(source):
if lineno < 2:
match = pep_0263.search(line)
if match:
self.encoding = bytes_to_str(match.group(1), 'ascii')
yield lineno, line.decode(self.encoding)
@lazy_attribute
def printpath(self):
"""
Whether the path is printed absolutely or relatively depends on an option.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: root = os.path.realpath(os.path.join(SAGE_SRC,'sage'))
sage: filename = os.path.join(root,'doctest','sources.py')
sage: cwd = os.getcwd()
sage: os.chdir(root)
sage: FDS = FileDocTestSource(filename,DocTestDefaults(randorder=0,abspath=False))
sage: FDS.printpath
'doctest/sources.py'
sage: FDS = FileDocTestSource(filename,DocTestDefaults(randorder=0,abspath=True))
sage: FDS.printpath
'.../sage/doctest/sources.py'
sage: os.chdir(cwd)
"""
if self.options.abspath:
return os.path.abspath(self.path)
else:
relpath = os.path.relpath(self.path)
if relpath.startswith(".." + os.path.sep):
return self.path
else:
return relpath
@lazy_attribute
def basename(self):
"""
The basename of this file source, e.g. sage.doctest.sources
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','rings','integer.pyx')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: FDS.basename
'sage.rings.integer'
"""
return get_basename(self.path)
@lazy_attribute
def in_lib(self):
"""
Whether this file is to be treated as a module in a Python package.
Such files aren't loaded before running tests.
This uses :func:`~sage.misc.package_dir.is_package_or_sage_namespace_package_dir`
but can be overridden via :class:`~sage.doctest.control.DocTestDefaults`.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC, 'sage', 'rings', 'integer.pyx')
sage: FDS = FileDocTestSource(filename, DocTestDefaults())
sage: FDS.in_lib
True
sage: filename = os.path.join(SAGE_SRC, 'sage', 'doctest', 'tests', 'abort.rst')
sage: FDS = FileDocTestSource(filename, DocTestDefaults())
sage: FDS.in_lib
False
You can override the default::
sage: FDS = FileDocTestSource("hello_world.py",DocTestDefaults())
sage: FDS.in_lib
False
sage: FDS = FileDocTestSource("hello_world.py",DocTestDefaults(force_lib=True))
sage: FDS.in_lib
True
"""
return (self.options.force_lib
or is_package_or_sage_namespace_package_dir(os.path.dirname(self.path)))
def create_doctests(self, namespace):
r"""
Return a list of doctests for this file.
INPUT:
- ``namespace`` -- a dictionary or :class:`sage.doctest.util.RecordingDict`.
OUTPUT:
- ``doctests`` -- a list of doctests defined in this file.
- ``extras`` -- a dictionary
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: doctests, extras = FDS.create_doctests(globals())
sage: len(doctests)
41
sage: extras['tab']
False
We give a self referential example::
sage: doctests[18].name
'sage.doctest.sources.FileDocTestSource.create_doctests'
sage: doctests[18].examples[10].source
'doctests[Integer(18)].examples[Integer(10)].source\n'
TESTS:
We check that we correctly process results that depend on 32
vs 64 bit architecture::
sage: import sys
sage: bitness = '64' if sys.maxsize > (1 << 32) else '32'
sage: gp.get_precision() == 38
False # 32-bit
True # 64-bit
sage: ex = doctests[18].examples[13]
sage: (bitness == '64' and ex.want == 'True \n') or (bitness == '32' and ex.want == 'False \n')
True
We check that lines starting with a # aren't doctested::
#sage: raise RuntimeError
"""
if not os.path.exists(self.path):
import errno
raise IOError(errno.ENOENT, "File does not exist", self.path)
base, filename = os.path.split(self.path)
_, ext = os.path.splitext(filename)
if not self.in_lib and ext in ('.py', '.pyx', '.sage', '.spyx'):
cwd = os.getcwd()
if base:
os.chdir(base)
try:
load(filename, namespace) # errors raised here will be caught in DocTestTask
finally:
os.chdir(cwd)
self.qualified_name = NestedName(self.basename)
return self._create_doctests(namespace)
def _test_enough_doctests(self, check_extras=True, verbose=True):
r"""
This function checks to see that the doctests are not getting
unexpectedly skipped. It uses a different (and simpler) code
path than the doctest creation functions, so there are a few
files in Sage that it counts incorrectly.
INPUT:
- ``check_extras`` -- bool (default ``True``), whether to check if
doctests are created that do not correspond to either a ``sage:``
or a ``>>>`` prompt
- ``verbose`` -- bool (default ``True``), whether to print
offending line numbers when there are missing or extra tests
TESTS::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: cwd = os.getcwd()
sage: os.chdir(SAGE_SRC)
sage: import itertools
sage: for path, dirs, files in itertools.chain(os.walk('sage'), os.walk('doc')): # long time
....: path = os.path.relpath(path)
....: dirs.sort(); files.sort()
....: for F in files:
....: _, ext = os.path.splitext(F)
....: if ext in ('.py', '.pyx', '.pxd', '.pxi', '.sage', '.spyx', '.rst'):
....: filename = os.path.join(path, F)
....: FDS = FileDocTestSource(filename, DocTestDefaults(long=True, optional=True, force_lib=True))
....: FDS._test_enough_doctests(verbose=False)
There are 3 unexpected tests being run in sage/doctest/parsing.py
There are 1 unexpected tests being run in sage/doctest/reporting.py
sage: os.chdir(cwd)
"""
expected = []
rest = isinstance(self, RestSource)
if rest:
skipping = False
in_block = False
last_line = ''
for lineno, line in self:
if not line.strip():
continue
if rest:
if line.strip().startswith(".. nodoctest"):
return
# We need to track blocks in order to figure out whether we're skipping.
if in_block:
indent = whitespace.match(line).end()
if indent <= starting_indent:
in_block = False
skipping = False
if not in_block:
m1 = double_colon.match(line)
m2 = code_block.match(line.lower())
starting = (m1 and not line.strip().startswith(".. ")) or m2
if starting:
if ".. skip" in last_line:
skipping = True
in_block = True
starting_indent = whitespace.match(line).end()
last_line = line
if (not rest or in_block) and sagestart.match(line) and not ((rest and skipping) or untested.search(line.lower())):
expected.append(lineno+1)
actual = []
tests, _ = self.create_doctests({})
for dt in tests:
if dt.examples:
for ex in dt.examples[:-1]: # the last entry is a sig_on_count()
actual.append(dt.lineno + ex.lineno + 1)
shortfall = sorted(set(expected).difference(set(actual)))
extras = sorted(set(actual).difference(set(expected)))
if len(actual) == len(expected):
if not shortfall:
return
dif = extras[0] - shortfall[0]
for e, s in zip(extras[1:],shortfall[1:]):
if dif != e - s:
break
else:
print("There are %s tests in %s that are shifted by %s" % (len(shortfall), self.path, dif))
if verbose:
print(" The correct line numbers are %s" % (", ".join(str(n) for n in shortfall)))
return
elif len(actual) < len(expected):
print("There are %s tests in %s that are not being run" % (len(expected) - len(actual), self.path))
elif check_extras:
print("There are %s unexpected tests being run in %s" % (len(actual) - len(expected), self.path))
if verbose:
if shortfall:
print(" Tests on lines %s are not run" % (", ".join(str(n) for n in shortfall)))
if check_extras and extras:
print(" Tests on lines %s seem extraneous" % (", ".join(str(n) for n in extras)))
class SourceLanguage:
"""
An abstract class for functions that depend on the programming language of a doctest source.
Currently supported languages include Python, ReST and LaTeX.
"""
def parse_docstring(self, docstring, namespace, start):
"""
Return a list of doctest defined in this docstring.
This function is called by :meth:`DocTestSource._process_doc`.
The default implementation, defined here, is to use the
:class:`sage.doctest.parsing.SageDocTestParser` attached to
this source to get doctests from the docstring.
INPUT:
- ``docstring`` -- a string containing documentation and tests.
- ``namespace`` -- a dictionary or :class:`sage.doctest.util.RecordingDict`.
- ``start`` -- an integer, one less than the starting line number
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.doctest.parsing import SageDocTestParser
sage: from sage.doctest.util import NestedName
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','util.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: doctests, _ = FDS.create_doctests({})
sage: for dt in doctests:
....: FDS.qualified_name = dt.name
....: dt.examples = dt.examples[:-1] # strip off the sig_on() test
....: assert(FDS.parse_docstring(dt.docstring,{},dt.lineno-1)[0] == dt)
"""
return [self.parser.get_doctest(docstring, namespace, str(self.qualified_name),
self.printpath, start + 1)]
class PythonSource(SourceLanguage):
"""
This class defines the functions needed for the extraction of doctests from python sources.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: type(FDS)
<class 'sage.doctest.sources.PythonFileSource'>
"""
# The same line can't both start and end a docstring
start_finish_can_overlap = False
def _init(self):
"""
This function is called before creating doctests from a Python source.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: FDS._init()
sage: FDS.last_indent
-1
"""
self.last_indent = -1
self.last_line = None
self.quotetype = None
self.paren_count = 0
self.bracket_count = 0
self.curly_count = 0
self.code_wrapping = False
def _update_quotetype(self, line):
r"""
Updates the track of what kind of quoted string we're in.
We need to track whether we're inside a triple quoted
string, since a triple quoted string that starts a line
could be the end of a string and thus not the beginning of a
doctest (see sage.misc.sageinspect for an example).
To do this tracking we need to track whether we're inside a
string at all, since ''' inside a string doesn't start a
triple quote (see the top of this file for an example).
We also need to track parentheses and brackets, since we only
want to update our record of last line and indentation level
when the line is actually over.
EXAMPLES::
sage: from sage.doctest.control import DocTestDefaults
sage: from sage.doctest.sources import FileDocTestSource
sage: from sage.env import SAGE_SRC
sage: import os
sage: filename = os.path.join(SAGE_SRC,'sage','doctest','sources.py')
sage: FDS = FileDocTestSource(filename,DocTestDefaults())
sage: FDS._init()
sage: FDS._update_quotetype('\"\"\"'); print(" ".join(list(FDS.quotetype)))
" " "
sage: FDS._update_quotetype("'''"); print(" ".join(list(FDS.quotetype)))
" " "
sage: FDS._update_quotetype('\"\"\"'); print(FDS.quotetype)
None
sage: FDS._update_quotetype("triple_quotes = re.compile(\"\\s*[rRuU]*((''')|(\\\"\\\"\\\"))\")")
sage: print(FDS.quotetype)
None
sage: FDS._update_quotetype("''' Single line triple quoted string \\''''")
sage: print(FDS.quotetype)
None
sage: FDS._update_quotetype("' Lots of \\\\\\\\'")
sage: print(FDS.quotetype)
None
"""
def _update_parens(start,end=None):
self.paren_count += line.count("(",start,end) - line.count(")",start,end)
self.bracket_count += line.count("[",start,end) - line.count("]",start,end)
self.curly_count += line.count("{",start,end) - line.count("}",start,end)
pos = 0
while pos < len(line):
if self.quotetype is None:
next_single = line.find("'",pos)
next_double = line.find('"',pos)
if next_single == -1 and next_double == -1:
next_comment = line.find("#",pos)
if next_comment == -1:
_update_parens(pos)
else:
_update_parens(pos,next_comment)
break
elif next_single == -1:
m = next_double
elif next_double == -1:
m = next_single