+++ /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