Mailman 3 January 2001 - Doc-SIG

Error in pyexpat docs
by uche.ogbuji＠fourthought.com July 9, 2002

July 9, 2002

An excerpt from the Python 2.0 docs for pyexpat: """ ParseFile (file) Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data. [snip] The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception. ErrorByteIndex Byte index at which an error occurred. [etc.] """ The wrong, "xml.parsers.expat" is the first indicator that there might be a problem, yet I took the docs at their word and wrapped the call to ParseFile in a blanket try/except, only to find that no exception of any sort is ever raised by ParseFile. It turns out that ParseFile actually returns 0 on error, returning 1 otherwise. The first matter is that the code and the docs need to be reconciled. However, I would _much_ rather prefer that things were as in the docs. I think ParseFile should raise an exception rather than return an error flag. Interestingly enough, this is the same argument I had with a colleague just last week. -- Uche Ogbuji Principal Consultant uche.ogbuji(a)fourthought.com +1 303 583 9900 x 101 Fourthought, Inc. http://Fourthought.com 4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA Software-engineering, knowledge-management, XML, CORBA, Linux, Python

3 2

RE: [Doc-SIG] Doc html Index only works with netscape
by Goodger, David Jan. 19, 2001

Jan. 19, 2001

> Ah, that explains it, is this available gzip'ed somewhere? > > What is the hoped for release date? I understand that 2.1 alpha 1 is due out in a few days (21st?), but may slip due to quality control. The docs should be available at the same time. I don't know if there's any archive of the current working docs though. /Dave

1 0

RE: [Doc-SIG] Doc html Index only works with netscape
by Fetherston, Tom Jan. 19, 2001

Jan. 19, 2001

Ah, that explains it, is this available gzip'ed somewhere? What is the hoped for release date? Tom doc-sig(a)python.org -----Original Message----- From: Goodger, David [mailto:dgoodger@atsautomation.com] Sent: Thursday, January 18, 2001 5:12 PM To: Fred L. Drake, Jr.; Fetherston, Tom Cc: Doc-SIG List Subject: RE: [Doc-SIG] Doc html Index only works with netscape It seems that the anchors (<a name='l2h-80'>-type tags) are missing from part(s) the 2.0 documentation. At least ref/types.html has discrepancies: the anchors exist in the 1.5.2 docs, but not in the 2.0 docs. A quick check of the online docs reveals that ... they're missing (http://www.python.org/doc/current/ref/types.html). The latest 2.1 alpha version does have anchors (http://python.sourceforge.net/devel-docs/ref/types.html). I seem to recall a message about this problem (that it was "finally resolved! yay!") some time ago. David Goodger (@work) Systems Administrator & Programmer, Advanced Systems Automation Tooling Systems Inc., Automation Systems Division direct: (519) 653-4483 ext. 7121 fax: (519) 650-6695 e-mail: dgoodger(a)atsautomation.com

1 0

RE: [Doc-SIG] Doc html Index only works with netscape
by Goodger, David Jan. 18, 2001

Jan. 18, 2001

It seems that the anchors (<a name='l2h-80'>-type tags) are missing from part(s) the 2.0 documentation. At least ref/types.html has discrepancies: the anchors exist in the 1.5.2 docs, but not in the 2.0 docs. A quick check of the online docs reveals that ... they're missing (http://www.python.org/doc/current/ref/types.html). The latest 2.1 alpha version does have anchors (http://python.sourceforge.net/devel-docs/ref/types.html). I seem to recall a message about this problem (that it was "finally resolved! yay!") some time ago. David Goodger (@work) Systems Administrator & Programmer, Advanced Systems Automation Tooling Systems Inc., Automation Systems Division direct: (519) 653-4483 ext. 7121 fax: (519) 650-6695 e-mail: dgoodger(a)atsautomation.com

1 0

RE: [Doc-SIG] Doc html Index only works with netscape
by Fetherston, Tom Jan. 17, 2001

Jan. 17, 2001

file:///C:/Python20/Doc/ref/types.html#l2h-80 This is the resolved link for the "sequence object" under the entry for "Sequence". Now types.html has an entry talking about Sequences, so I assume the fragment "#l2h-80" is supposed to bring that area into view. This is the html source at that jpoint: <P> </DD> </DL> <P> </DD> <DT><STRONG>Sequences</STRONG></DT> <DD>These represent finite ordered sets indexed by natural numbers. The built-in function <tt class="function">len()</tt> returns the number of items of a sequence. When the length of a sequence is <var>n</var>, the index set contains the numbers 0, 1, ..., <var>n</var>-1. Item <var>i</var> of sequence <var>a</var> is selected by <code><var>a</var>[<var>i</var>]</code>. I'm unclear how "#l2h-80" refers to this point. As Richard Gordon pointed out, fragments usually point to named anchor, and there isn't one here. -----Original Message----- From: Fred L. Drake, Jr. [mailto:fdrake@acm.org] Sent: Wednesday, January 17, 2001 3:53 PM To: Fetherston, Tom Cc: Doc-SIG List Subject: RE: [Doc-SIG] Doc html Index only works with netscape Fetherston, Tom writes: > It seems that this type of fragment (which I don't understand, and can't > find in Html reference books) only works in Netscape. I'm confused by what you mean "this type of fragment" -- there's nothing special going on here. The first character is a lower case "L", not the digit "1", in case that's hard to tell. > I note that the Window download of Python has the Doc type set to netscape > docs. This must be a Mac-specific thing; I don't know what this is about. Do MSIE and Netscape use different file types for HTML documents on the Mac? (Well, I *do* remember that there are file type codes on the Mac, I just don't know what Netscape and MSIE have to do with that.) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

1 0

RE: [Doc-SIG] Doc html Index only works with netscape
by Fetherston, Tom Jan. 17, 2001

Jan. 17, 2001

The urls are just those in the "C:\Python20\Doc\ref\genindex.html" file, I'm just collecting them in the Tcl equivalent of a Dictionary of list, with the python terms as the keys. On both Mac and Pc, netscape translates the fragment into a properly positioned page with respect to the looked up term, while Internet Explorer just opens each page with it's top showing. It seems that this type of fragment (which I don't understand, and can't find in Html reference books) only works in Netscape. I note that the Window download of Python has the Doc type set to netscape docs. Tom doc-sig(a)python.org -----Original Message----- From: Ka-Ping Yee [mailto:ping@lfw.org] Sent: Wednesday, January 17, 2001 2:40 PM To: Fetherston, Tom Cc: 'doc-sig(a)python.org' Subject: Re: [Doc-SIG] Doc html Index only works with netscape On Wed, 17 Jan 2001, Fetherston, Tom wrote: > Noe, I changed this so command-double clicking a keyword in Alpha sends an > AppleEvent to a browser containg the Url. Most of the urls contain > fragments (e.g. #12h-110) after the filename that are supposed to position > the relevant section in the browser for viewing, however, only Netscape > seems to accept this correctly. ICab and IE just open the file at the top. > This is also what they do if you click the hyperlink in the index file. The fact that they also behave this way when you click directly, as opposed to sending an AppleEvent, tells me that this is a more general browser issue rather than a Mac-specific or a Python-specific thing. I think there's a problem with your fragment syntax, but i can't tell anything further without seeing your HTML file. Can you provide the URL so we can look at it? -- ?!ng

2 1

Doc html Index only works with netscape
by Fetherston, Tom Jan. 17, 2001

Jan. 17, 2001

Hi, I sent the folowing to the Pythonmac-sig, this might be a better place.: ---------------------------------------------------------------------------- ------------------------- Hi, Not exactly an html list, but believe it or not this involves Python. I cam accross a program that would provide keyword look-ups into the Python Html doc. It came in too parts, a python program to parse the url's in the genindex.html file (in the ref sub directory), it created a dictionary (keyword : url), then it pickled that dictionary. I updated it to use the 're' module and to handle the 2.0 doc's, instead of pickling the dictionary, I have it write out a .tcl file, which when sourced, provide a Tcl equivalent of the dictionary. The second part of this system was a elisp function to initiated a lookup from within emacs. Noe, I changed this so command-double clicking a keyword in Alpha sends an AppleEvent to a browser containg the Url. Most of the urls contain fragments (e.g. #12h-110) after the filename that are supposed to position the relevant section in the browser for viewing, however, only Netscape seems to accept this correctly. ICab and IE just open the file at the top. This is also what they do if you click the hyperlink in the index file. !) Am I stuck with specifying Netscape as the only browser to use? 2) What is this fragment specifying? My Html 4 ref book does not list this kind of fragment, is it purely a Netscape extension? Tom --------------------------------- I got this as a reply: ----------------------- hi- I'm not convinced that I am really following you, but maybe this will help a little anyway. Generally, a url ending with # followed by a string is supposed to seek a named anchor, so #12h-110 would look for <a name="12h-110> in the target document. This works pretty much the same from one browser to another, so I don't think that's what's going on here. Another possibility is that this syntax is somehow being used to call the find() javascript function that is supported by Netscape but the last time I checked, was not supported by IE and probably isn't supported by iCab. This basically just triggers the find menu command, fills in the search string, and does the seek transparently once the entire target document is loaded. So, that's my best guess and if it's correct, there's not much you can do but go in and hack together something in javascript that would trap for IE and maybe try to use textRange or something to emulate the find function. Richard Gordon -------------------- Is this right? Seems more likely to be based on line numbers. It does seem to be specific to Netscape, why aren't the fragments consistent with more browsers? Tom

2 1

pydoc.py (show docs both inside and outside of Python)
by Ka-Ping Yee Jan. 16, 2001

Jan. 16, 2001

I'm pleased to announce a reasonable first pass at a documentation utility for interactive use. "pydoc" is usable in three ways: 1. At the shell prompt, "pydoc <name>" displays documentation on <name>, very much like "man". 2. At the shell prompt, "pydoc -k <keyword>" lists modules whose one-line descriptions mention the keyword, like "man -k". 3. Within Python, "from pydoc import help" provides a "help" function to display documentation at the interpreter prompt. All of them use sys.path in order to guarantee that the documentation you see matches the modules you get. To try "pydoc", download: http://www.lfw.org/python/pydoc.py http://www.lfw.org/python/htmldoc.py http://www.lfw.org/python/textdoc.py http://www.lfw.org/python/inspect.py I would very much appreciate your feedback, especially from testing on non-Unix platforms. Thank you! I've pasted some examples from my shell below (when you actually run pydoc, the output is piped through "less", "more", or a pager implemented in Python, depending on what is available). -- ?!ng "If I have seen farther than others, it is because I was standing on a really big heap of midgets." -- K. Eric Drexler skuld[1268]% pydoc -k mail mailbox - Classes to handle Unix style, MMDF style, and MH style mailboxes. mailcap - Mailcap file handling. See RFC 1524. mimify - Mimification and unmimification of mail messages. test.test_mailbox - (no description) skuld[1269]% pydoc -k text textdoc - Generate text documentation from live Python objects. collab - Routines for collaboration, especially group editing of text documents. gettext - Internationalization and localization support. test.test_gettext - (no description) curses.textpad - Simple textbox editing widget with Emacs-like keybindings. distutils.text_file - text_file ScrolledText - (no description) skuld[1270]% pydoc -k html htmldoc - Generate HTML documentation from live Python objects. htmlentitydefs - HTML character entity references. htmllib - HTML 2.0 parser. skuld[1271]% pydoc md5 Python Library Documentation: built-in module md5 NAME md5 FILE (built-in) DESCRIPTION This module implements the interface to RSA's MD5 message digest algorithm (see also Internet RFC 1321). Its use is quite straightforward: use the new() to create an md5 object. You can now feed this object with arbitrary strings using the update() method, and at any point you can ask it for the digest (a strong kind of 128-bit checksum, a.k.a. ``fingerprint'') of the contatenation of the strings fed to it so far using the digest() method. Functions: new([arg]) -- return a new md5 object, initialized with arg if provided md5([arg]) -- DEPRECATED, same as new, but for compatibility Special Objects: MD5Type -- type object for md5 objects FUNCTIONS md5(no arg info) new([arg]) -> md5 object Return a new md5 object. If arg is present, the method call update(arg) is made. new(no arg info) new([arg]) -> md5 object Return a new md5 object. If arg is present, the method call update(arg) is made. skuld[1272]% pydoc types Python Library Documentation: module types NAME types FILE /home/ping/sw/Python-1.5.2/Lib/types.py DESCRIPTION # Define names for all type symbols known in the standard interpreter. # Types that are part of optional modules (e.g. array) are not listed. skuld[1273]% pydoc abs Python Library Documentation: built-in function abs abs (no arg info) abs(number) -> number Return the absolute value of the argument. skuld[1274]% pydoc repr Python Library Documentation: built-in function repr repr (no arg info) repr(object) -> string Return the canonical string representation of the object. For most object types, eval(repr(object)) == object. Python Library Documentation: module repr NAME repr - # Redo the `...` (representation) but with limits on most sizes. FILE /home/ping/sw/Python-1.5.2/Lib/repr.py CLASSES Repr class Repr __init__(self) repr(self, x) repr1(self, x, level) repr_dictionary(self, x, level) repr_instance(self, x, level) repr_list(self, x, level) repr_long_int(self, x, level) repr_string(self, x, level) repr_tuple(self, x, level) FUNCTIONS repr(no arg info) skuld[1275]% pydoc re.MatchObject Python Library Documentation: class MatchObject in re class MatchObject __init__(self, re, string, pos, endpos, regs) end(self, g=0) Return the end of the substring matched by group g group(self, *groups) Return one or more groups of the match groupdict(self, default=None) Return a dictionary containing all named subgroups of the match groups(self, default=None) Return a tuple containing all subgroups of the match object span(self, g=0) Return (start, end) of the substring matched by group g start(self, g=0) Return the start of the substring matched by group g skuld[1276]% pydoc xml Python Library Documentation: package xml NAME xml - Core XML support for Python. FILE /home/ping/dev/python/dist/src/Lib/xml/__init__.py DESCRIPTION This package contains three sub-packages: dom -- The W3C Document Object Model. This supports DOM Level 1 + Namespaces. parsers -- Python wrappers for XML parsers (currently only supports Expat). sax -- The Simple API for XML, developed by XML-Dev, led by David Megginson and ported to Python by Lars Marius Garshol. This supports the SAX 2 API. VERSION 1.8 skuld[1277]% pydoc lovelyspam no Python documentation found for lovelyspam skuld[1278]% python Python 1.5.2 (#1, Dec 12 2000, 02:25:44) [GCC egcs-2.91.66 19990314/Linux (egcs- on linux2 Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam >>> >>> from pydoc import help >>> help(int) Help on built-in function int: int (no arg info) int(x) -> integer Convert a string or number to an integer, if possible. A floating point argument will be truncated towards zero. >>> help("urlparse.urljoin") Help on function urljoin in module urlparse: urljoin(base, url, allow_fragments=1) # Join a base URL and a possibly relative URL to form an absolute # interpretation of the latter. >>> import random >>> help(random.generator) Help on class generator in module random: class generator(whrandom.whrandom) Random generator class. __init__(self, a=None) Constructor. Seed from current time or hashable value. seed(self, a=None) Seed the generator from current time or hashable value. >>>

3 6

Re: [Python-Dev] pydoc.py (show docs both inside and outside of Python)
by Jack Jansen Jan. 12, 2001

Jan. 12, 2001

> I'm pleased to announce a reasonable first pass at a documentation > utility for interactive use. "pydoc" is usable in three ways: [...] > I would very much appreciate your feedback, especially from testing > on non-Unix platforms. Thank you! Wow, I'm impressed! To make it run on the mac I had to add tests for the existence of os.system only. (So all statements "if os.system(...) > 0:" got to be "if hasattr(os, "system") and os.system(...) > 0:"). There are however various other niceties that could be added to make it more useful, can this be put into the repository or something? -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)oratrix.com | ++++ if you agree copy these lines to your sig ++++ www.oratrix.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm

2 1

Updated development documentation
by Fred L. Drake, Jr. Jan. 9, 2001

Jan. 9, 2001

I've just updated the development version of the documentation, but am not sure the automated notice got sent. This version contains a wide variety of smaller updates, plus added documentation on the fpectl and xreadlines modules. http://python.sourceforge.net/devel-docs/ -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

1 0