python-utils 2.5.6__py3-none-any.whl → 4.0.0__py3-none-any.whl

python_utils/converters.py

@@ -1,17 +1,48 @@
-from __future__ import (absolute_import, division, print_function,
-                        unicode_literals)
+"""
+This module provides utility functions for type conversion.
 
-import re
-import six
+Functions::
+
+    to_int: Convert a string to an integer with optional regexp matching.
+    to_float: Convert a string to a float with optional regexp matching.
+    to_unicode: Convert objects to Unicode strings.
+    to_str: Convert objects to byte strings.
+    scale_1024: Scale a number down to a suitable size (powers of 1024).
+    remap: Remap a value from one range to another.
+"""
+
+# Ignoring all mypy errors because mypy doesn't understand many modern typing
+# constructs... please, use pyright instead if you can.
+from __future__ import annotations
+
+import decimal
 import math
+import re
+import typing
+
+from python_utils import _aliases
 
+#: Numeric type variable for ``remap`` (any ``int``, ``float`` or ``Decimal``).
+_TN = typing.TypeVar('_TN', bound=_aliases.DecimalNumber)
 
-def to_int(input_, default=0, exception=(ValueError, TypeError), regexp=None):
-    r'''
-    Convert the given input to an integer or return default
+#: Accepted ``regexp`` for ``to_int``/``to_float``: a compiled pattern, a
+#: pattern string, ``True`` for the built-in digit pattern, or ``None``.
+_RegexpType: typing.TypeAlias = (
+    re.Pattern[str] | str | typing.Literal[True] | None
+)
+
+
+def to_int(
+    input_: str | None = None,
+    default: int = 0,
+    exception: _aliases.ExceptionsType = (ValueError, TypeError),
+    regexp: _RegexpType = None,
+) -> int:
+    r"""
+    Convert the given input to an integer or return default.
 
     When trying to convert the exceptions given in the exception parameter
-    are automatically catched and the default will be returned.
+    are automatically caught and the default will be returned.
 
     The regexp parameter allows for a regular expression to find the digits
     in a string.
@@ -25,6 +56,10 @@ def to_int(input_, default=0, exception=(ValueError, TypeError), regexp=None):
     0
     >>> to_int('1')
     1
+    >>> to_int('')
+    0
+    >>> to_int()
+    0
     >>> to_int('abc123')
     0
     >>> to_int('123abc')
@@ -63,40 +98,45 @@ def to_int(input_, default=0, exception=(ValueError, TypeError), regexp=None):
     Traceback (most recent call last):
     ...
     TypeError: unknown argument for regexp parameter: 123
-    '''
-
+    """
     if regexp is True:
         regexp = re.compile(r'(\d+)')
-    elif isinstance(regexp, six.string_types):
+    elif isinstance(regexp, str):
         regexp = re.compile(regexp)
     elif hasattr(regexp, 'search'):
         pass
     elif regexp is not None:
-        raise TypeError('unknown argument for regexp parameter: %r' % regexp)
+        raise TypeError(f'unknown argument for regexp parameter: {regexp!r}')
 
     try:
-        if regexp:
-            match = regexp.search(input_)
-            if match:
-                input_ = match.groups()[-1]
-        return int(input_)
+        if regexp and input_ and (match := regexp.search(input_)):
+            input_ = match.groups()[-1]
+
+        if input_ is None:
+            return default
+        else:
+            return int(input_)
     except exception:
         return default
 
 
-def to_float(input_, default=0, exception=(ValueError, TypeError),
-             regexp=None):
-    r'''
-    Convert the given `input_` to an integer or return default
+def to_float(
+    input_: str,
+    default: int = 0,
+    exception: _aliases.ExceptionsType = (ValueError, TypeError),
+    regexp: _RegexpType = None,
+) -> _aliases.Number:
+    r"""
+    Convert the given `input_` to an integer or return default.
 
     When trying to convert the exceptions given in the exception parameter
-    are automatically catched and the default will be returned.
+    are automatically caught and the default will be returned.
 
     The regexp parameter allows for a regular expression to find the digits
     in a string.
     When True it will automatically match any digit in the string.
     When a (regexp) object (has a search method) is given, that will be used.
-    WHen a string is given, re.compile will be run over it first
+    When a string is given, re.compile will be run over it first
 
     The last group of the regexp will be used as value
 
@@ -136,11 +176,10 @@ def to_float(input_, default=0, exception=(ValueError, TypeError),
     Traceback (most recent call last):
     ...
     TypeError: unknown argument for regexp parameter
-    '''
-
+    """
     if regexp is True:
         regexp = re.compile(r'(\d+(\.\d+|))')
-    elif isinstance(regexp, six.string_types):
+    elif isinstance(regexp, str):
         regexp = re.compile(regexp)
     elif hasattr(regexp, 'search'):
         pass
@@ -148,69 +187,78 @@ def to_float(input_, default=0, exception=(ValueError, TypeError),
         raise TypeError('unknown argument for regexp parameter')
 
     try:
-        if regexp:
-            match = regexp.search(input_)
-            if match:
-                input_ = match.group(1)
+        if regexp and (match := regexp.search(input_)):
+            input_ = match.group(1)
         return float(input_)
     except exception:
         return default
 
 
-def to_unicode(input_, encoding='utf-8', errors='replace'):
-    '''Convert objects to unicode, if needed decodes string with the given
+def to_unicode(
+    input_: _aliases.StringTypes,
+    encoding: str = 'utf-8',
+    errors: str = 'replace',
+) -> str:
+    """Convert objects to unicode, if needed decodes string with the given
     encoding and errors settings.
 
-    :rtype: unicode
+    :rtype: str
 
     >>> to_unicode(b'a')
     'a'
     >>> to_unicode('a')
     'a'
-    >>> to_unicode(u'a')
+    >>> to_unicode('a')
     'a'
-    >>> class Foo(object): __str__ = lambda s: u'a'
+    >>> class Foo(object):
+    ...     __str__ = lambda s: 'a'
     >>> to_unicode(Foo())
     'a'
     >>> to_unicode(Foo)
     "<class 'python_utils.converters.Foo'>"
-    '''
-    if isinstance(input_, six.binary_type):
+    """
+    if isinstance(input_, bytes):
         input_ = input_.decode(encoding, errors)
     else:
-        input_ = six.text_type(input_)
+        input_ = str(input_)
     return input_
 
 
-def to_str(input_, encoding='utf-8', errors='replace'):
-    '''Convert objects to string, encodes to the given encoding
+def to_str(
+    input_: _aliases.StringTypes,
+    encoding: str = 'utf-8',
+    errors: str = 'replace',
+) -> bytes:
+    """Convert objects to string, encodes to the given encoding.
 
     :rtype: str
 
     >>> to_str('a')
     b'a'
-    >>> to_str(u'a')
+    >>> to_str('a')
     b'a'
     >>> to_str(b'a')
     b'a'
-    >>> class Foo(object): __str__ = lambda s: u'a'
+    >>> class Foo(object):
+    ...     __str__ = lambda s: 'a'
     >>> to_str(Foo())
     'a'
     >>> to_str(Foo)
     "<class 'python_utils.converters.Foo'>"
-    '''
-    if isinstance(input_, six.binary_type):
-        pass
-    else:
+    """
+    if not isinstance(input_, bytes):
         if not hasattr(input_, 'encode'):
-            input_ = six.text_type(input_)
+            input_ = str(input_)
 
         input_ = input_.encode(encoding, errors)
     return input_
 
 
-def scale_1024(x, n_prefixes):
-    '''Scale a number down to a suitable size, based on powers of 1024.
+def scale_1024(
+    x: _aliases.Number,
+    n_prefixes: int,
+) -> tuple[_aliases.Number, _aliases.Number]:
+    """Scale a number down to a suitable size, based on powers of 1024.
 
     Returns the scaled number and the power of 1024 used.
 
@@ -226,7 +274,7 @@ def scale_1024(x, n_prefixes):
     (0.5, 0)
     >>> scale_1024(1, 2)
     (1.0, 0)
-    '''
+    """
     if x <= 0:
         power = 0
     else:
@@ -235,9 +283,83 @@ def scale_1024(x, n_prefixes):
     return scaled, power
 
 
-def remap(value, old_min, old_max, new_min, new_max):
+@typing.overload
+def remap(
+    value: decimal.Decimal,
+    old_min: decimal.Decimal | float,
+    old_max: decimal.Decimal | float,
+    new_min: decimal.Decimal | float,
+    new_max: decimal.Decimal | float,
+) -> decimal.Decimal:
+    """Overload: a ``Decimal`` ``value`` yields a ``Decimal`` result."""
+
+
+@typing.overload
+def remap(
+    value: decimal.Decimal | float,
+    old_min: decimal.Decimal,
+    old_max: decimal.Decimal | float,
+    new_min: decimal.Decimal | float,
+    new_max: decimal.Decimal | float,
+) -> decimal.Decimal:
+    """Overload: a ``Decimal`` ``old_min`` yields a ``Decimal`` result."""
+
+
+@typing.overload
+def remap(
+    value: decimal.Decimal | float,
+    old_min: decimal.Decimal | float,
+    old_max: decimal.Decimal,
+    new_min: decimal.Decimal | float,
+    new_max: decimal.Decimal | float,
+) -> decimal.Decimal:
+    """Overload: a ``Decimal`` ``old_max`` yields a ``Decimal`` result."""
+
+
+@typing.overload
+def remap(
+    value: decimal.Decimal | float,
+    old_min: decimal.Decimal | float,
+    old_max: decimal.Decimal | float,
+    new_min: decimal.Decimal,
+    new_max: decimal.Decimal | float,
+) -> decimal.Decimal:
+    """Overload: a ``Decimal`` ``new_min`` yields a ``Decimal`` result."""
+
+
+@typing.overload
+def remap(
+    value: decimal.Decimal | float,
+    old_min: decimal.Decimal | float,
+    old_max: decimal.Decimal | float,
+    new_min: decimal.Decimal | float,
+    new_max: decimal.Decimal,
+) -> decimal.Decimal:
+    """Overload: a ``Decimal`` ``new_max`` yields a ``Decimal`` result."""
+
+
+# Note that float captures both int and float types so we don't need to
+# specify them separately
+@typing.overload
+def remap(
+    value: float,
+    old_min: float,
+    old_max: float,
+    new_min: float,
+    new_max: float,
+) -> float:
+    """Overload: all-``float`` (or ``int``) inputs yield a ``float``."""
+
+
+def remap(  # pyright: ignore[reportInconsistentOverload]
+    value: _TN,
+    old_min: _TN,
+    old_max: _TN,
+    new_min: _TN,
+    new_max: _TN,
+) -> _TN:
     """
-    remap a value from one range into another.
+    Remap a value from one range into another.
 
     >>> remap(500, 0, 1000, 0, 100)
     50
@@ -247,54 +369,112 @@ def remap(value, old_min, old_max, new_min, new_max):
     -750
     >>> remap(33, 0, 100, -500, 500)
     -170
+    >>> remap(decimal.Decimal('250.0'), 0.0, 1000.0, 0.0, 100.0)
+    Decimal('25.0')
 
     This is a great use case example. Take an AVR that has dB values the
     minimum being -80dB and the maximum being 10dB and you want to convert
-    volume percent to the equilivint in that dB range
+    volume percent to the equivalent in that dB range
 
     >>> remap(46.0, 0.0, 100.0, -80.0, 10.0)
     -38.6
 
-    Some edge cases to test
-    >>> remap(0, 0, 0, 0, 0)
-    0
-    >>> remap(0, 0, 0, 1, 0)
-    1
+    I added using decimal.Decimal so floating point math errors can be avoided.
+    Here is an example of a floating point math error
+    >>> 0.1 + 0.1 + 0.1
+    0.30000000000000004
+
+    If floating point remaps need to be done my suggestion is to pass at least
+    one parameter as a `decimal.Decimal`. This will ensure that the output
+    from this function is accurate. I left passing `floats` for backwards
+    compatibility and there is no conversion done from float to
+    `decimal.Decimal` unless one of the passed parameters has a type of
+    `decimal.Decimal`. This will ensure that any existing code that uses this
+    function will work exactly how it has in the past.
 
-    :param value: value to be converted
-    :type value: int, float
+    Some edge cases to test
+    >>> remap(1, 0, 0, 1, 2)
+    Traceback (most recent call last):
+    ...
+    ValueError: Input range (0-0) is empty
 
-    :param old_min: minimum of the range for the value that has been passed
-    :type old_min: int, float
+    >>> remap(1, 1, 2, 0, 0)
+    Traceback (most recent call last):
+    ...
+    ValueError: Output range (0-0) is empty
+
+    Args:
+        value (int, float, decimal.Decimal): Value to be converted.
+        old_min (int, float, decimal.Decimal): Minimum of the range for the
+            value that has been passed.
+        old_max (int, float, decimal.Decimal): Maximum of the range for the
+            value that has been passed.
+        new_min (int, float, decimal.Decimal): The minimum of the new range.
+        new_max (int, float, decimal.Decimal): The maximum of the new range.
+
+    Returns: int, float, decimal.Decimal: Value that has been re-ranged. If
+        any of the parameters passed is a `decimal.Decimal`, all of the
+        parameters will be converted to `decimal.Decimal`. The same thing also
+        happens if one of the parameters is a `float`. Otherwise, all
+        parameters will get converted into an `int`. Technically, you can pass
+        a `str` of an integer and it will get converted. The returned value
+        type will be `decimal.Decimal` if any of the passed parameters are
+        `decimal.Decimal`, the return type will be `float` if any of the
+        passed parameters are a `float`, otherwise the returned type will be
+        `int`.
+    """
+    # Promote every argument to one common type: Decimal if any input is a
+    # Decimal, otherwise float if any is a float, otherwise int. This preserves
+    # the caller's precision (see above) instead of silently downcasting.
+    type_: type[_aliases.DecimalNumber]
+    if (
+        isinstance(value, decimal.Decimal)
+        or isinstance(old_min, decimal.Decimal)
+        or isinstance(old_max, decimal.Decimal)
+        or isinstance(new_min, decimal.Decimal)
+        or isinstance(new_max, decimal.Decimal)
+    ):
+        type_ = decimal.Decimal
+    elif (
+        isinstance(value, float)
+        or isinstance(old_min, float)
+        or isinstance(old_max, float)
+        or isinstance(new_min, float)
+        or isinstance(new_max, float)
+    ):
+        type_ = float
+    else:
+        type_ = int
 
-    :param old_max: maximum of the range for the value that has been passed
-    :type old_max: int, float
+    value = typing.cast(_TN, type_(value))
+    old_min = typing.cast(_TN, type_(old_min))
+    old_max = typing.cast(_TN, type_(old_max))
+    new_max = typing.cast(_TN, type_(new_max))
+    new_min = typing.cast(_TN, type_(new_min))
 
-    :param new_min: the minimum of the new range
-    :type new_min: int, float
+    # These might not be floats but the Python type system doesn't understand
+    # the generic type system in this case
+    old_range = typing.cast(float, old_max) - typing.cast(float, old_min)
+    new_range = typing.cast(float, new_max) - typing.cast(float, new_min)
 
-    :param new_max: the maximum of the new range
-    :type new_max: int, float
+    if old_range == 0:
+        raise ValueError(f'Input range ({old_min}-{old_max}) is empty')
 
-    :return: value that has been re ranged, if the value is an int floor
-             division is used so the returned value will always be rounded down
-             to the closest whole number.
-    :rtype: int, float
-    """
-    old_range = old_max - old_min
-    new_range = new_max - new_min
     if new_range == 0:
-        return 0
+        raise ValueError(f'Output range ({new_min}-{new_max}) is empty')
 
-    if old_range == 0:
-        new_value = new_min
+    # The current state of Python typing makes it impossible to use the
+    # generic type system in this case. Or so extremely verbose that it's not
+    # worth it.
+    new_value = (value - old_min) * new_range  # type: ignore[operator]  # pyright: ignore[reportOperatorIssue, reportUnknownVariableType]
+
+    # Integer inputs use floor division to keep the result integral; float and
+    # Decimal inputs use true division.
+    if type_ is int:
+        new_value //= old_range  # pyright: ignore[reportUnknownVariableType]  # pyrefly: ignore[unsupported-operation]
     else:
-        new_value = (value - old_min) * new_range
-        if isinstance(value, int):
-            new_value = new_value // old_range
-        else:
-            new_value = new_value / old_range
+        new_value /= old_range  # pyright: ignore[reportUnknownVariableType]  # pyrefly: ignore[unsupported-operation]
 
-        new_value += new_min
+    new_value += new_min  # type: ignore[operator] # pyright: ignore[reportOperatorIssue, reportUnknownVariableType]
 
-    return new_value
+    return typing.cast(_TN, new_value)