fixed roman_range (descending generation) + better docs

daveoncode · daveoncode · commit e860da84a250 · 2020-03-04T10:14:08.000+01:00
diff --git a/README.md b/README.md
@@ -331,3 +331,12 @@ secure_random_hex(12)
 
 Full API documentation available on: http://python-string-utils.readthedocs.org/en/latest/
 
+
+## Support the project!
+
+Do you like this project? Would you like to see it updated more often with new features and improvements?
+If so, you can make a small donation by clicking the button down below, it would be really appreciated! :)
+
+<a href="https://www.buymeacoffee.com/c4yYUvp" target="_blank">
+<img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" width="217" height="51" />
+</a>
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -0,0 +1,20 @@
+{% extends '!layout.html' %}
+
+{% block document %}
+
+{{ super() }}
+
+<div style="padding: 30px 0 40px 0; border-top: 1px solid #ccc; margin-top: 30px">
+   <h1>Support the project!</h1>
+
+   <p>
+      Do you like this project? Would you like to see it updated more often with new features and improvements?
+      If so, you can make a small donation by clicking the button down below, it would be really appreciated! :)
+   </p>
+
+   <a href="https://www.buymeacoffee.com/c4yYUvp" target="_blank">
+      <img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" width="217" height="51" />
+   </a>
+</div>
+
+{% endblock %}
diff --git a/docs/index.rst b/docs/index.rst
@@ -32,7 +32,6 @@ The library basically consists in the python package `string_utils`, containing
 Plus a secondary package `tests` which includes several submodules.
 Specifically one for each test suite and named according to the api to test (eg. tests for `is_ip()`
 will be in `test_is_ip.py` and so on).
-
 All the public API are importable directly from the main package `string_utils`, so this:
 
 >>> from string_utils.validation import is_ip
diff --git a/string_utils/generation.py b/string_utils/generation.py
@@ -19,9 +19,10 @@ def uuid(as_hex: bool = False) -> str:
     """
     Generated an UUID string (using `uuid.uuid4()`).
 
-    *Example:*
+    *Examples:*
 
     >>> uuid() # possible output: '97e3a716-6b33-4ab9-9bb1-8128cb24d76b'
+    >>> uuid(as_hex=True) # possible output: '97e3a7166b334ab99bb18128cb24d76b'
 
     :param as_hex: True to return the hex value of the UUID, False to get its default representation (default).
     :return: uuid string.
@@ -60,7 +61,7 @@ def secure_random_hex(byte_count: int) -> str:
     """
     Generates a random string using secure low level random generator (os.urandom).
 
-    BEAR IN MIND: due to hex conversion, the returned string will have a size that is exactly\
+    **Bear in mind**: due to hex conversion, the returned string will have a size that is exactly\
     the double of the given `byte_count`.
 
     *Example:*
@@ -88,27 +89,49 @@ def roman_range(stop: int, start: int = 1, step: int = 1) -> Generator:
 
     *Example:*
 
-    >>> for n in roman_range(7): print(n) # prints: I, II, III, IV, V, VI, VII
+    >>> for n in roman_range(7): print(n)
+    >>> # prints: I, II, III, IV, V, VI, VII
+    >>> for n in roman_range(start=7, stop=1, step=-1): print(n)
+    >>> # prints: VII, VI, V, IV, III, II, I
 
     :param stop: Number at which the generation must stop (must be <= 3999).
     :param start: Number at which the generation must start (must be >= 1).
     :param step: Increment of each generation step (default to 1).
     :return: Generator of roman numbers.
     """
 
-    def validate(arg_value, arg_name):
-        if not isinstance(arg_value, int) or (arg_value < 1 or arg_value > 3999):
-            raise ValueError('"{}" must be an integer in the range 1-3999'.format(arg_name))
+    def validate(arg_value, arg_name, allow_negative=False):
+        msg = '"{}" must be an integer in the range 1-3999'.format(arg_name)
+
+        if not isinstance(arg_value, int):
+            raise ValueError(msg)
+
+        if allow_negative:
+            arg_value = abs(arg_value)
+
+        if arg_value < 1 or arg_value > 3999:
+            raise ValueError(msg)
 
     def generate():
-        current_step = start
+        current = start
+
+        # generate values for each step
+        while current != stop:
+            yield roman_encode(current)
+            current += step
 
-        while current_step < stop + 1:
-            yield roman_encode(current_step)
-            current_step += step
+        # last value to return
+        yield roman_encode(current)
 
+    # checks each single argument value
     validate(stop, 'stop')
     validate(start, 'start')
-    validate(step, 'step')
+    validate(step, 'step', allow_negative=True)
+
+    # checks if the provided configuration leads to a feasible iteration with respect to boundaries or not
+    forward_exceed = step > 0 and (start > stop or start + step > stop)
+    backward_exceed = step < 0 and (start < stop or start + step < stop)
+    if forward_exceed or backward_exceed:
+        raise OverflowError('Invalid start/stop/step configuration')
 
     return generate()
diff --git a/string_utils/manipulation.py b/string_utils/manipulation.py
@@ -404,24 +404,24 @@ def strip_html(input_string: str, keep_tag_content: bool = False) -> str:
 
 def prettify(input_string: str) -> str:
     """
-    Turns an ugly text string into a beautiful one by applying a regex pipeline which ensures the following:
+    Reformat a string by applying the following basic grammar and formatting rules:
 
-    - String cannot start or end with spaces\
-    - String cannot have multiple sequential spaces, empty lines or punctuation (except for "?", "!" and ".")\
-    - Arithmetic operators (+, -, /, \\*, =) must have one, and only one space before and after themselves\
-    - The first letter after a dot, an exclamation or a question mark must be uppercase\
-    - One, and only one space should follow a dot, an exclamation or a question mark\
+    - String cannot start or end with spaces
+    - The first letter in the string and the ones after a dot, an exclamation or a question mark must be uppercase
+    - String cannot have multiple sequential spaces, empty lines or punctuation (except for "?", "!" and ".")
+    - Arithmetic operators (+, -, /, \\*, =) must have one, and only one space before and after themselves
+    - One, and only one space should follow a dot, a comma, an exclamation or a question mark
     - Text inside double quotes cannot start or end with spaces, but one, and only one space must come first and \
     after quotes (foo" bar"baz -> foo "bar" baz)
     - Text inside round brackets cannot start or end with spaces, but one, and only one space must come first and \
-    after brackets ("foo(bar )baz" -> "foo (bar) baz")\
-    - Percentage sign ("%") cannot be preceded by a space if there is a number before ("100 %" -> "100%")\
+    after brackets ("foo(bar )baz" -> "foo (bar) baz")
+    - 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!'
+    >>> # -> 'Unprettified string, like this one, will be "prettified". It\'s awesome!'
 
     :param input_string: String to manipulate
     :return: Prettified string.
@@ -435,7 +435,7 @@ def asciify(input_string: str) -> str:
     Force string content to be ascii-only by translating all non-ascii chars into the closest possible representation
     (eg: ó -> o, Ë -> E, ç -> c...).
 
-    Some chars may be lost if impossible to translate.
+    **Bear in mind**: Some chars may be lost if impossible to translate.
 
     *Example:*
 
@@ -500,16 +500,21 @@ def slugify(input_string: str, separator: str = '-') -> str:
 def booleanize(input_string: str) -> bool:
     """
     Turns a string into a boolean based on its content (CASE INSENSITIVE).
+
     A positive boolean (True) is returned if the string value is one of the following:
+
     - "true"
     - "1"
     - "yes"
     - "y"
+
     Otherwise False is returned.
 
-    *Example:*
+    *Examples:*
 
     >>> booleanize('true') # returns True
+    >>> booleanize('YES') # returns True
+    >>> booleanize('nope') # returns False
 
     :param input_string: String to convert
     :type input_string: str
@@ -525,6 +530,20 @@ def strip_margin(input_string: str) -> str:
     """
     Removes tab indentation from multi line strings (inspired by analogous Scala function).
 
+    *Example:*
+
+    >>> strip_margin('''
+    >>>                 line 1
+    >>>                 line 2
+    >>>                 line 3
+    >>> ''')
+    >>> # returns:
+    >>> '''
+    >>> line 1
+    >>> line 2
+    >>> line 3
+    >>> '''
+
     :param input_string: String to format
     :type input_string: str
     :return: A string without left margins
@@ -559,7 +578,7 @@ def compress(input_string: str, encoding: str = 'utf-8', compression_level: int
 
     *Examples:*
 
-    >>> n = 0 # fix for Pycharm (not fixable using ignore comments)... ignore it
+    >>> n = 0 # <- ignore this, it's a fix for Pycharm (not fixable using ignore comments)
     >>> # "original" will be a string with 169 chars:
     >>> original = ' '.join(['word n{}'.format(n) for n in range(20)])
     >>> # "compressed" will be a string of 88 chars
@@ -592,6 +611,7 @@ def decompress(input_string: str, encoding: str = 'utf-8') -> str:
 def roman_encode(input_number: Union[str, int]) -> str:
     """
     Convert the given number/string into a roman number.
+
     The passed input must represents a positive integer in the range 1-3999 (inclusive).
 
     Why this limit? You may be wondering:
diff --git a/string_utils/validation.py b/string_utils/validation.py
@@ -204,11 +204,11 @@ def is_email(input_string: Any) -> bool:
     """
     Check if a string is an email.
 
-    By design, the implementation of this checking does not follow the specification for a valid \
+    By design, the implementation of this checking does not strictly follow the specification for a valid \
     email address, but instead it's based on real world cases in order to match more than 99% \
     of emails and catch user mistakes. For example the percentage sign "%" is a valid sign for an email, \
     but actually no one use it, instead if such sign is found in a string coming from user input (like a \
-    web form) is very likely that the intention was to type "5" (which is on the same key on a US keyboard).
+    web form) it's very likely that it's a mistake.
 
     *Examples:*
 
@@ -225,22 +225,21 @@ def is_email(input_string: Any) -> bool:
 def is_credit_card(input_string: Any, card_type: str = None) -> bool:
     """
     Checks if a string is a valid credit card number.
-    If card type is provided then it checks that specific type,
+    If card type is provided then it checks against that specific type only,
     otherwise any known credit card number will be accepted.
 
-    :param input_string: String to check.
-    :type input_string: str
-    :param card_type: Card type. Can be one of these:
+    Supported card types are the following:
 
-    * VISA
-    * MASTERCARD
-    * AMERICAN_EXPRESS
-    * DINERS_CLUB
-    * DISCOVER
-    * JCB
-
-    or None. Default to None (any card).
+    - VISA
+    - MASTERCARD
+    - AMERICAN_EXPRESS
+    - DINERS_CLUB
+    - DISCOVER
+    - JCB
 
+    :param input_string: String to check.
+    :type input_string: str
+    :param card_type: Card type. Default to None (any card).
     :type card_type: str
 
     :return: True if credit card, false otherwise.
@@ -290,10 +289,9 @@ def is_snake_case(input_string: Any, separator: str = '_') -> bool:
 
     A string is considered snake case when:
 
-    * it's composed only by lowercase letters ([a-z]), underscores (or provided separator) \
-    and optionally numbers ([0-9])
-    * it does not start/end with an underscore (or provided separator)
-    * it does not start with a number
+    - it's composed only by lowercase/uppercase letters and digits
+    - it contains at least one underscore (or provided separator)
+    - it does not start with a number
 
     *Examples:*
 
@@ -511,7 +509,7 @@ def is_isogram(input_string: Any) -> bool:
 
 def is_slug(input_string: Any, sign: str = '-') -> bool:
     """
-    Checks if a given string is a slug.
+    Checks if a given string is a slug (as created by `slugify()`).
 
     *Examples:*
 
@@ -534,9 +532,10 @@ def is_slug(input_string: Any, sign: str = '-') -> bool:
 
 def contains_html(input_string: str) -> bool:
     """
-    Checks if the given string contains html code.
-    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.
+    Checks if the given string contains HTML/XML tags.
+
+    By design, this function matches ANY type of tag, so don't expect to use it
+    as an HTML validator, its goal is to detect "malicious" or undesired tags in the text.
 
     *Examples:*
 
@@ -565,7 +564,7 @@ def words_count(input_string: str) -> int:
     *Examples:*
 
     >>> words_count('hello world') # returns 2
-    >>> words_count('one,two,three') # returns 3 (no need for spaces, punctuation is recognized!)
+    >>> words_count('one,two,three.stop') # returns 4
 
     :param input_string: String to check.
     :type input_string: str
diff --git a/tests/test_roman_range.py b/tests/test_roman_range.py
