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
|
#!/usr/bin/env python
"""Utility for making a doctest file out of Python or IPython input.
%prog [options] input_file [output_file]
This script is a convenient generator of doctest files that uses IPython's
irunner script to execute valid Python or IPython input in a separate process,
capture all of the output, and write it to an output file.
It can be used in one of two ways:
1. With a plain Python or IPython input file (denoted by extensions '.py' or
'.ipy'. In this case, the output is an auto-generated reST file with a
basic header, and the captured Python input and output contained in an
indented code block.
If no output filename is given, the input name is used, with the extension
replaced by '.txt'.
2. With an input template file. Template files are simply plain text files
with special directives of the form
%run filename
to include the named file at that point.
If no output filename is given and the input filename is of the form
'base.tpl.txt', the output will be automatically named 'base.txt'.
"""
# Standard library imports
import optparse
import os
import re
import sys
import tempfile
# IPython-specific libraries
from IPython.lib import irunner
from IPython.utils.warn import fatal
class IndentOut(object):
"""A simple output stream that indents all output by a fixed amount.
Instances of this class trap output to a given stream and first reformat it
to indent every input line."""
def __init__(self,out=sys.stdout,indent=4):
"""Create an indented writer.
:Keywords:
- `out` : stream (sys.stdout)
Output stream to actually write to after indenting.
- `indent` : int
Number of spaces to indent every input line by.
"""
self.indent_text = ' '*indent
self.indent = re.compile('^',re.MULTILINE).sub
self.out = out
self._write = out.write
self.buffer = []
self._closed = False
def write(self,data):
"""Write a string to the output stream."""
if self._closed:
raise ValueError('I/O operation on closed file')
self.buffer.append(data)
def flush(self):
if self.buffer:
data = ''.join(self.buffer)
self.buffer[:] = []
self._write(self.indent(self.indent_text,data))
def close(self):
self.flush()
self._closed = True
class RunnerFactory(object):
"""Code runner factory.
This class provides an IPython code runner, but enforces that only one
runner is every instantiated. The runner is created based on the extension
of the first file to run, and it raises an exception if a runner is later
requested for a different extension type.
This ensures that we don't generate example files for doctest with a mix of
python and ipython syntax.
"""
def __init__(self,out=sys.stdout):
"""Instantiate a code runner."""
self.out = out
self.runner = None
self.runnerClass = None
def _makeRunner(self,runnerClass):
self.runnerClass = runnerClass
self.runner = runnerClass(out=self.out)
return self.runner
def __call__(self,fname):
"""Return a runner for the given filename."""
if fname.endswith('.py'):
runnerClass = irunner.PythonRunner
elif fname.endswith('.ipy'):
runnerClass = irunner.IPythonRunner
else:
raise ValueError('Unknown file type for Runner: %r' % fname)
if self.runner is None:
return self._makeRunner(runnerClass)
else:
if runnerClass==self.runnerClass:
return self.runner
else:
e='A runner of type %r can not run file %r' % \
(self.runnerClass,fname)
raise ValueError(e)
TPL = """
=========================
Auto-generated doctests
=========================
This file was auto-generated by IPython in its entirety. If you need finer
control over the contents, simply make a manual template. See the
mkdoctests.py script for details.
%%run %s
"""
def main():
"""Run as a script."""
# Parse options and arguments.
parser = optparse.OptionParser(usage=__doc__)
newopt = parser.add_option
newopt('-f','--force',action='store_true',dest='force',default=False,
help='Force overwriting of the output file.')
newopt('-s','--stdout',action='store_true',dest='stdout',default=False,
help='Use stdout instead of a file for output.')
opts,args = parser.parse_args()
if len(args) < 1:
parser.error("incorrect number of arguments")
# Input filename
fname = args[0]
# We auto-generate the output file based on a trivial template to make it
# really easy to create simple doctests.
auto_gen_output = False
try:
outfname = args[1]
except IndexError:
outfname = None
if fname.endswith('.tpl.txt') and outfname is None:
outfname = fname.replace('.tpl.txt','.txt')
else:
bname, ext = os.path.splitext(fname)
if ext in ['.py','.ipy']:
auto_gen_output = True
if outfname is None:
outfname = bname+'.txt'
# Open input file
# In auto-gen mode, we actually change the name of the input file to be our
# auto-generated template
if auto_gen_output:
infile = tempfile.TemporaryFile()
infile.write(TPL % fname)
infile.flush()
infile.seek(0)
else:
infile = open(fname)
# Now open the output file. If opts.stdout was given, this overrides any
# explicit choice of output filename and just directs all output to
# stdout.
if opts.stdout:
outfile = sys.stdout
else:
# Argument processing finished, start main code
if os.path.isfile(outfname) and not opts.force:
fatal("Output file %r exists, use --force (-f) to overwrite."
% outfname)
outfile = open(outfname,'w')
# all output from included files will be indented
indentOut = IndentOut(outfile,4)
getRunner = RunnerFactory(indentOut)
# Marker in reST for transition lines
rst_transition = '\n'+'-'*76+'\n\n'
# local shorthand for loop
write = outfile.write
# Process input, simply writing back out all normal lines and executing the
# files in lines marked as '%run filename'.
for line in infile:
if line.startswith('%run '):
# We don't support files with spaces in their names.
incfname = line.split()[1]
# We make the output of the included file appear bracketed between
# clear reST transition marks, and indent it so that if anyone
# makes an HTML or PDF out of the file, all doctest input and
# output appears in proper literal blocks.
write(rst_transition)
write('Begin included file %s::\n\n' % incfname)
# I deliberately do NOT trap any exceptions here, so that if
# there's any problem, the user running this at the command line
# finds out immediately by the code blowing up, rather than ending
# up silently with an incomplete or incorrect file.
getRunner(incfname).run_file(incfname)
write('\nEnd included file %s\n' % incfname)
write(rst_transition)
else:
# The rest of the input file is just written out
write(line)
infile.close()
# Don't close sys.stdout!!!
if outfile is not sys.stdout:
outfile.close()
if __name__ == '__main__':
main()
|