#-------------------------------------------------------------------------------
#
# Copyright (c) 2007, Enthought, Inc.
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in enthought/LICENSE.txt and may be redistributed only
# under the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!
#
# Author: David C. Morrill
# Date: 03/30/2007
#
# fixme:
# - Get custom tree view images.
# - Write a program to create a directory structure from a lesson plan file.
#
#-------------------------------------------------------------------------------
""" A framework for creating interactive Python tutorials.
"""
#-------------------------------------------------------------------------------
# Imports:
#-------------------------------------------------------------------------------
import sys
import os
import re
from string \
import capwords
from traits.api \
import HasPrivateTraits, HasTraits, File, Directory, Instance, Int, Str, \
List, Bool, Dict, Any, Property, Delegate, Button, cached_property
from traitsui.api \
import View, VGroup, HGroup, VSplit, HSplit, Tabbed, Item, Heading, \
Handler, ListEditor, CodeEditor, EnumEditor, HTMLEditor, \
TreeEditor, TitleEditor, ValueEditor, ShellEditor
from traitsui.menu \
import NoButtons
from traitsui.tree_node \
import TreeNode
from pyface.image_resource \
import ImageResource
try:
from traitsui.wx.extra.windows.ie_html_editor \
import IEHTMLEditor
from traitsui.wx.extra.windows.flash_editor \
import FlashEditor
except:
IEHTMLEditor = FlashEditor = None
#-------------------------------------------------------------------------------
# Constants:
#-------------------------------------------------------------------------------
# Correct program usage information:
Usage = """
Correct usage is: tutor.py [root_dir]
where:
root_dir = Path to root of the tutorial tree
If omitted, 'root_dir' defaults to the current directory."""
# The standard list editor used:
list_editor = ListEditor(
use_notebook = True,
deletable = False,
page_name = '.title',
export = 'DockWindowShell',
dock_style = 'fixed'
)
# The standard code snippet editor used:
snippet_editor = ListEditor(
use_notebook = True,
deletable = False,
page_name = '.title',
export = 'DockWindowShell',
dock_style = 'tab',
selected = 'snippet'
)
# Regular expressions used to match section directories:
dir_pat1 = re.compile( r'^(\d\d\d\d)_(.*)$' )
dir_pat2 = re.compile( r'^(.*)_(\d+\.\d+)$' )
# Regular expression used to match section header in a Python source file:
section_pat1 = re.compile( r'^#-*\[(.*)\]' ) # Normal
section_pat2 = re.compile( r'^#-*<(.*)>' ) # Hidden
section_pat3 = re.compile( r'^#-*\((.*)\)' ) # Description
# Regular expression used to extract item titles from URLs:
url_pat1 = re.compile( r'^(.*)\[(.*)\](.*)$' ) # Normal
# Is this running on the Windows platform?
is_windows = (sys.platform in ( 'win32', 'win64' ))
# Python file section types:
IsCode = 0
IsHiddenCode = 1
IsDescription = 2
# HTML template for a default lecture:
DefaultLecture = """<html>
<head>
</head>
<body>
<p>This section contains the following topics:</p>
<ul>
%s
</ul>
</body>
</html>
"""
# HTML template for displaying a .wmv/.avi movie file:
WMVMovieTemplate = """<html>
<head>
</head>
<body>
<p><object classid="clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95" codebase="http://activex.microsoft.com/activex/controls/mplayer/en/nsmp2inf.cab#Version=6,4,5,715">
<param name="FileName" value="%s">
<param name="AutoStart" value="true">
<param name="ShowTracker" value="true">
<param name="ShowControls" value="true">
<param name="ShowGotoBar" value="false">
<param name="ShowDisplay" value="false">
<param name="ShowStatusBar" value="false">
<param name="AutoSize" value="true">
<embed src="%s" AutoStart="true" ShowTracker="true" ShowControls="true" ShowGotoBar="false" ShowDisplay="false" ShowStatusBar="false" AutoSize="true" pluginspage="http://www.microsoft.com/windows/windowsmedia/download/"></object></p>
</body>
</html>
"""
# HTML template for displaying a QuickTime.mov movie file:
QTMovieTemplate = """<html>
<head>
</head>
<body>
<p><object classid="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B" codebase="http://www.apple.com/qtactivex/qtplugin.cab" width="100%%" height="100%%">
<param name="src" value="file:///%s">
<param name="scale" value="aspect">
<param name="autoplay" value="true">
<param name="loop" value="false">
<param name="controller" value="true">
<embed src="file:///%s" width="100%%" height="100%%" scale="aspect" autoplay="true" loop="false" controller="true" pluginspage="http://www.apple.com/quicktime/download"></object></p>
</body>
</html>
"""
# HTML template for displaying an image file:
ImageTemplate = """<html>
<head>
</head>
<body>
<img src="%s">
</body>
</html>
"""
# HTML template for playing an MP3 audio file:
MP3Template = """<html>
<head>
<bgsound src="%s">
</head>
<body>
<p> </p>
</body>
</html>
"""
#-------------------------------------------------------------------------------
# Returns the contents of a specified text file (or None):
#-------------------------------------------------------------------------------
def read_file ( path, mode = 'rb' ):
""" Returns the contents of a specified text file (or None).
"""
fh = result = None
try:
fh = file( path, mode )
result = fh.read()
except:
pass
if fh is not None:
try:
fh.close()
except:
pass
return result
#-------------------------------------------------------------------------------
# Creates a title from a specified string:
#-------------------------------------------------------------------------------
def title_for ( title ):
""" Creates a title from a specified string.
"""
return capwords( title.replace( '_', ' ' ) )
#-------------------------------------------------------------------------------
# Returns a relative CSS style sheet path for a specified path and parent
# section:
#-------------------------------------------------------------------------------
def css_path_for ( path, parent ):
""" Returns a relative CSS style sheet path for a specified path and parent
section.
"""
if os.path.isfile( os.path.join( path, 'default.css' ) ):
return 'default.css'
if parent is not None:
result = parent.css_path
if result != '':
if path != parent.path:
result = os.path.join( '..', result )
return result
return ''
#-------------------------------------------------------------------------------
# 'StdOut' class:
#-------------------------------------------------------------------------------
class StdOut ( object ):
""" Simulate stdout, but redirect the output to the 'output' string
supplied by some 'owner' object.
"""
def __init__ ( self, owner ):
self.owner = owner
def write ( self, data ):
""" Adds the specified data to the output log.
"""
self.owner.output += data
def flush ( self ):
""" Flushes all current data to the output log.
"""
pass
#-------------------------------------------------------------------------------
# 'NoDemo' class:
#-------------------------------------------------------------------------------
class NoDemo ( HasPrivateTraits ):
#-- Traits View Definitions ------------------------------------------------
view = View(
Heading( 'No demo defined for this lab.' ),
resizable = True
)
#-------------------------------------------------------------------------------
# 'DemoPane' class:
#-------------------------------------------------------------------------------
class DemoPane ( HasPrivateTraits ):
""" Displays the contents of a Python lab's *demo* value.
"""
#-- Trait Definitions ------------------------------------------------------
demo = Instance( HasTraits, factory = NoDemo )
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'demo',
id = 'demo',
show_label = False,
style = 'custom',
resizable = True
),
id = 'enthought.tutor.demo',
resizable = True
)
#-------------------------------------------------------------------------------
# 'ATutorialItem' class:
#-------------------------------------------------------------------------------
class ATutorialItem ( HasPrivateTraits ):
""" Defines the abstract base class for each type of item (HTML, Flash,
text, code) displayed within the tutor.
"""
#-- Traits Definitions -----------------------------------------------------
# The title for the item:
title = Str
# The path to the item:
path = File
# The displayable content for the item:
content = Property
#-------------------------------------------------------------------------------
# 'ADescriptionItem' class:
#-------------------------------------------------------------------------------
class ADescriptionItem ( ATutorialItem ):
""" Defines a common base class for all description items.
"""
#-- Event Handlers ---------------------------------------------------------
def _path_changed ( self, path ):
""" Sets the title for the item based on the item's path name.
"""
self.title = title_for( os.path.splitext( os.path.basename(
path ) )[0] )
#-------------------------------------------------------------------------------
# 'HTMLItem' class:
#-------------------------------------------------------------------------------
class HTMLItem ( ADescriptionItem ):
""" Defines a class used for displaying a single HTML page within the tutor
using the default Traits HTML editor.
"""
#-- Traits Definitions -----------------------------------------------------
url = Str
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'content',
style = 'readonly',
show_label = False,
editor = HTMLEditor()
)
)
#-- Event Handlers ---------------------------------------------------------
def _url_changed ( self, url ):
""" Sets the item title when the 'url' is changed.
"""
match = url_pat1.match( url )
if match is not None:
title = match.group(2).strip()
else:
title = url.strip()
col = title.rfind( '/' )
if col >= 0:
title = os.path.splitext( title[ col + 1: ] )[0]
self.title = title
#-- Property Implementations -----------------------------------------------
@cached_property
def _get_content ( self ):
""" Returns the item content.
"""
url = self.url
if url != '':
match = url_pat1.match( url )
if match is not None:
url = match.group(1) + match.group(3)
return url
return read_file( self.path )
def _set_content ( self, content ):
""" Sets the item content.
"""
self._content = content
#-------------------------------------------------------------------------------
# 'HTMLStrItem' class:
#-------------------------------------------------------------------------------
class HTMLStrItem ( HTMLItem ):
""" Defines a class used for displaying a single HTML text string within
the tutor using the default Traits HTML editor.
"""
# Make the content a real trait rather than a property:
content = Str
#-------------------------------------------------------------------------------
# 'IEHTMLItem' class:
#-------------------------------------------------------------------------------
class IEHTMLItem ( HTMLItem ):
""" Defines a class used for displaying a single HTML page within the tutor
using the Traits Internet Explorer HTML editor.
"""
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'content',
style = 'readonly',
show_label = False,
editor = IEHTMLEditor()
)
)
#-------------------------------------------------------------------------------
# 'IEHTMLStrItem' class:
#-------------------------------------------------------------------------------
class IEHTMLStrItem ( IEHTMLItem ):
""" Defines a class used for displaying a single HTML text string within
the tutor using the Traits Internet Explorer HTML editor.
"""
# Make the content a real trait rather than a property:
content = Str
#-------------------------------------------------------------------------------
# 'FlashItem' class:
#-------------------------------------------------------------------------------
class FlashItem ( HTMLItem ):
""" Defines a class used for displaying a Flash-based animation or video
within the tutor.
"""
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'content',
style = 'readonly',
show_label = False,
editor = FlashEditor()
)
)
#-------------------------------------------------------------------------------
# 'TextItem' class:
#-------------------------------------------------------------------------------
class TextItem ( ADescriptionItem ):
""" Defines a class used for displaying a text file within the tutor.
"""
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'content',
style = 'readonly',
show_label = False,
editor = CodeEditor( show_line_numbers = False,
selected_color = 0xFFFFFF )
)
)
#-- Property Implementations -----------------------------------------------
@cached_property
def _get_content ( self ):
""" Returns the item content.
"""
return read_file( self.path )
#-------------------------------------------------------------------------------
# 'TextStrItem' class:
#-------------------------------------------------------------------------------
class TextStrItem ( TextItem ):
""" Defines a class used for displaying a text file within the tutor.
"""
# Make the content a real trait, rather than a property:
content = Str
#-------------------------------------------------------------------------------
# 'CodeItem' class:
#-------------------------------------------------------------------------------
class CodeItem ( ATutorialItem ):
""" Defines a class used for displaying a Python source code fragment
within the tutor.
"""
#-- Trait Definitions ------------------------------------------------------
# The displayable content for the item (override):
content = Str
# The starting line of the code snippet within the original file:
start_line = Int
# The currently selected line:
selected_line = Int
# Should this section normally be hidden?
hidden = Bool
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'content',
style = 'custom',
show_label = False,
editor = CodeEditor( selected_line = 'selected_line' )
)
)
#-------------------------------------------------------------------------------
# 'ASection' abstract base class:
#-------------------------------------------------------------------------------
class ASection ( HasPrivateTraits ):
""" Defines an abstract base class for a single section of a tutorial.
"""
#-- Traits Definitions -----------------------------------------------------
# The title of the section:
title = Str
# The path to this section:
path = Directory
# The parent section of this section (if any):
parent = Instance( 'ASection' )
# Optional table of contents (can be used to define/locate the subsections):
toc = List( Str )
# The path to the CSS style sheet to use for this section:
css_path = Property
# The list of subsections contained in this section:
subsections = Property # List( ASection )
# This section can be executed:
is_runnable = Bool( True )
# Should the Python code be automatically executed on start-up?
auto_run = Bool( False )
#-- Property Implementations -----------------------------------------------
@cached_property
def _get_subsections ( self ):
""" Returns the subsections for this section:
"""
if len( self.toc ) > 0:
self._load_toc()
else:
self._load_dirs()
# Return the cached list of sections:
return self._subsections
@cached_property
def _get_css_path ( self ):
""" Returns the path to the CSS style sheet for this section.
"""
return css_path_for( self.path, self.parent )
#-- Private Methods --------------------------------------------------------
def _load_dirs ( self ):
""" Defines the section's subsections by analyzing all of the section's
sub-directories.
"""
# No value cached yet:
dirs = []
path = self.path
# Find every sub-directory whose name begins with a number of the
# form ddd, or ends with a number of the form _ddd.ddd (used for
# sorting them into the correct presentation order):
for name in os.listdir( path ):
dir = os.path.join( path, name )
if os.path.isdir( dir ):
match = dir_pat1.match( name )
if match is not None:
dirs.append( ( float( match.group(1) ),
match.group(2), dir ) )
else:
match = dir_pat2.match( name )
if match is not None:
dirs.append( ( float( match.group(2) ),
match.group(1), dir ) )
# Sort the directories by their index value:
dirs.sort( lambda l, r: cmp( l[0], r[0] ) )
# Create the appropriate type of section for each valid directory:
self._subsections = [
sf.section for sf in [
SectionFactory( title = title_for( title ),
parent = self ).set(
path = dir )
for index, title, dir in dirs
] if sf.section is not None
]
def _load_toc ( self ):
""" Defines the section's subsections by finding matches for the items
defined in the section's table of contents.
"""
toc = self.toc
base_names = [ item.split( ':', 1 )[0] for item in toc ]
subsections = [ None ] * len( base_names )
path = self.path
# Classify all file names that match a base name in the table of
# contents:
for name in os.listdir( path ):
try:
base_name = os.path.splitext( os.path.basename( name ) )[0]
index = base_names.index( base_name )
if subsections[ index ] is None:
subsections[ index ] = []
subsections[ index ].append( name )
except:
pass
# Try to convert each group of names into a section:
for i, names in enumerate( subsections ):
# Only process items for which we found at least one matching file
# name:
if names is not None:
# Get the title for the section from its table of contents
# entry:
parts = toc[i].split( ':', 1 )
if len( parts ) == 1:
title = title_for( parts[0].strip() )
else:
title = parts[1].strip()
# Handle an item with one file which is a directory as a normal
# section:
if len( names ) == 1:
dir = os.path.join( path, names[0] )
if os.path.isdir( dir ):
subsections[i] = SectionFactory( title = title,
parent = self ).set(
path = dir ).section
continue
# Otherwise, create a section from the list of matching files:
subsections[i] = SectionFactory( title = title,
parent = self,
files = names ).set(
path = path ).section
# Set the subsections to the non-None values that are left:
self._subsections = [ subsection for subsection in subsections
if subsection is not None ]
#-------------------------------------------------------------------------------
# 'Lecture' class:
#-------------------------------------------------------------------------------
class Lecture ( ASection ):
""" Defines a lecture, which is a section of a tutorial with descriptive
information, but no associated Python code. Can be used to provide
course overviews, introductory sections, or lead-ins to follow-on
lessons or labs.
"""
#-- Trait Definitions-------------------------------------------------------
# The list of descriptive items for the lecture:
descriptions = List( ATutorialItem )
# This section can be executed (override):
is_runnable = False
#-- Traits View Definitions ------------------------------------------------
view = View(
Item( 'descriptions',
style = 'custom',
show_label = False,
editor = list_editor
),
id = 'enthought.tutor.lecture'
)
#-------------------------------------------------------------------------------
# 'LabHandler' class:
#-------------------------------------------------------------------------------
class LabHandler ( Handler ):
""" Defines the controller functions for the Lab view.
"""
def init ( self, info ):
""" Handles initialization of the view.
"""
# Run the associated Python code if the 'auto-run' feature is enabled:
if info.object.auto_run:
info.object.run_code()
#-------------------------------------------------------------------------------
# 'Lab' class:
#-------------------------------------------------------------------------------
class Lab ( ASection ):
""" Defines a lab, which is a section of a tutorial with only Python code.
This type of section might typically follow a lecture which introduced
the code being worked on in the lab.
"""
#-- Trait Definitions-------------------------------------------------------
# The set-up code (if any) for the lab:
setup = Instance( CodeItem )
# The list of code items for the lab:
snippets = List( CodeItem )
# The list of visible code items for the lab:
visible_snippets = Property( depends_on = 'visible', cached = True )
# The currently selected snippet:
snippet = Instance( CodeItem )
# Should normally hidden code items be shown?
visible = Bool( False )
# The dictionary containing the items from the Python code execution:
values = Dict #Any( {} )
# The run Python code button:
run = Button( image = ImageResource( 'run' ), height_padding = 1 )
# User error message:
message = Str
# The output produced while the program is running:
output = Str
# The current demo pane (if any):
demo = Instance( DemoPane, () )
#-- Traits View Definitions ------------------------------------------------
view = View(
VSplit(
VGroup(
Item( 'visible_snippets',
style = 'custom',
show_label = False,
editor = snippet_editor
),
HGroup(
Item( 'run',
style = 'custom',
show_label = False,
tooltip = 'Run the Python code'
),
'_',
Item( 'message',
springy = True,
show_label = False,
editor = TitleEditor()
),
'_',
Item( 'visible',
label = 'View hidden sections'
)
),
),
Tabbed(
Item( 'values',
id = 'values_1',
label = 'Shell',
editor = ShellEditor( share = True ),
dock = 'tab',
export = 'DockWindowShell'
),
Item( 'values',
id = 'values_2',
editor = ValueEditor(),
dock = 'tab',
export = 'DockWindowShell'
),
Item( 'output',
style = 'readonly',
editor = CodeEditor( show_line_numbers = False,
selected_color = 0xFFFFFF ),
dock = 'tab',
export = 'DockWindowShell'
),
Item( 'demo',
id = 'demo',
style = 'custom',
resizable = True,
dock = 'tab',
export = 'DockWindowShell'
),
show_labels = False,
),
id = 'splitter',
),
id = 'enthought.tutor.lab',
handler = LabHandler
)
#-- Event Handlers ---------------------------------------------------------
def _run_changed ( self ):
""" Runs the current set of snippet code.
"""
self.run_code()
#-- Property Implementations -----------------------------------------------
@cached_property
def _get_visible_snippets ( self ):
""" Returns the list of code items that are currently visible.
"""
if self.visible:
return self.snippets
return [ snippet for snippet in self.snippets if (not snippet.hidden) ]
#-- Public Methods ---------------------------------------------------------
def run_code ( self ):
""" Runs all of the code snippets associated with the section.
"""
# Reconstruct the lab code from the current set of code snippets:
start_line = 1
module = ''
for snippet in self.snippets:
snippet.start_line = start_line
module = '%s\n\n%s' % ( module, snippet.content )
start_line += (snippet.content.count( '\n' ) + 2)
# Reset any syntax error and message log values:
self.message = self.output = ''
# Redirect standard out and error to the message log:
stdout, stderr = sys.stdout, sys.stderr
sys.stdout = sys.stderr = StdOut( self )
try:
try:
# Get the execution context dictionary:
values = self.values
# Clear out any special variables defined by the last run:
for name in ( 'demo', 'popup' ):
if isinstance( values.get( name ), HasTraits ):
del values[ name ]
# Execute the current lab code:
exec module[2:] in values, values
# fixme: Hack trying to update the Traits UI view of the dict.
self.values = {}
self.values = values
# Handle a 'demo' value being defined:
demo = values.get( 'demo' )
if not isinstance( demo, HasTraits ):
demo = NoDemo()
self.demo.demo = demo
# Handle a 'popup' value being defined:
popup = values.get( 'popup' )
if isinstance( popup, HasTraits ):
popup.edit_traits( kind = 'livemodal' )
except SyntaxError, excp:
# Convert the line number of the syntax error from one in the
# composite module to one in the appropriate code snippet:
line = excp.lineno
if line is not None:
snippet = self.snippets[0]
for s in self.snippets:
if s.start_line > line:
break
snippet = s
line -= (snippet.start_line - 1)
# Highlight the line in error:
snippet.selected_line = line
# Select the correct code snippet:
self.snippet = snippet
# Display the syntax error message:
self.message = '%s in column %s of line %s' % (
excp.msg.capitalize(), excp.offset, line )
else:
# Display the syntax error message without line # info:
self.message = excp.msg.capitalize()
except:
import traceback
traceback.print_exc()
finally:
# Restore standard out and error to their original values:
sys.stdout, sys.stderr = stdout, stderr
#-------------------------------------------------------------------------------
# 'Lesson' class:
#-------------------------------------------------------------------------------
class Lesson ( Lab ):
""" Defines a lesson, which is a section of a tutorial with both descriptive
information and associated Python code.
"""
#-- Trait Definitions-------------------------------------------------------
# The list of descriptive items for the lesson:
descriptions = List( ATutorialItem )
#-- Traits View Definitions ------------------------------------------------
view = View(
HSplit(
Item( 'descriptions',
label = 'Lesson',
style = 'custom',
show_label = False,
dock = 'horizontal',
editor = list_editor
),
VSplit(
VGroup(
Item( 'visible_snippets',
style = 'custom',
show_label = False,
editor = snippet_editor
),
HGroup(
Item( 'run',
style = 'custom',
show_label = False,
tooltip = 'Run the Python code'
),
'_',
Item( 'message',
springy = True,
show_label = False,
editor = TitleEditor()
),
'_',
Item( 'visible',
label = 'View hidden sections'
)
),
label = 'Lab',
dock = 'horizontal'
),
Tabbed(
Item( 'values',
id = 'values_1',
label = 'Shell',
editor = ShellEditor( share = True ),
dock = 'tab',
export = 'DockWindowShell'
),
Item( 'values',
id = 'values_2',
editor = ValueEditor(),
dock = 'tab',
export = 'DockWindowShell'
),
Item( 'output',
style = 'readonly',
editor = CodeEditor( show_line_numbers = False,
selected_color = 0xFFFFFF ),
dock = 'tab',
export = 'DockWindowShell'
),
Item( 'demo',
id = 'demo',
style = 'custom',
resizable = True,
dock = 'tab',
export = 'DockWindowShell'
),
show_labels = False,
),
label = 'Lab',
dock = 'horizontal'
),
id = 'splitter',
),
id = 'enthought.tutor.lesson',
handler = LabHandler
)
#-------------------------------------------------------------------------------
# 'Demo' class:
#-------------------------------------------------------------------------------
class Demo ( Lesson ):
""" Defines a demo, which is a section of a tutorial with both descriptive
information and associated Python code which is executed but not
shown.
"""
#-- Traits View Definitions ------------------------------------------------
view = View(
HSplit(
Item( 'descriptions',
label = 'Lesson',
style = 'custom',
show_label = False,
dock = 'horizontal',
editor = list_editor
),
Item( 'demo',
id = 'demo',
style = 'custom',
show_label = False,
resizable = True,
dock = 'horizontal',
export = 'DockWindowShell'
),
id = 'splitter',
),
id = 'enthought.tutor.demo',
handler = LabHandler
)
#-------------------------------------------------------------------------------
# 'SectionFactory' class:
#-------------------------------------------------------------------------------
class SectionFactory ( HasPrivateTraits ):
""" Defines a class that creates Lecture, Lesson or Lab sections (or None),
based on the content of a specified directory. None is returned if the
directory does not contain any recognized files.
"""
#-- Traits Definitions -----------------------------------------------------
# The path the section is to be created for:
path = Directory
# The list of files contained in the section:
files = List( Str )
# The parent of the section being created:
parent = Instance( ASection )
# The section created from the path:
section = Instance( ASection )
# The title for the section:
title = Str
# The optional table of contents for the section:
toc = List( Str )
# The list of descriptive items for the section:
descriptions = List( ADescriptionItem )
# The list of code snippet items for the section:
snippets = List( CodeItem )
# The path to the CSS style sheet for the section:
css_path = Property
# Should the Python code be automatically executed on start-up?
auto_run = Bool( False )
#-- Event Handlers ---------------------------------------------------------
def _path_changed ( self, path ):
""" Creates the appropriate section based on the value of the path.
"""
# Get the list of files to process:
files = self.files
if len( files ) == 0:
# If none were specified, then use all files in the directory:
files = os.listdir( path )
# Process the description file (if any) first:
for name in files:
if os.path.splitext( name )[1] == '.desc':
self._add_desc_item( os.path.join( path, name ) )
break
# Try to convert each file into one or more 'xxxItem' objects:
toc = [ item.split( ':', 1 )[0].strip() for item in self.toc ]
for name in files:
file_name = os.path.join( path, name )
# Only process the ones that are actual files:
if os.path.isfile( file_name ):
# Use the file extension to determine the file's type:
root, ext = os.path.splitext( name )
if (root not in toc) and (len( ext ) > 1):
# If we have a handler for the file type, invoke it:
method = getattr( self, '_add_%s_item' % ext[1:].lower(),
None )
if method is not None:
method( file_name )
# Based on the type of items created (if any), create the corresponding
# type of section:
if len( self.descriptions ) > 0:
if len( self.snippets ) > 0:
if len( [ snippet for snippet in self.snippets
if (not snippet.hidden) ] ) > 0:
self.section = Lesson(
title = self.title,
path = path,
toc = self.toc,
parent = self.parent,
descriptions = self.descriptions,
snippets = self.snippets,
auto_run = self.auto_run
)
else:
self.section = Demo(
title = self.title,
path = path,
toc = self.toc,
parent = self.parent,
descriptions = self.descriptions,
snippets = self.snippets,
auto_run = True
)
else:
self.section = Lecture(
title = self.title,
path = path,
toc = self.toc,
parent = self.parent,
descriptions = self.descriptions
)
elif len( self.snippets ) > 0:
self.section = Lab(
title = self.title,
path = path,
toc = self.toc,
parent = self.parent,
snippets = self.snippets,
auto_run = self.auto_run
)
else:
# No descriptions or code snippets were found. Create a lecture
# anyway:
section = Lecture(
title = self.title,
path = path,
toc = self.toc,
parent = self.parent
)
# If the lecture has subsections, then return the lecture and add
# a default item containing a description of the subsections of the
# lecture:
if len( section.subsections ) > 0:
self._create_html_item( path = path, content =
DefaultLecture % ( '\n'.join(
[ '<li>%s</li>' % subsection.title
for subsection in section.subsections ] ) ) )
section.descriptions = self.descriptions
self.section = section
#-- Property Implementations -----------------------------------------------
def _get_css_path ( self ):
""" Returns the path to the CSS style sheet for the section.
"""
return css_path_for( self.path, self.parent )
#-- Factory Methods for Creating Section Items Based on File Type ----------
def _add_py_item ( self, path ):
""" Creates the code snippets for a Python source file.
"""
source = read_file( path )
if source is not None:
lines = source.replace( '\r', '' ).split( '\n' )
start_line = 0
title = 'Prologue'
type = IsCode
for i, line in enumerate( lines ):
match = section_pat1.match( line )
if match is not None:
next_type = IsCode
else:
match = section_pat2.match( line )
if match is not None:
next_type = IsHiddenCode
else:
next_type = IsDescription
match = section_pat3.match( line )
if match is not None:
self._add_snippet( title, path, lines, start_line, i - 1,
type )
start_line = i + 1
title = match.group(1).strip()
type = next_type
self._add_snippet( title, path, lines, start_line, i, type )
def _add_txt_item ( self, path ):
""" Creates a description item for a normal text file.
"""
self.descriptions.append( TextItem( path = path ) )
def _add_htm_item ( self, path ):
""" Creates a description item for an HTML file.
"""
# Check if there is a corresponding .rst (restructured text) file:
dir, base_name = os.path.split( path )
rst = os.path.join( dir, os.path.splitext( base_name )[0] + '.rst' )
# If no .rst file exists, just add the file as a normal HTML file:
if not os.path.isfile( rst ):
self._create_html_item( path = path )
def _add_html_item ( self, path ):
""" Creates a description item for an HTML file.
"""
self._add_htm_item( path )
def _add_url_item ( self, path ):
""" Creates a description item for a file containing URLs.
"""
data = read_file( path )
if data is not None:
for url in [ line for line in data.split( '\n' )
if line.strip()[:1] not in ( '', '#' ) ]:
self._create_html_item( url = url.strip() )
def _add_rst_item ( self, path ):
""" Creates a description item for a ReSTructured text file.
"""
# If docutils is not installed, just process the file as an ordinary
# text file:
try:
from docutils.core import publish_cmdline
except:
self._add_txt_item( path )
return
# Get the name of the HTML file we will write to:
dir, base_name = os.path.split( path )
html = os.path.join( dir, os.path.splitext( base_name )[0] + '.htm' )
# Try to find a CSS style sheet, and set up the docutil overrides if
# found:
settings = {}
css_path = self.css_path
if css_path != '':
css_path = os.path.join( self.path, css_path )
settings[ 'stylesheet_path' ] = css_path
settings[ 'embed_stylesheet' ] = True
settings[ 'stylesheet' ] = None
else:
css_path = path
# If the HTML file does not exist, or is older than the restructured
# text file, then let docutils convert it to HTML:
is_file = os.path.isfile( html )
if ((not is_file) or
(os.path.getmtime( path ) > os.path.getmtime( html )) or
(os.path.getmtime( css_path ) > os.path.getmtime( html ))):
# Delete the current HTML file (if any):
if is_file:
os.remove( html )
# Let docutils create a new HTML file from the restructured text
# file:
publish_cmdline( writer_name = 'html',
argv = [ path, html ],
settings_overrides = settings )
if os.path.isfile( html ):
# If there is now a valid HTML file, use it:
self._create_html_item( path = html )
else:
# Otherwise, just use the original restructured text file:
self._add_txt_item( path )
def _add_swf_item ( self, path ):
""" Creates a description item for a Flash file.
"""
if is_windows:
self.descriptions.append( FlashItem( path = path ) )
def _add_mov_item ( self, path ):
""" Creates a description item for a QuickTime movie file.
"""
path2 = path.replace( ':', '|' )
self._create_html_item( path = path,
content = QTMovieTemplate % ( path2, path2 ) )
def _add_wmv_item ( self, path ):
""" Creates a description item for a Windows movie file.
"""
self._create_html_item( path = path,
content = WMVMovieTemplate % ( path, path ) )
def _add_avi_item ( self, path ):
""" Creates a description item for an AVI movie file.
"""
self._add_wmv_item( path )
def _add_jpg_item ( self, path ):
""" Creates a description item for a JPEG image file.
"""
self._create_html_item( path = path,
content = ImageTemplate % path )
def _add_jpeg_item ( self, path ):
""" Creates a description item for a JPEG image file.
"""
self._add_jpg_item( path )
def _add_png_item ( self, path ):
""" Creates a description item for a PNG image file.
"""
self._add_jpg_item( path )
def _add_mp3_item ( self, path ):
""" Creates a description item for an mp3 audio file.
"""
self._create_html_item( path = path,
content = MP3Template % path )
def _add_desc_item ( self, path ):
""" Creates a section title from a description file.
"""
# If we've already processed a description file, then we're done:
if len( self.toc ) > 0:
return
lines = []
desc = read_file( path )
if desc is not None:
# Split the file into lines and save the non-empty, non-comment
# lines:
for line in desc.split( '\n' ):
line = line.strip()
if (len( line ) > 0) and (line[0] != '#'):
lines.append( line )
if len( lines ) == 0:
# If the file didn't have anything useful in it, set a title based
# on the description file name:
self.title = title_for(
os.path.splitext( os.path.basename( path ) )[0] )
else:
# Otherwise, set the title and table of contents from the lines in
# the file:
self.title = lines[0]
self.toc = lines[1:]
#-- Private Methods --------------------------------------------------------
def _add_snippet ( self, title, path, lines, start_line, end_line, type ):
""" Adds a new code snippet or restructured text item to the list of
code snippet or description items.
"""
# Trim leading and trailing blank lines from the snippet:
while start_line <= end_line:
if lines[ start_line ].strip() != '':
break
start_line += 1
while end_line >= start_line:
if lines[ end_line ].strip() != '':
break
end_line -= 1
# Only add if the snippet is not empty:
if start_line <= end_line:
# Check for the title containing the 'auto-run' flag ('*'):
if title[:1] == '*':
self.auto_run = True
title = title[1:].strip()
if title[-1:] == '*':
self.auto_run = True
title = title[:-1].strip()
# Extract out just the lines we will use:
content_lines = lines[ start_line: end_line + 1 ]
if type == IsDescription:
# Add the new restructured text description:
self._add_description( content_lines, title )
else:
# Add the new code snippet:
self.snippets.append( CodeItem(
title = title or 'Code',
path = path,
hidden = (type == IsHiddenCode),
content = '\n'.join( content_lines )
) )
def _add_description ( self, lines, title ):
""" Converts a restructured text string to HTML and adds it as
description item.
"""
# Scan the lines for any imbedded Python code that should be shown as
# a separate snippet:
i = 0
while i < len( lines ):
if lines[i].strip()[-2:] == '::':
i = self._check_embedded_code( lines, i + 1 )
else:
i += 1
# Strip off any docstring style triple quotes (if necessary):
content = '\n'.join( lines ).strip()
if content[:3] in ( '"""', "'''" ):
content = content[3:]
if content[-3:] in ( '"""', "'''" ):
content = content[:-3]
content = content.strip()
# If docutils is not installed, just add it as a text string item:
try:
from docutils.core import publish_string
except:
self.descriptions.append( TextStrItem( content = content,
title = title ) )
return
# Try to find a CSS style sheet, and set up the docutil overrides if
# found:
settings = {}
css_path = self.css_path
if css_path != '':
css_path = os.path.join( self.path, css_path )
settings[ 'stylesheet_path' ] = css_path
settings[ 'embed_stylesheet' ] = True
settings[ 'stylesheet' ] = None
# Convert it from restructured text to HTML:
html = publish_string( content, writer_name = 'html',
settings_overrides = settings )
# Choose the right HTML renderer:
if is_windows:
item = IEHTMLStrItem( content = html, title = title )
else:
item = HTMLStrItem( content = html, title = title )
# Add the resulting item to the descriptions list:
self.descriptions.append( item )
def _create_html_item ( self, **traits ):
""" Creates a platform specific html item and adds it to the list of
descriptions.
"""
if is_windows:
item = IEHTMLItem( **traits )
else:
item = HTMLItem( **traits )
self.descriptions.append( item )
def _check_embedded_code ( self, lines, start ):
""" Checks for an embedded Python code snippet within a description.
"""
n = len( lines )
while start < n:
line = lines[ start ].strip()
if line == '':
start += 1
continue
if (line[:1] != '[') or (line[-1:] != ']'):
break
del lines[ start ]
n -= 1
title = line[1:-1].strip()
line = lines[ start ] + '.'
pad = len( line ) - len( line.strip() )
clines = []
while start < n:
line = lines[ start ] + '.'
len_line = len( line.strip() )
if (len_line > 1) and ((len( line ) - len_line) < pad):
break
if (len( clines ) > 0) or (len_line > 1):
clines.append( line[ pad: -1 ] )
start += 1
# Add the new code snippet:
self.snippets.append( CodeItem(
title = title or 'Code',
content = '\n'.join( clines )
) )
break
return start
#-------------------------------------------------------------------------------
# Tutor tree editor:
#-------------------------------------------------------------------------------
tree_editor = TreeEditor(
nodes = [
TreeNode(
children = 'subsections',
label = 'title',
rename = False,
copy = False,
delete = False,
delete_me = False,
insert = False,
auto_open = True,
auto_close = False,
node_for = [ ASection ],
icon_group = '<group>'
)
],
editable = False,
auto_open = 1,
selected = 'section'
)
#-------------------------------------------------------------------------------
# 'Tutor' class:
#-------------------------------------------------------------------------------
class Tutor ( HasPrivateTraits ):
""" The main tutorial class which manages the presentation and navigation
of the entire tutorial.
"""
#-- Trait Definitions ------------------------------------------------------
# The path to the files distributed with the tutor:
home = Directory
# The path to the root of the tutorial tree:
path = Directory
# The root of the tutorial lesson tree:
root = Instance( ASection )
# The current section of the tutorial being displayed:
section = Instance( ASection )
# The next section:
next_section = Property( depends_on = 'section', cached = True )
# The previous section:
previous_section = Property( depends_on = 'section', cached = True )
# The previous section button:
previous = Button( image = ImageResource( 'previous' ), height_padding = 1 )
# The next section button:
next = Button( image = ImageResource( 'next' ), height_padding = 1 )
# The parent section button:
parent = Button( image = ImageResource( 'parent' ), height_padding = 1 )
# The reload tutor button:
reload = Button( image = ImageResource( 'reload' ), height_padding = 1 )
# The title of the current session:
title = Property( depends_on = 'section' )
#-- Traits View Definitions ------------------------------------------------
view = View(
VGroup(
HGroup(
Item( 'previous',
style = 'custom',
enabled_when = 'previous_section is not None',
tooltip = 'Go to previous section'
),
Item( 'parent',
style = 'custom',
enabled_when = '(section is not None) and '
'(section.parent is not None)',
tooltip = 'Go up one level'
),
Item( 'next',
style = 'custom',
enabled_when = 'next_section is not None',
tooltip = 'Go to next section'
),
'_',
Item( 'title',
springy = True,
editor = TitleEditor()
),
'_',
Item( 'reload',
style = 'custom',
tooltip = 'Reload the tutorial'
),
show_labels = False
),
'_',
HSplit(
Item( 'root',
label = 'Table of Contents',
editor = tree_editor,
dock = 'horizontal',
export = 'DockWindowShell'
),
Item( 'section',
id = 'section',
label = 'Current Lesson',
style = 'custom',
resizable = True,
dock = 'horizontal'
),
id = 'splitter',
show_labels = False
)
),
title = 'Python Tutor',
id = 'dmorrill.tutor.tutor:1.0',
buttons = NoButtons,
resizable = True,
width = 0.8,
height = 0.8
)
#-- Event Handlers ---------------------------------------------------------
def _path_changed ( self, path ):
""" Handles the tutorial root path being changed.
"""
self.init_tutor()
def _next_changed ( self ):
""" Displays the next tutorial section.
"""
self.section = self.next_section
def _previous_changed ( self ):
""" Displays the previous tutorial section.
"""
self.section = self.previous_section
def _parent_changed ( self ):
""" Displays the parent of the current tutorial section.
"""
self.section = self.section.parent
def _reload_changed ( self ):
""" Reloads the tutor from the original path specified.
"""
self.init_tutor()
#-- Property Implementations -----------------------------------------------
@cached_property
def _get_next_section ( self ):
""" Returns the next section of the tutorial.
"""
next = None
section = self.section
if len( section.subsections ) > 0:
next = section.subsections[0]
else:
parent = section.parent
while parent is not None:
index = parent.subsections.index( section )
if index < (len( parent.subsections ) - 1):
next = parent.subsections[ index + 1 ]
break
parent, section = parent.parent, parent
return next
@cached_property
def _get_previous_section ( self ):
""" Returns the previous section of the tutorial.
"""
previous = None
section = self.section
parent = section.parent
if parent is not None:
index = parent.subsections.index( section )
if index > 0:
previous = parent.subsections[ index - 1 ]
while len( previous.subsections ) > 0:
previous = previous.subsections[-1]
else:
previous = parent
return previous
def _get_title ( self ):
""" Returns the title of the current section.
"""
section = self.section
if section is None:
return ''
return ('%s: %s' % ( section.__class__.__name__, section.title ))
#-- Public Methods ---------------------------------------------------------
def init_tutor ( self ):
""" Initials the tutor by creating the root section from the specified
path.
"""
path = self.path
title = title_for( os.path.splitext( os.path.basename( path ) )[0] )
section = SectionFactory( title = title ).set( path = path ).section
if section is not None:
self.section = self.root = section
#-------------------------------------------------------------------------------
# Run the program:
#-------------------------------------------------------------------------------
# Only run the program if we were invoked from the command line:
if __name__ == '__main__':
# Validate the command line arguments:
if len( sys.argv ) > 2:
print Usage
sys.exit( 1 )
# Determine the root path to use for the tutorial files:
if len( sys.argv ) == 2:
path = sys.argv[1]
else:
path = os.getcwd()
# Create a tutor and display the tutorial:
tutor = Tutor( home = os.path.dirname( sys.argv[0] ) ).set(
path = path )
if tutor.root is not None:
tutor.configure_traits()
else:
print """No traits tutorial found in %s.
Correct usage is: python tutor.py [tutorial_path]
where: tutorial_path = Path to the root of the traits tutorial.
If tutorial_path is omitted, the current directory is assumed to be the root of
the tutorial.""" % path
