|
| 1 | +# Copyright 2015 Google Inc. All rights reserved. |
| 2 | +# |
| 3 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +# you may not use this file except in compliance with the License. |
| 5 | +# You may obtain a copy of the License at |
| 6 | +# |
| 7 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +# |
| 9 | +# Unless required by applicable law or agreed to in writing, software |
| 10 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +# See the License for the specific language governing permissions and |
| 13 | +# limitations under the License. |
| 14 | + |
| 15 | +"""Helper functions for commonly used utilities.""" |
| 16 | + |
| 17 | +import functools |
| 18 | +import inspect |
| 19 | +import logging |
| 20 | +import warnings |
| 21 | + |
| 22 | +import six |
| 23 | +from six.moves import urllib |
| 24 | + |
| 25 | + |
| 26 | +logger = logging.getLogger(__name__) |
| 27 | + |
| 28 | +POSITIONAL_WARNING = 'WARNING' |
| 29 | +POSITIONAL_EXCEPTION = 'EXCEPTION' |
| 30 | +POSITIONAL_IGNORE = 'IGNORE' |
| 31 | +POSITIONAL_SET = frozenset([POSITIONAL_WARNING, POSITIONAL_EXCEPTION, |
| 32 | + POSITIONAL_IGNORE]) |
| 33 | + |
| 34 | +positional_parameters_enforcement = POSITIONAL_WARNING |
| 35 | + |
| 36 | +_SYM_LINK_MESSAGE = 'File: {0}: Is a symbolic link.' |
| 37 | +_IS_DIR_MESSAGE = '{0}: Is a directory' |
| 38 | +_MISSING_FILE_MESSAGE = 'Cannot access {0}: No such file or directory' |
| 39 | + |
| 40 | + |
| 41 | +def positional(max_positional_args): |
| 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 keyword-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 | + ^^^^^^^ |
| 57 | +
|
| 58 | + To define a function like above, do:: |
| 59 | +
|
| 60 | + @positional(1) |
| 61 | + def fn(pos1, kwonly1=None, kwonly2=None): |
| 62 | + ... |
| 63 | +
|
| 64 | + If no default value is provided to a keyword argument, it becomes a |
| 65 | + required keyword argument:: |
| 66 | +
|
| 67 | + @positional(0) |
| 68 | + def fn(required_kw): |
| 69 | + ... |
| 70 | +
|
| 71 | + This must be called with the keyword parameter:: |
| 72 | +
|
| 73 | + fn() # Raises exception. |
| 74 | + fn(10) # Raises exception. |
| 75 | + fn(required_kw=10) # Ok. |
| 76 | +
|
| 77 | + When defining instance or class methods always remember to account for |
| 78 | + ``self`` and ``cls``:: |
| 79 | +
|
| 80 | + class MyClass(object): |
| 81 | +
|
| 82 | + @positional(2) |
| 83 | + def my_method(self, pos1, kwonly1=None): |
| 84 | + ... |
| 85 | +
|
| 86 | + @classmethod |
| 87 | + @positional(2) |
| 88 | + def my_method(cls, pos1, kwonly1=None): |
| 89 | + ... |
| 90 | +
|
| 91 | + The positional decorator behavior is controlled by |
| 92 | + ``_helpers.positional_parameters_enforcement``, which may be set to |
| 93 | + ``POSITIONAL_EXCEPTION``, ``POSITIONAL_WARNING`` or |
| 94 | + ``POSITIONAL_IGNORE`` to raise an exception, log a warning, or do |
| 95 | + nothing, respectively, if a declaration is violated. |
| 96 | +
|
| 97 | + Args: |
| 98 | + max_positional_arguments: Maximum number of positional arguments. All |
| 99 | + parameters after the this index must be |
| 100 | + keyword only. |
| 101 | +
|
| 102 | + Returns: |
| 103 | + A decorator that prevents using arguments after max_positional_args |
| 104 | + from being used as positional parameters. |
| 105 | +
|
| 106 | + Raises: |
| 107 | + TypeError: if a key-word only argument is provided as a positional |
| 108 | + parameter, but only if |
| 109 | + _helpers.positional_parameters_enforcement is set to |
| 110 | + POSITIONAL_EXCEPTION. |
| 111 | + """ |
| 112 | + |
| 113 | + def positional_decorator(wrapped): |
| 114 | + @functools.wraps(wrapped) |
| 115 | + def positional_wrapper(*args, **kwargs): |
| 116 | + if len(args) > max_positional_args: |
| 117 | + plural_s = '' |
| 118 | + if max_positional_args != 1: |
| 119 | + plural_s = 's' |
| 120 | + message = ('{function}() takes at most {args_max} positional ' |
| 121 | + 'argument{plural} ({args_given} given)'.format( |
| 122 | + function=wrapped.__name__, |
| 123 | + args_max=max_positional_args, |
| 124 | + args_given=len(args), |
| 125 | + plural=plural_s)) |
| 126 | + if positional_parameters_enforcement == POSITIONAL_EXCEPTION: |
| 127 | + raise TypeError(message) |
| 128 | + elif positional_parameters_enforcement == POSITIONAL_WARNING: |
| 129 | + logger.warning(message) |
| 130 | + return wrapped(*args, **kwargs) |
| 131 | + return positional_wrapper |
| 132 | + |
| 133 | + if isinstance(max_positional_args, six.integer_types): |
| 134 | + return positional_decorator |
| 135 | + else: |
| 136 | + args, _, _, defaults = inspect.getargspec(max_positional_args) |
| 137 | + return positional(len(args) - len(defaults))(max_positional_args) |
| 138 | + |
| 139 | + |
| 140 | +def parse_unique_urlencoded(content): |
| 141 | + """Parses unique key-value parameters from urlencoded content. |
| 142 | +
|
| 143 | + Args: |
| 144 | + content: string, URL-encoded key-value pairs. |
| 145 | +
|
| 146 | + Returns: |
| 147 | + dict, The key-value pairs from ``content``. |
| 148 | +
|
| 149 | + Raises: |
| 150 | + ValueError: if one of the keys is repeated. |
| 151 | + """ |
| 152 | + urlencoded_params = urllib.parse.parse_qs(content) |
| 153 | + params = {} |
| 154 | + for key, value in six.iteritems(urlencoded_params): |
| 155 | + if len(value) != 1: |
| 156 | + msg = ('URL-encoded content contains a repeated value:' |
| 157 | + '%s -> %s' % (key, ', '.join(value))) |
| 158 | + raise ValueError(msg) |
| 159 | + params[key] = value[0] |
| 160 | + return params |
| 161 | + |
| 162 | + |
| 163 | +def update_query_params(uri, params): |
| 164 | + """Updates a URI with new query parameters. |
| 165 | +
|
| 166 | + If a given key from ``params`` is repeated in the ``uri``, then |
| 167 | + the URI will be considered invalid and an error will occur. |
| 168 | +
|
| 169 | + If the URI is valid, then each value from ``params`` will |
| 170 | + replace the corresponding value in the query parameters (if |
| 171 | + it exists). |
| 172 | +
|
| 173 | + Args: |
| 174 | + uri: string, A valid URI, with potential existing query parameters. |
| 175 | + params: dict, A dictionary of query parameters. |
| 176 | +
|
| 177 | + Returns: |
| 178 | + The same URI but with the new query parameters added. |
| 179 | + """ |
| 180 | + parts = urllib.parse.urlparse(uri) |
| 181 | + query_params = parse_unique_urlencoded(parts.query) |
| 182 | + query_params.update(params) |
| 183 | + new_query = urllib.parse.urlencode(query_params) |
| 184 | + new_parts = parts._replace(query=new_query) |
| 185 | + return urllib.parse.urlunparse(new_parts) |
| 186 | + |
| 187 | + |
| 188 | +def _add_query_parameter(url, name, value): |
| 189 | + """Adds a query parameter to a url. |
| 190 | +
|
| 191 | + Replaces the current value if it already exists in the URL. |
| 192 | +
|
| 193 | + Args: |
| 194 | + url: string, url to add the query parameter to. |
| 195 | + name: string, query parameter name. |
| 196 | + value: string, query parameter value. |
| 197 | +
|
| 198 | + Returns: |
| 199 | + Updated query parameter. Does not update the url if value is None. |
| 200 | + """ |
| 201 | + if value is None: |
| 202 | + return url |
| 203 | + else: |
| 204 | + return update_query_params(url, {name: value}) |
0 commit comments