<commit_before>#!/usr/bin/python
"""
Design by Contract in Python.

@description: This project enables to use the basics of Design by Contract capabilities in Python,
              such as enforcing the contracts defined in the epydoc documentation.

@copyright: <NAME> <<EMAIL>>

@url: http://code.google.com/p/python-dbc/
"""

from itertools import izip, chain
import inspect


def typed(var, types):
    """
    Ensure that the "var" argument is among the types passed as the "types" argument.

    @param var: The argument to be typed.

    @param types: A tuple of types to check.
    @type types: tuple

    @returns: The var argument.
    """
    assert isinstance(var, types), \
        "Variable %s of type %s not among the allowed types: %s" % (var, type(var), repr(types))
    return var


def ntyped(var, types):
    """
    Ensure that the "var" argument is among the types passed as the "types" argument, or is None.

    @param var: The argument to be typed.

    @param types: A tuple of types to check.
    @type types: tuple

    @returns: The var argument.

    >>> ntyped(5, int)
    5
    >>> ntyped(5, str)
    Traceback (most recent call last):
       ...
    AssertionError: Variable 5 of type <type 'int'> not among the allowed types: NoneType, <type 'str'>

    """
    assert var is None or isinstance(var, types), \
        "Variable %s of type %s not among the allowed types: NoneType, %s" % (var, type(var), repr(types))
    return var


def epydoc_contract(f):
    """
    The decorator for any functions which have a epydoc-formatted docstring.
    It validates the function inputs and output against the contract defined by the epydoc description.

    Currently, it supports the usual functions as well as simple object methods
    (though neither classmethods nor staticmethods).

    Inside the epydoc contracts, it supports the following fields:

    - C{@type arg:} - the type of the C{arg} argument is validated before the function is called.

    - C{@rtype:} - the return type of the function is validated after the function is called.
<commit_msg>Added some doctests, and the new convenient function consists_of().<commit_after>#!/usr/bin/python
"""
Design by Contract in Python.

@description: This project enables to use the basics of Design by Contract capabilities in Python,
              such as enforcing the contracts defined in the epydoc documentation.

@copyright: <NAME> <<EMAIL>>

@url: http://code.google.com/p/python-dbc/
"""

from itertools import izip, chain
import inspect


def typed(var, types):
    """
    Ensure that the "var" argument is among the types passed as the "types" argument.

    @param var: The argument to be typed.

    @param types: A tuple of types to check.
    @type types: tuple

    @returns: The var argument.

    >>> a = typed("abc", str)
    >>> type(a)
    <type 'str'>

    >>> b = typed("abc", int) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    Traceback (most recent call last):
      ...
    AssertionError: Variable abc of type <type 'str'> not among the allowed types: <type 'int'>

    >>> c = typed(None, int) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    Traceback (most recent call last):
      ...
    AssertionError: Variable None of type <type 'NoneType'> not among the allowed types: <type 'int'>
    """
    assert isinstance(var, types), \
        "Variable %s of type %s not among the allowed types: %s" % (var, type(var), repr(types))
    return var


def ntyped(var, types):
    """
    Ensure that the "var" argument is among the types passed as the "types" argument, or is None.

    @param var: The argument to be typed.

    @param types: A tuple of types to check.
    @type types: tuple

    @returns: The var argument.

    >>> a = ntyped("abc", str)
    >>> type(a)
    <type 'str'>

    >>> b = ntyped("abc", int) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    Traceback (most recent call last):
      ...
    AssertionError: Variable abc of type <type 'str'> not among the allowed types: NoneType, <type 'int'>

    >>> c = ntyped(None, int) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    """
    assert var is None or isinstance(var, types), \
        "Variable %s of type %s not among the allowed types: NoneType, %s" % (var, type(var), repr(types))
    return var


def consists_of(seq, types):
    """
    Check that the all elements from the "seq" argument (sequence) are among the types passed as the "types" argument.

    @param seq: The sequence which elements are to be typed.

    @param types: A tuple of types to check.
    @type types: tuple

    @return: Whether the check succeeded.
    @rtype: bool

    >>> consists_of([5, 6, 7], int)
    True
    >>> consists_of([5, 6, 7, "abc"], int)
    False
    >>> consists_of([5, 6, 7, "abc"], (int, str))
    True
    """
    return all(isinstance(element, types) for element in seq)


def epydoc_contract(f):
    """
    The decorator for any functions which have a epydoc-formatted docstring.
    It validates the function inputs and output against the contract defined by the epydoc description.

    Currently, it supports the usual functions as well as simple object methods
    (though neither classmethods nor staticmethods).

    Inside the epydoc contracts, it supports the following fields:

    - C{@type arg:} - the type of the C{arg} argument is validated before the function is called.

    - C{@rtype:} - the return type of the function is validated after the function is called.

{'fraction_non_alphanumeric': 0.1043605181536216, 'fraction_numerical': 0.0023718299580368545, 'mean_word_length': 3.1094452773613193, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 58, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1701836', 'n_tokens_mistral': 1646, 'n_tokens_neox': 1590, 'n_words': 700}