[Python-checkins] CVS: python/dist/src/Lib onlinehelp.py,NONE,1.1

2000年7月16日 12:53:02 -0700

Update of /cvsroot/python/python/dist/src/Lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv30103
Added Files:
	onlinehelp.py 
Log Message:
Online help facility for the Python interprter and other interactive 
environments.
--- NEW FILE ---
"""
Online help module. 
This module is experimental and could be removed or radically changed
at any time.
It is intended specifically for the standard interpreter command 
line but is intended to be compatible with and useful for other
(e.g. GUI, handheld) environments. Help with those other environments is
appreciated.
Please remember to set PYTHONDOCS to the location of your HTML files:
e.g. 
set PYTHONDOCS=c:\python\docs
PYTHONDOCS=/python/docs
The docs directory should have a lib subdirectory with "index.html" in it.
If it has *.tex then you have the documentation *source* distribution, not
the runtime distribution.
The module exposes one object: "help". "help" has a repr that does something
useful if you just type:
>>> from onlinehelp import help
>>> help

Of course one day the first line will be done automatically by site.py or
something like that. help can be used as a function.
The function takes the following forms of input:
help( "string" ) -- built-in topic or global
help( <ob> ) -- docstring from object or type
help( "doc:filename" ) -- filename from Python documentation
Type help to get the rest of the instructions.
"""
import htmllib # todo: add really basic tr/td support
import formatter
import os, sys
import re
prompt="--more-- (enter for more, q to quit) "
topics={} # all built-in (non-HTML, non-docstring) topics go in here
commands="" # only used at the top level
def topLevelCommand( name, description, text ):
 """ this function is just for use at the top-level to make sure that
 every advertised top-level topic has a description and every 
 description has text. Maybe we can generalize it later."""
 global commands
 topics[name]=text
 if description[0]=="[":
 placeholder="(dummy)"
 elif description[0]=="<":
 placeholder="link"
 else:
 placeholder=""
 commands=commands+'help( "%s" ) %s - %s\n' % \
 (name, placeholder, description )
topLevelCommand( 
"intro", 
"What is Python? Read this first!",
"""Welcome to Python, the easy to learn, portable, object oriented 
programming language.
[info on how to use help]
[info on intepreter]"""
)
topLevelCommand( 
"keywords", 
"What are the keywords?", 
"")
topLevelCommand( 
"syntax", 
"What is the overall syntax?", 
"[placeholder]")
topLevelCommand( 
"operators", 
"What operators are available?", 
"<doc:ref/operators.html>" )
topLevelCommand( 
"builtins", 
"What functions, types, etc. are built-in?", 
"<doc:lib/built-in-funcs.html>")
topLevelCommand( "modules", 
"What modules are in the standard library?", 
"<doc:lib/lib.html>")
topLevelCommand( 
"copyright", 
"Who owns Python?", 
"[who knows]")
topLevelCommand( 
"moreinfo", 
"Where is there more information?", 
"[placeholder]")
topLevelCommand( 
"changes", 
"What changed in Python 2.0?",
"[placeholder]"
)
topLevelCommand( 
"extensions", 
"What extensions are installed?",
"[placeholder]")
topLevelCommand( 
"faq", 
"What questions are frequently asked?", 
"[placeholder]")
topLevelCommand( 
"ack", 
"Who has done work on Python lately?", 
"[placeholder for list of people who contributed patches]")
topics[ "prompt" ]="""<doc:tut/node4.html>"""
topics[ "types" ]="""<doc:ref/types.html>"""
topics["everything"]= \
"""<pre>The help function allows you to read help on Python's various 
functions, objects, instructions and modules. You have two options:
1. Use help( obj ) to browse the help attached to some function, module
class or other object. e.g. help( dir )
2. Use help( "somestring" ) to browse help on one of the predefined 
help topics, unassociated with any particular object:
%s</pre>""" % commands
topics[ "keywords" ]=\
"""<pre>"if" - Conditional execution
"while" - Loop while a condition is true
"for" - Loop over a sequence of values (often numbers)
"try" - Set up an exception handler
"def" - Define a named function
"class" - Define a class
"assert" - Check that some code is working as you expect it to.
"pass" - Do nothing
"del" - Delete a data value
"print" - Print a value
"return" - Return information from a function
"raise" - Raise an exception
"break" - Terminate a loop
"continue" - Skip to the next loop statement
"import" - Import a module
"global" - Declare a variable global
"exec" - Execute some dynamically generated code
"lambda" - Define an unnamed function
For more information, type e.g. help("assert")</pre>"""
topics[ "if" ]="""<doc:ref/if.html>"""
topics[ "while" ]="""<doc:ref/while.html>"""
topics[ "for" ]="""<doc:ref/for.html>"""
topics[ "try" ]="""<doc:ref/try.html>"""
topics[ "def" ]="""<doc:ref/def.html>"""
topics[ "class" ]="""<doc:ref/class.html>"""
topics[ "assert" ]="""<doc:ref/assert.html>"""
topics[ "pass" ]="""<doc:ref/pass.html>"""
topics[ "del" ]="""<doc:ref/del.html>"""
topics[ "print" ]="""<doc:ref/print.html>"""
topics[ "return" ]="""<doc:ref/return.html>"""
topics[ "raise" ]="""<doc:ref/raise.html>"""
topics[ "break" ]="""<doc:ref/break.html>"""
topics[ "continue" ]="""<doc:ref/continue.html>"""
topics[ "import" ]="""<doc:ref/import.html>"""
topics[ "global" ]="""<doc:ref/global.html>"""
topics[ "exec" ]="""<doc:ref/exec.html>"""
topics[ "lambda" ]="""<doc:ref/lambda.html>"""
envir_var="PYTHONDOCS"
class Help:
 def __init__( self, out, line_length, docdir=None ):
 self.out=out
 self.line_length=line_length
 self.Parser=htmllib.HTMLParser
 self.Formatter=formatter.AbstractFormatter
 self.Pager=Pager
 self.Writer=formatter.DumbWriter
 if os.environ.has_key(envir_var):
 self.docdir=os.environ[envir_var]
 else:
 if os.environ.has_key("PYTHONHOME"):
 pyhome=os.environ["PYTHONHOME"]
 else:
 pyhome=os.path.split( sys.executable )[0]
 self.docdir=os.path.join( pyhome, "doc" )
 testfile=os.path.join( 
 os.path.join( self.docdir, "lib" ), "index.html")
 if not os.path.exists( testfile ):
 error = \
"""Cannot find documentation directory %s. 
Set the %s environment variable to point to a "doc" directory.
It should have a subdirectory "Lib" with a file named "index.html".
""" % (self.docdir, envir_var )
 raise EnvironmentError, error
 def __repr__( self ):
 self( "everything" )
 return ""
 def __call__( self, ob, out=None ):
 try:
 self.call( ob, out )
 return 1
 except (KeyboardInterrupt, EOFError):
 return 0
 def call( self, ob, out ):
 self.pager=out or self.Pager( self.out, self.line_length )
 if type( ob ) in (type(""),type(u"")):
 if ob.startswith( "<" ):
 ob=ob[1:]
 if ob.endswith( ">" ):
 ob=ob[:-1]
 self.write( 'Topic: help( "%s" )\n' % ob )
 if ob.startswith("doc:"):
 path=ob[4:]
 fullpath=os.path.join( self.docdir, path )
 data=open( fullpath ).read()
 index=ob.rfind( "/" )
 self.writeHTML( ob[:index], data )
 else:
 try:
 info=topics[ob]
 docrlmatch=re.search( "(<doc:[^>]+>)", info.split("\n")[0] )
 if docrlmatch: # a first-line redirect
 self( docrlmatch.group(1) )
 else:
 self.writeHTML( "", info )
 except KeyError:
 glo=__builtins__.__dict__.get( ob, 0 )
 if glo:
 self( glo )
 else:
 sys.stderr.write( "No such topic "+`ob` )
 return None
 else:
 self.write( 'Topic: help( %s )\n' % ob )
 if hasattr( ob, "__doc__" ):
 self.writeText(ob.__doc__)
 else:
 self.writeText( type( ob ).__doc__ )

 def writeHTML( self, base, str ):
 parser=self.Parser(self.Formatter( self.Writer( self )))
 parser.feed( str ) # calls self.write automatically
 for i in range( len( parser.anchorlist) ):
 self.pager.write( "[%s] %s/%s\n" %(i+1, base,parser.anchorlist[i] ))
 self.pager.flush()
 self.out.write( "\n" )
 def writeText( self, str ):
 self.pager.write( str )
 self.pager.flush()
 self.out.write( "\n" )
 def write( self, str ):
 self.pager.write( str )
from cStringIO import StringIO
class Pager:
 numlines=1
 def __init__(self, out, pagesize=24, linestart="" ):
 self.out=out
 self.pagesize=pagesize
 self.buf=StringIO()
 self.linestart=linestart
 def close(self ):
 self.flush()
 def flush(self ):
 data=self.buf.getvalue().rstrip() # dump trailing ws
 while data.endswith( "\n|" ): # dump trailing lines
 data=data[:-2]
 self.out.write( data )
 self.buf=StringIO()
 def write(self, str ):
 lines=str.split( "\n" )
 self.buf.write( lines[0] )
 for line in lines[1:]:
 self.buf.write( "\n| " )
 self.buf.write( line )
 if self.numlines and not self.numlines%(self.pagesize):
 dat=self.buf.getvalue().strip()
 self.out.write( "| " )
 self.out.write( dat )
 self.out.write( "\n" )
 j=raw_input(prompt)
 if j and j[0]=="q":
 raise EOFError
 self.buf=StringIO()
 self.numlines=self.numlines+1
help=Help(sys.stdout,24)
def test():
 rc = 1
 rc = rc and help( "everything" )
 rc = rc and help( "exec" )
 rc = rc and help( "doc:lib/unix.html" )
 rc = rc and help( "doc:lib/module-tty.html" )
 rc = rc and help( "doc:ref/print.html" )
 rc = rc and help( "faq" )
 rc = rc and help( dir )
 repr( help )
if __name__=="__main__":
 if len( sys.argv )!=2:
 print "Usage: %s <topic> or %s test" % ( sys.argv[0], sys.argv[0] )
 sys.exit(0)
 elif sys.argv[1]=="test":
 test()
 else:
 help( sys.argv[1] )