1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 """Common utility library."""
19
20 __author__ = ['rafek@google.com (Rafe Kaplan)',
21 'guido@google.com (Guido van Rossum)',
22 ]
23 __all__ = [
24 'positional',
25 ]
26
27 import gflags
28 import inspect
29 import logging
30 import types
31
32 logger = logging.getLogger(__name__)
33
34 FLAGS = gflags.FLAGS
35
36 gflags.DEFINE_enum('positional_parameters_enforcement', 'WARNING',
37 ['EXCEPTION', 'WARNING', 'IGNORE'],
38 'The action when an oauth2client.util.positional declaration is violated.')
39
40
42 """A decorator to declare that only the first N arguments my be positional.
43
44 This decorator makes it easy to support Python 3 style key-word only
45 parameters. For example, in Python 3 it is possible to write:
46
47 def fn(pos1, *, kwonly1=None, kwonly1=None):
48 ...
49
50 All named parameters after * must be a keyword:
51
52 fn(10, 'kw1', 'kw2') # Raises exception.
53 fn(10, kwonly1='kw1') # Ok.
54
55 Example:
56 To define a function like above, do:
57
58 @positional(1)
59 def fn(pos1, kwonly1=None, kwonly2=None):
60 ...
61
62 If no default value is provided to a keyword argument, it becomes a required
63 keyword argument:
64
65 @positional(0)
66 def fn(required_kw):
67 ...
68
69 This must be called with the keyword parameter:
70
71 fn() # Raises exception.
72 fn(10) # Raises exception.
73 fn(required_kw=10) # Ok.
74
75 When defining instance or class methods always remember to account for
76 'self' and 'cls':
77
78 class MyClass(object):
79
80 @positional(2)
81 def my_method(self, pos1, kwonly1=None):
82 ...
83
84 @classmethod
85 @positional(2)
86 def my_method(cls, pos1, kwonly1=None):
87 ...
88
89 The positional decorator behavior is controlled by the
90 --positional_parameters_enforcement flag. The flag may be set to 'EXCEPTION',
91 'WARNING' or 'IGNORE' to raise an exception, log a warning, or do nothing,
92 respectively, if a declaration is violated.
93
94 Args:
95 max_positional_arguments: Maximum number of positional arguments. All
96 parameters after the this index must be keyword only.
97
98 Returns:
99 A decorator that prevents using arguments after max_positional_args from
100 being used as positional parameters.
101
102 Raises:
103 TypeError if a key-word only argument is provided as a positional parameter,
104 but only if the --positional_parameters_enforcement flag is set to
105 'EXCEPTION'.
106 """
107 def positional_decorator(wrapped):
108 def positional_wrapper(*args, **kwargs):
109 if len(args) > max_positional_args:
110 plural_s = ''
111 if max_positional_args != 1:
112 plural_s = 's'
113 message = '%s() takes at most %d positional argument%s (%d given)' % (
114 wrapped.__name__, max_positional_args, plural_s, len(args))
115 if FLAGS.positional_parameters_enforcement == 'EXCEPTION':
116 raise TypeError(message)
117 elif FLAGS.positional_parameters_enforcement == 'WARNING':
118 logger.warning(message)
119 else:
120 pass
121 return wrapped(*args, **kwargs)
122 return positional_wrapper
123
124 if isinstance(max_positional_args, (int, long)):
125 return positional_decorator
126 else:
127 args, _, _, defaults = inspect.getargspec(max_positional_args)
128 return positional(len(args) - len(defaults))(max_positional_args)
129
130
132 """Converts scope value to a string.
133
134 If scopes is a string then it is simply passed through. If scopes is an
135 iterable then a string is returned that is all the individual scopes
136 concatenated with spaces.
137
138 Args:
139 scopes: string or iterable of strings, the scopes.
140
141 Returns:
142 The scopes formatted as a single string.
143 """
144 if isinstance(scopes, types.StringTypes):
145 return scopes
146 else:
147 return ' '.join(scopes)
148
149
151 """Converts a dictionary to a tuple that can be used as an immutable key.
152
153 The resulting key is always sorted so that logically equivalent dictionaries
154 always produce an identical tuple for a key.
155
156 Args:
157 dictionary: the dictionary to use as the key.
158
159 Returns:
160 A tuple representing the dictionary in it's naturally sorted ordering.
161 """
162 return tuple(sorted(dictionary.items()))
163