# -*- coding: iso-8859-1 -*- # Copyright (C) 2000-2005 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., 675 Mass Ave, Cambridge, MA 02139, USA. """ Various string utility functions. Note that these functions are not necessarily optimised for large strings, so use with care. """ import re import textwrap import os import time import urlparse import pydoc def unicode_safe (s, encoding="iso-8859-1"): """ Get unicode string without raising encoding errors. Unknown characters of the given encoding will be ignored. @param s: the string to be decoded @type s: any object except None @return: if s is already unicode, return s unchanged; else return decoded unicode string of str(s) @rtype: unicode """ assert s is not None, "argument to unicode_safe was None" if isinstance(s, unicode): # s is already unicode, nothing to do return s return unicode(str(s), encoding, "ignore") def ascii_safe (s): """ Get ASCII string without raising encoding errors. Unknown characters of the given encoding will be ignored. @param s: the Unicode string to be encoded @type s: unicode or None @return: encoded ASCII version of s, or s itself if s evaluated to False @rtype: string """ if s: s = s.encode('ascii', 'ignore') return s def is_ascii (s): """ Test if a string can be encoded in ASCII. """ try: s.encode('ascii', 'strict') return True except (UnicodeEncodeError, UnicodeDecodeError): return False def url_unicode_split (url): """ Like urlparse.urlsplit(), but always returning unicode parts. """ return [unicode_safe(s) for s in urlparse.urlsplit(url)] 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 evaluting 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)s)(?:(?:%(sep)s)\s*)+" % {'sep': '\r'} _para_posix = r"(?:%(sep)s)(?:(?:%(sep)s)\s*)+" % {'sep': '\n'} _para_win = r"(?:%(sep)s)(?:(?:%(sep)s)\s*)+" % {'sep': '\r\n'} _para_ro = re.compile("%s|%s|%s" % (_para_mac, _para_posix, _para_win)) 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) 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): ret.extend(textwrap.wrap(para.strip(), width, **kwargs)) return os.linesep.join(ret) def indent (text, indent_string=" "): """ Indent each line of text with the given indent string. """ lines = str(text).splitlines() return os.linesep.join(["%s%s" % (indent_string, x) for x in lines]) def get_line_number (s, index): """ Return the line number of s[index]. Lines are assumed to be separated by the ASCII character '\\n'. """ i = 0 if index < 0: index = 0 line = 1 while i < index: if s[i] == '\n': line += 1 i += 1 return line def paginate (text): """ Print text in pages of lines. """ pydoc.pager(text) _markup_re = re.compile("<.*?>", re.DOTALL) def remove_markup (s): """ Remove all <*> html markup tags from s. """ mo = _markup_re.search(s) while mo: s = s[0:mo.start()] + s[mo.end():] mo = _markup_re.search(s) return s def strsize (b): """ 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 == 1: return u"%d Byte" % b if b < 1024: return u"%d Bytes" % b b /= 1024.0 if b < 1024: return u"%.2f kB" % b b /= 1024.0 if b < 1024: return u"%.2f MB" % b b /= 1024.0 return u"%.2f GB" def strtime (t): """ Return ISO 8601 formatted time. """ return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(t)) + \ strtimezone() def strduration (duration): """ Return translated and formatted time duration. """ name = _("seconds") if duration > 60: duration = duration / 60 name = _("minutes") if duration > 60: duration = duration / 60 name = _("hours") return u" %.3f %s" % (duration, name) 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" % int(-zone/3600) _sub_ws = re.compile(r"\s+").sub def stripall (s): """ Remove all whitespace from given string. """ if not s: return s return _sub_ws("", s) 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]