python-contract 1.4-3 / usr / share / pyshared / contract.py

"""Programming-by-contract for Python, based on Eiffel's DBC.

Programming by contract documents class and modules with invariants,
expressions that must be true during the lifetime of a module or
instance; and documents functions and methods with pre- and post-
conditions that must be true during entry and return.

Copyright (c) 2003, 2006, 2007 Terence Way

This program is free software; you can redistribute it and/or modify
it under the terms of either:

a) GNU Library or Lesser General Public License as published by the
   Free Software Foundation; either version 3, or (at your option)
   any later version, or

b) Python Software Foundation License
   You may redistribute and/or modify this program under the same
   terms as Python itself, so long as this copyright message and
   disclaimer are retained in their original form, or

c) The "Artistic License" which comes with this Kit.

You should have received a copy of the Artistic License with this
Kit, in the file named "Artistic".  If not, I'll be glad to provide one.

You should also have received a copy of the GNU Lesser General Public
License along with this program in the files named "COPYING" and
"COPYING.LESSER".  If not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston MA 02111-1307, USA or visit their
web page on the internet at http://www.gnu.org/copyleft/lgpl.html.

IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF
THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
"""

# Changes:
#   ttw001 2003-05-26
#   Jeff Epler points out we should have separate assertion exception
#   base class ContractViolationError, then exception classes
#   PreconditionViolationError, PostconditionViolationError, and
#   InvariantViolationError inheriting from ContractViolationError.
#
#   ttw002 2003-05-26
#   Support restructured text by allowing double colon (::) in
#   addition to single colon (:) after 'pre' 'inv' 'post' or
#   post variable declarations.
#
#   ttw003 2003-05-29
#   Dickon Reed discovers problem: invariants mustn't be checked after
#   a constructor throws an exception.
#
#   ttw004 2003-06-02
#   Make sure that objects returned in _get_members only include
#   things defined by that module
#
#   ttw005 2003-06-02
#   Save line number information in parse_docstring, _read_block, to
#   be trapped if a TokenError or ParseError occurs, and to pass along
#   to any contract exceptions raised.
#
#   ttw006 2003-06-06
#   The _read_block internal function past the last line of a docstring
#   contract.  This saves some hackery in parse_docstring, and makes
#   _read_block more useful for external tools.
#
#   ttw007 2003-06-06
#   Phillip Eby points out that OR-ed pre-conditions are worse than
#   useless.  So instead of OR-ing pre-conditions of a method with all
#   overridden methods, we check if a pre-condition fails whether *any*
#   overridden pre-condition would succeed, if so we raise an
#   InvalidPreconditionError
#
#   ttw008 2003-06-13
#   Support partial contract enforcement: check preconditions only.
#   add flag to checkmod to specify checklevel: CHECK_NONE,
#   CHECK_PRECONDITIONS, or CHECK_ALL
#
#   ttw009 2003-06-13
#   String module names can be passed into checkmod as well.
#
#   ttw010 2003-06-20
#   Python 2.2.1 has bool, True, False but Python 2.2 doesn't.  To
#   support built-in Python on Mac OS X, define local bool() if not
#   defined globally
#
#   ttw011 2003-06-21
#   Support Jython (Python 2.1).  Refactored the tokenize logic in
#   _read_block() to support older tokenize.tokenize(), backtracked
#   some 2.2 conveniences (like 'x in {dict}').
#
#   ttw012 2005-10-19
#   From Gintautas Miliauskas:
#   "I discovered one problem though: you expect __import__(modname) to
#   return the corresponding module, however, it does not work like
#   that.  For example, if you invoke __import__('a.b.c.d'), the result
#   will be module <a>, not module <d>.  Yes, I think this is dumb too,
#   but that's how it works.  A workaround is to use __import__ to
#   import the module and then get the actual module from sys.modules."
#
#   ttw013 2006-04-22
#   From Aaron Bingham:
#   "The subclass's method defines no new pre- or postconditions; the
#   script testunchecked.py thus exits normally, even though the
#   superclass's contract is violated!"
#
#   All methods need to have checking code installed, even if there
#   are not any conditions in the method docstring, because the
#   super-class may have conditions.
#
#   A method without any docstring conditions is implicitly declaring
#   "pre: True"
#
#   rr001 2007-06-02
#   From Ruben Reifenberg
#   "There is some behaviour in contract.py that might be a bug.
#   It happened that line 1300 re-raised the AttributeError from 1292
#   although a PreconditionVioloation was going on.  Changing 1300 to:
#    1300: raise args
#   solved the problem"
#
#   ab001 2007-08-31
#   From Aaron Bingham
#   "Fix handling of constructor preconditions.
#
#   Subclass constructors' parameter lists may be legitimately completely
#   different from the superclass constructor's parameter list. Thus, for
#   constructors we only evaluate preconditions of the current class's
#   constructor and do not follow the mro.  See Meyer, Object Oriented
#   Software Construction, 2nd Edition, p. 466."
# 
#   ttw015 2007-08-31
#   Avoid building a list of methods for preconditions.
#
#   ttw016 2007-08-31
#   All installed checker functions return True, so they can be used
#   in contracts, ex: "pre: Base.method.__assert_pre(self, a, b)"
#
__author__ = "Terence Way"
__email__ = "terry@wayforward.net"
__version__ = "1.4: August 31, 2007"
MODULE = 'contract'

import new
import re
import sys
import tokenize

from cStringIO import StringIO
from types import *

# Programming-by-contract extends the language to include invariant
# expressions for classes, and pre-condition and post-condition
# expressions for methods.  These are very similar to assertions,
# expressions which must be true or the program is stopped.
#
# Class invariants are expressions which must be true at the end of a
# class's constructor, and at the beginning and end of each public
# method.
#
# Pre-conditions must be true at the start of each method.  Post-
# conditions must be true at the end of each method.  Post-condition
# logic has access to an 'old' variable which records variable values
# before they were changed by the method.
#
# This implementation tries to fix what I consider a defect in
# Eiffel's DBC -- while it is easy to specify what does change after
# invoking a method, it is impossible to specify what doesn't change.
# This makes it hard to reason about methods, and limits portability
# to more formal techniques such as Z.
#
# A simple fix is to declare what parts change.  Simply modify the
# line 'post:' to 'post [a]:' to declare that the variable a is the
# only thing changed by the sort function.  This is modelled after Z
# schemas [2].
#
# Simply saying 'post:' means anything can be changed: this is the
# original semantics of the Eiffel ENSURES statement.  Saying 'post
# []:' means nothing is changed.
#
# Python Specifications
# ---------------------
# The docstring of any module or class can have invariants documented
# by having the keyword 'inv' followed by a colon (:) at the start of
# a line.  Whitespace is ignored.  This is either followed by a single
# expression on the same line, or a series of expressions on following
# lines indented past the 'post' key- word.  The normal Python rules
# about implicit and explicit line continuations are followed here.
#
# To support Re-structured text, two colons (::) after the keyword is
# supported.
#
# Module invariants must be true at module load time, and at the entry
# and return of every public function within the module.
#
# Class invariants must be true after the __init__ function returns,
# and at the entry and return of every public method of the class.
#
# The docstring of any function or method can have pre-conditions
# documented with the keyword 'pre' following the same rules above,
# and can have post-conditions documented with the keyword 'post'
# optionally followed by a list of variables.  The variables are in
# the same scope as the body of the function or method.
#
# Expressions have access to some additional convenience values.  To
# make evaluating sequences easier, there are two functions: forall(a)
# and exists(a).  To make implication easier, there is a
# implies(x,a,b=True) function which mirrors C's conditional
# expression (x?a:c).
#
# The expressions in the post-conditions have access to two additional
# variables, __old__ which is filled with variables declared in the
# 'post' statement bound to shallow copies before the function or
# method is called; and __return__ which is bound to the return value
# of the function or method.
#
# Implementation
# --------------
# This module is divided into four parts:
#
# 1 -- Find docstrings and parse them for contract expressions...
#
#      This is accomplished by:
#      a. recursive enumerating elements in modules, classes using code
#         lifted from the 'inspect' Python standard module
#         see: checkmod, _check
#      b. scanning the docstrings of public functions with a regular
#         expression looking for lines that matches 'pre:' 'post:' or
#         'inv:' at the start
#         see: parse_docstring
#      c. Using the 'tokenize' Python tokenizer to build expressions
#         see: _read_block, _read_decl, _read_token
#
# 2 -- Construct functions that do contract checking...
#      This is done by just constructing big strings that are function
#      definitions.  Each function or method gets associated with four
#      'helper' functions... to check pre-conditions, to save old
#      values, to check post-conditions, and of course the saved
#      original code.  These are stored as function attributes.
#         see: _install_wrapper, _define_checker
#
# 3 -- Run-time support for call checking
#         see: call_public_function_*, call_private_function_*,
#              call_public_method_*, call_private_method_*,
#              call_constructor_*, call_destructor_*
#
# 4 -- Declarations for use within contract expressions
#      includes 'forall' 'exists' 'implies' and exception classes


# change the keywords here, if necessary
INV = 'inv'
PRE = 'pre'
POST = 'post'
TYPE_CONTRACTS = [INV]
CODE_CONTRACTS = [PRE, POST]
OLD = '__old__'
RETURN = '__return__'
PREFIX = '__assert_'

# enumeration to pass to checkmod: how extensive checking should be
CHECK_DEFAULT, CHECK_NONE, CHECK_PRECONDITIONS, CHECK_ALL = range(4)

_ORIG = 'orig'
_SAVE = 'save'
_CHK = 'chk'

_CONTRACTS = tuple(TYPE_CONTRACTS + CODE_CONTRACTS)

# look for word+ [expr] space* ':' at the start of a line
#
_re_start = re.compile(r'^\s*(%s|%s|%s)\s*(\[|:)' % _CONTRACTS,
                       re.MULTILINE)
_RE_KEYWORD = 1

# the tokenizer only seems to return OP(50) for any operators like : [ ] . ,
# we need to do a further lookup to get the operator value, but only for the
# tokens we care about
#
_OPS = {':': tokenize.COLON,
        '[': tokenize.LSQB,
        ']': tokenize.RSQB,
        '.': tokenize.DOT,
        ',': tokenize.COMMA}

_EXCEPTIONS = {PRE: 'PreconditionViolationError',
               POST: 'PostconditionViolationError',
               INV: 'InvariantViolationError'}

# ttw010 support pre 2.2.1...
try:
    bool, True, False = bool, True, False
except NameError:
    False, True = 0, 1
    def bool(x):
        return not not x
# ...ttw010

###############################################################################
# Part 1 -- Find docstrings and parse them for contract expressions...
#

def checkmod(module, checklevel = CHECK_DEFAULT):
    """Add invariant, pre- and post-condition checking to a module.

    pre::
        isstring(module) or isinstance(module, ModuleType)
        checklevel in [CHECK_DEFAULT, CHECK_NONE, CHECK_PRECONDITIONS,
                       CHECK_ALL]
    """
    # ttw009 string module names...
    if isinstance(module, StringType) or isinstance(module, UnicodeType):
	# ttw012 imports...
	__import__(module)
	module = sys.modules[module]
	# ...ttw012
    # ...ttw009

    # ttw008 partial contract enforcement...
    if checklevel == CHECK_DEFAULT:
        if __debug__:
            checklevel = CHECK_ALL
        else:
            checklevel = CHECK_PRECONDITIONS
    # ...ttw008

    if checklevel != CHECK_NONE:
        # get members *before* we start adding stuff to this module
        path = [module]
        members = _get_members(module, path)
        invs = parse_docstring(module.__doc__, TYPE_CONTRACTS)[0]
        name = PREFIX + INV
        func = getattr(module, name, None)
        # should we override
        if not func or func.__name__.startswith(PREFIX):
            if invs[2]:
                func = _define_checker(name, '', invs, path)
            else:
                func = __assert_inv
                module.__assert_inv = func
        _check_members(members, path, checklevel)
        # check module invariants now
        func()

def _check_type(code, path, checklevel):
    """Modify a class to add invariant checking.

    pre::
        isstring(code[0])
        type(code[1]) == code[2]
        isinstance(code[0], MethodType) or isinstance(code[0], FunctionType)
        isinstance(path[0], ModuleType)
        forall(path[1:], isclass)
    """
    name, obj = code

    # get members *before* we start adding stuff to this class
    path = path + [obj]
    members = _get_members(obj, path)
    invs = parse_docstring(obj.__doc__, TYPE_CONTRACTS)[0]
    if invs[2]:
        func = _define_checker(_mkname(path, INV), 'self', invs, path)
        setattr(obj, PREFIX + INV, func)
        delattr(path[0], func.func_name)
    _check_members(members, path, checklevel)

def _check_proc(code, path, checklevel):
    """Modify a module or class to add invariant checking.
    """
    name, obj = code
    _install_wrapper(code, parse_docstring(obj.__doc__, CODE_CONTRACTS), path,
                     is_public = _ispublic(name), checklevel = checklevel)

def _get_location(f):
    """Get function location as tuple (name, filename, lineno).

    pre::
        isinstance(f, MethodType) or isinstance(f, FunctionType)
    post[]::
        isstring(__return__[0])
        isstring(__return__[1])
        isinstance(__return__[2], int)
    """
    if isinstance(f, MethodType):
        f = f.im_func
    c = f.func_code
    return f.func_name, c.co_filename, c.co_firstlineno

def _get_members(obj, path):
    """Returns two lists (procs, types) where each list contains (name,
    value) tuples.

    For classes, only attributes defined by the specific class are returned,
    i.e. not inherited attributes.  Attributes created by this module
    (prefixed by '__assert_') are skipped as well.

    Examples:
    >>> import contract
    >>> path = [contract]
    >>> hasattr(contract, '_re_start')
    1
    >>> '_re_start' in [x[0] for x in _get_members(contract, path)[0]]
    0
    >>> '_get_members' in [x[0] for x in _get_members(contract, path)[0]]
    1
    >>> 'checkmod' in [x[0] for x in _get_members(contract, path)[0]]
    1
    >>> class base:
    ...     def foo(self): pass
    >>> class derived(base):
    ...     def bar(self): pass

    hasattr can get inherited attributes:
    >>> hasattr(derived, 'foo')
    1

    but we don't:
    >>> path = [__import__('__main__')]
    >>> 'foo' in [x[0] for x in _get_members(derived, path)[0]]
    0
    """
    module_name = path[0].__name__
    module_dict = path[0].__dict__
    parent = path[-1]
    procs = []
    types = []
    for key in obj.__dict__.keys():
        if not key.startswith(PREFIX):
            m = getattr(obj, key)
            # ttw004 only objects that belong to this module...
            if (isinstance(m, MethodType) and
                m.im_class is parent) or \
               (isinstance(m, FunctionType) and \
                m.func_globals is module_dict):
                procs.append((key, m))
            elif isclass(m) and getattr(m, '__module__', None) is module_name:
                types.append((key, m))
            # ...ttw004
    return (procs, types)

def _check_members((procs, types), path, checklevel):
    for p in procs:
        _check_proc(p, path, checklevel)
    for t in types:
        _check_type(t, path, checklevel)

def _ispublic(name):
    """Checks if a name is public (starts and ends with '__' or doesn't
    start with a _ at all).

    Examples:
    >>> _ispublic('__init__')
    1
    >>> _ispublic('foo')
    1
    >>> _ispublic('_ispublic')
    0
    """
    return not name.startswith('_') or \
        (name.startswith('__') and name.endswith('__'))

def parse_docstring(docstring, keywords):
    """Parse a docstring, looking for design-by-contract expressions.

    Returns a list of tuples: the list is the same length as keywords, and
    matches each keyword.  The tuple is (keyword, [decls], [exprs]), namely
    the keyword, a list of string declarations, and a list of tuples (string,
    lineno).

    Examples::
    >>> from pprint import pprint
    >>> pprint( parse_docstring(parse_docstring.__doc__, ['post', 'pre']) )
    [('post', [], [('[ x [ 0 ] for x in __return__ ] == keywords', 22)]),
     ('pre',
      [],
      [('docstring is None or isstring ( docstring )', 18),
       ('forall ( keywords , isstring )', 19)])]

    pre::
        docstring is None or isstring(docstring)
        forall(keywords, isstring)

    post[]::
        [x[0] for x in __return__] == keywords
    """
    result = [(x, [], []) for x in keywords]

    if docstring is None:
        return result

    # step 1: scan through docstring looking for keyword
    input = StringIO(docstring)

    offset = 0
    assert input.tell() == 0

    line = input.readline()
    lineno = 0 # zero-origined because tokenizer keeps 1-origined
    while line != '':
        a = _re_start.split(line)

        if len(a) > _RE_KEYWORD and a[_RE_KEYWORD] in keywords:
            # step 2: found a keyword, now rewind and scan looking
            # for either an inline expression or a series of sub-
            # indented expressions
            input.seek(offset)

            # ttw005... get lineno info and add to exception's lineno
            #           if a TokenError occurs...
            try:
                l = _read_block(input, lineno)
                lineno = l[3]
                # returns (keyword, decls, exprs, lineno)
            except tokenize.TokenError, ex:
                # reformat to include new line info
                raise tokenize.TokenError(ex[0],
                                          (lineno + ex[1][0],) + ex[1][1:])
            # ...ttw005

            # Find the right result index based on keyword
            r = result[keywords.index(l[0])]
            r[1].extend(l[1])
            r[2].extend(l[2])
        else:
            lineno += 1
        if offset == input.tell(): break
        offset = input.tell()
        line = input.readline()
    return result

# ttw011 refactor tokenize parser to use older tokenize.tokenize()...
#
# [INDENT] NAME
# [LSQB (NAME (DOT NAME)* (COMMA NAME (DOT NAME)*)*)* RSQB]
# COLON [COLON]
# (NEWLINE INDENT (not DEDENT)*) | (not NEWLINE)*

class Done(Exception): pass

class tokenizer:
    def __init__(self, input, startlineno):
        self.input = input
        self.startlineno = startlineno
        self.endlineno = self.lineno = startlineno + 1
        self.state = self.start
        self.decl, self.decls, self.expr, self.exprs = [], [], [], []
        self.keyword, self.offset = '', input.tell()

    def next(self, token, string, start, end, line):
        if token != tokenize.COMMENT and token != tokenize.NL:
            if token == tokenize.OP and _OPS.has_key(string):
                token = _OPS[string]
            self.state(token, string)
        if token == tokenize.NEWLINE or token == tokenize.NL:
            self.lineno = self.startlineno + start[0] + 1

    # all following methods are states in the state machine.
    # the self.state variable indicates which function/state we're in
    def start(self, token, string):
        if token == tokenize.INDENT:
            self.state = self.indent
        else:
            self.indent(token, string)

    def indent(self, token, string):
        if token == tokenize.NAME:
            self.keyword = string
            self.state = self.name
        else:
            raise SyntaxError("expected pre, post, or inv")

    def name(self, token, string):
        if token == tokenize.LSQB:
            self.state = self.decl0
        else:
            self.colon(token, string)

    def decl0(self, token, string):
        if token == tokenize.NAME:
            self.decl.append(string)
            self.state = self.decl1
        elif token == tokenize.RSQB:
            self.state = self.colon
        else:
            raise SyntaxError("expected variable name or ]")

    def decl1(self, token, string):
        if token == tokenize.DOT:
            self.state = self.decln
        elif token == tokenize.COMMA:
            self.decls.append(self.decl)
            self.decl = []
            self.state = self.decln
        elif token == tokenize.RSQB:
            self.decls.append(self.decl)
            self.state = self.colon
        else:
            raise SyntaxError("expected one of (,.])")

    def decln(self, token, string):
        if token == tokenize.NAME:
            self.decl.append(string)
            self.state = self.decl1
        else:
            raise SyntaxError("expected name")

    def colon(self, token, string):
        if token == tokenize.COLON:
            self.state = self.colon1
        else:
            raise SyntaxError("expected colon(:)")

    def colon1(self, token, string):
        if token == tokenize.COLON:
            self.state = self.colon2
        else:
            self.colon2(token, string)

    def colon2(self, token, string):
        if token == tokenize.NEWLINE:
            self.state = self.newline
        else:
            self.endtoken = tokenize.NEWLINE
            self.state = self.rest
            self.rest(token, string)

    def newline(self, token, string):
        if token == tokenize.INDENT:
            self.endtoken = tokenize.DEDENT
            self.state = self.rest
        else:
            raise IndentationError("expected an indented block")

    def rest(self, token, string):
        if token == self.endtoken or token == tokenize.ENDMARKER:
            if self.expr:
                self.exprs.append( (' '.join(self.expr), self.lineno) )
            raise Done()
        self.offset, self.endlineno = self.input.tell(), self.lineno
        if token == tokenize.NEWLINE:
            self.exprs.append( (' '.join(self.expr), self.lineno) )
            self.expr = []
        else:
            self.expr.append(string)

def _read_block(input, startlineno):
    r"""Read an indented block of expressions

    startlineno is *zero* origined line number.

    pre::
        input.readline  # must have readline function

    Examples:
    #>>> _read_block(StringIO('\tfoo:\n'), 0)
    #0
    >>> _read_block(StringIO('\tpost[]: True\n'), 0)
    ('post', [], [('True', 1)], 1)
    >>> _read_block(StringIO('\tpre: 5 + 6 > 10\n'), 0)
    ('pre', [], [('5 + 6 > 10', 1)], 1)
    >>> _read_block(StringIO('\tpost:\n\t\t5 + 6 < 12\n\t\t2 + 2 == 4\n'), 0)
    ('post', [], [('5 + 6 < 12', 2), ('2 + 2 == 4', 3)], 3)
    >>> _read_block(StringIO('\tpost[foo.bar]: # changes\n' \
    ...                      '\t\tlen(foo.bar) > 0\n'), 0)
    ('post', [['foo', 'bar']], [('len ( foo . bar ) > 0', 2)], 2)

    Handles double colons (for re-structured text)::
    >>> _read_block(StringIO('\tpre:: 5 + 6 > 10\n'), 0)
    ('pre', [], [('5 + 6 > 10', 1)], 1)
    """
    t = tokenizer(input, startlineno)
    try:
        tokenize.tokenize(input.readline, t.next)
    except Done:
        pass
    input.seek(t.offset)
    return (t.keyword, t.decls, t.exprs, t.endlineno)
# ...ttw011

# ...part 1
###############################################################################

###############################################################################
# Part 2 -- Construct functions that do contract checking...
#
def _install_wrapper(code, contracts, path, is_public, checklevel):
    """Creates and installs a function/method checker.

    pre::
        contracts[0][0] == PRE and contracts[1][0] == POST
        isinstance(path[0], ModuleType)
        forall(path[1:], isclass)
    """
    name, obj = code

    newpath = path + [obj]

    ismethod = isinstance(obj, MethodType)

    if ismethod:
        func = obj.im_func
        invs = hasattr(path[-1], PREFIX + INV)
    else:
        func = obj
        invs = hasattr(path[0], PREFIX + INV)

    # we must create a checker if:
    #  1. there are any pre-conditions or any post-conditions OR
    #  2. this is public AND there are invariants
    # ttw013...
    #  3. this is a method call, to check any super-class method
    #     conditions
    # ...ttw003
    if ismethod or contracts[0][2] or contracts[1][2] or (is_public and invs):
        argspec = getargspec(func)
        args = _format_args(argspec)

        # argl: argument list suitable for appending at the end of other args
        if args:
            argl = ', ' + args
        else:
            argl = args

        output = StringIO()

        output.write('def %s(%s):\n' % (_mkname(path, name, _CHK), args))
        output.write('\timport %s\n' % MODULE)

        classname = '.'.join([c.__name__ for c in path[1:]])

        if isinstance(obj, FunctionType):
            if is_public:
                chkname, chkargs = 'call_public_function', '__assert_inv, '
            else:
                chkname, chkargs = 'call_private_function', ''
        else:
            if not is_public:
                chkname = 'call_private_method'
            elif name == '__init__':
                chkname = 'call_constructor'
            elif name == '__del__':
                chkname = 'call_destructor'
            else:
                chkname = 'call_public_method'
            chkargs = classname + ', '

        # ttw008 partial contract enforcement...
        if checklevel == CHECK_ALL:
            suffix = '_all'
        else:
            suffix = '_pre'
        # ...ttw008

        output.write('\treturn %s.%s%s(%s' % (MODULE, chkname, suffix,
                                              chkargs))
        if classname:
            output.write(classname)
            output.write('.')
        output.write(name)
        output.write(argl)
        output.write(')\n')

        newfunc = _define(_mkname(path, name, _CHK), output.getvalue(),
                          path[0])

        # if there are default arguments
        if argspec[3]:
            # install the default arguments... don't try to put them into
            # our printed function definition, above, as they have already
            # been evaluated.
            newfunc = new.function(newfunc.func_code, newfunc.func_globals,
                                   newfunc.func_name, argspec[3])

        setattr(newfunc, PREFIX + _ORIG, getattr(func, PREFIX + _ORIG, func))

        # write preconditions checker
        if contracts[0][2]:
            pre = _define_checker(_mkname(path, name, contracts[0][0]), args,
                                  contracts[0], newpath)

            delattr(path[0], pre.func_name)
            setattr(newfunc, PREFIX + contracts[0][0], pre)

        if checklevel == CHECK_ALL:
            # write __old__ saver
            if contracts[1][1]:
                saver = _define_saver(_mkname(path, name, _SAVE), OLD + argl,
                                      contracts[1][1], path[0])
                delattr(path[0], saver.func_name)
                setattr(newfunc, PREFIX + _SAVE, saver)

            # write postconditions checker
            if contracts[1][2]:
                post = _define_checker(_mkname(path, name, contracts[1][0]),
                                       OLD + ', ' + RETURN + argl,
                                       contracts[1], newpath)

                delattr(path[0], post.func_name)
                setattr(newfunc, PREFIX + contracts[1][0], post)

        newname = newfunc.func_name
        newfunc.__doc__ = obj.__doc__

        if isclass(path[-1]) and isinstance(obj, FunctionType):
            # static method
            newfunc = staticmethod(newfunc)

        setattr(path[-1], name, newfunc)

        if name != newname or len(path) > 1:
            delattr(path[0], newname)
    # end _install_wrapper

def isclass(obj):
    return isinstance(obj, TypeType) or isinstance(obj, ClassType)

def isstring(obj):
    return isinstance(obj, StringType) or isinstance(obj, UnicodeType)

def _define_checker(name, args, contract, path):
    """Define a function that does contract assertion checking.

    args is a string argument declaration (ex: 'a, b, c = 1, *va, **ka')
    contract is an element of the contracts list returned by parse_docstring
    module is the containing module (not parent class)

    Returns the newly-defined function.

    pre::
        isstring(name)
        isstring(args)
        contract[0] in _CONTRACTS
        len(contract[2]) > 0
    post::
        isinstance(__return__, FunctionType)
        __return__.__name__ == name
    """
    output = StringIO()
    output.write('def %s(%s):\n' % (name, args))
    # ttw001... raise new exception classes
    ex = _EXCEPTIONS.get(contract[0], 'ContractViolationError')
    output.write('\tfrom %s import forall, exists, implies, %s\n' % \
                 (MODULE, ex))
    loc = '.'.join([x.__name__ for x in path])
    for c in contract[2]:
        output.write('\tif not (')
        output.write(c[0])
        output.write('): raise %s("%s", %u)\n' % (ex, loc, c[1]))
    # ...ttw001

    # ttw016: return True for superclasses to use in preconditions
    output.write('\treturn True')
    # ...ttw016

    return _define(name, output.getvalue(), path[0])

def _define_saver(name, args, decls, module):
    """Create a function that saves values into an __old__ variable.

    pre:: decls
    post:: isinstance(__return__, FunctionType)
    """
    output = StringIO()
    output.write('def %s(%s):\n' % (name, args))
    output.write('\timport %s, copy\n' % MODULE)

    _save_decls(output, '', _decltodict(decls))

    return _define(name, output.getvalue(), module)

def _define(name, text, module):
    #print text
    exec text in vars(module)
    return getattr(module, name)

def _format_args( (arguments, rest, keywords, default_values) ):
    """Formats an argument desc into a string suitable for both a function/
    method declaration or a function call.

    This does *not* handle default arguments.  Default arguments are already
    evaluated... use new.function() to create a function with pre-evaluated
    default arguments.

    Examples:
    >>> def foo(a, (b, c), d = 1, e = 2, *va, **ka):
    ...     pass
    >>> a = getargspec(foo)
    >>> a
    (['a', '(b, c)', 'd', 'e'], 'va', 'ka', (1, 2))
    >>> _format_args(a)
    'a, (b, c), d, e, *va, **ka'

    pre::
        isinstance(arguments, list)
        rest is None or isstring(rest)
        keywords is None or isstring(keywords)
    post[]:: True
    """
    if rest is not None: arguments = arguments + ['*' + rest]
    if keywords is not None: arguments = arguments + ['**' + keywords]
    return ', '.join(arguments)

CO_VARARGS, CO_VARKEYWORDS = 4, 8

try:
    import inspect

    def _format_arg(a):
        """Convert an argument list into a tuple string.

        >>> _format_arg(['a', 'b', 'c'])
        '(a, b, c)'
        >>> _format_arg(['a', ['b', 'c', 'd']])
        '(a, (b, c, d))'
        >>> _format_arg(['a'])
        '(a,)'
        >>> _format_arg('a')
        'a'
        """
        if isinstance(a, ListType):
            if len(a) == 1:
                return '(' + _format_arg(a[0]) + ',)'
            else:
                return '(' + ', '.join([_format_arg(z) for z in a]) + ')'
        else:
            return a

    def _getargs(function):
        t = inspect.getargspec(function)
        return ([_format_arg(a) for a in t[0]], t[1], t[2], t[3])

    getmro = inspect.getmro

except ImportError:
    # inspect module not available, on say Jython 2.1
    def _getargs(function):
        code = function.func_code
        i = code.co_argcount
        args = list(code.co_varnames[:i])
        if code.co_flags & CO_VARARGS:
            va = code.co_varnames[i]
            i += 1
        else:
            va = None
        if code.co_flags & CO_VARKEYWORDS:
            ka = code.co_varnames[i]
            i += 1
        else:
            ka = None
        return (args, va, ka, function.func_defaults)

    def _searchbases(cls, accum):
        # Simulate the "classic class" search order.
        if cls in accum:
            return
        accum.append(cls)
        for base in cls.__bases__:
            _searchbases(base, accum)

    def getmro(cls):
        """Return tuple of base classes (including cls) in method resolution
        order."""
        if hasattr(cls, "__mro__"):
            return cls.__mro__
        else:
            result = []
            _searchbases(cls, result)
            return tuple(result)

def getargspec(function):
    """Get argument information about a function.

    Returns a tuple (args, varargs, keywordvarargs, defaults) where
    args is a list of strings, varargs is None or the name of the
    *va argument, keywordvarargs is None or the name of the **ka
    argument, and defaults is a list of default values.

    This function is different from the Python-provided
    inspect.getargspec in that 1) tuple arguments are returned as
    a string grouping '(a, b, c)' instead of broken out "['a', 'b', 'c']"
    and 2) it works in Jython, which doesn't support inspect (yet).

    >>> getargspec(lambda a, b: a * b)
    (['a', 'b'], None, None, None)
    >>> getargspec(lambda a, (b, c, d) = (5, 6, 7), *va, **ka: a * b)
    (['a', '(b, c, d)'], 'va', 'ka', ((5, 6, 7),))

    pre::
        isinstance(function, FunctionType)
    post[]::
        # tuple of form (args, va, ka, defaults)
        isinstance(__return__, TupleType) and len(__return__) == 4
        # args is a list of strings
        isinstance(__return__[0], ListType)
        forall(__return__[0], isstring)
        # va is None or a string
        __return__[1] is None or isstring(__return__[1])
        # ka is None or a string
        __return__[2] is None or isstring(__return__[2])
        # defaults is None or a tuple
        __return__[3] is None or isinstance(__return__[3], TupleType)
    """
    return _getargs(function)

def _mkname(path, *va):
    """Define a name combining a path and arbitrary strings.

    pre::
       isinstance(path[0], ModuleType)
       forall(path[1:], isclass)

    Examples:
    >>> import contract
    >>> _mkname([contract], 'test')
    '__assert_test'
    >>> class foo:
    ...     pass
    >>> _mkname([contract, foo], 'func', 'pre')
    '__assert_foo_func_pre'
    """
    return PREFIX + '_'.join([c.__name__ for c in path[1:]] + list(va))

def _save_decls(output, name, d):
    """Recursively output a dictionary into a set of 'old' assignments.

    The dictionary d is a tree of variable declarations.  So, for example,
    the declaration [self, self.buf, self.obj.a] would turn into the dict
    {'self': {'buf': {}, 'obj': {'a': {}}}}, and would get output as
        __old__.self = contract._holder()
        __old__.self.buf = copy.copy(self.buf)
        __old__.self.obj = contract._holder()
        __old__.self.obj.a = copy.copy(self.obj.a)
    """
    for k, v in d.items():
        n = name + k
        output.write('\t%s.%s = ' % (OLD, n))
        if v == {}:
            output.write('copy.copy(%s)\n' % n)
        else:
            output.write('%s._holder()\n' % MODULE)
            _save_decls(output, n + '.', v)

def _decltodict(l):
    """Converts a list of list of names into a hierarchy of dictionaries.

    Examples:
    >>> d = _decltodict([['self', 'buf'],
    ...                  ['self', 'item', 'a'],
    ...                  ['self', 'item', 'b']])
    >>> d == {'self': {'buf': {}, 'item': {'a': {}, 'b': {}}}}
    1
    """
    result = {}
    for i in l:
        d = result
        for n in i:
            # n in d ? d[n] : d[n] = {}
            d = d.setdefault(n, {})
    return result

#
# ...part 2
###############################################################################

###############################################################################
# Part 3... Run-time support for call checking
#

#####################################
# ttw001 add new assertion classes...
class ContractViolationError(AssertionError):
    pass

class PreconditionViolationError(ContractViolationError):
    pass

class PostconditionViolationError(ContractViolationError):
    pass

class InvariantViolationError(ContractViolationError):
    pass
# ...ttw001
#####################################

# ttw006 correctly weaken pre-conditions...
class InvalidPreconditionError(ContractViolationError):
    """Method pre-conditions can only weaken overridden methods'
    preconditions.
    """
    pass
# ...ttw006

# ttw008 partial contract enforcement

# these are 'drivers': functions which check contracts and call the
# original wrapped functions.  Each driver has two variants: one for
# CHECK_PRECONDITIONS and one for CHECK_ALL: the CHECK_ALL checks
# preconditions and invariants on entry, and postconditions and
# invariants on exit.  The CHECK_PRECONDITIONS only checks pre-
# conditions and invariants on entry.  There needs to be a driver
# for public and private functions, public and private methods, and
# constructors and destructors.  Hence:
#   call_public_function_pre/call_public_function_all
#       checks module invariants and function pre[post] conditions
#   call_private_function_pre/call_private_function_all
#       checks function pre[post] conditions
#   call_public_method_pre/call_public_method_all
#       checks class/type invariants and method pre[post] conditions
#   call_private_method_pre/call_private_method_all
#       checks method pre[post] conditions
#   call_constructor_pre/call_constructor_all
#       checks method pre-conditions [type/class invariants and post-
#       conditions on exit]
#   call_destructor_pre/call_destructor_all
#       checks method pre-conditions and class/type invariants on entry.

def call_public_function_all(inv, func, *va, **ka):
    """Check the invocation of a public function or static method.

    Checks module invariants on entry and exit.  Checks any
    pre-conditions and post-conditions.
    """
    inv()
    try:
        # ttw015: avoid making a list of functions...
        return _call_one_all(func, va, ka)
        # ...ttw015
    finally:
        inv()

def call_public_function_pre(inv, func, *va, **ka):
    """Check the invocation of a public function or static method.

    Checks module invariants on entry.  Checks any pre-conditions.
    """
    inv()
    # ttw015: avoid making a list of functions...
    return _call_one_pre(func, va, ka)
    # ...ttw015

def call_private_function_all(func, *va, **ka):
    """Check the invocation of a private function or static method.

    Only checks pre-conditions and post-conditions.
    """
    # ttw015: avoid making a list of functions...
    return _call_one_all(func, va, ka)
    # ...ttw015

def call_private_function_pre(func, *va, **ka):
    """Check the invocation of a private function or static method.

    Only checks pre-conditions
    """
    # ttw015: avoid making a list of functions...
    return _call_one_pre(func, va, ka)
    # ...ttw015

def call_public_method_all(cls, method, *va, **ka):
    """Check the invocation of a public method.

    Check this class and all super-classes invariants on entry and
    exit.  Checks all post-conditions of this method and all over-
    ridden method.
    """
    mro = getmro(cls)
    _check_class_invariants(mro, va[0])
    try:
        return _method_call_all(mro, method, va, ka)
    finally:
        _check_class_invariants(mro, va[0])

def call_public_method_pre(cls, method, *va, **ka):
    """Check the invocation of a public method.

    Check this class and all super-classes invariants on entry.
    exit.
    """
    mro = getmro(cls)
    _check_class_invariants(mro, va[0])
    return _method_call_pre(mro, method, va, ka)

def call_constructor_all(cls, method, *va, **ka):
    """Check the invocation of an __init__ constructor.

    Checks pre-conditions and post-conditions, and only checks
    invariants on successful completion.
    """
    # ttw003 invariants mustn't be checked if constructor raises exception...

    # ab001 fix handling of constructor preconditions...
    # mro = getmro(cls)
    # result = _method_call_all(mro, method, va, ka)
    # _check_class_invariants(mro, va[0])
    result = _method_call_all([cls], method, va, ka)
    _check_class_invariants(getmro(cls), va[0])
    # ...ab001

    return result
    # ...ttw003

def call_constructor_pre(cls, method, *va, **ka):
    """Check the invocation of an __init__ constructor.

    Checks pre-conditions and post-conditions, and only checks
    invariants on successful completion.
    """
    # ttw003 invariants mustn't be checked if constructor raises exception...

    # ab001 fix handling of constructor preconditions...
    # mro = getmro(cls)
    # result = _method_call_pre(mro, method, va, ka)
    # _check_class_invariants(mro, va[0])
    result = _method_call_pre([cls], method, va, ka)
    _check_class_invariants(getmro(cls), va[0])
    # ...ab001

    return result
    # ...ttw003

def call_destructor_all(cls, method, *va, **ka):
    """Check the invocation of a __del__ destructor.

    Checks pre-conditions and post-conditions, and only checks
    invariants on entry.
    """
    mro = getmro(cls)
    _check_class_invariants(mro, va[0])
    return _method_call_all(mro, method, va, ka)

def call_destructor_pre(cls, method, *va, **ka):
    """Check the invocation of a __del__ destructor.

    Checks pre-conditions and post-conditions, and only checks
    invariants on entry.
    """
    mro = getmro(cls)
    _check_class_invariants(mro, va[0])
    return _method_call_pre(mro, method, va, ka)

def call_private_method_all(cls, method, *va, **ka):
    """Check the invocation of a private method call.

    Checks pre-conditions and post-conditions.
    """
    return _method_call_all(getmro(cls), method, va, ka)

def call_private_method_pre(cls, method, *va, **ka):
    """Check the invocation of a private method call.

    Checks pre-conditions.
    """
    return _method_call_pre(getmro(cls), method, va, ka)

def _check_class_invariants(mro, instance):
    """Checks class invariants on an instance.

    mro - list of classes in method-resolution order
    instance - object to test

    pre::
        # instance must be an instance of each class in mro
        forall(mro, lambda x: isinstance(instance, x))
    """
    # ab002: Avoid generating AttributeError exceptions...
    for c in mro:
        if hasattr(c, '__assert_inv'):
            c.__assert_inv(instance)
    # ...ab002

def _method_call_all(mro, method, va, ka):
    """Check the invocation of a method.

    mro -- list/tuple of class objects in method resolution order
    """
    # NO CONTRACTS... recursion
    assert isinstance(method, MethodType)

    func = method.im_func
    name = func.__assert_orig.__name__
    # list of all method functions with name
    a = [getattr(c, name).im_func for c in mro if _has_method(c, name)]

    return _call_all(a, func, va, ka)

def _method_call_pre(mro, method, va, ka):
    """Check the invocation of a method.

    mro -- list/tuple of class objects in method resolution order
    """
    # NO CONTRACTS... recursion
    func = method.im_func
    name = func.__assert_orig.__name__
    # list of all method functions with name
    a = [getattr(c, name).im_func for c in mro if _has_method(c, name)]

    return _call_pre(a, func, va, ka)

def _call_one_all(func, va, ka):
    if hasattr(func, '__assert_pre'):
        func.__assert_pre(*va, **ka)

    # save old values
    old = _holder()

    if hasattr(func, '__assert_save'):
        func.__assert_save(old, *va, **ka)

    result = func.__assert_orig(*va, **ka)
    # check post-conditions
    if hasattr(func, '__assert_post'):
        func.__assert_post(old, result, *va, **ka)

    return result

def _call_one_pre(func, va, ka):
    if hasattr(func, '__assert_pre'):
        func.__assert_pre(*va, **ka)

    return func.__assert_orig(*va, **ka)

def _call_all(a, func, va, ka):
    _check_preconditions(a, func, va, ka)

    # save old values
    old = _holder()

    # ab002: Avoid generating AttributeError exceptions...
    for f in a:
        if hasattr(f, '__assert_save'):
            f.__assert_save(old, *va, **ka)

    result = func.__assert_orig(*va, **ka)
    for f in a:
        # check post-conditions
        if hasattr(f, '__assert_post'):
            f.__assert_post(old, result, *va, **ka)
    # ...ab002

    return result

def _call_pre(a, func, va, ka):
    _check_preconditions(a, func, va, ka)
    return func.__assert_orig(*va, **ka)

def _check_preconditions(a, func, va, ka):
    # ttw006: correctly weaken pre-conditions...
    # ab002: Avoid generating AttributeError exceptions...
    if hasattr(func, '__assert_pre'):
        try:
            func.__assert_pre(*va, **ka)
        except PreconditionViolationError, args:
            # if the pre-conditions fail, *all* super-preconditions
            # must fail too, otherwise
            for f in a:
                if f is not func and hasattr(f, '__assert_pre'):
                    f.__assert_pre(*va, **ka)
                    raise InvalidPreconditionError(args)
            # rr001: raise original PreconditionViolationError, not
            # inner AttributeError...
            # raise
            raise args
            # ...rr001
    # ...ab002
    # ...ttw006

def _has_method(cls, name):
    """Test if a class has a named method.

    pre::
        isclass(cls)
        isstring(name)
    post:: __return__ == (hasattr(cls, name) and \
                         isinstance(getattr(cls, name), MethodType))
    """
    return isinstance(getattr(cls, name, None), MethodType)

def __assert_inv():
    """Empty invariant assertions
    """
    pass

# ...part 3
###############################################################################

###############################################################################
# Part 4 -- Declarations for use within contract expressions...
#
def forall(a, fn = bool):
    """Checks that all elements in a sequence are true.

    Returns True(1) if all elements are true.  Return False(0) otherwise.

    Examples:
    >>> forall([True, True, True])
    1
    >>> forall( () )
    1
    >>> forall([True, True, False, True])
    0
    """
    for i in a:
        if not fn(i):
            return False
    return True

def exists(a, fn = bool):
    """Checks that at least one element in a sequence is true.

    Returns True(1) if at least one element is true.  Return False(0)
    otherwise.

    Examples:
    >>> exists([False, False, True])
    1
    >>> exists([])
    0
    >>> exists([False, 0, '', []])
    0
    """
    for i in a:
       if fn(i):
           return True
    return False

def implies(test, then_val, else_val = True):
    """Logical implication.

    implies(x, y) should be read 'x implies y' or 'if x then y'
    implies(x, a, b) should be read 'if x then a else b'

    Examples:
    >>> implies(False, False)
    1
    >>> implies(False, True)
    1
    >>> implies(True, False)
    0
    >>> implies(True, True)
    1
    """
    if test:
        return then_val
    else:
        return else_val

class _holder:
    """Placeholder for arbitrary 'old' values.
    """
    pass

#
# ...part 4
###############################################################################

__test__ = {
    '_ispublic': _ispublic, '_get_members': _get_members,
    '_decltodict': _decltodict, '_read_block': _read_block,
    '_format_args': _format_args, '_mkname': _mkname}

if __name__ == '__main__':
    import doctest, contract
    #contract.checkmod(contract)
    doctest.testmod(contract)