[Doc-SIG] Oscar - pre-announcement over on Types-SIG

[Tony J Ibbs (Tibs)]

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.)