Mailman 3 July 2000 - Doc-SIG

Nit in "urllib" library documentation
by Ka-Ping Yee Oct. 10, 2000

Oct. 10, 2000

See http://www.python.org/doc/1.5.2p2/lib/module-urllib.html The last chunk of the section on "urlopen" appears to be repeated twice: The urlopen() function works transparently with proxies... For example (the "%" is the command prompt): ... In a Macintosh environment, urlopen() will retrieve proxy information from Internet Config. The urlopen() function works transparently with proxies... For example (the "%" is the command prompt): ... In a Macintosh environment, urlopen() will retrieve proxy information from Internet Config. -- ?!ng

2 1

library reference contents
by Ka-Ping Yee Oct. 10, 2000

Oct. 10, 2000

The contents page of the Library Reference has a few warts: - A few section headers (e.g. operator, pprint, repr) end in periods that probably ought to be deleted. (Complete list: 3.5, 3.23, 3.24, 3.27, 3.32, 4.2, 4.3, 4.5, 5.10, 6.13, 6.15, 7.1, 7.6, 11.11, 11.12, 11.13, 12.13, 12.14, 14.9, 14.10, 15.4.) - Description of 3.28 "new" doesn't make much sense: "runtime implementation object creation" (probably you want to replace "implementation" with "instance") - Description of 4.3 "regex" should probably say "old" or "deprecated". - Description of 6.12 "curses" has a spelling mistake: "Terminal independant (sic) console handling". - Description of 7.14 "rlcompleter" probably ought to say "Completion function for GNU readline". - Descriptions of 11.14 "SimpleHTTPServer" and 11.15 "CGIHTTPServer" seem strange: "A Do-Something Request Handler". Suggest "11.14 SimpleHTTPServer -- A simple HTTP request handler" and "11.16 CGIHTTPServer -- A CGI-capable HTTP request handler". Hope this helps. -- ?!ng "I'm not trying not to answer the question; i'm just not answering it." -- Lenore Snell

2 1

The Western Web Newsletter
by The Western Web July 30, 2000

July 30, 2000

THE WESTERN WEB WEEKLY NEWS LETTER Week of July 24, 2000 Serving Over 75000 Recipients With your assistance "The Western Web" continues to improve and your input is helpful.Our goal is to make "The Western Web" THE one place stop for all your Horse, Livestock and Western Life Style needs. If You have added your site to our search engine, please make sure everything is correct. If you haven't noticed we have upgraded the look and capabilities of The Western Web search engine. You can now type in your search word and find all related site links. Don't forget to add your Web Site to our search engine too. http://www.searchthewesternweb.com This week you might take a look at our "Events Calendar" in our Classified Ad section. You can post your upcoming events in subcategories such as: Events, Shows, Cuttings, Team Roping, Gymkhana, Clinics, Trail, Auctions, Rodeos, Reining, Barrel Racing, Team Penning and Performance & Halter. We also have a subcategory for "Other" to place any event not categorized. These ads are free and you can add pictures, video and audio. A note to our subscribers who have posted ads, with you User Name and Password you can update your events. http://www.westernwebclassified.com/cgi-bin/classifieds/classifieds.cgi At last, an online service available with the horse lover in mind, The Sale Barn.Com (www.thesalebarn.com). The Sale Barn offers an online auction specifically for horse-related items, whether you are buying or selling. The Sale Barn auctions off 100s of items daily with many items in the Hot Items Listing starting at $1.00! Usually there are from 150 to 200 items starting at only $1.00. >From saddles, bridles, bits, spurs and unique gift items. Register now to qualify for our weekly drawing. The current prize is a 34 x 36 Wool Blend Show Blanket with wear leathers and silver conchos valued at $99.95! This item is featured on our Home Page at www.thesalebarn.com. Registration is free on our secure site with no credit card necessary. The Sale Barn is amongst the top 10 visited horse sites on the Internet with over 10,000 hits a day. A perfect opportunity to turn unneeded horse related items in to cash. The Sale Barn is the ebay of the horse world with categories directed to specific items such as saddles, headstalls, bits, spurs, ropes, gift items, horse trailers, etc. http://www.thesalebarn.com We appreciate you patronizing our sponsors. You to can have your web site on our front page along with Banks Power, Roo-hyde Saddlery, GMC, Bootbarn.com,Truckloads.net, Zig Zigler, Comforce, The Gaited Horse, Cowboy Tack, Painted Acres Ranch,The ShawnOshine,Tom Balding Bits & Spurs, Centenary of Federation and Stoxrus.com. You can find our reasonable rates at: http://www.thewesternweb.com/Advertising/Advertising.htm While at The Western Web site take a look at our message board: http://www.westernmessageboard.com/cgi-bin/Ultimate.cgi We can Design & Host your web site. Check out our low domain name registration prices at: http://www.thewesternweb.com/Web_Design/Domain_Name_Registration.htm For you convenience, there are links to these sites and more, from The Western Web Home Page. http://www.thewesternweb.com/ If you receive this message in error or want us to remove you from our newsletter e-mail list, please reply to this email address with the word "Remove" in the subject line. Thank You, http://www.thewesternweb.com

1 0

Re: [Python-Dev] Checked in...
by Paul Prescod July 17, 2000

July 17, 2000

Ka-Ping Yee wrote: > > ... > > I'd like Python to come packaged in such a way that people can > easily deploy it in an organization along with whatever stuff > they develop. So being able to very easily generate and see docs > on their own modules, integrated with the view of docs for the > rest of the standard library, would be a nice thing. It makes a > Python environment easier to support. Agreed. I'm just not sure if it requires a webserver. You could set up a makefile to recognize when an HTML doc is out of sync with its Python. > The way i imagined it, it wouldn't depend on htmldoc or the web > server at all. It would call inspect.py to get its info and just > format some text on its own. I didn't know about the clean separation of htmldoc and inspect when I wrote that. You're right, it should call inspect directly. > This is basically identical to how you were describing the > onlinehelp/help commands. I didn't think of using the external > (TeX/HTML) documentation though... that's a clever idea. So: > > - use doc pages only? That's not doable unless there is a process to get docstrings into doc pages -- which is a great idea but probably some ways away. > - use internal info only? Where do I get information on statements and "topics" (like slicing, as a topic). > - separate scripts for each? Maybe internally. Ideally not at the user interface layer. > - use doc pages if installed, then fall back to internal info? My model, which you may or may not have noticed yet, is to use docstrings for objects that have docstrings, but the docstrings can point to HTML documentation in the circumstance where the canonical doc is maintained in HTML. In that case, I magically go to the HTML, rather than showing the reference. My personal feeling is that over time a lot of the library documentation should move inline for ease of maintenance and reduction of duplication. But that won't happen until we integrate inspect.py and latex2html. I have some ideas about that too. It's the opposite of the current scheme. We should put pointers from the LaTeX into the modules. A preprocessor would use inspect.py to generate a combined LaTeX that merges inline (LaTeX) and out-of-line (docstring) information. Then we start moving bits of the documentation into docstrings a little at a time. Anything that uses LaTeX features that are "funky" can stay in LaTeX until we invent a structured docstring syntax (whenever). > One other note: how about leaving the job of listing the text to > to an external app like "less"/"more", as determined by the PAGER > environment variable, allowing customization? The code we use to > figure out what program to run should eventually move into > launch.textviewer. I'm happy to do this on platforms that support it. I'm somewhat nervous about popen on non-Unix systems...maybe I should write a text file and then launch the pager on that. > Perhaps this would then provide interactive apps (e.g. IDLE) the > opportunity to simply replace (or hook into) launch.textviewer. Good idea. One tricky issue is what format to use, though. troff/man is great for Unix TTY, HTML is great for GUIs and raw text is the lowest common denominiator. Do I want to get into n*m translations? Maybe, maybe not. Or maybe HTML is the lowest common denominator and Unix TTY users should use lynx? -- Paul Prescod - Not encumbered by corporate consensus It's difficult to extract sense from strings, but they're the only communication coin we can count on. - http://www.cs.yale.edu/~perlis-alan/quotes.html

1 0

Help tool
by Paul Prescod July 17, 2000

July 17, 2000

There is a new module for interactive help at the Python command line. It is not official or anything yet but it needs more feedback to get to that stage. Please take a look and comment. Also consider working on content for the command line so that the tool will be more useful. It is attached. Read the docstring for usage information. -- Paul Prescod - Not encumbered by corporate consensus It's difficult to extract sense from strings, but they're the only communication coin we can count on. - http://www.cs.yale.edu/~perlis-alan/quotes.html """ 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. You can also use the module as a command line program: python onlinehelp.py if """ # todo: consider following links: # help( 3 ) -> follows link 3 in the last-displayed doc # help( 4 ) -> follows link 4 in the last-displayed doc # ... 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 self.docdir=docdir def initDocDir( self ): 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:] if not self.docdir: self.initDocDir() 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] )

1 0

Re: [Python-Dev] Pre-PEP Idea
by Moshe Zadka July 15, 2000

July 15, 2000

On Sat, 15 Jul 2000, Paul Prescod wrote: > Moshe Zadka wrote: > > > > ... > > > > -- have all that wonderful stuff in help.py > > -- have the startup code of the *interactive interpreter only* do > > "from help import help" at the beginning. > > Sorry, that's a part I should have explanied more. > > help is not a magical function/statement but an instance with a repr > that does the right thing. And yes, it will probably only be loaded at > the repl. Or it could be a 10-line instance that loads its content when > it is actually used. That might allow > > python -c "import help" > > Here's a sample definition. > > class helploader: > def __repr__( self ): > global help > from helptext import help > return repr( help ) > def __call__( self ): > global help > from helptext import help > return repr( help ) > help=helploader() BTW, that should probably be CCed to the doc-sig, because that information has to come from somewhere. doc-sig traffic kind of died after the initial IPC8-induced burst. Fred, any plans on seriously reviving doc-sig? -- Moshe Zadka <moshez(a)math.huji.ac.il> There is no GOD but Python, and HTTP is its prophet. http://advogato.org/person/moshez

1 0

The Western Web has just finished our new classified ad section. Please check it out and make sure that your classified ad has been moved. We are in the process of moving ads at this time, but would appreciate your help to insure that if your ad has been moved. If it hasn't been moved or you would like to place a new ad feel free to do so. We have added new sections in the classifieds, hay/feed/shavings, livestock, camelids, cattle, deer and elk, poultry, rabbits, sheep, livestock equipment,
by The Western Web July 1, 2000

July 1, 2000

The Western Web has just finished our new classified ad section. Please check it out and make sure that your classified ad has been moved. We are in the process of moving ads at this time, but would appreciate your help to insure that if your ad has been moved. If it hasn't been moved or you would like to place a new ad feel free to do so. We have added new sections in the classifieds, hay/feed/shavings, livestock, camelids, cattle, deer and elk, poultry, rabbits, sheep, livestock equipment, swine, donkeys, dogs and mules. We are currently receiving 100 new ads a day, and over 20,000 unique hits a day. http://www.thewesternweb.com The new classified section is automated now and your ads will be posted immediatly. You can also add Multi-Media files (photos, sound and video) on line. This is a free service to you so use it at your will. http://www.westernwebclassified.com We have also finished the Western Web Search Engine, which is solely optimized for the western way of life. Please stop by the search engine add your site. http://www.lookelu.com Our message board is also now up and running so please use it . http://www.westernmessageboard.com/cgi-bin/Ultimate.cgi We are sorry for any inconvenience. Thank you, http://www.thewesternweb.com This ad is being sent in compliance with Senate bill 1618, Title 3, section 301. http://www.senate.gov/ ~murkowski/commercialemail/S771index.html Here is a more detailed version of the legal notice above: This message is sent in compliance of the new e-mail bill: SECTION 301. Per Section 301, Paragraph (a)(2)(C) of S. 1618, http://www.senate.gov/~murkowski/commercialemail/S771index.html Further transmissions to you by the sender of this email may be stopped at no cost to you by sending a reply to this email address with the word "remove" in the subject line.

1 0