[Doc-SIG] Oscar - pre-announcement over on Types-SIG
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Tue, 21 Aug 2001 09:23:36 +0100
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.)