| """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(*args, **kws): |
| if not args: |
| raise TypeError("descriptor 'substitute' of 'Template' object " |
| "needs an argument") |
| self, args = args[0], args[1:] # allow the "self" keyword be passed |
| 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(*args, **kws): |
| if not args: |
| raise TypeError("descriptor 'safe_substitute' of 'Template' object " |
| "needs an argument") |
| self, args = args[0], args[1:] # allow the "self" keyword be passed |
| 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') or mo.group('braced') |
| 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 mo.group() |
| if mo.group('escaped') is not None: |
| return self.delimiter |
| if mo.group('invalid') is not None: |
| return mo.group() |
| 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(*args, **kwargs): |
| if not args: |
| raise TypeError("descriptor 'format' of 'Formatter' object " |
| "needs an argument") |
| self, args = args[0], args[1:] # allow the "self" keyword be passed |
| try: |
| format_string, args = args[0], args[1:] # allow the "format_string" keyword be passed |
| except IndexError: |
| if 'format_string' in kwargs: |
| format_string = kwargs.pop('format_string') |
| else: |
| raise TypeError("format() missing 1 required positional " |
| "argument: 'format_string'") |
| 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 is None: |
| return value |
| elif conversion == 's': |
| return str(value) |
| elif conversion == 'r': |
| return repr(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 |
