mirror of https://github.com/python/cpython.git
At GVR's request.
This commit is contained in:
Paul Prescod
parent
ff975003cf
commit
d61591813c
|
|
@ -1,344 +0,0 @@
|
|||
"""
|
||||
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] )
|
||||
|
||||
Loading…
Reference in New Issue