# Copyright (C) 2000-2014 Bastian Kleineidam
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
#
# Some functions have been taken and adjusted from the quodlibet
# source. Quodlibet is (C) 2004-2005 Joe Wreschnig, Michael Urman
# and licensed under the GNU General Public License version 2.
"""
Various string utility functions. Note that these functions are not
necessarily optimised for large strings, so use with care.
"""
import math
import re
import textwrap
import os
import time
import locale
import pydoc
# some handy time constants
SECONDS_PER_MINUTE = 60
SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE
SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR
[docs]
def ascii_safe(s):
"""Get ASCII string without raising encoding errors. Unknown
characters of the given encoding will be ignored.
@param s: the string to be encoded
@type s: string or None
@return: version of s containing only ASCII characters, or None if s was None
@rtype: string or None
"""
if s:
s = s.encode('ascii', 'ignore').decode('ascii')
return s
[docs]
def unquote(s, matching=False):
"""Remove leading and ending single and double quotes.
The quotes need to match if matching is True. Only one quote from each
end will be stripped.
@return: if s evaluates to False, return s as is, else return
string with stripped quotes
@rtype: unquoted string, or s unchanged if it is evaluating to False
"""
if not s:
return s
if len(s) < 2:
return s
if matching:
if s[0] in ("\"'") and s[0] == s[-1]:
s = s[1:-1]
else:
if s[0] in ("\"'"):
s = s[1:]
if s[-1] in ("\"'"):
s = s[:-1]
return s
_para_mac = r"(?:{sep})(?:(?:{sep})\s*)+".format(sep='\r')
_para_posix = r"(?:{sep})(?:(?:{sep})\s*)+".format(sep='\n')
_para_win = r"(?:{sep})(?:(?:{sep})\s*)+".format(sep='\r\n')
_para_ro = re.compile(f"{_para_mac}|{_para_posix}|{_para_win}")
[docs]
def get_paragraphs(text):
"""A new paragraph is considered to start at a line which follows
one or more blank lines (lines containing nothing or just spaces).
The first line of the text also starts a paragraph."""
if not text:
return []
return _para_ro.split(text)
[docs]
def wrap(text, width, **kwargs):
"""Adjust lines of text to be not longer than width. The text will be
returned unmodified if width <= 0.
See textwrap.wrap() for a list of supported kwargs.
Returns text with lines no longer than given width."""
if width <= 0 or not text:
return text
ret = []
for para in get_paragraphs(text):
text = " ".join(para.strip().split())
ret.extend(textwrap.wrap(text, width, **kwargs))
return os.linesep.join(ret)
[docs]
def indent(text, indent_string=" "):
"""Indent each line of text with the given indent string."""
return os.linesep.join(f"{indent_string}{x}" for x in text.splitlines())
[docs]
def paginate(text):
"""Print text in pages of lines."""
pydoc.pager(text)
[docs]
def strsize(b, grouping=True):
"""Return human representation of bytes b. A negative number of bytes
raises a value error."""
if b < 0:
raise ValueError("Invalid negative byte number")
if b < 1024:
return "%sB" % locale.format_string("%d", b, grouping)
if b < 1024 * 10:
return "%sKB" % locale.format_string("%d", (b // 1024), grouping)
if b < 1024 * 1024:
return "%sKB" % locale.format_string("%.2f", (float(b) / 1024), grouping)
if b < 1024 * 1024 * 10:
return "%sMB" % locale.format_string(
"%.2f", (float(b) / (1024 * 1024)), grouping
)
if b < 1024 * 1024 * 1024:
return "%sMB" % locale.format_string(
"%.1f", (float(b) / (1024 * 1024)), grouping
)
if b < 1024 * 1024 * 1024 * 10:
return "%sGB" % locale.format_string(
"%.2f", (float(b) / (1024 * 1024 * 1024)), grouping
)
return "%sGB" % locale.format_string(
"%.1f", (float(b) / (1024 * 1024 * 1024)), grouping
)
[docs]
def strtime(t, func=time.localtime):
"""Return ISO 8601 formatted time."""
return time.strftime("%Y-%m-%d %H:%M:%S", func(t)) + strtimezone()
# from quodlibet
[docs]
def strduration_long(duration, do_translate=True):
"""Turn a time value in seconds into x hours, x minutes, etc."""
if do_translate:
# use global translator functions
global _, _n
else:
# do not translate
def _(x): return x
def _n(a, b, n): return a if n == 1 else b
if duration < 0:
duration = abs(duration)
prefix = "-"
else:
prefix = ""
if duration < 1:
return _("%(prefix)s%(duration).02f seconds") % {
"prefix": prefix,
"duration": duration,
}
# translation dummies
_n("%d second", "%d seconds", 1)
_n("%d minute", "%d minutes", 1)
_n("%d hour", "%d hours", 1)
_n("%d day", "%d days", 1)
_n("%d year", "%d years", 1)
cutoffs = [
(60, "%d second", "%d seconds"),
(60, "%d minute", "%d minutes"),
(24, "%d hour", "%d hours"),
(365, "%d day", "%d days"),
(None, "%d year", "%d years"),
]
time_str = []
for divisor, single, plural in cutoffs:
if duration < 1:
break
if divisor is None:
duration, unit = 0, duration
else:
duration, unit = divmod(duration, divisor)
if unit:
time_str.append(_n(single, plural, math.ceil(unit)) % unit)
time_str.reverse()
if len(time_str) > 2:
time_str.pop()
return "{}{}".format(prefix, ", ".join(time_str))
[docs]
def strtimezone():
"""Return timezone info, %z on some platforms, but not supported on all.
"""
if time.daylight:
zone = time.altzone
else:
zone = time.timezone
return "%+04d" % (-zone // SECONDS_PER_HOUR)
[docs]
def stripurl(s):
"""Remove any lines from string after the first line.
Also remove whitespace at start and end from given string."""
if not s:
return s
return s.splitlines()[0].strip()
[docs]
def limit(s, length=72):
"""If the length of the string exceeds the given limit, it will be cut
off and three dots will be appended.
@param s: the string to limit
@type s: string
@param length: maximum length
@type length: non-negative integer
@return: limited string, at most length+3 characters long
"""
assert length >= 0, "length limit must be a non-negative integer"
if not s or len(s) <= length:
return s
if length == 0:
return ""
return "%s..." % s[:length]
[docs]
def strline(s):
"""Display string representation on one line."""
return strip_control_chars("`%s'" % s.replace("\n", "\\n"))
[docs]
def strip_control_chars(text):
"""Remove console control characters from text."""
if text:
return re.sub(r"[\x01-\x1F\x7F]", "", text)
return text