Source code for bokeh.util.string

#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2021, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
''' Functions useful for string manipulations or encoding.

'''

#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
import logging # isort:skip
log = logging.getLogger(__name__)

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------

# Standard library imports
import re
from typing import Any, Dict, Optional, Sequence
from urllib.parse import quote_plus

#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------

__all__ = (
    'format_docstring',
    'indent',
    'nice_join',
    'snakify',
)

#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------

[docs]def indent(text: str, n: int = 2, ch: str = " ") -> str: ''' Indent all the lines in a given block of text by a specified amount. Args: text (str) : The text to indent n (int, optional) : The amount to indent each line by (default: 2) ch (char, optional) : What character to fill the indentation with (default: " ") ''' padding = ch * n return "\n".join(padding + line for line in text.split("\n"))
[docs]def nice_join(seq: Sequence[str], sep: str = ", ", conjuction: str = "or") -> str: ''' Join together sequences of strings into English-friendly phrases using the conjunction ``or`` when appropriate. Args: seq (seq[str]) : a sequence of strings to nicely join sep (str, optional) : a sequence delimiter to use (default: ", ") conjunction (str or None, optional) : a conjuction to use for the last two items, or None to reproduce basic join behaviour (default: "or") Returns: a joined string Examples: >>> nice_join(["a", "b", "c"]) 'a, b or c' ''' seq = [str(x) for x in seq] if len(seq) <= 1 or conjuction is None: return sep.join(seq) else: return "%s %s %s" % (sep.join(seq[:-1]), conjuction, seq[-1])
[docs]def snakify(name: str, sep: str = "_") -> str: ''' Convert CamelCase to snake_case. ''' name = re.sub("([A-Z]+)([A-Z][a-z])", r"\1%s\2" % sep, name) name = re.sub("([a-z\\d])([A-Z])", r"\1%s\2" % sep, name) return name.lower()
[docs]def format_docstring(docstring: Optional[str], *args: Any, **kwargs: Any) -> Optional[str]: ''' Safely format docstrings. When Python is executed with the ``-OO`` option, doc strings are removed and replaced the value ``None``. This function guards against applying the string formatting options in that case. Args: docstring (str or None) : The docstring to format, or ``None`` args (tuple) : string formatting arguments for the docsring kwargs (dict) : string formatting arguments for the docsring Returns: str or None ''' return None if docstring is None else docstring.format(*args, **kwargs)
def format_url_query_arguments(url: str, arguments: Optional[Dict[str, str]] = None) -> str: ''' Format a base URL with optional query arguments Args: url (str) : An base URL to append query arguments to arguments (dict or None, optional) : A mapping of key/value URL query arguments, or None (default: None) Returns: str ''' if arguments is not None: items = (f"{quote_plus(key)}={quote_plus(value)}" for key, value in arguments.items()) url += "?" + "&".join(items) return url #----------------------------------------------------------------------------- # Dev API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Code #-----------------------------------------------------------------------------