Converted a large part of utils/ folder to google code docstrings as per #709.

evennia/utils/ansi.py

@@ -80,6 +80,13 @@ class ANSIParser(object):
         """
         Replacer used by `re.sub` to replace ANSI
         markers with correct ANSI sequences
+
+        Args:
+            ansimatch (re.matchobject): The match.
+
+        Returns:
+            processed (str): The processed match string.
+
         """
         return self.ansi_map.get(ansimatch.group(), "")
 
@@ -87,6 +94,13 @@ class ANSIParser(object):
         """
         Replacer used by `re.sub` to replace ANSI
         bright background markers with Xterm256 replacement
+
+        Args:
+            ansimatch (re.matchobject): The match.
+
+        Returns:
+            processed (str): The processed match string.
+
         """
         return self.ansi_bright_bgs.get(ansimatch.group(), "")
 
@@ -97,6 +111,14 @@ class ANSIParser(object):
 
         It checks `self.do_xterm256` to determine if conversion
         to standard ANSI should be done or not.
+
+        Args:
+            rgbmatch (re.matchobject): The match.
+            convert (bool, optional): Convert 256-colors to 16.
+
+        Returns:
+            processed (str): The processed match string.
+
         """
         if not rgbmatch:
             return ""
@@ -177,21 +199,43 @@ class ANSIParser(object):
     def strip_raw_codes(self, string):
         """
         Strips raw ANSI codes from a string.
+
+        Args:
+            string (str): The string to strip.
+
+        Returns:
+            string (str): The processed string.
+
         """
         return self.ansi_regex.sub("", string)
 
     def strip_mxp(self, string):
         """
         Strips all MXP codes from a string.
+
+        Args:
+            string (str): The string to strip.
+
+        Returns:
+            string (str): The processed string.
+
         """
         return self.mxp_sub.sub(r'\2', string)
 
     def parse_ansi(self, string, strip_ansi=False, xterm256=False, mxp=False):
         """
-        Parses a string, subbing color codes according to
-        the stored mapping.
+        Parses a string, subbing color codes according to the stored
+        mapping.
 
-        strip_ansi flag instead removes all ANSI markup.
+        Args:
+            string (str): The string to parse.
+            strip_ansi (boolean, optional): Strip all found ansi markup.
+            xterm256 (boolean, optional): If actually using xterm256 or if
+                these values should be converted to 16-color ANSI.
+            mxp (boolean, optional): Parse MXP commands in string.
+
+        Returns:
+            string (str): The parsed string.
 
         """
         if hasattr(string, '_raw_string'):
@@ -351,27 +395,57 @@ def parse_ansi(string, strip_ansi=False, parser=ANSI_PARSER, xterm256=False, mxp
     """
     Parses a string, subbing color codes as needed.
 
+    Args:
+        string (str): The string to parse.
+        strip_ansi (bool, optional): Strip all ANSI sequences.
+        parser (ansi.AnsiParser, optional): A parser instance to use.
+        xterm256 (bool, optional): Support xterm256 or not.
+        mxp (bool, optional): Support MXP markup or not.
+
+    Returns:
+        string (str): The parsed string.
+
     """
     return parser.parse_ansi(string, strip_ansi=strip_ansi, xterm256=xterm256, mxp=mxp)
 
 
 def strip_ansi(string, parser=ANSI_PARSER):
     """
-    Strip all ansi from the string.
+    Strip all ansi from the string. This handles the Evennia-specific
+    markup.
+
+    Args:
+        parser (ansi.AnsiParser, optional): The parser to use.
+
+    Returns:
+        string (str): The stripped string.
 
     """
     return parser.parse_ansi(string, strip_ansi=True)
 
 def strip_raw_ansi(string, parser=ANSI_PARSER):
     """
-    Remove raw ansi codes from string
+    Remove raw ansi codes from string. This assumes pure
+    ANSI-bytecodes in the string.
+
+    Args:
+        string (str): The string to parse.
+        parser (bool, optional): The parser to use.
+
+    Returns:
+        string (str): the stripped string.
     """
     return parser.strip_raw_codes(string)
 
 
 def raw(string):
     """
-    Escapes a string into a form which won't be colorized by the ansi parser.
+    Escapes a string into a form which won't be colorized by the ansi
+    parser.
+
+    Returns:
+        string (str): The raw, escaped string.
+
     """
     return string.replace('{', '{{')
 
@@ -385,8 +459,9 @@ def group(lst, n):
 
 def _spacing_preflight(func):
     """
-    This wrapper function is used to do some preflight checks on functions used
-    for padding ANSIStrings.
+    This wrapper function is used to do some preflight checks on
+    functions used for padding ANSIStrings.
+
     """
     def wrapped(self, width, fillchar=None):
         if fillchar is None:
@@ -404,8 +479,9 @@ def _spacing_preflight(func):
 
 def _query_super(func_name):
     """
-    Have the string class handle this with the cleaned string instead of
-    ANSIString.
+    Have the string class handle this with the cleaned string instead
+    of ANSIString.
+
     """
     def wrapped(self, *args, **kwargs):
         return getattr(self.clean(), func_name)(*args, **kwargs)
@@ -415,6 +491,7 @@ def _query_super(func_name):
 def _on_raw(func_name):
     """
     Like query_super, but makes the operation run on the raw string.
+
     """
     def wrapped(self, *args, **kwargs):
         args = list(args)
@@ -439,6 +516,7 @@ def _transform(func_name):
     return a string the same length as the original. This function
     allows us to do the same, replacing all the non-coded characters
     with the resulting string.
+
     """
     def wrapped(self, *args, **kwargs):
         replacement_string = _query_super(func_name)(self, *args, **kwargs)
@@ -461,6 +539,7 @@ class ANSIMeta(type):
     """
     Many functions on ANSIString are just light wrappers around the unicode
     base class. We apply them here, as part of the classes construction.
+
     """
     def __init__(cls, *args, **kwargs):
         for func_name in [
@@ -493,6 +572,7 @@ class ANSIString(unicode):
 
     Please refer to the Metaclass, ANSIMeta, which is used to apply wrappers
     for several of the methods that need not be defined directly here.
+
     """
     __metaclass__ = ANSIMeta
 
@@ -506,6 +586,7 @@ class ANSIString(unicode):
         Internally, ANSIString can also passes itself precached code/character
         indexes and clean strings to avoid doing extra work when combining
         ANSIStrings.
+
         """
         string = args[0]
         if not isinstance(string, basestring):
@@ -554,9 +635,11 @@ class ANSIString(unicode):
 
     def __unicode__(self):
         """
-        Unfortunately, this is not called during print() statements due to a
-        bug in the Python interpreter. You can always do unicode() or str()
-        around the resulting ANSIString and print that.
+        Unfortunately, this is not called during print() statements
+        due to a bug in the Python interpreter. You can always do
+        unicode() or str() around the resulting ANSIString and print
+        that.
+
         """
         return self._raw_string
 
@@ -564,6 +647,7 @@ class ANSIString(unicode):
         """
         Let's make the repr the command that would actually be used to
         construct this object, for convenience and reference.
+
         """
         return "ANSIString(%s, decoded=True)" % repr(self._raw_string)
 
@@ -592,6 +676,7 @@ class ANSIString(unicode):
         Finally, _code_indexes and _char_indexes are defined. These are lookup
         tables for which characters in the raw string are related to ANSI
         escapes, and which are for the readable text.
+
         """
         self.parser = kwargs.pop('parser', ANSI_PARSER)
         super(ANSIString, self).__init__()
@@ -603,6 +688,7 @@ class ANSIString(unicode):
         """
         Takes a list of integers, and produces a new one incrementing all
         by a number.
+
         """
         return [i + offset for i in iterable]
 
@@ -610,6 +696,7 @@ class ANSIString(unicode):
     def _adder(cls, first, second):
         """
         Joins two ANSIStrings, preserving calculated info.
+
         """
 
         raw_string = first._raw_string + second._raw_string
@@ -629,6 +716,7 @@ class ANSIString(unicode):
         We have to be careful when adding two strings not to reprocess things
         that don't need to be reprocessed, lest we end up with escapes being
         interpreted literally.
+
         """
         if not isinstance(other, basestring):
             return NotImplemented
@@ -639,6 +727,7 @@ class ANSIString(unicode):
     def __radd__(self, other):
         """
         Likewise, if we're on the other end.
+
         """
         if not isinstance(other, basestring):
             return NotImplemented
@@ -650,6 +739,7 @@ class ANSIString(unicode):
         """
         This function is deprecated, so we just make it call the proper
         function.
+
         """
         return self.__getitem__(slice(i, j))
 
@@ -667,6 +757,7 @@ class ANSIString(unicode):
         indexes that need slicing in the raw string. We can check between
         those indexes to figure out what escape characters need to be
         replayed.
+
         """
         slice_indexes = self._char_indexes[slc]
         # If it's the end of the string, we need to append final color codes.
@@ -700,6 +791,7 @@ class ANSIString(unicode):
         this is a regexable ANSIString, it will get the data from the raw
         string instead, bypassing ANSIString's intelligent escape skipping,
         for reasons explained in the __new__ method's docstring.
+
         """
         if isinstance(item, slice):
             # Slices must be handled specially.
@@ -727,12 +819,14 @@ class ANSIString(unicode):
     def clean(self):
         """
         Return a unicode object without the ANSI escapes.
+
         """
         return self._clean_string
 
     def raw(self):
         """
         Return a unicode object with the ANSI escapes.
+
         """
         return self._raw_string
 
@@ -746,6 +840,7 @@ class ANSIString(unicode):
 
         We use the same techniques we used in split() to make sure each are
         colored.
+
         """
         if hasattr(sep, '_clean_string'):
             sep = sep.clean()
@@ -776,6 +871,7 @@ class ANSIString(unicode):
 
         It's possible that only one of these tables is actually needed, the
         other assumed to be what isn't in the first.
+
         """
 
         code_indexes = []
@@ -792,6 +888,7 @@ class ANSIString(unicode):
         """
         Get the code characters from the given slice end to the next
         character.
+
         """
         try:
             index = self._char_indexes[index - 1]
@@ -815,6 +912,7 @@ class ANSIString(unicode):
 
         PyPy is distributed under the MIT licence.
         http://opensource.org/licenses/MIT
+
         """
         bylen = len(by)
         if bylen == 0:
@@ -837,6 +935,7 @@ class ANSIString(unicode):
     def __mul__(self, other):
         """
         Multiplication method. Implemented for performance reasons.
+
         """
         if not isinstance(other, int):
             return NotImplemented
@@ -863,6 +962,7 @@ class ANSIString(unicode):
 
         PyPy is distributed under the MIT licence.
         http://opensource.org/licenses/MIT
+
         """
         res = []
         end = len(self)
@@ -886,6 +986,7 @@ class ANSIString(unicode):
     def join(self, iterable):
         """
         Joins together strings in an iterable.
+
         """
         result = ANSIString('')
         last_item = None
@@ -902,6 +1003,7 @@ class ANSIString(unicode):
         """
         Generate a line of characters in a more efficient way than just adding
         ANSIStrings.
+
         """
         if not isinstance(char, ANSIString):
             line = char * amount
@@ -929,6 +1031,7 @@ class ANSIString(unicode):
     def center(self, width, fillchar, difference):
         """
         Center some text with some spaces padding both sides.
+
         """
         remainder = difference % 2
         difference /= 2
@@ -940,6 +1043,7 @@ class ANSIString(unicode):
     def ljust(self, width, fillchar, difference):
         """
         Left justify some text.
+
         """
         return self + self._filler(fillchar, difference)
 
@@ -947,5 +1051,6 @@ class ANSIString(unicode):
     def rjust(self, width, fillchar, difference):
         """
         Right justify some text.
+
         """
         return self._filler(fillchar, difference) + self