[Python-Dev] annotations and PEP 316

[Jewett, Jim J]

I've already run into problems when my docstrings get 
longer than a few lines -- the function signature and 
the function body are too far apart.

doctest makes this worse.

PEP 316 is another good idea -- that makes docstrings
even longer.

As Skip pointed out, docstrings are a special case; 
if we were starting fresh, it might make sense to 
create new attributes for docstrings (__doc__), 
contracts, extra tests to run, longer documentation,
etc, rather than cramming them all into the plaintext
first string.

Annotation decorators would support this, but would
definately be too long for squeezing in mid-def.  It
would also make the "real transforms get lost" problem
worse, if the two types of decorators were not 
separated.

Based on an example from PEP 316

    class circbuf:

        note:
            dbc = """
                  pre: not self.is_empty()
                  post[self.g, self.len]:
                      __return__ == self.buf[__old__.self.g]
                      self.len == __old__.self.len - 1
                  """
            changed = (2004, 3, 26, 17, 9, 47, 4, 86, 0)
        using:
            synchronized(self.lock)
        def get(self):
            """Pull an entry from a non-empty circular buffer."""

I like leaving the current declaration alone; it lets me copy and
paste to the calling code.  But the separation works with any 
proposed transformer syntax - and some that were rejected for not
scaling.  The key is pulling out annotations (which *will* get long) 
in hopes of leaving a short list of true transformers.

Note that while Design By Contract is intended to be executable, it
is also intended to be something that the user can optimize out.
Attaching a second entry point does not require replacing the original
object;  DBC-aware tracing tools can look for the DBC entry point
attribute at least as easily as they can parse docstrings.  

I suspect many of the other "non-annotation" wrappers could be reduced
to an annotation in a similar manner.

-jJ