232 lines
6.5 KiB
Python
232 lines
6.5 KiB
Python
# Copyright 2015 Google Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""Helper functions for commonly used utilities."""
|
|
|
|
import base64
|
|
import calendar
|
|
import datetime
|
|
|
|
import six
|
|
from six.moves import urllib
|
|
|
|
|
|
CLOCK_SKEW_SECS = 10 # 10 seconds
|
|
CLOCK_SKEW = datetime.timedelta(seconds=CLOCK_SKEW_SECS)
|
|
|
|
|
|
def copy_docstring(source_class):
|
|
"""Decorator that copies a method's docstring from another class.
|
|
|
|
Args:
|
|
source_class (type): The class that has the documented method.
|
|
|
|
Returns:
|
|
Callable: A decorator that will copy the docstring of the same
|
|
named method in the source class to the decorated method.
|
|
"""
|
|
|
|
def decorator(method):
|
|
"""Decorator implementation.
|
|
|
|
Args:
|
|
method (Callable): The method to copy the docstring to.
|
|
|
|
Returns:
|
|
Callable: the same method passed in with an updated docstring.
|
|
|
|
Raises:
|
|
ValueError: if the method already has a docstring.
|
|
"""
|
|
if method.__doc__:
|
|
raise ValueError("Method already has a docstring.")
|
|
|
|
source_method = getattr(source_class, method.__name__)
|
|
method.__doc__ = source_method.__doc__
|
|
|
|
return method
|
|
|
|
return decorator
|
|
|
|
|
|
def utcnow():
|
|
"""Returns the current UTC datetime.
|
|
|
|
Returns:
|
|
datetime: The current time in UTC.
|
|
"""
|
|
return datetime.datetime.utcnow()
|
|
|
|
|
|
def datetime_to_secs(value):
|
|
"""Convert a datetime object to the number of seconds since the UNIX epoch.
|
|
|
|
Args:
|
|
value (datetime): The datetime to convert.
|
|
|
|
Returns:
|
|
int: The number of seconds since the UNIX epoch.
|
|
"""
|
|
return calendar.timegm(value.utctimetuple())
|
|
|
|
|
|
def to_bytes(value, encoding="utf-8"):
|
|
"""Converts a string value to bytes, if necessary.
|
|
|
|
Unfortunately, ``six.b`` is insufficient for this task since in
|
|
Python 2 because it does not modify ``unicode`` objects.
|
|
|
|
Args:
|
|
value (Union[str, bytes]): The value to be converted.
|
|
encoding (str): The encoding to use to convert unicode to bytes.
|
|
Defaults to "utf-8".
|
|
|
|
Returns:
|
|
bytes: The original value converted to bytes (if unicode) or as
|
|
passed in if it started out as bytes.
|
|
|
|
Raises:
|
|
ValueError: If the value could not be converted to bytes.
|
|
"""
|
|
result = value.encode(encoding) if isinstance(value, six.text_type) else value
|
|
if isinstance(result, six.binary_type):
|
|
return result
|
|
else:
|
|
raise ValueError("{0!r} could not be converted to bytes".format(value))
|
|
|
|
|
|
def from_bytes(value):
|
|
"""Converts bytes to a string value, if necessary.
|
|
|
|
Args:
|
|
value (Union[str, bytes]): The value to be converted.
|
|
|
|
Returns:
|
|
str: The original value converted to unicode (if bytes) or as passed in
|
|
if it started out as unicode.
|
|
|
|
Raises:
|
|
ValueError: If the value could not be converted to unicode.
|
|
"""
|
|
result = value.decode("utf-8") if isinstance(value, six.binary_type) else value
|
|
if isinstance(result, six.text_type):
|
|
return result
|
|
else:
|
|
raise ValueError("{0!r} could not be converted to unicode".format(value))
|
|
|
|
|
|
def update_query(url, params, remove=None):
|
|
"""Updates a URL's query parameters.
|
|
|
|
Replaces any current values if they are already present in the URL.
|
|
|
|
Args:
|
|
url (str): The URL to update.
|
|
params (Mapping[str, str]): A mapping of query parameter
|
|
keys to values.
|
|
remove (Sequence[str]): Parameters to remove from the query string.
|
|
|
|
Returns:
|
|
str: The URL with updated query parameters.
|
|
|
|
Examples:
|
|
|
|
>>> url = 'http://example.com?a=1'
|
|
>>> update_query(url, {'a': '2'})
|
|
http://example.com?a=2
|
|
>>> update_query(url, {'b': '3'})
|
|
http://example.com?a=1&b=3
|
|
>> update_query(url, {'b': '3'}, remove=['a'])
|
|
http://example.com?b=3
|
|
|
|
"""
|
|
if remove is None:
|
|
remove = []
|
|
|
|
# Split the URL into parts.
|
|
parts = urllib.parse.urlparse(url)
|
|
# Parse the query string.
|
|
query_params = urllib.parse.parse_qs(parts.query)
|
|
# Update the query parameters with the new parameters.
|
|
query_params.update(params)
|
|
# Remove any values specified in remove.
|
|
query_params = {
|
|
key: value for key, value in six.iteritems(query_params) if key not in remove
|
|
}
|
|
# Re-encoded the query string.
|
|
new_query = urllib.parse.urlencode(query_params, doseq=True)
|
|
# Unsplit the url.
|
|
new_parts = parts._replace(query=new_query)
|
|
return urllib.parse.urlunparse(new_parts)
|
|
|
|
|
|
def scopes_to_string(scopes):
|
|
"""Converts scope value to a string suitable for sending to OAuth 2.0
|
|
authorization servers.
|
|
|
|
Args:
|
|
scopes (Sequence[str]): The sequence of scopes to convert.
|
|
|
|
Returns:
|
|
str: The scopes formatted as a single string.
|
|
"""
|
|
return " ".join(scopes)
|
|
|
|
|
|
def string_to_scopes(scopes):
|
|
"""Converts stringifed scopes value to a list.
|
|
|
|
Args:
|
|
scopes (Union[Sequence, str]): The string of space-separated scopes
|
|
to convert.
|
|
Returns:
|
|
Sequence(str): The separated scopes.
|
|
"""
|
|
if not scopes:
|
|
return []
|
|
|
|
return scopes.split(" ")
|
|
|
|
|
|
def padded_urlsafe_b64decode(value):
|
|
"""Decodes base64 strings lacking padding characters.
|
|
|
|
Google infrastructure tends to omit the base64 padding characters.
|
|
|
|
Args:
|
|
value (Union[str, bytes]): The encoded value.
|
|
|
|
Returns:
|
|
bytes: The decoded value
|
|
"""
|
|
b64string = to_bytes(value)
|
|
padded = b64string + b"=" * (-len(b64string) % 4)
|
|
return base64.urlsafe_b64decode(padded)
|
|
|
|
|
|
def unpadded_urlsafe_b64encode(value):
|
|
"""Encodes base64 strings removing any padding characters.
|
|
|
|
`rfc 7515`_ defines Base64url to NOT include any padding
|
|
characters, but the stdlib doesn't do that by default.
|
|
|
|
_rfc7515: https://tools.ietf.org/html/rfc7515#page-6
|
|
|
|
Args:
|
|
value (Union[str|bytes]): The bytes-like value to encode
|
|
|
|
Returns:
|
|
Union[str|bytes]: The encoded value
|
|
"""
|
|
return base64.urlsafe_b64encode(value).rstrip(b"=")
|