--- /dev/null
+"""
+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] )
+
projects / python / commitdiff