improved is_palindrome and docs

daveoncode · daveoncode · commit 136ff9332ce5 · 2020-03-03T12:40:55.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -64,7 +64,8 @@ leading or trailing underscores and string containing multiple underscores in se
 - String checks should now be a bit faster (switched from `.search()` to `.match()` in internal regex when the goal 
 is to match the full string)
 - `is_palindrome()` algorithm has been redesigned to offer a faster check and better memory usage 
-(only 2 chars are now being access at the same time instead of the whole string)
+(only 2 chars are now being access at the same time instead of the whole string)... 
+signature has changed (now it has two optional boolean arguments: `ignore_spaces` and `ignore_case`)
 - `slugify()` is now able to translate more non-ascii chars during the string conversion 
 (it now makes use of the new extracted method `asciify()`)
 - `is_uuid()` has now a second parameter `allow_hex` that if true, considers as valid UUID hex value
diff --git a/README.md b/README.md
@@ -178,7 +178,7 @@ contains_html('my string is not bold') # returns false
 **words_count**: Returns the number of words contained in the string
 ~~~~
 words_count('hello world') # returns 2
-words_count('one,two,three') # returns 3 (no need for spaces, punctuation is regnognized!)
+words_count('one,two,three') # returns 3 (no need for spaces, punctuation is recognized!)
 ~~~~
 
 **is_palindrome**: Checks if the string is a palindrome
@@ -322,3 +322,4 @@ secure_random_hex(12)
 ## Documentation
 
 Full API documentation available on: http://python-string-utils.readthedocs.org/en/latest/
+
diff --git a/string_utils/manipulation.py b/string_utils/manipulation.py
@@ -301,7 +301,11 @@ def format(self) -> str:
 
 def reverse(input_string: str) -> str:
     """
-    Returns the string reversed ("abc" -> "cba").
+    Returns the string with its chars reversed.
+
+    *Example:*
+
+    >>> reverse('hello') # returns 'olleh'
 
     :param input_string: String to revert.
     :type input_string: str
@@ -318,6 +322,10 @@ def camel_case_to_snake(input_string, separator='_'):
     Convert a camel case string into a snake case one.
     (The original string is returned if is not a valid camel case string)
 
+    *Example:*
+
+    >>> camel_case_to_snake('ThisIsACamelStringTest') # returns 'this_is_a_camel_case_string_test'
+
     :param input_string: String to convert.
     :type input_string: str
     :param separator: Sign to use as separator.
@@ -338,6 +346,10 @@ def snake_case_to_camel(input_string: str, upper_case_first: bool = True, separa
     Convert a snake case string into a camel case one.
     (The original string is returned if is not a valid snake case string)
 
+    *Example:*
+
+    >>> snake_case_to_camel('the_snake_is_green') # returns 'TheSnakeIsGreen'
+
     :param input_string: String to convert.
     :type input_string: str
     :param upper_case_first: True to turn the first letter into uppercase (default).
@@ -364,7 +376,11 @@ def snake_case_to_camel(input_string: str, upper_case_first: bool = True, separa
 
 def shuffle(input_string: str) -> str:
     """
-    Return a new string containing shuffled items.
+    Return a new string containing same chars of the given one but in a randomized order.
+
+    *Example:*
+
+    >>> shuffle('hello world') # possible output: 'l wodheorll'
 
     :param input_string: String to shuffle
     :type input_string: str
@@ -387,6 +403,11 @@ def strip_html(input_string: str, keep_tag_content: bool = False) -> str:
     """
     Remove html code contained into the given string.
 
+    *Examples:*
+
+    >>> strip_html('test: <a href="foo/bar">click here</a>') # returns 'test: '
+    >>> strip_html('test: <a href="foo/bar">click here</a>', keep_tag_content=True) # returns 'test: click here'
+
     :param input_string: String to manipulate.
     :type input_string: str
     :param keep_tag_content: True to preserve tag content, False to remove tag and its content too (default).
@@ -417,6 +438,11 @@ def prettify(input_string: str) -> str:
     - Percentage sign ("%") cannot be preceded by a space if there is a number before ("100 %" -> "100%")\
     - Saxon genitive is correct ("Dave' s dog" -> "Dave's dog")
 
+    *Examples:*
+
+    >>> prettify(' unprettified string ,, like this one,will be"prettified" .it\\' s awesome! ')
+    >>> # the ouput will be: 'Unprettified string, like this one, will be "prettified". It\'s awesome!'
+
     :param input_string: String to manipulate
     :return: Prettified string.
     """
diff --git a/string_utils/validation.py b/string_utils/validation.py
@@ -6,10 +6,10 @@
 
 __all__ = [
     'is_string',
+    'is_full_string',
     'is_number',
     'is_integer',
     'is_decimal',
-    'is_full_string',
     'is_url',
     'is_email',
     'is_credit_card',
@@ -83,6 +83,11 @@ def is_string(obj: Any) -> bool:
     """
     Checks if an object is a string.
 
+    *Example:*
+
+    >>> is_string('foo') # returns true
+    >>> is_string(b'foo') # returns false
+
     :param obj: Object to test.
     :return: True if string, false otherwise.
     """
@@ -423,43 +428,61 @@ def is_ip(input_string: Any) -> bool:
     return is_ip_v6(input_string) or is_ip_v4(input_string)
 
 
-def is_palindrome(input_string: Any, strict: bool = True) -> bool:
+def is_palindrome(input_string: Any, ignore_spaces: bool = False, ignore_case: bool = False) -> bool:
     """
     Checks if the string is a palindrome (https://en.wikipedia.org/wiki/Palindrome).
 
+    *Examples:*
+
+    >>> is_palindrome('LOL') # returns true
+    >>> is_palindrome('Lol') # returns false
+    >>> is_palindrome('Lol', ignore_case=True) # returns true
+    >>> is_palindrome('ROTFL') # returns false
+
     :param input_string: String to check.
     :type input_string: str
-    :param strict: True if white spaces matter (default), false otherwise.
-    :type strict: bool
+    :param ignore_spaces: False if white spaces matter (default), true otherwise.
+    :type ignore_spaces: bool
+    :param ignore_case: False if char case matters (default), true otherwise.
+    :type ignore_case: bool
     :return: True if the string is a palindrome (like "otto", or "i topi non avevano nipoti" if strict=False),\
     False otherwise
     """
-    if is_full_string(input_string):
-        if strict:
-            string_len = len(input_string)
+    if not is_full_string(input_string):
+        return False
 
-            # Traverse the string one char at step, and for each step compares the
-            # "head_char" (the one on the left of the string) to the "tail_char" (the one on the right).
-            # In this way we avoid to manipulate the whole string in advance if not necessary and provide a faster
-            # algorithm which can scale very well for long strings.
-            for index in range(string_len):
-                head_char = input_string[index]
-                tail_char = input_string[string_len - index - 1]
+    if ignore_spaces:
+        input_string = SPACES_RE.sub('', input_string)
 
-                if head_char != tail_char:
-                    return False
+    string_len = len(input_string)
 
-            return True
+    # Traverse the string one char at step, and for each step compares the
+    # "head_char" (the one on the left of the string) to the "tail_char" (the one on the right).
+    # In this way we avoid to manipulate the whole string in advance if not necessary and provide a faster
+    # algorithm which can scale very well for long strings.
+    for index in range(string_len):
+        head_char = input_string[index]
+        tail_char = input_string[string_len - index - 1]
 
-        return is_palindrome(SPACES_RE.sub('', input_string))
+        if ignore_case:
+            head_char = head_char.lower()
+            tail_char = tail_char.lower()
 
-    return False
+        if head_char != tail_char:
+            return False
+
+    return True
 
 
 def is_pangram(input_string: Any) -> bool:
     """
     Checks if the string is a pangram (https://en.wikipedia.org/wiki/Pangram).
 
+    *Examples:*
+
+    >>> is_pangram('The quick brown fox jumps over the lazy dog') # returns true
+    >>> is_pangram('hello world') # returns false
+
     :param input_string: String to check.
     :type input_string: str
     :return: True if the string is a pangram, False otherwise.
@@ -474,6 +497,11 @@ def is_isogram(input_string: Any) -> bool:
     """
     Checks if the string is an isogram (https://en.wikipedia.org/wiki/Isogram).
 
+    *Examples:*
+
+    >>> is_isogram('dermatoglyphics') # returns true
+    >>> is_isogram('hello') # returns false
+
     :param input_string: String to check.
     :type input_string: str
     :return: True if isogram, false otherwise.
@@ -485,6 +513,11 @@ def is_slug(input_string: Any, sign: str = '-') -> bool:
     """
     Checks if a given string is a slug.
 
+    *Examples:*
+
+    >>> is_slug('my-blog-post-title') # returns true
+    >>> is_slug('My blog post title') # returns false
+
     :param input_string: String to check.
     :type input_string: str
     :param sign: Join sign used by the slug.
@@ -505,6 +538,11 @@ def contains_html(input_string: str) -> bool:
     By design, this function is very permissive regarding what to consider html code, don't expect to use it
     as an html validator, its goal is to detect "malicious" or undesired html tags in the text.
 
+    *Examples:*
+
+    >>> contains_html('my string is <strong>bold</strong>') # returns true
+    >>> contains_html('my string is not bold') # returns false
+
     :param input_string: Text to check
     :type input_string: str
     :return: True if string contains html, false otherwise.
@@ -524,6 +562,11 @@ def words_count(input_string: str) -> int:
     Moreover it is aware of punctuation, so the count for a string like "one,two,three.stop"
     will be 4 not 1 (even if there are no spaces in the string).
 
+    *Examples:*
+
+    >>> words_count('hello world') # returns 2
+    >>> words_count('one,two,three') # returns 3 (no need for spaces, punctuation is recognized!)
+
     :param input_string: String to check.
     :type input_string: str
     :return: Number of words.
@@ -540,6 +583,12 @@ def is_isbn_10(input_string: str, normalize: bool = True) -> bool:
     By default hyphens in the string are ignored, so digits can be separated in different ways, by calling this
     function with `normalize=False` only digit-only strings will pass the validation.
 
+    *Examples:*
+
+    >>> is_isbn_10('1506715214') # returns true
+    >>> is_isbn_10('150-6715214') # returns true
+    >>> is_isbn_10('150-6715214', normalize=False) # returns false
+
     :param input_string: String to check.
     :param normalize: True to ignore hyphens ("-") in the string (default), false otherwise.
     :return: True if valid ISBN 10, false otherwise.
@@ -554,6 +603,12 @@ def is_isbn_13(input_string: str, normalize: bool = True) -> bool:
     By default hyphens in the string are ignored, so digits can be separated in different ways, by calling this
     function with `normalize=False` only digit-only strings will pass the validation.
 
+    *Examples:*
+
+    >>> is_isbn_13('9780312498580') # returns true
+    >>> is_isbn_13('978-0312498580') # returns true
+    >>> is_isbn_13('978-0312498580', normalize=False) # returns false
+
     :param input_string: String to check.
     :param normalize: True to ignore hyphens ("-") in the string (default), false otherwise.
     :return: True if valid ISBN 13, false otherwise.
@@ -568,6 +623,11 @@ def is_isbn(input_string: str, normalize: bool = True) -> bool:
     By default hyphens in the string are ignored, so digits can be separated in different ways, by calling this
     function with `normalize=False` only digit-only strings will pass the validation.
 
+    *Examples:*
+
+    >>> is_isbn('9780312498580') # returns true
+    >>> is_isbn('1506715214') # returns true
+
     :param input_string: String to check.
     :param normalize: True to ignore hyphens ("-") in the string (default), false otherwise.
     :return: True if valid ISBN (10 or 13), false otherwise.
diff --git a/tests/test_is_palindrome.py b/tests/test_is_palindrome.py
@@ -26,14 +26,20 @@ def test_non_string_objects_return_false(self):
     def test_empty_strings_are_not_palindromes(self):
         self.assertFalse(is_palindrome(''))
         self.assertFalse(is_palindrome(' '))
-        self.assertFalse(is_palindrome(' \n\t '))
+        self.assertFalse(is_palindrome('\n\t\n'))
 
-    def test_strict_checking(self):
-        self.assertFalse(is_palindrome('nope!'))
-        self.assertFalse(is_palindrome('i topi non avevano nipoti'))
+    def test_returns_true_if_palindrome_with_default_options(self):
+        self.assertTrue(is_palindrome('LOL'))
         self.assertTrue(is_palindrome('otto'))
 
-    def test_no_strict_mode(self):
-        self.assertFalse(is_palindrome('nope!', False))
-        self.assertTrue(is_palindrome('i topi non avevano nipoti', False))
-        self.assertTrue(is_palindrome('otto', False))
+    def test_returns_false_if_not_palindrome_with_default_options(self):
+        self.assertFalse(is_palindrome('nope!'))
+        self.assertFalse(is_palindrome('ROTFL'))
+
+    def test_if_not_specified_case_matters(self):
+        self.assertFalse(is_palindrome('Lol'))
+        self.assertTrue(is_palindrome('Lol', ignore_case=True))
+
+    def test_if_not_specified_spaces_matter(self):
+        self.assertFalse(is_palindrome('i topi non avevano nipoti'))
+        self.assertTrue(is_palindrome('i topi non avevano nipoti', ignore_spaces=True))
diff --git a/tests/test_is_string.py b/tests/test_is_string.py
@@ -11,6 +11,9 @@ def test_return_false_for_non_string_objects(self):
         self.assertFalse(is_string([]))
         self.assertFalse(is_string({'a': 1}))
 
+    def test_bytes_sequence_is_ont_considered_string(self):
+        self.assertFalse(is_string(b'nope!'))
+
     def test_return_true_for_string_objects(self):
         self.assertTrue(is_string(''))
         self.assertTrue(is_string('hello world'))
