webull-openapi-python-sdk 1.0.0__py3-none-any.whl

webull/core/retry/retry_condition.py

@@ -0,0 +1,214 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+# coding=utf-8
+
+"""
+This file borrowed some of its methods from a  modified fork of the
+https://github.com/aliyun/aliyun-openapi-python-sdk/blob/master/aliyun-python-sdk-core/aliyunsdkcore/retry/retry_condition.py
+which was part of Alibaba Group.
+"""
+
+import logging
+import jmespath
+from webull.core.utils import data
+from webull.core.utils import validation
+from webull.core.exception.exceptions import ClientException, ServerException
+from webull.core.exception import error_code
+from webull.core.common.api_type import DEFAULT as HTTP_API_TYPE
+
+
+logger = logging.getLogger(__name__)
+
+
+def _find_data_in_retry_config(key_name, request, retry_config, api_type=HTTP_API_TYPE):
+    path = '"{0}"."{1}"'.format(api_type, key_name)
+    return jmespath.search(path, retry_config)
+
+
+class RetryCondition(object):
+    BLANK_STATUS = 0
+    NO_RETRY = 1
+    RETRY = 2
+    SHOULD_RETRY_WITH_THROTTLING_BACKOFF = 4
+
+    def should_retry(self, retry_policy_context):
+        """Decide whether the previous request should be retried."""
+        pass
+
+
+class NoRetryCondition(RetryCondition):
+    def should_retry(self, retry_policy_context):
+        return RetryCondition.NO_RETRY
+
+
+class MaxRetryTimesCondition(RetryCondition):
+
+    def __init__(self, max_retry_times):
+        validation.assert_integer_positive(max_retry_times, "max_retry_times")
+        self.max_retry_times = max_retry_times
+
+    def should_retry(self, retry_policy_context):
+
+        if retry_policy_context.retries_attempted < self.max_retry_times:
+            return RetryCondition.RETRY
+        else:
+            logger.debug("Reached the maximum number of retry. Attempts:%d",
+                         retry_policy_context.retries_attempted)
+            return RetryCondition.NO_RETRY
+
+
+class RetryOnExceptionCondition(RetryCondition):
+    def __init__(self, retry_config):
+        self.retry_config = retry_config
+
+    def should_retry(self, retry_policy_context):
+        request = retry_policy_context.original_request
+        exception = retry_policy_context.exception
+
+        if isinstance(exception, ClientException) and exception.get_error_code() == error_code.SDK_HTTP_ERROR:
+            logger.debug("Retryable ClientException:%s", exception)
+            return RetryCondition.RETRY
+
+        if isinstance(exception, ServerException):
+            _error_code = exception.get_error_code()
+            errors = _find_data_in_retry_config(
+                "RetryableNormalErrors", request, self.retry_config)
+            if isinstance(errors, list) and _error_code in errors:
+                logger.debug("Retryable ServerException:%s", exception)
+                return RetryCondition.RETRY
+            errors = _find_data_in_retry_config(
+                "RetryableThrottlingErrors", request, self.retry_config)
+            if isinstance(errors, list) and _error_code in errors:
+                logger.debug("Retryable ThrottlingError:%s", exception)
+                return RetryCondition.RETRY | RetryCondition.SHOULD_RETRY_WITH_THROTTLING_BACKOFF
+
+        return RetryCondition.NO_RETRY
+
+
+class RetryOnMethodTypeCondition(RetryCondition):
+    def __init__(self, retry_config):
+        self.retry_config = retry_config
+
+    def should_retry(self, retry_policy_context):
+        request = retry_policy_context.original_request
+        exception = retry_policy_context.exception
+
+        if isinstance(exception, (ClientException, ServerException)):
+            method = request.get_method()
+            methods = _find_data_in_retry_config(
+                "RetryableMethods", request, self.retry_config)
+            if isinstance(methods, list) and method in methods:
+                logger.debug("Retryable MethodType:%s", method)
+                return RetryCondition.RETRY
+
+        return RetryCondition.NO_RETRY
+
+
+class RetryOnHttpStatusCondition(RetryCondition):
+
+    DEFAULT_RETRYABLE_HTTP_STATUS_LIST = [
+        500, 502, 503, 504
+    ]
+
+    def __init__(self, retryable_http_status_list=None):
+        if retryable_http_status_list:
+            self.retryable_http_status_list = retryable_http_status_list
+        else:
+            self.retryable_http_status_list = self.DEFAULT_RETRYABLE_HTTP_STATUS_LIST
+
+    def should_retry(self, retry_policy_context):
+        if retry_policy_context.http_status_code in self.retryable_http_status_list:
+            logger.debug(
+                "Retryable HTTP error occurred. HTTP status code: %s",
+                retry_policy_context.http_status_code)
+            return RetryCondition.RETRY
+        else:
+            return RetryCondition.NO_RETRY
+
+
+class MergeRetryCondition(RetryCondition):
+    def __init__(self, conditions):
+        self.conditions = conditions
+
+    def should_retry(self, retry_policy_context):
+        retryable = RetryCondition.BLANK_STATUS
+        for condition in self.conditions:
+            retryable |= condition.should_retry(retry_policy_context)
+        return retryable
+
+
+class MergeAndRetryCondition(RetryCondition):
+    def __init__(self, conditions):
+        self.conditions = conditions
+
+    def should_retry(self, retry_policy_context):
+        retryable = RetryCondition.BLANK_STATUS
+        no_retry = RetryCondition.NO_RETRY
+        retry_mask = RetryCondition.RETRY | RetryCondition.SHOULD_RETRY_WITH_THROTTLING_BACKOFF
+        for condition in self.conditions:
+            ret = condition.should_retry(retry_policy_context)
+            retryable |= ret & retry_mask
+            no_retry &= ret & RetryCondition.NO_RETRY
+        return retryable | no_retry
+
+
+class DefaultMixedRetryCondition(RetryCondition):
+    def __init__(self, max_retry_times, retry_config):
+        RetryCondition.__init__(self)
+        self._condition = MergeRetryCondition([
+            MaxRetryTimesCondition(max_retry_times),
+            RetryOnMethodTypeCondition(retry_config),
+            MergeAndRetryCondition([
+                RetryOnExceptionCondition(retry_config),
+                RetryOnHttpStatusCondition(),
+            ]),
+        ])
+
+    def should_retry(self, retry_policy_context):
+        return self._condition.should_retry(retry_policy_context)
+
+
+class DefaultConfigRetryCondition(DefaultMixedRetryCondition):
+    DEFAULT_MAX_RETRY_TIMES = 3
+    RETRY_CONFIG_FILE = "retry_config.json"
+    _loaded_config = None
+
+    def __init__(self, max_retry_times=None):
+        if not self._loaded_config:
+            self._loaded_config = data._load_json_from_data_dir(
+                self.RETRY_CONFIG_FILE)
+        if max_retry_times is None:
+            max_retry_times = self.DEFAULT_MAX_RETRY_TIMES
+        DefaultMixedRetryCondition.__init__(
+            self, max_retry_times, self._loaded_config)

webull/core/retry/retry_policy.py

@@ -0,0 +1,63 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+# coding=utf-8
+
+"""
+This file borrowed some of its methods from a  modified fork of the
+https://github.com/aliyun/aliyun-openapi-python-sdk/blob/master/aliyun-python-sdk-core/aliyunsdkcore/retry/retry_policy.py
+which was part of Alibaba Group.
+"""
+
+from webull.core.retry.retry_condition import RetryCondition, NoRetryCondition, \
+    DefaultConfigRetryCondition
+from webull.core.retry.backoff_strategy import BackoffStrategy, NoDelayStrategy, DefaultMixedBackoffStrategy
+
+
+class RetryPolicy(RetryCondition, BackoffStrategy):
+    def __init__(self, retry_condition, backoff_strategy):
+        self.retry_condition = retry_condition
+        self.backoff_strategy = backoff_strategy
+
+    def should_retry(self, retry_policy_context):
+        return self.retry_condition.should_retry(retry_policy_context)
+
+    def compute_delay_before_next_retry(self, retry_policy_context):
+        return self.backoff_strategy.compute_delay_before_next_retry(retry_policy_context)
+
+
+NO_RETRY_POLICY = RetryPolicy(NoRetryCondition(), NoDelayStrategy())
+
+
+def get_default_retry_policy(max_retry_times=None):
+    return RetryPolicy(DefaultConfigRetryCondition(max_retry_times), DefaultMixedBackoffStrategy())

webull/core/retry/retry_policy_context.py

@@ -0,0 +1,51 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+# coding=utf-8
+
+"""
+This file borrowed some of its methods from a  modified fork of the
+https://github.com/aliyun/aliyun-openapi-python-sdk/blob/master/aliyun-python-sdk-core/aliyunsdkcore/retry/retry_policy_context.py
+which was part of Alibaba Group.
+"""
+
+from webull.core.retry.retry_condition import RetryCondition
+
+class RetryPolicyContext:
+    
+    def __init__(self, original_request, exception, retries_attempted, http_status_code):
+        self.original_request = original_request
+        self.exception = exception
+        self.retries_attempted = retries_attempted
+        self.http_status_code = http_status_code
+        self.retryable = RetryCondition.BLANK_STATUS

webull/core/utils/common.py

@@ -0,0 +1,62 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# coding=utf-8
+import base64
+import hashlib
+import socket
+from datetime import datetime
+import uuid
+import json
+from webull.core.compat import ensure_bytes, ensure_string
+
+TIME_ZONE = "UTC"
+FORMAT_ISO_8601 = "%Y-%m-%dT%H:%M:%SZ"
+FORMAT_ISO_8601_MILLIS = "%Y-%m-%dT%H:%M:%S.%fZ"
+
+def get_uuid():
+    name = socket.gethostname() + str(uuid.uuid1())
+    namespace = uuid.NAMESPACE_URL
+    return str(uuid.uuid5(namespace, name))
+
+def get_iso_8601_date(dt_as_utc=None):
+    if dt_as_utc:
+        return dt_as_utc.strftime(FORMAT_ISO_8601)
+    d = datetime.utcnow()
+    return d.strftime(FORMAT_ISO_8601)
+
+def get_iso_8601_date_with_millis(dt_as_utc=None):
+    if dt_as_utc:
+        d = dt_as_utc
+    else:
+        d = datetime.utcnow()
+    ret = d.strftime(FORMAT_ISO_8601_MILLIS)
+    if len(ret) != 27:
+        raise RuntimeError("failed to convent timestamp, result: %s" % ret)
+    return ret[:-4] + ret[-1:]
+
+def parse_timestamp_to_dt(timestamp_of_millis):
+    return datetime.utcfromtimestamp(timestamp_of_millis / 1000.0)
+
+def md5_sum(content):
+    content_bytes = ensure_bytes(content)
+    md5_bytes = hashlib.md5(content_bytes).digest()
+    return ensure_string(base64.standard_b64encode(md5_bytes))
+
+def md5_hex(content):
+    content_bytes = ensure_bytes(content)
+    return hashlib.md5(content_bytes).hexdigest()
+
+def json_dumps_compact(content):
+    return json.dumps(content, ensure_ascii=False, separators=(',', ':'))

webull/core/utils/data.py

@@ -0,0 +1,25 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# coding=utf-8
+
+import json
+import os.path
+import webull.core
+
+def _load_json_from_data_dir(name):
+    entry_dir = os.path.dirname(os.path.abspath(webull.core.__file__))
+    json_file = os.path.join(entry_dir, "data", name)
+    with open(json_file) as fp:
+        return json.load(fp)

webull/core/utils/desensitize.py

@@ -0,0 +1,33 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# coding=utf-8
+
+
+def desensitize_token(token, keep_length=6, mask_length=6):
+    if not token:
+        return token
+
+    total_length = len(token)
+
+    # 如果字符串长度不足需要保留长度的两倍，则返回全部内容
+    if total_length <= keep_length * 2:
+        return token
+
+    # 提取前保留部分、后保留部分，并用星号连接
+    front_part = token[:keep_length]
+    rear_part = token[-keep_length:] if keep_length > 0 else ''
+    mask = '*' * mask_length
+
+    return f"{front_part}{mask}{rear_part}"

webull/core/utils/validation.py

@@ -0,0 +1,49 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+# coding=utf-8
+
+"""
+This file borrowed some of its methods from a  modified fork of the
+https://github.com/aliyun/aliyun-openapi-python-sdk/blob/master/aliyun-python-sdk-core/aliyunsdkcore/utils/validation.py
+which was part of Alibaba Group.
+"""
+
+from webull.core.exception.exceptions import ClientException
+from webull.core.exception import error_code
+
+def assert_integer_positive(integer, name):
+    if isinstance(integer, int) and integer > 0:
+        return
+    raise ClientException(error_code.SDK_INVALID_PARAMETER,
+                          "{0} should be a positive integer.".format(name))

webull/core/vendored/requests/__init__.py

@@ -0,0 +1,94 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# -*- coding: utf-8 -*-
+
+#   __
+#  /__)  _  _     _   _ _/   _
+# / (   (- (/ (/ (- _)  /  _)
+#          /
+
+"""
+Requests HTTP Library
+~~~~~~~~~~~~~~~~~~~~~
+
+Requests is an HTTP library, written in Python, for human beings. Basic GET
+usage:
+
+   >>> import requests
+   >>> r = requests.get('https://www.python.org')
+   >>> r.status_code
+   200
+   >>> 'Python is a programming language' in r.content
+   True
+
+... or POST:
+
+   >>> payload = dict(key1='value1', key2='value2')
+   >>> r = requests.post('http://httpbin.org/post', data=payload)
+   >>> print(r.text)
+   {
+     ...
+     "form": {
+       "key2": "value2",
+       "key1": "value1"
+     },
+     ...
+   }
+
+The other HTTP methods are supported - see `requests.api`. Full documentation
+is at <http://python-requests.org>.
+
+:copyright: (c) 2017 by Kenneth Reitz.
+:license: Apache 2.0, see LICENSE for more details.
+"""
+
+__title__ = 'requests'
+__version__ = '2.18.3'
+
+# Attempt to enable urllib3's SNI support, if possible
+try:
+    from .packages.urllib3.contrib import pyopenssl
+    pyopenssl.inject_into_urllib3()
+except ImportError:
+    pass
+
+
+from . import utils
+from .models import Request, Response, PreparedRequest
+from .api import request, get, head, post, patch, put, delete, options
+from .sessions import session, Session
+from .status_codes import codes
+from .exceptions import (
+    RequestException, Timeout, URLRequired,
+    TooManyRedirects, HTTPError, ConnectionError,
+    FileModeWarning, ConnectTimeout, ReadTimeout
+)
+
+# Set default logging handler to avoid "No handler found" warnings.
+import logging
+try:  # Python 2.7+
+    from logging import NullHandler
+except ImportError:
+    class NullHandler(logging.Handler):
+        def emit(self, record):
+            """
+            null handler
+            """
+            pass
+
+logging.getLogger(__name__).addHandler(NullHandler())
+logging.getLogger(__name__).setLevel(logging.CRITICAL)
+
+

webull/core/vendored/requests/__version__.py

@@ -0,0 +1,28 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# .-. .-. .-. . . .-. .-. .-. .-.
+# |(  |-  |.| | | |-  `-.  |  `-.
+# ' ' `-' `-`.`-' `-' `-'  '  `-'
+
+__title__ = 'requests'
+__description__ = 'Python HTTP for Humans.'
+__url__ = 'http://python-requests.org'
+__version__ = '2.18.3'
+__build__ = 0x021803
+__author__ = 'Kenneth Reitz'
+__author_email__ = 'me@kennethreitz.org'
+__license__ = 'Apache 2.0'
+__copyright__ = 'Copyright 2017 Kenneth Reitz'
+__cake__ = u'\u2728 \U0001f370 \u2728'

webull/core/vendored/requests/_internal_utils.py

@@ -0,0 +1,56 @@
+# Copyright 2022 Webull
+#
+# 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.
+
+# -*- coding: utf-8 -*-
+
+"""
+requests._internal_utils
+~~~~~~~~~~~~~~
+
+Provides utility functions that are consumed internally by Requests
+which depend on extremely few external helpers (such as compat)
+"""
+
+from .compat import is_py2, builtin_str, str
+
+
+def to_native_string(string, encoding='ascii'):
+    """Given a string object, regardless of type, returns a representation of
+    that string in the native string type, encoding and decoding where
+    necessary. This assumes ASCII unless told otherwise.
+    """
+    if isinstance(string, builtin_str):
+        out = string
+    else:
+        if is_py2:
+            out = string.encode(encoding)
+        else:
+            out = string.decode(encoding)
+
+    return out
+
+
+def unicode_is_ascii(u_string):
+    """Determine if unicode string only contains ASCII characters.
+
+    :param str u_string: unicode string to check. Must be unicode
+        and not Python 2 `str`.
+    :rtype: bool
+    """
+    assert isinstance(u_string, str)
+    try:
+        u_string.encode('ascii')
+        return True
+    except UnicodeEncodeError:
+        return False