demo.py
578 lines
| 20.1 KiB
| text/x-python
|
PythonLexer
|
r8306 | from __future__ import unicode_literals | ||
|
r22 | """Module for interactive demos using IPython. | ||
|
r23 | |||
|
r178 | This module implements a few classes for running Python scripts interactively | ||
in IPython for demonstrations. With very simple markup (a few tags in | ||||
comments), you can control points where the script stops executing and returns | ||||
control to IPython. | ||||
|
r515 | |||
Provided classes | ||||
================ | ||||
|
r178 | The classes are (see their docstrings for further details): | ||
- Demo: pure python demos | ||||
- IPythonDemo: demos with input to be processed by IPython as if it had been | ||||
typed interactively (so magics work, as well as any other special syntax you | ||||
may have added via input prefilters). | ||||
- LineDemo: single-line version of the Demo class. These demos are executed | ||||
one line at a time, and require no markup. | ||||
- IPythonLineDemo: IPython version of the LineDemo class (the demo is | ||||
executed a line at a time, but processed via IPython). | ||||
|
r523 | - ClearMixin: mixin to make Demo classes with less visual clutter. It | ||
declares an empty marquee and a pre_cmd that clears the screen before each | ||||
block (see Subclassing below). | ||||
- ClearDemo, ClearIPDemo: mixin-enabled versions of the Demo and IPythonDemo | ||||
classes. | ||||
|
r31 | |||
|
r515 | Subclassing | ||
=========== | ||||
The classes here all include a few methods meant to make customization by | ||||
subclassing more convenient. Their docstrings below have some more details: | ||||
- marquee(): generates a marquee to provide visible on-screen markers at each | ||||
block start and end. | ||||
- pre_cmd(): run right before the execution of each block. | ||||
|
r523 | - post_cmd(): run right after the execution of each block. If the block | ||
|
r515 | raises an exception, this is NOT called. | ||
|
r4872 | |||
|
r515 | |||
Operation | ||||
========= | ||||
|
r31 | The file is run in its own empty namespace (though you can pass it a string of | ||
arguments as if in a command line environment, and it will see those as | ||||
sys.argv). But at each stop, the global IPython namespace is updated with the | ||||
current internal demo namespace, so you can work interactively with the data | ||||
accumulated so far. | ||||
By default, each block of code is printed (with syntax highlighting) before | ||||
executing it and you have to confirm execution. This is intended to show the | ||||
code to an audience first so you can discuss it, and only proceed with | ||||
execution once you agree. There are a few tags which allow you to modify this | ||||
behavior. | ||||
The supported tags are: | ||||
|
r523 | # <demo> stop | ||
|
r31 | |||
Defines block boundaries, the points where IPython stops execution of the | ||||
file and returns to the interactive prompt. | ||||
|
r523 | You can optionally mark the stop tag with extra dashes before and after the | ||
word 'stop', to help visually distinguish the blocks in a text editor: | ||||
# <demo> --- stop --- | ||||
|
r4872 | |||
|
r523 | |||
|
r31 | # <demo> silent | ||
Make a block execute silently (and hence automatically). Typically used in | ||||
cases where you have some boilerplate or initialization code which you need | ||||
executed but do not want to be seen in the demo. | ||||
|
r4872 | |||
|
r31 | # <demo> auto | ||
Make a block execute automatically, but still being printed. Useful for | ||||
simple code which does not warrant discussion, since it avoids the extra | ||||
manual confirmation. | ||||
# <demo> auto_all | ||||
This tag can _only_ be in the first block, and if given it overrides the | ||||
individual auto tags to make the whole demo fully automatic (no block asks | ||||
for confirmation). It can also be given at creation time (or the attribute | ||||
set later) to override what's in the file. | ||||
While _any_ python file can be run as a Demo instance, if there are no stop | ||||
tags the whole file will run in a single block (no different that calling | ||||
first %pycat and then %run). The minimal markup to make this useful is to | ||||
place a set of stop tags; the other tags are only there to let you fine-tune | ||||
the execution. | ||||
This is probably best explained with the simple example file below. You can | ||||
copy this into a file named ex_demo.py, and try running it via: | ||||
from IPython.demo import Demo | ||||
d = Demo('ex_demo.py') | ||||
|
r178 | d() <--- Call the d object (omit the parens if you have autocall set to 2). | ||
|
r31 | |||
Each time you call the demo object, it runs the next block. The demo object | ||||
|
r178 | has a few useful methods for navigation, like again(), edit(), jump(), seek() | ||
and back(). It can be reset for a new run via reset() or reloaded from disk | ||||
(in case you've edited the source) via reload(). See their docstrings below. | ||||
|
r31 | |||
|
r1942 | Note: To make this simpler to explore, a file called "demo-exercizer.py" has | ||
|
r2102 | been added to the "docs/examples/core" directory. Just cd to this directory in | ||
an IPython session, and type:: | ||||
%run demo-exercizer.py | ||||
|
r4872 | |||
|
r1939 | and then follow the directions. | ||
|
r515 | |||
Example | ||||
======= | ||||
The following is a very simple example of a valid demo file. | ||||
|
r31 | #################### EXAMPLE DEMO <ex_demo.py> ############################### | ||
'''A simple interactive demo to illustrate the use of IPython's Demo class.''' | ||||
print 'Hello, welcome to an interactive IPython demo.' | ||||
# The mark below defines a block boundary, which is a point where IPython will | ||||
|
r523 | # stop execution and return to the interactive prompt. The dashes are actually | ||
# optional and used only as a visual aid to clearly separate blocks while | ||||
|
r1889 | # editing the demo code. | ||
|
r523 | # <demo> stop | ||
|
r31 | |||
x = 1 | ||||
y = 2 | ||||
|
r523 | # <demo> stop | ||
|
r31 | |||
# the mark below makes this block as silent | ||||
# <demo> silent | ||||
print 'This is a silent block, which gets executed but not printed.' | ||||
|
r523 | # <demo> stop | ||
|
r31 | # <demo> auto | ||
print 'This is an automatic block.' | ||||
print 'It is executed without asking for confirmation, but printed.' | ||||
z = x+y | ||||
print 'z=',x | ||||
|
r523 | # <demo> stop | ||
|
r31 | # This is just another normal block. | ||
print 'z is now:', z | ||||
print 'bye!' | ||||
################### END EXAMPLE DEMO <ex_demo.py> ############################ | ||||
|
r22 | """ | ||
|
r515 | |||
|
r22 | #***************************************************************************** | ||
|
r88 | # Copyright (C) 2005-2006 Fernando Perez. <Fernando.Perez@colorado.edu> | ||
|
r22 | # | ||
# Distributed under the terms of the BSD License. The full license is in | ||||
# the file COPYING, distributed as part of this software. | ||||
# | ||||
#***************************************************************************** | ||||
|
r7817 | from __future__ import print_function | ||
|
r22 | |||
|
r178 | import os | ||
|
r23 | import re | ||
|
r284 | import shlex | ||
|
r52 | import sys | ||
|
r22 | |||
|
r2042 | from IPython.utils.PyColorize import Parser | ||
|
r3800 | from IPython.utils import io | ||
|
r2775 | from IPython.utils.io import file_read, file_readlines | ||
|
r2498 | from IPython.utils.text import marquee | ||
|
r8306 | from IPython.utils import openpy | ||
|
r178 | __all__ = ['Demo','IPythonDemo','LineDemo','IPythonLineDemo','DemoError'] | ||
|
r22 | |||
|
r4731 | class DemoError(Exception): pass | ||
|
r22 | |||
|
r31 | def re_mark(mark): | ||
return re.compile(r'^\s*#\s+<demo>\s+%s\s*$' % mark,re.MULTILINE) | ||||
|
r523 | class Demo(object): | ||
|
r31 | |||
|
r1743 | re_stop = re_mark('-*\s?stop\s?-*') | ||
|
r31 | re_silent = re_mark('silent') | ||
re_auto = re_mark('auto') | ||||
re_auto_all = re_mark('auto_all') | ||||
|
r1889 | def __init__(self,src,title='',arg_str='',auto_all=None): | ||
|
r24 | """Make a new demo object. To run the demo, simply call the object. | ||
|
r31 | See the module docstring for full details and an example (you can use | ||
IPython.Demo? in IPython to see it). | ||||
|
r24 | Inputs: | ||
|
r4872 | |||
|
r1889 | - src is either a file, or file-like object, or a | ||
string that can be resolved to a filename. | ||||
|
r24 | |||
Optional inputs: | ||||
|
r4872 | |||
|
r1889 | - title: a string to use as the demo name. Of most use when the demo | ||
|
r4872 | you are making comes from an object that has no filename, or if you | ||
|
r1889 | want an alternate denotation distinct from the filename. | ||
|
r24 | |||
- arg_str(''): a string of arguments, internally converted to a list | ||||
just like sys.argv, so the demo script can see a similar | ||||
environment. | ||||
|
r31 | - auto_all(None): global flag to run all blocks automatically without | ||
|
r30 | confirmation. This attribute overrides the block-level tags and | ||
applies to the whole demo. It is an attribute of the object, and | ||||
can be changed at runtime simply by reassigning it to a boolean | ||||
value. | ||||
|
r24 | """ | ||
|
r1889 | if hasattr(src, "read"): | ||
# It seems to be a file or a file-like object | ||||
self.fname = "from a file-like object" | ||||
if title == '': | ||||
self.title = "from a file-like object" | ||||
else: | ||||
self.title = title | ||||
else: | ||||
# Assume it's a string or something that can be converted to one | ||||
self.fname = src | ||||
if title == '': | ||||
(filepath, filename) = os.path.split(src) | ||||
self.title = filename | ||||
else: | ||||
self.title = title | ||||
self.sys_argv = [src] + shlex.split(arg_str) | ||||
|
r31 | self.auto_all = auto_all | ||
|
r2562 | self.src = src | ||
|
r4872 | |||
|
r22 | # get a few things from ipython. While it's a bit ugly design-wise, | ||
# it ensures that things like color scheme and the like are always in | ||||
# sync with the ipython mode being used. This class is only meant to | ||||
# be used inside ipython anyways, so it's OK. | ||||
|
r2552 | ip = get_ipython() # this is in builtins whenever IPython is running | ||
self.ip_ns = ip.user_ns | ||||
self.ip_colorize = ip.pycolorize | ||||
self.ip_showtb = ip.showtraceback | ||||
|
r3087 | self.ip_run_cell = ip.run_cell | ||
|
r2552 | self.shell = ip | ||
|
r30 | |||
# load user data and initialize data structures | ||||
self.reload() | ||||
|
r22 | |||
|
r2587 | def fload(self): | ||
"""Load file object.""" | ||||
|
r22 | # read data and parse into blocks | ||
|
r2562 | if hasattr(self, 'fobj') and self.fobj is not None: | ||
self.fobj.close() | ||||
if hasattr(self.src, "read"): | ||||
# It seems to be a file or a file-like object | ||||
self.fobj = self.src | ||||
else: | ||||
# Assume it's a string or something that can be converted to one | ||||
|
r8306 | self.fobj = openpy.open(self.fname) | ||
|
r2562 | |||
|
r2587 | def reload(self): | ||
"""Reload source from disk and initialize state.""" | ||||
self.fload() | ||||
|
r4872 | |||
|
r8306 | self.src = "".join(openpy.strip_encoding_cookie(self.fobj)) | ||
|
r31 | src_b = [b.strip() for b in self.re_stop.split(self.src) if b] | ||
self._silent = [bool(self.re_silent.findall(b)) for b in src_b] | ||||
self._auto = [bool(self.re_auto.findall(b)) for b in src_b] | ||||
# if auto_all is not given (def. None), we read it from the file | ||||
if self.auto_all is None: | ||||
self.auto_all = bool(self.re_auto_all.findall(src_b[0])) | ||||
else: | ||||
self.auto_all = bool(self.auto_all) | ||||
# Clean the sources from all markup so it doesn't get displayed when | ||||
# running the demo | ||||
src_blocks = [] | ||||
|
r30 | auto_strip = lambda s: self.re_auto.sub('',s) | ||
|
r31 | for i,b in enumerate(src_b): | ||
|
r30 | if self._auto[i]: | ||
|
r31 | src_blocks.append(auto_strip(b)) | ||
|
r30 | else: | ||
|
r31 | src_blocks.append(b) | ||
# remove the auto_all marker | ||||
src_blocks[0] = self.re_auto_all.sub('',src_blocks[0]) | ||||
self.nblocks = len(src_blocks) | ||||
self.src_blocks = src_blocks | ||||
# also build syntax-highlighted source | ||||
self.src_blocks_colored = map(self.ip_colorize,self.src_blocks) | ||||
|
r30 | # ensure clean namespace and seek offset | ||
|
r22 | self.reset() | ||
def reset(self): | ||||
|
r23 | """Reset the namespace and seek pointer to restart the demo""" | ||
|
r31 | self.user_ns = {} | ||
self.finished = False | ||||
|
r22 | self.block_index = 0 | ||
def _validate_index(self,index): | ||||
if index<0 or index>=self.nblocks: | ||||
raise ValueError('invalid block index %s' % index) | ||||
|
r178 | def _get_index(self,index): | ||
"""Get the current block index, validating and checking status. | ||||
Returns None if the demo is finished""" | ||||
|
r4872 | |||
|
r178 | if index is None: | ||
if self.finished: | ||||
|
r7817 | print('Demo finished. Use <demo_name>.reset() if you want to rerun it.', file=io.stdout) | ||
|
r178 | return None | ||
index = self.block_index | ||||
else: | ||||
self._validate_index(index) | ||||
return index | ||||
|
r22 | def seek(self,index): | ||
|
r523 | """Move the current seek pointer to the given block. | ||
You can use negative indices to seek from the end, with identical | ||||
semantics to those of Python lists.""" | ||||
if index<0: | ||||
index = self.nblocks + index | ||||
|
r22 | self._validate_index(index) | ||
|
r30 | self.block_index = index | ||
|
r22 | self.finished = False | ||
|
r31 | def back(self,num=1): | ||
"""Move the seek pointer back num blocks (default is 1).""" | ||||
self.seek(self.block_index-num) | ||||
|
r523 | def jump(self,num=1): | ||
"""Jump a given number of blocks relative to the current one. | ||||
The offset can be positive or negative, defaults to 1.""" | ||||
|
r31 | self.seek(self.block_index+num) | ||
def again(self): | ||||
"""Move the seek pointer back one block and re-execute.""" | ||||
self.back(1) | ||||
self() | ||||
|
r178 | def edit(self,index=None): | ||
"""Edit a block. | ||||
If no number is given, use the last block executed. | ||||
This edits the in-memory copy of the demo, it does NOT modify the | ||||
original source file. If you want to do that, simply open the file in | ||||
an editor and use reload() when you make changes to the file. This | ||||
method is meant to let you change a block during a demonstration for | ||||
explanatory purposes, without damaging your original script.""" | ||||
index = self._get_index(index) | ||||
if index is None: | ||||
return | ||||
# decrease the index by one (unless we're at the very beginning), so | ||||
# that the default demo.edit() call opens up the sblock we've last run | ||||
if index>0: | ||||
index -= 1 | ||||
|
r4872 | |||
|
r178 | filename = self.shell.mktempfile(self.src_blocks[index]) | ||
self.shell.hooks.editor(filename,1) | ||||
new_block = file_read(filename) | ||||
# update the source and colored block | ||||
self.src_blocks[index] = new_block | ||||
self.src_blocks_colored[index] = self.ip_colorize(new_block) | ||||
self.block_index = index | ||||
# call to run with the newly edited index | ||||
self() | ||||
|
r4872 | |||
|
r30 | def show(self,index=None): | ||
|
r23 | """Show a single block on screen""" | ||
|
r178 | |||
index = self._get_index(index) | ||||
|
r22 | if index is None: | ||
|
r178 | return | ||
|
r7817 | print(self.marquee('<%s> block # %s (%s remaining)' % | ||
(self.title,index,self.nblocks-index-1)), file=io.stdout) | ||||
print((self.src_blocks_colored[index]), file=io.stdout) | ||||
|
r147 | sys.stdout.flush() | ||
|
r23 | |||
|
r30 | def show_all(self): | ||
|
r23 | """Show entire demo on screen, block by block""" | ||
|
r1889 | fname = self.title | ||
title = self.title | ||||
|
r23 | nblocks = self.nblocks | ||
|
r30 | silent = self._silent | ||
|
r515 | marquee = self.marquee | ||
|
r23 | for index,block in enumerate(self.src_blocks_colored): | ||
if silent[index]: | ||||
|
r7817 | print(marquee('<%s> SILENT block # %s (%s remaining)' % | ||
(title,index,nblocks-index-1)), file=io.stdout) | ||||
|
r23 | else: | ||
|
r7817 | print(marquee('<%s> block # %s (%s remaining)' % | ||
(title,index,nblocks-index-1)), file=io.stdout) | ||||
print(block, end=' ', file=io.stdout) | ||||
|
r147 | sys.stdout.flush() | ||
|
r178 | |||
|
r3087 | def run_cell(self,source): | ||
|
r178 | """Execute a string with one or more lines of code""" | ||
exec source in self.user_ns | ||||
|
r4872 | |||
|
r22 | def __call__(self,index=None): | ||
"""run a block of the demo. | ||||
If index is given, it should be an integer >=1 and <= nblocks. This | ||||
means that the calling convention is one off from typical Python | ||||
lists. The reason for the inconsistency is that the demo always | ||||
prints 'Block n/N, and N is the total, so it would be very odd to use | ||||
zero-indexing here.""" | ||||
|
r178 | index = self._get_index(index) | ||
|
r22 | if index is None: | ||
|
r178 | return | ||
|
r22 | try: | ||
|
r515 | marquee = self.marquee | ||
|
r22 | next_block = self.src_blocks[index] | ||
self.block_index += 1 | ||||
|
r30 | if self._silent[index]: | ||
|
r7817 | print(marquee('Executing silent block # %s (%s remaining)' % | ||
(index,self.nblocks-index-1)), file=io.stdout) | ||||
|
r23 | else: | ||
|
r517 | self.pre_cmd() | ||
|
r30 | self.show(index) | ||
|
r31 | if self.auto_all or self._auto[index]: | ||
|
r7817 | print(marquee('output:'), file=io.stdout) | ||
|
r26 | else: | ||
|
r7817 | print(marquee('Press <q> to quit, <Enter> to execute...'), end=' ', file=io.stdout) | ||
|
r23 | ans = raw_input().strip() | ||
if ans: | ||||
|
r7817 | print(marquee('Block NOT executed'), file=io.stdout) | ||
|
r23 | return | ||
|
r24 | try: | ||
save_argv = sys.argv | ||||
sys.argv = self.sys_argv | ||||
|
r3087 | self.run_cell(next_block) | ||
|
r515 | self.post_cmd() | ||
|
r24 | finally: | ||
sys.argv = save_argv | ||||
|
r4872 | |||
|
r22 | except: | ||
|
r30 | self.ip_showtb(filename=self.fname) | ||
|
r22 | else: | ||
self.ip_ns.update(self.user_ns) | ||||
if self.block_index == self.nblocks: | ||||
|
r523 | mq1 = self.marquee('END OF DEMO') | ||
if mq1: | ||||
|
r3800 | # avoid spurious print >>io.stdout,s if empty marquees are used | ||
|
r7817 | print(file=io.stdout) | ||
print(mq1, file=io.stdout) | ||||
print(self.marquee('Use <demo_name>.reset() if you want to rerun it.'), file=io.stdout) | ||||
|
r22 | self.finished = True | ||
|
r30 | |||
|
r515 | # These methods are meant to be overridden by subclasses who may wish to | ||
# customize the behavior of of their demos. | ||||
def marquee(self,txt='',width=78,mark='*'): | ||||
"""Return the input string centered in a 'marquee'.""" | ||||
return marquee(txt,width,mark) | ||||
def pre_cmd(self): | ||||
"""Method called before executing each block.""" | ||||
pass | ||||
def post_cmd(self): | ||||
"""Method called after executing each block.""" | ||||
pass | ||||
|
r178 | class IPythonDemo(Demo): | ||
"""Class for interactive demos with IPython's input processing applied. | ||||
This subclasses Demo, but instead of executing each block by the Python | ||||
interpreter (via exec), it actually calls IPython on it, so that any input | ||||
filters which may be in place are applied to the input block. | ||||
If you have an interactive environment which exposes special input | ||||
processing, you can use this class instead to write demo scripts which | ||||
operate exactly as if you had typed them interactively. The default Demo | ||||
class requires the input to be valid, pure Python code. | ||||
""" | ||||
|
r3087 | def run_cell(self,source): | ||
|
r178 | """Execute a string with one or more lines of code""" | ||
|
r3087 | self.shell.run_cell(source) | ||
|
r4872 | |||
|
r178 | class LineDemo(Demo): | ||
"""Demo where each line is executed as a separate block. | ||||
The input script should be valid Python code. | ||||
This class doesn't require any markup at all, and it's meant for simple | ||||
scripts (with no nesting or any kind of indentation) which consist of | ||||
multiple lines of input to be executed, one at a time, as if they had been | ||||
|
r2587 | typed in the interactive prompt. | ||
Note: the input can not have *any* indentation, which means that only | ||||
single-lines of input are accepted, not even function definitions are | ||||
valid.""" | ||||
|
r4872 | |||
|
r178 | def reload(self): | ||
"""Reload source from disk and initialize state.""" | ||||
# read data and parse into blocks | ||||
|
r2587 | self.fload() | ||
lines = self.fobj.readlines() | ||||
src_b = [l for l in lines if l.strip()] | ||||
|
r178 | nblocks = len(src_b) | ||
|
r2587 | self.src = ''.join(lines) | ||
|
r178 | self._silent = [False]*nblocks | ||
self._auto = [True]*nblocks | ||||
self.auto_all = True | ||||
self.nblocks = nblocks | ||||
self.src_blocks = src_b | ||||
# also build syntax-highlighted source | ||||
self.src_blocks_colored = map(self.ip_colorize,self.src_blocks) | ||||
# ensure clean namespace and seek offset | ||||
self.reset() | ||||
|
r523 | |||
|
r178 | class IPythonLineDemo(IPythonDemo,LineDemo): | ||
"""Variant of the LineDemo class whose input is processed by IPython.""" | ||||
pass | ||||
|
r523 | |||
class ClearMixin(object): | ||||
"""Use this mixin to make Demo classes with less visual clutter. | ||||
|
r4872 | |||
|
r523 | Demos using this mixin will clear the screen before every block and use | ||
blank marquees. | ||||
|
r4872 | |||
|
r523 | Note that in order for the methods defined here to actually override those | ||
of the classes it's mixed with, it must go /first/ in the inheritance | ||||
tree. For example: | ||||
|
r4872 | |||
|
r523 | class ClearIPDemo(ClearMixin,IPythonDemo): pass | ||
|
r4872 | |||
|
r523 | will provide an IPythonDemo class with the mixin's features. | ||
""" | ||||
|
r4872 | |||
|
r523 | def marquee(self,txt='',width=78,mark='*'): | ||
"""Blank marquee that returns '' no matter what the input.""" | ||||
return '' | ||||
|
r4872 | |||
|
r523 | def pre_cmd(self): | ||
"""Method called before executing each block. | ||||
|
r4872 | |||
|
r523 | This one simply clears the screen.""" | ||
|
r2498 | from IPython.utils.terminal import term_clear | ||
|
r2125 | term_clear() | ||
|
r523 | |||
class ClearDemo(ClearMixin,Demo): | ||||
pass | ||||
class ClearIPDemo(ClearMixin,IPythonDemo): | ||||
pass | ||||