[Python-Dev] annotations and PEP 316 (original) (raw)

Jewett, Jim J jim.jewett at eds.com
Fri Mar 26 17:36:43 EST 2004

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

More information about the Python-Dev mailing list