Refs #27656 -- Updated django.utils docstring verbs according to PEP 257.

django/utils/text.py

@@ -32,10 +32,10 @@ def wrap(text, width):
     A word-wrap function that preserves existing line breaks. Expects that
     existing line breaks are posix newlines.
 
-    All white space is preserved except added line breaks consume the space on
+    Preserve all white space except added line breaks consume the space on
     which they break the line.
 
-    Long words are not wrapped, so the output text may have lines longer than
+    Don't wrap long words, thus the output text may have lines longer than
     ``width``.
     """
     text = force_text(text)
@@ -84,12 +84,12 @@ class Truncator(SimpleLazyObject):
 
     def chars(self, num, truncate=None, html=False):
         """
-        Returns the text truncated to be no longer than the specified number
+        Return the text truncated to be no longer than the specified number
         of characters.
 
-        Takes an optional argument of what should be used to notify that the
-        string has been truncated, defaulting to a translatable string of an
-        ellipsis (...).
+        `truncate` specifies what should be used to notify that the string has
+        been truncated, defaulting to a translatable string of an ellipsis
+        (...).
         """
         self._setup()
         length = int(num)
@@ -107,9 +107,7 @@ class Truncator(SimpleLazyObject):
         return self._text_chars(length, truncate, text, truncate_len)
 
     def _text_chars(self, length, truncate, text, truncate_len):
-        """
-        Truncates a string after a certain number of chars.
-        """
+        """Truncate a string after a certain number of chars."""
         s_len = 0
         end_index = None
         for i, char in enumerate(text):
@@ -130,9 +128,9 @@ class Truncator(SimpleLazyObject):
 
     def words(self, num, truncate=None, html=False):
         """
-        Truncates a string after a certain number of words. Takes an optional
-        argument of what should be used to notify that the string has been
-        truncated, defaulting to ellipsis (...).
+        Truncate a string after a certain number of words. `truncate` specifies
+        what should be used to notify that the string has been truncated,
+        defaulting to ellipsis (...).
         """
         self._setup()
         length = int(num)
@@ -142,9 +140,9 @@ class Truncator(SimpleLazyObject):
 
     def _text_words(self, length, truncate):
         """
-        Truncates a string after a certain number of words.
+        Truncate a string after a certain number of words.
 
-        Newlines in the string will be stripped.
+        Strip newlines in the string.
         """
         words = self._wrapped.split()
         if len(words) > length:
@@ -154,11 +152,11 @@ class Truncator(SimpleLazyObject):
 
     def _truncate_html(self, length, truncate, text, truncate_len, words):
         """
-        Truncates HTML to a certain number of chars (not counting tags and
+        Truncate HTML to a certain number of chars (not counting tags and
         comments), or, if words is True, then to a certain number of words.
-        Closes opened tags if they were correctly closed in the given HTML.
+        Close opened tags if they were correctly closed in the given HTML.
 
-        Newlines in the HTML are preserved.
+        Preserve newlines in the HTML.
         """
         if words and length <= 0:
             return ''
@@ -228,10 +226,10 @@ class Truncator(SimpleLazyObject):
 @keep_lazy_text
 def get_valid_filename(s):
     """
-    Returns the given string converted to a string that can be used for a clean
-    filename. Specifically, leading and trailing spaces are removed; other
-    spaces are converted to underscores; and anything that is not an
-    alphanumeric, dash, underscore, or dot, is removed.
+    Return the given string converted to a string that can be used for a clean
+    filename. Remove leading and trailing spaces; convert other spaces to
+    underscores; and remove anything that is not an alphanumeric, dash,
+    underscore, or dot.
     >>> get_valid_filename("john's portrait in 2004.jpg")
     'johns_portrait_in_2004.jpg'
     """
@@ -265,14 +263,14 @@ def get_text_list(list_, last_word=gettext_lazy('or')):
 
 @keep_lazy_text
 def normalize_newlines(text):
-    """Normalizes CRLF and CR newlines to just LF."""
+    """Normalize CRLF and CR newlines to just LF."""
     text = force_text(text)
     return re_newlines.sub('\n', text)
 
 
 @keep_lazy_text
 def phone2numeric(phone):
-    """Converts a phone number with letters into its numeric equivalent."""
+    """Convert a phone number with letters into its numeric equivalent."""
     char2number = {
         'a': '2', 'b': '2', 'c': '2', 'd': '3', 'e': '3', 'f': '3', 'g': '4',
         'h': '4', 'i': '4', 'j': '5', 'k': '5', 'l': '5', 'm': '6', 'n': '6',
@@ -426,8 +424,7 @@ def slugify(value, allow_unicode=False):
 
 def camel_case_to_spaces(value):
     """
-    Splits CamelCase and converts to lower case. Also strips leading and
-    trailing whitespace.
+    Split CamelCase and convert to lower case. Strip surrounding whitespace.
     """
     return re_camel_case.sub(r' \1', value).strip().lower()