import repository from arizona
[raven.git] / lib / ravenlib / typecheck.py
1 """
2    Type checking for python functions
3
4    intended usage:
5       def foo(some_integer, some_string, some_list, some_string_list):
6           ravenlib.typecheck.simple(some_integer, "some_integer", int, "foo")
7           ravenlib.typecheck.simple(some_string, "some_string", str, "foo")
8           ravenlib.typecheck.simple(some_list, "some_list", list, "foo")
9           ravenlib.typecheck.stringlist(some_string_list, "some_string_list", "foo")
10 """
11
12 def simple(variable, parameter_name, expected_type, function_name, noneok=False):
13    """
14    <Purpose>
15       Checks the actual type of variable against the expected type, and
16       raises a TypeError if variable is of a type other than expected.
17       This function accepts only a limited amount of functionality in
18       order to increase its speed.  Does not check its own input, so must
19       be called correctly.
20
21    <Author>
22       Jeffry Johnston
23
24    <Arguments>
25       variable:
26               Variable to check the type of.  Can be anything.
27       parameter_name:
28               Name of the function parameter being tested, as a string.
29               Used for error reporting.
30       expected_type:
31               The expected variable type (int, str, dict, ...)
32       function_name:
33               Name of the called function, as a string.  Used for error
34               reporting.
35
36    <Exceptions>
37       TypeError if a type mismatch or parameter error is detected.
38
39    <Side Effects>
40       None.
41
42    <Returns>
43       None.
44    """
45    if not isinstance(variable, expected_type) and (not noneok or variable != None):
46       raise TypeError, "Incorrect type passed to parameter '" + \
47             parameter_name + "' of function '" + \
48             function_name + "'.  Received the type: '" + \
49             str(type(variable)).split("'")[1] + "' (with value: " + \
50             str(variable) + \
51             "), but expected to receive a type matching the pattern: '" + \
52             str(expected_type) + "'."
53
54 def stringlist(variable, parameter_name, function_name):
55    """
56    <Purpose>
57       Checks the actual type of variable to see if it is a list containing
58       either nothing, or containing strings (or unicodes) only.  Raises a
59       TypeError if variable is of a type other than expected.  Does not
60       check its own input, so must be called correctly.
61
62    <Author>
63       Jeffry Johnston
64
65    <Arguments>
66       variable:
67               Variable to check the type of.  Can be anything.
68       parameter_name:
69               Name of the function parameter being tested, as a string.
70               Used for error reporting.
71       function_name:
72               Name of the called function, as a string.  Used for error
73               reporting.
74
75    <Exceptions>
76       TypeError if a type mismatch or parameter error is detected.
77
78    <Side Effects>
79       None.
80
81    <Returns>
82       None.
83    """
84    # is it a list?
85    if not isinstance(variable, list):
86       raise TypeError, "Incorrect type passed to parameter '" + \
87             parameter_name + "' of function '" + \
88             function_name + "'.  Received the type: '" + \
89             str(type(variable)).split("'")[1] + "' (with value: " + \
90             str(variable) + \
91             "), but expected to receive a string list."
92
93    # empty list?
94    if not variable:
95       return
96
97    # iterate over values, check for strings
98    for item in variable:
99       if not isinstance(item, str) and not isinstance(item, unicode):
100          raise TypeError, "Incorrect type passed to parameter '" + \
101                parameter_name + "' of function '" + \
102                function_name + "'.  Received the type: '" + \
103                str(type(variable)).split("'")[1] + "' (with value: " + \
104                str(variable) + \
105                "), but expected to receive a string list."