Source code for highcharts_core.utility_functions

"""Collection of utility functions used across the library."""
import csv
import string
import random

from validator_collection import validators

from highcharts_core import errors


def get_random_string(length = 6):
    """Generate a short random alphanumeric string.
    
    :param length: The length of the string to generate. Defaults to ``8``.
    :type length: :class:`int <python:int>`
    
    :returns: A random alphanumeric string of length ``length``.
    :rtype: :class:`str <python:str>`
    """
    length = validators.integer(length, minimum = 1)
    result = ''.join(random.choices(string.ascii_uppercase + string.digits,
                                    k = length))

    return str(result)


[docs]def mro_to_dict(obj): """Work through ``obj``'s multiple parent classes, executing the appropriate ``to_dict()`` method for each parent and consolidaitng the results to a single :class:`dict <python:dict>`. :param obj: An object that has a ``to_dict()`` method. :rtype: :class:`dict <python:dict>` """ if not hasattr(obj, 'to_dict'): raise TypeError('obj does not have a to_dict() method.') classes = [x for x in obj.__class__.mro() if x.__name__ != 'object'] as_dict = {} for item in classes: has_to_dict = hasattr(super(item, obj), 'to_dict') if not has_to_dict: break try: item_dict = super(item, obj).to_dict() except (NotImplementedError, AttributeError): continue for key in item_dict: as_dict[key] = item_dict[key] return as_dict
[docs]def get_remaining_mro(cls, in_cls = None, method = '_to_untrimmed_dict'): """Retrieve the remaining classes that should be processed for ``method`` when traversing ``cls``. :param cls: The class whose ancestors are being traversed. :type cls: :class:`HighchartsMeta` :param in_cls: The class that the traversal currently finds itself in. Defaults to :obj:`None <python:None>` :type in_cls: ``type`` or :obj:`None <python:None>` :param method: The method to search for in the MRO. Defaults to ``'_to_untrimmed_dict'``. :type method: :class:`str <python:str>` :returns: List of classes that have ``method`` that occur *after* ``in_cls`` in the MRO for ``cls``. :rtype: :class:`list <python:list>` of ``type`` objects """ mro = [x for x in cls.mro() if hasattr(x, method) and x.__name__ != 'HighchartsMeta'] if in_cls is None: return mro[1:] else: index = mro.index(in_cls) return mro[(index + 1):]
[docs]def mro__to_untrimmed_dict(obj, in_cls = None): """Traverse the ancestor classes of ``obj`` and execute their ``_to_untrimmed_dict()`` methods. :param obj: The object to be traversed. :type obj: :class:`HighchartsMeta` :param in_cls: The class from which ``mro__to_untrimmed_dict()`` was called. :type in_cls: ``type`` or :obj:`None <python:None>` :returns: Collection of untrimmed :class:`dict <python:dict>` representations in the same order as the MRO. :rtype: :class:`list <python:list>` of :class:`dict <python:dict>` for each class in the MRO, execute _to_untrimmed_dict() do not repeat for each class """ cls = obj.__class__ remaining_mro = get_remaining_mro(cls, in_cls = in_cls, method = '_to_untrimmed_dict') ancestor_dicts = [] for x in remaining_mro: if hasattr(x, '_to_untrimmed_dict') and x != cls: ancestor_dicts.append(x._to_untrimmed_dict(obj, in_cls = x)) consolidated = {} for item in ancestor_dicts: for key in item: consolidated[key] = item[key] return consolidated
[docs]def validate_color(value): """Validate that ``value`` is either a :class:`Gradient`, :class:`Pattern`, or a :class:`str <python:str>`. :param value: The value to validate. :returns: The validated value. :rtype: :class:`str <python:str>`, :class:`Gradient`, :class:`Pattern``, or :obj:`None <python:None>` """ from highcharts_core.utility_classes.gradients import Gradient from highcharts_core.utility_classes.patterns import Pattern if not value: return None elif value.__class__.__name__ == 'EnforcedNullType': return value elif isinstance(value, (Gradient, Pattern)): return value elif isinstance(value, (dict, str)) and ('linearGradient' in value or 'radialGradient' in value): try: value = Gradient.from_json(value) except (TypeError, ValueError): if isinstance(value, dict): value = Gradient.from_dict(value) else: value = validators.string(value) elif isinstance(value, dict) and ('linear_gradient' in value or 'radial_gradient' in value): value = Gradient(**value) elif isinstance(value, (dict, str)) and ('patternOptions' in value or 'pattern' in value): try: value = Pattern.from_json(value) except (TypeError, ValueError): if isinstance(value, dict): value = Pattern.from_dict(value) else: value = validators.string(value) elif isinstance(value, dict) and 'pattern_options' in value: value = Pattern(**value) elif isinstance(value, str): value = validators.string(value) else: raise errors.HighchartsValueError(f'Unable to resolve value to a string, ' f'Gradient, or Pattern. Value received ' f'was: {value}') return value
[docs]def to_camelCase(snake_case): """Convert ``snake_case`` to ``camelCase``. :param snake_case: A :class:`str <python:str>` which is likely to contain ``snake_case``. :type snake_case: :class:`str <python:str>` :returns: A ``camelCase`` representation of ``snake_case``. :rtype: :class:`str <python:str>` """ snake_case = validators.string(snake_case) if '_' not in snake_case: return snake_case if 'url' in snake_case: snake_case = snake_case.replace('url', 'URL') elif 'utc' in snake_case: snake_case = snake_case.replace('utc', 'UTC') elif '_csv' in snake_case: snake_case = snake_case.replace('csv', 'CSV') elif '_jpeg' in snake_case: snake_case = snake_case.replace('jpeg', 'JPEG') elif '_pdf' in snake_case: snake_case = snake_case.replace('pdf', 'PDF') elif '_png' in snake_case: snake_case = snake_case.replace('png', 'PNG') elif '_svg' in snake_case: snake_case = snake_case.replace('svg', 'SVG') elif '_xls' in snake_case: snake_case = snake_case.replace('xls', 'XLS') elif '_atr' in snake_case: snake_case = snake_case.replace('atr', 'ATR') elif '_hlc' in snake_case: snake_case = snake_case.replace('hlc', 'HLC') elif '_ohlc' in snake_case: snake_case = snake_case.replace('ohlc', 'OHLC') elif '_xy' in snake_case: snake_case = snake_case.replace('xy', 'XY') elif snake_case.endswith('_x'): snake_case = snake_case.replace('_x', '_X') elif snake_case.endswith('_y'): snake_case = snake_case.replace('_y', '_Y') elif snake_case.endswith('_id'): snake_case = snake_case.replace('_id', '_ID') elif snake_case == 'drillup_text': snake_case = 'drillUpText' elif snake_case == 'drillup_button': snake_case = 'drillUpButton' elif snake_case == 'thousands_separator': snake_case = 'thousandsSep' elif snake_case == 'measure_xy': snake_case = 'measureXY' elif snake_case == 'use_gpu_translations': snake_case = 'useGPUTranslations' elif snake_case == 'label_rank': snake_case = 'labelrank' elif '_di_line' in snake_case: snake_case = snake_case.replace('_di_line', '_DILine') camel_case = '' previous_character = '' for character in snake_case: if character != '_' and previous_character != '_': camel_case += character previous_character = character elif character == '_': previous_character = character elif character != '_' and previous_character == '_': camel_case += character.upper() previous_character = character return camel_case
[docs]def parse_csv(csv_data, has_header_row = True, delimiter = ',', null_text = 'None', wrapper_character = "'", wrap_all_strings = False, double_wrapper_character_when_nested = False, escape_character = "\\", line_terminator = '\r\n'): """Parse ``csv_data`` to return a list of :class:`dict <python:dict>` objects, one for each record. :param csv_data: The CSV record expressed as a :class:`str <python:str>` :type csv_data: :class:`str <python:str>` :param delimiter: The delimiter used between columns. Defaults to ``,``. :type delimiter: :class:`str <python:str>` :param wrapper_character: The string used to wrap string values when wrapping is applied. Defaults to ``'``. :type wrapper_character: :class:`str <python:str>` :param null_text: The string used to indicate an empty value if empty values are wrapped. Defaults to `None`. :type null_text: :class:`str <python:str>` :returns: Collection of column names (or numerical keys) and CSV records as :class:`dict <python:dict>` values :rtype: :class:`tuple <python:tuple>` of a :class:`list <python:list>` of column names and :class:`list <python:list>` of :class:`dict <python:dict>` """ if not csv_data: return [], [] if isinstance(csv_data, str): csv_data = csv_data.split(line_terminator) if not wrapper_character: wrapper_character = "'" if wrap_all_strings: quoting = csv.QUOTE_NONNUMERIC else: quoting = csv.QUOTE_MINIMAL if 'highcharts' in csv.list_dialects(): csv.unregister_dialect('highcharts') csv.register_dialect('highcharts', delimiter = delimiter, doublequote = double_wrapper_character_when_nested, escapechar = escape_character, quotechar = wrapper_character, quoting = quoting, lineterminator = line_terminator) if has_header_row: csv_reader = csv.DictReader(csv_data, dialect = 'highcharts', restkey = None, restval = None) records_as_dicts = [x for x in csv_reader] columns = csv_reader.fieldnames else: csv_reader = csv.reader(csv_data, dialect = 'highcharts') records_as_dicts = [] columns = [] for row in csv_reader: record_as_dict = {} column_counter = 0 for column in row: record_as_dict[column_counter] = column columns.append(column_counter) column_counter += 1 records_as_dicts.append(record_as_dict) return columns, records_as_dicts
def jupyter_add_script(url, is_last = False): """Generates the JavaScript code Promise which adds a <script/> tag to the Jupyter Lab environment. :param url: The URL to use for the script's source. :type url: :class:`str <python:str>` :param is_last: Whether the URL is the last of the promises. :type is_last: :class:`bool <python:bool>` :returns: The JavaScript code for adding the script. :rtype: :class:`str <python:str>` """ url = validators.url(url) if url.endswith('.css'): return jupyter_add_link(url, is_last = is_last) js_str = '' js_str += """new Promise(function(resolve, reject) {\n""" js_str += f""" var existing_tags = document.querySelectorAll("script[src='{url}']");""" js_str += """ if (existing_tags.length == 0) { var script = document.createElement("script"); script.onload = resolve; script.onerror = reject;""" js_str += f""" script.src = '{url}';""" js_str += """ document.head.appendChild(script); }; })""" return js_str def jupyter_add_link(url, is_last = False): """Generates the JavaScript code Promise which adds a <link/> tag to the Jupyter Lab environment. :param url: The URL to use for the link's source. :type url: :class:`str <python:str>` :param is_last: Whether the URL is the last of the promises. :type is_last: :class:`bool <python:bool>` :returns: The JavaScript code for adding the link. :rtype: :class:`str <python:str>` """ url = validators.url(url) js_str = '' js_str += """new Promise(function(resolve, reject) {\n""" js_str += f""" var existing_tags = document.querySelectorAll("link[href='{url}']");""" js_str += """ if (existing_tags.length == 0) { var link = document.createElement("link"); link.onload = resolve; link.onerror = reject;""" js_str += f""" link.href = '{url}';""" js_str += f""" link.rel = 'stylesheet';""" js_str += f""" link.type = 'text/css';""" js_str += """ document.head.appendChild(link); }; })""" return js_str def get_retryHighcharts(): """Retrieve the ``retryHighcharts()`` JavaScript function. :returns: The JavaScript code of the ``retryHighcharts()`` JavaScript function. :rtype: :class:`str <python:str>` """ js_str = """function retryHighcharts(fn, container = 'highcharts_target_div', retries = 3, retriesLeft = 3, interval = 1000) { return new Promise((resolve, reject) => { try { fn() return resolve(); } catch (err) { if ((err instanceof ReferenceError) || (err instanceof TypeError)) { if (retriesLeft === 0) { var target_div = document.getElementById(container); if (target_div) { var timeElapsed = (retries * interval) / 1000; var errorMessage = "Something went wrong with the Highcharts.js script. It should have been automatically loaded, but it did not load for over " + timeElapsed + " seconds. Check your internet connection, and then if the problem persists please reach out for support. (You can also check your browser's console log for more details.)"; var errorHTML = "<p>" + errorMessage + "</p>"; target_div.innerHTML = errorMessage; console.log(errorMessage); console.error(err); } return reject(); } setTimeout(() => { retryHighcharts(fn, container, retries, retriesLeft - 1, interval).then(resolve).catch(reject); }, interval); } else if ((err instanceof Error) && (err.message.includes('#13'))) { var errorMessage = "It looks like the container specified \'" + container + "\' was not created successfully. Please check your browser\'s console log for more details."; console.error(errorMessage); console.error(err); return reject(); } else { throw err; } } }); };""" return js_str def prep_js_for_jupyter(js_str, container = 'highcharts_target_div', random_slug = None, retries = 3, interval = 1000): """Remove the JavaScript event listeners from the code in ``js_str`` and prepare the JavaScript code for rending in an IPython context. :param js_str: The JavaScript code from which the event listeners should be stripped. :type js_str: :class:`str <python:str>` :param container: The DIV where the Highcharts visualization is to be rendered. Defaults to ``'highcharts_target_div'``. :type container: :class:`str <python:str>` :param random_slug: The random sequence of characters to append to the container/function name to ensure uniqueness. Defaults to :obj:`None <python:None>` :type random_slug: :class:`str <python:str>` or :obj:`None <python:None>` :param retries: The number of times to retry the rendering. Defaults to 3. :type retries: :class:`int <python:int>` :param interval: The number of milliseconds to wait between retries. Defaults to 1000 (1 second). :type interval: :class:`int <python:int>` :returns: The JavaScript code having removed the non-Jupyter compliant JS code. :rtype: :class:`str <python:str>` """ js_str = js_str.replace( """document.addEventListener('DOMContentLoaded', function() {""", '') js_str = js_str.replace('renderTo = ', '') js_str = js_str.replace(',\noptions = ', ',\n') js_str = js_str[:-3] if random_slug: function_str = f"""function insertChart_{random_slug}() """ else: function_str = """function insertChart() """ function_str += """{\n""" function_str += js_str function_str += """\n};\n""" if random_slug: function_str += f"""retryHighcharts(insertChart_{random_slug}, '{container}', {retries}, {retries}, {interval});""" else: function_str += f"""retryHighcharts(insertChart, '{container}', {retries}, {retries}, {interval});""" return function_str