#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2019, 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
#-----------------------------------------------------------------------------
from __future__ import absolute_import, division, print_function, unicode_literals
import logging
log = logging.getLogger(__name__)
#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------
# Standard library imports
import re
# External imports
# Bokeh imports
#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------
__all__ = (
'decode_utf8',
'encode_utf8',
'escape',
'format_docstring',
'indent',
'nice_join',
'snakify',
)
#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------
[docs]def encode_utf8(u):
''' Encode a UTF-8 string to a sequence of bytes.
Args:
u (str) : the string to encode
Returns:
bytes
'''
import sys
if sys.version_info[0] == 2:
u = u.encode('utf-8')
return u
[docs]def decode_utf8(u):
''' Decode a sequence of bytes to a UTF-8 string
Args:
u (str) : the bytes to decode
Returns:
UTF-8 string
'''
import sys
if sys.version_info[0] == 2:
u = u.decode('utf-8')
return u
# based on `html` stdlib module (3.2+)
[docs]def escape(s, quote=("'", '"')):
''' Perform HTML-safe escaping.
Replaces special characters "&", "<" and ">" to HTML-safe sequences, and
optionally translates quote characters.
Args:
s (str): a string to escape
quote (seq[str], optional) : which quote characters to replace
(default: ("'", '"'))
Returns:
str
'''
s = s.replace("&", "&")
s = s.replace("<", "<")
s = s.replace(">", ">")
if quote:
if '"' in quote:
s = s.replace('"', """)
if "'" in quote:
s = s.replace("'", "'")
return s
[docs]def indent(text, n=2, ch=" "):
''' 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, sep=", ", conjuction="or"):
''' 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, sep='_'):
''' 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()
#-----------------------------------------------------------------------------
# Dev API
#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# Private API
#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# Code
#-----------------------------------------------------------------------------