Mailman 3 August 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

quick_reST 0.4.6
by Tony J Ibbs (Tibs) Sept. 14, 2001

Sept. 14, 2001

I've uploaded a new version of the quick reference, at (as always): http://www.tibsnjoan.co.uk/reST/quick_reST.html It merges back in some changes David made, and has a start at some text (well, a table) about what to do in docstrings if you want to use backslashes to escape reST things. Main other changes: all uses of <pre> in the left hand side of tables removed (this gives better formatting in many browsers); title hack suggested by David adopted (to get the <tt> part in a better size) - this may be temporary. (hmm - will we ever reach version 0.5?) Tibs (who's now having mad thoughts about:: .. reSTexample:: :title: Inline markup :link: :rest:reStructuredText.html#inline_markup :plain: ``*emphasis*`` :shown: *emphasis* directives, despite having said to David that one couldn't use reST to produce the quick reference...) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Give a pedant an inch and they'll take 25.4mm (once they've established you're talking a post-1959 inch, of course) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

2 20

Oscar - pre-announcement over on Types-SIG
by Tony J Ibbs (Tibs) Aug. 24, 2001

Aug. 24, 2001

I don't know if people here watch the Types-SIG, and I suspect that Greg doesn't watch the Doc-SIG, so... Greg Ward has just made a pre-announcement of Oscar [1]_. To quote: several months ago, I cooked up a tool, Oscar for rigorously type-checking a Python object graph: you define an object schema (currently through specially- formatted class docstrings), and Oscar crawls a persistent object graph to ensure that every scrap of data in it conforms to your schema. We use this regularly in the MEMS Exchange for integrity-checking our ZODB database; it's not the be-all-end-all to checking that all is well with an object database, but it's a hell of a lot better than nothing. The interesting bit for us is "through specially-formatted class docstrings". These look like, for instance:: class Animal (Thing): """An animal, ie. a thing with multiple legs and possibly fur. Instance attributes: num_legs : int the number of legs this animal has furry : boolean whether this animal is furry or not Outsiders should use 'get_num_legs()' and 'is_furry()' to access these attributes. """ His parser looks for the ``Instance attributes:``, and eats anything indented after it (and the formatting of that is fairly strict). Thought for us - this is something we need to bear in mind, since it would be nice if we didn't muck up its appearance when processing a docstring for presentation. Thoughts for Greg - currently the ``Instance attributes`` clause, as presented, would not be acceptable to the DPS/reStructuredText system. However, it's very near. There are two ways to change it to *make* it acceptable: 1. Simply add a blank line after ``Instance attributes:`` (that would make the stuff thereafter a descriptive list, which sort-of makes sense) 2. Prepend an additional colon before ``Instance attributes:``, and make the "title" into a single "word" - for instance:: :Instance-attributes: or:: :InstanceAttributes: This looks a bit uglier, but means that the text following could be handed to a specialised plugin which knows to do special things with it. The "schema spec ends when indentation returns to that of the title" rule will work OK in DPS/reST. .. [1] http://aspn.activestate.com/ASPN/Mail/Message/types-sig/751935 Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

3 8

Re: [Python-Dev] Inline and SWIG
by Fred L. Drake, Jr. Aug. 23, 2001

Aug. 23, 2001

Thomas Heller writes: > Makes a pretty good pair with a calldll-like extension module. I guess calldll is very different from the dl module, which has documentation. Is anyone up to writing docs for calldll? I've CC'd to the Doc-SIG since there may be volunteers there ;-) -- please remove python-dev from doc-related followups. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

RE: Not escaping the escape leaves no escape ;)
by Tony J Ibbs (Tibs) Aug. 23, 2001

Aug. 23, 2001

Edward Welbourne (hi Eddy) wrote: > Hi Tibs [..deletia..] > but the backslash stuff has me a bit confused > ... partly because the illustrations didn't appear > to be using r'...' strings. > > In non-raw strings, a backslash followed by > something it doesn't find interesting is just > an ordinary character > > >>> 'hell\o there' > 'hell\\o > >>> 'h\appy birthday' > 'h\007ppy birthday' > >>> # (James Bond escapes as an alert character ;^) > > but a backslash is, itself, interesting to a backslash; > so (changing one of your ' pairs to a ` pair so I can > enclose in a ' pair) > > >>> '\*escape* \`with` "\\"' > '\\*escape* \\`with` "\\"' > >>> '\\*escape* \\`with` "\\"' > '\\*escape* \\`with` "\\"' > > your parser isn't going to be able to distinguish > whether the source contained doubled or single > backslashes, except when the following character > is one that backslash finds interesting ... but > your rules seem to depend on your parser knowing > this. > > I may be worrying needlessly, but just thought I'd > better throw a sanity-check `\007' ! He also said: > Feel free to forward to doc-sig if novel and interesting > enough ;^> so I am doing so... Ah - it may be necessary to beware that DPS/reST is not only aimed at docstrings, so almost all of the examples are going to assume "plain text" as the input - i.e., some form of non-Pythonic text file - and leave the "docstring-isation" up to the user ('cos that's easier to do - it also (personal opinion!) makes it easier to ignore how, erm, rather hard it is to use backslashes as escape characters within Python strings... Indeed, your choice of example shows that you've been reading the quickref, and it is also talking about "bare" text - so that sounds like I need to add a small section on embedding reST within *actual* docstrings. I'll try to get around to amending the quickref to mention something along those lines. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

2 1

[development doc updates]
by Fred L. Drake Aug. 20, 2001

Aug. 20, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Final documentation for Python 2.2 alpha 2.

1 0

Changes to reStructuredText spec
by David Goodger Aug. 17, 2001

Aug. 17, 2001

I've updated the specification documents quite a bit, along the lines of the recent discussions. Highlights: - Removed leading underscore from footnote definition [1]_ and added implicit hyperlink target generation (like section headers). - Added automatic numbering of footnotes. - Moved interpreted text's role outside of backquotes. - Settled on field list syntax (":field-name: field body"), updated definition. I'm in the process of updating the *uses* of field lists in the various documents and modules as well. - Added 'abstract' to list of bibliographic elements. - Loosened enumerated list requirements (2-in-a-row). - Removed requirement for blank lines between definition list items. - Added option lists & doctest blocks from pyextensions.txt (which will be removed soon, and the non-syntax parts reincarnated as a DPS Python "mode"). .. [1] This is one of the most interesting changes, I expect. By leveraging the implicit hyperlink target generation of section headers, footnotes now look much more natural. And confusion with hyperlink targets should decrease too. The implementation changes will follow shortly. (Wait a sec -- isn't that backwards? Usually the docs lag behind the code. Not for a documentation project, I guess. ;-) I haven't made a new release yet, but there are now daily snapshots updated at midnight EDT (04:00 UTC): - reStructuredText code & spec: http://structuredtext.sourceforge.net/rst-snapshot.tgz - DPS code & spec: http://docstring.sourceforge.net/dps-snapshot.tgz -- David Goodger dgoodger(a)users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net

1 0

Re: [Docstring-develop] Attribute docstrings
by David Goodger Aug. 16, 2001

Aug. 16, 2001

Tony J Ibbs (Tibs) <tony(a)lsl.co.uk> wrote on 2001-08-16 09:42: > DPS (pep 258) is proposing to support attribute docstrings. > > Yet PEP 224 was rejected by the BDFL because he dislikes the look of:: > > a = 1 > """Documentation.""" > b = 1 > > a. because he doesn't like it > b. because he can't tell if the docstring belongs > to `a` or `b` > > This rejection did *not* worry about issues of what value was used to > store the docstring (obviously not an issue for us). > > Is DPS on dodgy ground in supporting a PEP that has been fundamentally > rejected? The fundamental differences between PEP 224 and the relevant part of PEP 258 are the impact and the context. PEP 224 required changes to the core Python language for a feature of marginal usefulness *to* the core language. The DPS (PEP 258) provides a useful, application context for the concept of attribute docstrings, without requiring any changes to the core Python language. Attribute docstrings become a simple documentation convention with no impact or incompatibilities. Although I think attribute docstrings are very useful (see dps/statemachine.py for a complete example), the success of the DPS does not hinge on them being accepted. If push comes to shove, they're easy to drop. But I hope it doesn't come to that, since it's really an application issue. > As a potential *slight* cure for the BDFL objections (I'm doubtful), I > can only propose that we mark up the docstring itself:: > > a = 1 > """.. doc::a Some documentation""" > > would be documentation for `a`. That's a bit verbose, so maybe it should > be:: > > """:doc:a Some documentation""" > > Or even:: > > """:a: Some documentation""" > > (is that last stretching too far?) > > [I'm not sure I like any of the above, in fact Nor do I; I don't think any of these would fly. If forced to use such markup, I think I'd rather just leave these docstrings in the parent module/class/method/function docstring. > Or maybe we should enforce no blank line before the docstring, and at > least one blank line after it (I've yet to see if we can tell that from > the AST, but I suspect we can). If we can glean this info from the AST, then that's certainly a possibility. > do we have a BDFL comment on this part of the DPS spec? Let's ask. What do you think, Guido? -- David Goodger dgoodger(a)users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net

1 0

[development doc updates]
by Fred L. Drake Aug. 16, 2001

Aug. 16, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Improved documentation for the os.spawn*() functions. Fix some HTML generation problems.

1 0

Version 0.4 of reST quick guide
by Tony J Ibbs (Tibs) Aug. 16, 2001

Aug. 16, 2001

As it says, version 0.4 of the quick ref is now at http://www.tibsnjoan.co.uk/reST/quick_reST.html This should be a lot closer to being correct. David, feel free to put this into the CVS tree if you wish. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

2 3