"""A collection of string operations (most are no longer used). | |
Warning: most of the code you see here isn't normally used nowadays. | |
Beginning with Python 1.6, many of these functions are implemented as | |
methods on the standard string object. They used to be implemented by | |
a built-in module called strop, but strop is now obsolete itself. | |
Public module variables: | |
whitespace -- a string containing all characters considered whitespace | |
lowercase -- a string containing all characters considered lowercase letters | |
uppercase -- a string containing all characters considered uppercase letters | |
letters -- a string containing all characters considered letters | |
digits -- a string containing all characters considered decimal digits | |
hexdigits -- a string containing all characters considered hexadecimal digits | |
octdigits -- a string containing all characters considered octal digits | |
punctuation -- a string containing all characters considered punctuation | |
printable -- a string containing all characters considered printable | |
""" | |
# Some strings for ctype-style character classification | |
whitespace = ' \t\n\r\v\f' | |
lowercase = 'abcdefghijklmnopqrstuvwxyz' | |
uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' | |
letters = lowercase + uppercase | |
ascii_lowercase = lowercase | |
ascii_uppercase = uppercase | |
ascii_letters = ascii_lowercase + ascii_uppercase | |
digits = '0123456789' | |
hexdigits = digits + 'abcdef' + 'ABCDEF' | |
octdigits = '01234567' | |
punctuation = """!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~""" | |
printable = digits + letters + punctuation + whitespace | |
# Case conversion helpers | |
# Use str to convert Unicode literal in case of -U | |
l = map(chr, xrange(256)) | |
_idmap = str('').join(l) | |
del l | |
# Functions which aren't available as string methods. | |
# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def". | |
def capwords(s, sep=None): | |
"""capwords(s [,sep]) -> string | |
Split the argument into words using split, capitalize each | |
word using capitalize, and join the capitalized words using | |
join. If the optional second argument sep is absent or None, | |
runs of whitespace characters are replaced by a single space | |
and leading and trailing whitespace are removed, otherwise | |
sep is used to split and join the words. | |
""" | |
return (sep or ' ').join(x.capitalize() for x in s.split(sep)) | |
# Construct a translation string | |
_idmapL = None | |
def maketrans(fromstr, tostr): | |
"""maketrans(frm, to) -> string | |
Return a translation table (a string of 256 bytes long) | |
suitable for use in string.translate. The strings frm and to | |
must be of the same length. | |
""" | |
if len(fromstr) != len(tostr): | |
raise ValueError, "maketrans arguments must have same length" | |
global _idmapL | |
if not _idmapL: | |
_idmapL = list(_idmap) | |
L = _idmapL[:] | |
fromstr = map(ord, fromstr) | |
for i in range(len(fromstr)): | |
L[fromstr[i]] = tostr[i] | |
return ''.join(L) | |
#################################################################### | |
import re as _re | |
class _multimap: | |
"""Helper class for combining multiple mappings. | |
Used by .{safe_,}substitute() to combine the mapping and keyword | |
arguments. | |
""" | |
def __init__(self, primary, secondary): | |
self._primary = primary | |
self._secondary = secondary | |
def __getitem__(self, key): | |
try: | |
return self._primary[key] | |
except KeyError: | |
return self._secondary[key] | |
class _TemplateMetaclass(type): | |
pattern = r""" | |
%(delim)s(?: | |
(?P<escaped>%(delim)s) | # Escape sequence of two delimiters | |
(?P<named>%(id)s) | # delimiter and a Python identifier | |
{(?P<braced>%(id)s)} | # delimiter and a braced identifier | |
(?P<invalid>) # Other ill-formed delimiter exprs | |
) | |
""" | |
def __init__(cls, name, bases, dct): | |
super(_TemplateMetaclass, cls).__init__(name, bases, dct) | |
if 'pattern' in dct: | |
pattern = cls.pattern | |
else: | |
pattern = _TemplateMetaclass.pattern % { | |
'delim' : _re.escape(cls.delimiter), | |
'id' : cls.idpattern, | |
} | |
cls.pattern = _re.compile(pattern, _re.IGNORECASE | _re.VERBOSE) | |
class Template: | |
"""A string class for supporting $-substitutions.""" | |
__metaclass__ = _TemplateMetaclass | |
delimiter = '$' | |
idpattern = r'[_a-z][_a-z0-9]*' | |
def __init__(self, template): | |
self.template = template | |
# Search for $$, $identifier, ${identifier}, and any bare $'s | |
def _invalid(self, mo): | |
i = mo.start('invalid') | |
lines = self.template[:i].splitlines(True) | |
if not lines: | |
colno = 1 | |
lineno = 1 | |
else: | |
colno = i - len(''.join(lines[:-1])) | |
lineno = len(lines) | |
raise ValueError('Invalid placeholder in string: line %d, col %d' % | |
(lineno, colno)) | |
def substitute(self, *args, **kws): | |
if len(args) > 1: | |
raise TypeError('Too many positional arguments') | |
if not args: | |
mapping = kws | |
elif kws: | |
mapping = _multimap(kws, args[0]) | |
else: | |
mapping = args[0] | |
# Helper function for .sub() | |
def convert(mo): | |
# Check the most common path first. | |
named = mo.group('named') or mo.group('braced') | |
if named is not None: | |
val = mapping[named] | |
# We use this idiom instead of str() because the latter will | |
# fail if val is a Unicode containing non-ASCII characters. | |
return '%s' % (val,) | |
if mo.group('escaped') is not None: | |
return self.delimiter | |
if mo.group('invalid') is not None: | |
self._invalid(mo) | |
raise ValueError('Unrecognized named group in pattern', | |
self.pattern) | |
return self.pattern.sub(convert, self.template) | |
def safe_substitute(self, *args, **kws): | |
if len(args) > 1: | |
raise TypeError('Too many positional arguments') | |
if not args: | |
mapping = kws | |
elif kws: | |
mapping = _multimap(kws, args[0]) | |
else: | |
mapping = args[0] | |
# Helper function for .sub() | |
def convert(mo): | |
named = mo.group('named') | |
if named is not None: | |
try: | |
# We use this idiom instead of str() because the latter | |
# will fail if val is a Unicode containing non-ASCII | |
return '%s' % (mapping[named],) | |
except KeyError: | |
return self.delimiter + named | |
braced = mo.group('braced') | |
if braced is not None: | |
try: | |
return '%s' % (mapping[braced],) | |
except KeyError: | |
return self.delimiter + '{' + braced + '}' | |
if mo.group('escaped') is not None: | |
return self.delimiter | |
if mo.group('invalid') is not None: | |
return self.delimiter | |
raise ValueError('Unrecognized named group in pattern', | |
self.pattern) | |
return self.pattern.sub(convert, self.template) | |
#################################################################### | |
# NOTE: Everything below here is deprecated. Use string methods instead. | |
# This stuff will go away in Python 3.0. | |
# Backward compatible names for exceptions | |
index_error = ValueError | |
atoi_error = ValueError | |
atof_error = ValueError | |
atol_error = ValueError | |
# convert UPPER CASE letters to lower case | |
def lower(s): | |
"""lower(s) -> string | |
Return a copy of the string s converted to lowercase. | |
""" | |
return s.lower() | |
# Convert lower case letters to UPPER CASE | |
def upper(s): | |
"""upper(s) -> string | |
Return a copy of the string s converted to uppercase. | |
""" | |
return s.upper() | |
# Swap lower case letters and UPPER CASE | |
def swapcase(s): | |
"""swapcase(s) -> string | |
Return a copy of the string s with upper case characters | |
converted to lowercase and vice versa. | |
""" | |
return s.swapcase() | |
# Strip leading and trailing tabs and spaces | |
def strip(s, chars=None): | |
"""strip(s [,chars]) -> string | |
Return a copy of the string s with leading and trailing | |
whitespace removed. | |
If chars is given and not None, remove characters in chars instead. | |
If chars is unicode, S will be converted to unicode before stripping. | |
""" | |
return s.strip(chars) | |
# Strip leading tabs and spaces | |
def lstrip(s, chars=None): | |
"""lstrip(s [,chars]) -> string | |
Return a copy of the string s with leading whitespace removed. | |
If chars is given and not None, remove characters in chars instead. | |
""" | |
return s.lstrip(chars) | |
# Strip trailing tabs and spaces | |
def rstrip(s, chars=None): | |
"""rstrip(s [,chars]) -> string | |
Return a copy of the string s with trailing whitespace removed. | |
If chars is given and not None, remove characters in chars instead. | |
""" | |
return s.rstrip(chars) | |
# Split a string into a list of space/tab-separated words | |
def split(s, sep=None, maxsplit=-1): | |
"""split(s [,sep [,maxsplit]]) -> list of strings | |
Return a list of the words in the string s, using sep as the | |
delimiter string. If maxsplit is given, splits at no more than | |
maxsplit places (resulting in at most maxsplit+1 words). If sep | |
is not specified or is None, any whitespace string is a separator. | |
(split and splitfields are synonymous) | |
""" | |
return s.split(sep, maxsplit) | |
splitfields = split | |
# Split a string into a list of space/tab-separated words | |
def rsplit(s, sep=None, maxsplit=-1): | |
"""rsplit(s [,sep [,maxsplit]]) -> list of strings | |
Return a list of the words in the string s, using sep as the | |
delimiter string, starting at the end of the string and working | |
to the front. If maxsplit is given, at most maxsplit splits are | |
done. If sep is not specified or is None, any whitespace string | |
is a separator. | |
""" | |
return s.rsplit(sep, maxsplit) | |
# Join fields with optional separator | |
def join(words, sep = ' '): | |
"""join(list [,sep]) -> string | |
Return a string composed of the words in list, with | |
intervening occurrences of sep. The default separator is a | |
single space. | |
(joinfields and join are synonymous) | |
""" | |
return sep.join(words) | |
joinfields = join | |
# Find substring, raise exception if not found | |
def index(s, *args): | |
"""index(s, sub [,start [,end]]) -> int | |
Like find but raises ValueError when the substring is not found. | |
""" | |
return s.index(*args) | |
# Find last substring, raise exception if not found | |
def rindex(s, *args): | |
"""rindex(s, sub [,start [,end]]) -> int | |
Like rfind but raises ValueError when the substring is not found. | |
""" | |
return s.rindex(*args) | |
# Count non-overlapping occurrences of substring | |
def count(s, *args): | |
"""count(s, sub[, start[,end]]) -> int | |
Return the number of occurrences of substring sub in string | |
s[start:end]. Optional arguments start and end are | |
interpreted as in slice notation. | |
""" | |
return s.count(*args) | |
# Find substring, return -1 if not found | |
def find(s, *args): | |
"""find(s, sub [,start [,end]]) -> in | |
Return the lowest index in s where substring sub is found, | |
such that sub is contained within s[start,end]. Optional | |
arguments start and end are interpreted as in slice notation. | |
Return -1 on failure. | |
""" | |
return s.find(*args) | |
# Find last substring, return -1 if not found | |
def rfind(s, *args): | |
"""rfind(s, sub [,start [,end]]) -> int | |
Return the highest index in s where substring sub is found, | |
such that sub is contained within s[start,end]. Optional | |
arguments start and end are interpreted as in slice notation. | |
Return -1 on failure. | |
""" | |
return s.rfind(*args) | |
# for a bit of speed | |
_float = float | |
_int = int | |
_long = long | |
# Convert string to float | |
def atof(s): | |
"""atof(s) -> float | |
Return the floating point number represented by the string s. | |
""" | |
return _float(s) | |
# Convert string to integer | |
def atoi(s , base=10): | |
"""atoi(s [,base]) -> int | |
Return the integer represented by the string s in the given | |
base, which defaults to 10. The string s must consist of one | |
or more digits, possibly preceded by a sign. If base is 0, it | |
is chosen from the leading characters of s, 0 for octal, 0x or | |
0X for hexadecimal. If base is 16, a preceding 0x or 0X is | |
accepted. | |
""" | |
return _int(s, base) | |
# Convert string to long integer | |
def atol(s, base=10): | |
"""atol(s [,base]) -> long | |
Return the long integer represented by the string s in the | |
given base, which defaults to 10. The string s must consist | |
of one or more digits, possibly preceded by a sign. If base | |
is 0, it is chosen from the leading characters of s, 0 for | |
octal, 0x or 0X for hexadecimal. If base is 16, a preceding | |
0x or 0X is accepted. A trailing L or l is not accepted, | |
unless base is 0. | |
""" | |
return _long(s, base) | |
# Left-justify a string | |
def ljust(s, width, *args): | |
"""ljust(s, width[, fillchar]) -> string | |
Return a left-justified version of s, in a field of the | |
specified width, padded with spaces as needed. The string is | |
never truncated. If specified the fillchar is used instead of spaces. | |
""" | |
return s.ljust(width, *args) | |
# Right-justify a string | |
def rjust(s, width, *args): | |
"""rjust(s, width[, fillchar]) -> string | |
Return a right-justified version of s, in a field of the | |
specified width, padded with spaces as needed. The string is | |
never truncated. If specified the fillchar is used instead of spaces. | |
""" | |
return s.rjust(width, *args) | |
# Center a string | |
def center(s, width, *args): | |
"""center(s, width[, fillchar]) -> string | |
Return a center version of s, in a field of the specified | |
width. padded with spaces as needed. The string is never | |
truncated. If specified the fillchar is used instead of spaces. | |
""" | |
return s.center(width, *args) | |
# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03' | |
# Decadent feature: the argument may be a string or a number | |
# (Use of this is deprecated; it should be a string as with ljust c.s.) | |
def zfill(x, width): | |
"""zfill(x, width) -> string | |
Pad a numeric string x with zeros on the left, to fill a field | |
of the specified width. The string x is never truncated. | |
""" | |
if not isinstance(x, basestring): | |
x = repr(x) | |
return x.zfill(width) | |
# Expand tabs in a string. | |
# Doesn't take non-printing chars into account, but does understand \n. | |
def expandtabs(s, tabsize=8): | |
"""expandtabs(s [,tabsize]) -> string | |
Return a copy of the string s with all tab characters replaced | |
by the appropriate number of spaces, depending on the current | |
column, and the tabsize (default 8). | |
""" | |
return s.expandtabs(tabsize) | |
# Character translation through look-up table. | |
def translate(s, table, deletions=""): | |
"""translate(s,table [,deletions]) -> string | |
Return a copy of the string s, where all characters occurring | |
in the optional argument deletions are removed, and the | |
remaining characters have been mapped through the given | |
translation table, which must be a string of length 256. The | |
deletions argument is not allowed for Unicode strings. | |
""" | |
if deletions or table is None: | |
return s.translate(table, deletions) | |
else: | |
# Add s[:0] so that if s is Unicode and table is an 8-bit string, | |
# table is converted to Unicode. This means that table *cannot* | |
# be a dictionary -- for that feature, use u.translate() directly. | |
return s.translate(table + s[:0]) | |
# Capitalize a string, e.g. "aBc dEf" -> "Abc def". | |
def capitalize(s): | |
"""capitalize(s) -> string | |
Return a copy of the string s with only its first character | |
capitalized. | |
""" | |
return s.capitalize() | |
# Substring replacement (global) | |
def replace(s, old, new, maxreplace=-1): | |
"""replace (str, old, new[, maxreplace]) -> string | |
Return a copy of string str with all occurrences of substring | |
old replaced by new. If the optional argument maxreplace is | |
given, only the first maxreplace occurrences are replaced. | |
""" | |
return s.replace(old, new, maxreplace) | |
# Try importing optional built-in module "strop" -- if it exists, | |
# it redefines some string operations that are 100-1000 times faster. | |
# It also defines values for whitespace, lowercase and uppercase | |
# that match <ctype.h>'s definitions. | |
try: | |
from strop import maketrans, lowercase, uppercase, whitespace | |
letters = lowercase + uppercase | |
except ImportError: | |
pass # Use the original versions | |
######################################################################## | |
# the Formatter class | |
# see PEP 3101 for details and purpose of this class | |
# The hard parts are reused from the C implementation. They're exposed as "_" | |
# prefixed methods of str and unicode. | |
# The overall parser is implemented in str._formatter_parser. | |
# The field name parser is implemented in str._formatter_field_name_split | |
class Formatter(object): | |
def format(self, format_string, *args, **kwargs): | |
return self.vformat(format_string, args, kwargs) | |
def vformat(self, format_string, args, kwargs): | |
used_args = set() | |
result = self._vformat(format_string, args, kwargs, used_args, 2) | |
self.check_unused_args(used_args, args, kwargs) | |
return result | |
def _vformat(self, format_string, args, kwargs, used_args, recursion_depth): | |
if recursion_depth < 0: | |
raise ValueError('Max string recursion exceeded') | |
result = [] | |
for literal_text, field_name, format_spec, conversion in \ | |
self.parse(format_string): | |
# output the literal text | |
if literal_text: | |
result.append(literal_text) | |
# if there's a field, output it | |
if field_name is not None: | |
# this is some markup, find the object and do | |
# the formatting | |
# given the field_name, find the object it references | |
# and the argument it came from | |
obj, arg_used = self.get_field(field_name, args, kwargs) | |
used_args.add(arg_used) | |
# do any conversion on the resulting object | |
obj = self.convert_field(obj, conversion) | |
# expand the format spec, if needed | |
format_spec = self._vformat(format_spec, args, kwargs, | |
used_args, recursion_depth-1) | |
# format the object and append to the result | |
result.append(self.format_field(obj, format_spec)) | |
return ''.join(result) | |
def get_value(self, key, args, kwargs): | |
if isinstance(key, (int, long)): | |
return args[key] | |
else: | |
return kwargs[key] | |
def check_unused_args(self, used_args, args, kwargs): | |
pass | |
def format_field(self, value, format_spec): | |
return format(value, format_spec) | |
def convert_field(self, value, conversion): | |
# do any conversion on the resulting object | |
if conversion == 'r': | |
return repr(value) | |
elif conversion == 's': | |
return str(value) | |
elif conversion is None: | |
return value | |
raise ValueError("Unknown conversion specifier {0!s}".format(conversion)) | |
# returns an iterable that contains tuples of the form: | |
# (literal_text, field_name, format_spec, conversion) | |
# literal_text can be zero length | |
# field_name can be None, in which case there's no | |
# object to format and output | |
# if field_name is not None, it is looked up, formatted | |
# with format_spec and conversion and then used | |
def parse(self, format_string): | |
return format_string._formatter_parser() | |
# given a field_name, find the object it references. | |
# field_name: the field being looked up, e.g. "0.name" | |
# or "lookup[3]" | |
# used_args: a set of which args have been used | |
# args, kwargs: as passed in to vformat | |
def get_field(self, field_name, args, kwargs): | |
first, rest = field_name._formatter_field_name_split() | |
obj = self.get_value(first, args, kwargs) | |
# loop through the rest of the field_name, doing | |
# getattr or getitem as needed | |
for is_attr, i in rest: | |
if is_attr: | |
obj = getattr(obj, i) | |
else: | |
obj = obj[i] | |
return obj, first |