python-utils 3.8.2__py2.py3-none-any.whl → 3.9.1__py2.py3-none-any.whl

python_utils/converters.py

@@ -1,21 +1,45 @@
+"""
+This module provides utility functions for type conversion.
+
+Functions:
+    - to_int: Convert a string to an integer with optional regular expression
+    matching.
+    - to_float: Convert a string to a float with optional regular expression
+    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 based on 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 typing import Union
 
 from . import types
 
 _TN = types.TypeVar('_TN', bound=types.DecimalNumber)
 
+_RegexpType: types.TypeAlias = Union[
+    types.Pattern[str], str, types.Literal[True], None
+]
+
 
 def to_int(
-    input_: typing.Optional[str] = None,
+    input_: str | None = None,
     default: int = 0,
     exception: types.ExceptionsType = (ValueError, TypeError),
-    regexp: types.Optional[types.Pattern[str]] = None,
+    regexp: _RegexpType = None,
 ) -> int:
-    r'''
-    Convert the given input to an integer or return default
+    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.
@@ -74,7 +98,7 @@ def to_int(
     Traceback (most recent call last):
     ...
     TypeError: unknown argument for regexp parameter: 123
-    '''
+    """
     if regexp is True:
         regexp = re.compile(r'(\d+)')
     elif isinstance(regexp, str):
@@ -82,18 +106,17 @@ def to_int(
     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 and input_:
-            if match := regexp.search(input_):
-                input_ = match.groups()[-1]
+        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:  # type: ignore
+    except exception:
         return default
 
 
@@ -101,10 +124,10 @@ def to_float(
     input_: str,
     default: int = 0,
     exception: types.ExceptionsType = (ValueError, TypeError),
-    regexp: types.Optional[types.Pattern[str]] = None,
+    regexp: _RegexpType = None,
 ) -> types.Number:
-    r'''
-    Convert the given `input_` to an integer or return default
+    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.
@@ -113,7 +136,7 @@ def to_float(
     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
 
@@ -153,8 +176,7 @@ def to_float(
     Traceback (most recent call last):
     ...
     TypeError: unknown argument for regexp parameter
-    '''
-
+    """
     if regexp is True:
         regexp = re.compile(r'(\d+(\.\d+|))')
     elif isinstance(regexp, str):
@@ -165,9 +187,8 @@ def to_float(
         raise TypeError('unknown argument for regexp parameter')
 
     try:
-        if regexp:
-            if match := regexp.search(input_):
-                input_ = match.group(1)
+        if regexp and (match := regexp.search(input_)):
+            input_ = match.group(1)
         return float(input_)
     except exception:
         return default
@@ -178,7 +199,7 @@ def to_unicode(
     encoding: str = 'utf-8',
     errors: str = 'replace',
 ) -> str:
-    '''Convert objects to unicode, if needed decodes string with the given
+    """Convert objects to unicode, if needed decodes string with the given
     encoding and errors settings.
 
     :rtype: str
@@ -187,14 +208,15 @@ def to_unicode(
     '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_, bytes):
         input_ = input_.decode(encoding, errors)
     else:
@@ -207,22 +229,23 @@ def to_str(
     encoding: str = 'utf-8',
     errors: str = 'replace',
 ) -> bytes:
-    '''Convert objects to string, encodes to the given encoding
+    """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 not isinstance(input_, bytes):
         if not hasattr(input_, 'encode'):
             input_ = str(input_)
@@ -235,7 +258,7 @@ def scale_1024(
     x: types.Number,
     n_prefixes: int,
 ) -> types.Tuple[types.Number, types.Number]:
-    '''Scale a number down to a suitable size, based on powers of 1024.
+    """Scale a number down to a suitable size, based on powers of 1024.
 
     Returns the scaled number and the power of 1024 used.
 
@@ -251,7 +274,7 @@ def scale_1024(
     (0.5, 0)
     >>> scale_1024(1, 2)
     (1.0, 0)
-    '''
+    """
     if x <= 0:
         power = 0
     else:
@@ -260,14 +283,76 @@ def scale_1024(
     return scaled, power
 
 
+@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: ...
+
+
+@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: ...
+
+
+@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: ...
+
+
+@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: ...
+
+
+@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: ...
+
+
+# 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: ...
+
+
+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(500, 0, 1000, 0, 100)
@@ -312,33 +397,26 @@ def remap(
     ...
     ValueError: Output range (0-0) is empty
 
-    :param value: value to be converted
-    :type value: int, float, decimal.Decimal
-
-    :param old_min: minimum of the range for the value that has been passed
-    :type old_min: int, float, decimal.Decimal
-
-    :param old_max: maximum of the range for the value that has been passed
-    :type old_max: int, float, decimal.Decimal
-
-    :param new_min: the minimum of the new range
-    :type new_min: int, float, decimal.Decimal
-
-    :param new_max: the maximum of the new range
-    :type new_max: int, float, decimal.Decimal
-
-    :return: 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`
-        of any of the passed parameters ar `decimal.Decimal`, the return type
-        will be `float` if any of the passed parameters are a `float` otherwise
-        the returned type will be `int`.
-
-    :rtype: int, float, decimal.Decimal
-    '''
+    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`.
+    """
     type_: types.Type[types.DecimalNumber]
     if (
         isinstance(value, decimal.Decimal)
@@ -356,7 +434,6 @@ def remap(
         or isinstance(new_max, float)
     ):
         type_ = float
-
     else:
         type_ = int
 
@@ -377,13 +454,16 @@ def remap(
     if new_range == 0:
         raise ValueError(f'Output range ({new_min}-{new_max}) is empty')
 
-    new_value = (value - old_min) * new_range  # type: ignore
+    # 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]
 
-    if type_ == int:
-        new_value //= old_range  # type: ignore
+    if type_ is int:
+        new_value //= old_range  # pyright: ignore[reportUnknownVariableType]
     else:
-        new_value /= old_range  # type: ignore
+        new_value /= old_range  # pyright: ignore[reportUnknownVariableType]
 
-    new_value += new_min  # type: ignore
+    new_value += new_min  # type: ignore[operator] # pyright: ignore[reportOperatorIssue, reportUnknownVariableType]
 
     return types.cast(_TN, new_value)

python_utils/decorators.py

@@ -1,17 +1,33 @@
+"""
+This module provides various utility decorators for Python functions
+and methods.
+
+The decorators include:
+
+1. `set_attributes`: Sets attributes on functions and classes.
+2. `listify`: Converts any generator to a list or other collection.
+3. `sample`: Limits calls to a function based on a sample rate.
+4. `wraps_classmethod`: Wraps classmethods with type info from a
+   regular method.
+
+Each decorator is designed to enhance the functionality of Python
+functions and methods in a simple and reusable manner.
+"""
+
 import contextlib
 import functools
 import logging
 import random
+
 from . import types
 
 _T = types.TypeVar('_T')
-_TC = types.TypeVar('_TC', bound=types.Container[types.Any])
 _P = types.ParamSpec('_P')
 _S = types.TypeVar('_S', covariant=True)
 
 
 def set_attributes(**kwargs: types.Any) -> types.Callable[..., types.Any]:
-    '''Decorator to set attributes on functions and classes
+    """Decorator to set attributes on functions and classes.
 
     A common usage for this pattern is the Django Admin where
     functions can get an optional short_description. To illustrate:
@@ -23,19 +39,19 @@ def set_attributes(**kwargs: types.Any) -> types.Callable[..., types.Any]:
 
     >>> @set_attributes(short_description='Name')
     ... def upper_case_name(self, obj):
-    ...     return ("%s %s" % (obj.first_name, obj.last_name)).upper()
+    ...     return ('%s %s' % (obj.first_name, obj.last_name)).upper()
 
     The standard Django version:
 
     >>> def upper_case_name(obj):
-    ...     return ("%s %s" % (obj.first_name, obj.last_name)).upper()
+    ...     return ('%s %s' % (obj.first_name, obj.last_name)).upper()
 
     >>> upper_case_name.short_description = 'Name'
 
-    '''
+    """
 
     def _set_attributes(
-        function: types.Callable[_P, _T]
+        function: types.Callable[_P, _T],
     ) -> types.Callable[_P, _T]:
         for key, value in kwargs.items():
             setattr(function, key, value)
@@ -46,14 +62,14 @@ def set_attributes(**kwargs: types.Any) -> types.Callable[..., types.Any]:
 
 def listify(
     collection: types.Callable[
-        [types.Iterable[_T]], _TC
-    ] = list,  # type: ignore
+        [types.Iterable[_T]], types.Collection[_T]
+    ] = list,
     allow_empty: bool = True,
 ) -> types.Callable[
     [types.Callable[..., types.Optional[types.Iterable[_T]]]],
-    types.Callable[..., _TC],
+    types.Callable[..., types.Collection[_T]],
 ]:
-    '''
+    """
     Convert any generator to a list or other type of collection.
 
     >>> @listify()
@@ -97,12 +113,14 @@ def listify(
 
     >>> dict_generator()
     {'a': 1, 'b': 2}
-    '''
+    """
 
     def _listify(
-        function: types.Callable[..., types.Optional[types.Iterable[_T]]]
-    ) -> types.Callable[..., _TC]:
-        def __listify(*args: types.Any, **kwargs: types.Any) -> _TC:
+        function: types.Callable[..., types.Optional[types.Iterable[_T]]],
+    ) -> types.Callable[..., types.Collection[_T]]:
+        def __listify(
+            *args: types.Any, **kwargs: types.Any
+        ) -> types.Collection[_T]:
             result: types.Optional[types.Iterable[_T]] = function(
                 *args, **kwargs
             )
@@ -122,8 +140,13 @@ def listify(
     return _listify
 
 
-def sample(sample_rate: float):
-    '''
+def sample(
+    sample_rate: float,
+) -> types.Callable[
+    [types.Callable[_P, _T]],
+    types.Callable[_P, types.Optional[_T]],
+]:
+    """
     Limit calls to a function based on given sample rate.
     Number of calls to the function will be roughly equal to
     sample_rate percentage.
@@ -135,10 +158,10 @@ def sample(sample_rate: float):
     ...     return 1
 
     Calls to *demo_function* will be limited to 50% approximatly.
-    '''
+    """
 
     def _sample(
-        function: types.Callable[_P, _T]
+        function: types.Callable[_P, _T],
     ) -> types.Callable[_P, types.Optional[_T]]:
         @functools.wraps(function)
         def __sample(
@@ -152,7 +175,7 @@ def sample(sample_rate: float):
                     function,
                     args,
                     kwargs,
-                )  # noqa: E501
+                )
                 return None
 
         return __sample
@@ -166,16 +189,16 @@ def wraps_classmethod(
     [
         types.Callable[types.Concatenate[types.Any, _P], _T],
     ],
-    types.Callable[types.Concatenate[types.Type[_S], _P], _T],
+    types.Callable[types.Concatenate[_S, _P], _T],
 ]:
-    '''
+    """
     Like `functools.wraps`, but for wrapping classmethods with the type info
-    from a regular method
-    '''
+    from a regular method.
+    """
 
     def _wraps_classmethod(
         wrapper: types.Callable[types.Concatenate[types.Any, _P], _T],
-    ) -> types.Callable[types.Concatenate[types.Type[_S], _P], _T]:
+    ) -> types.Callable[types.Concatenate[_S, _P], _T]:
         # For some reason `functools.update_wrapper` fails on some test
         # runs but not while running actual code
         with contextlib.suppress(AttributeError):

python_utils/exceptions.py

@@ -1,3 +1,15 @@
+"""
+This module provides utility functions for raising and reraising exceptions.
+
+Functions:
+    raise_exception(exception_class, *args, **kwargs):
+        Returns a function that raises an exception of the given type with
+        the given arguments.
+
+    reraise(*args, **kwargs):
+        Reraises the current exception.
+"""
+
 from . import types
 
 
@@ -6,7 +18,7 @@ def raise_exception(
     *args: types.Any,
     **kwargs: types.Any,
 ) -> types.Callable[..., None]:
-    '''
+    """
     Returns a function that raises an exception of the given type with the
     given arguments.
 
@@ -14,7 +26,7 @@ def raise_exception(
     Traceback (most recent call last):
         ...
     ValueError: spam
-    '''
+    """
 
     def raise_(*args_: types.Any, **kwargs_: types.Any) -> types.Any:
         raise exception_class(*args, **kwargs)
@@ -23,4 +35,10 @@ def raise_exception(
 
 
 def reraise(*args: types.Any, **kwargs: types.Any) -> types.Any:
+    """
+    Reraises the current exception.
+
+    This function seems useless, but it can be useful when you need to pass
+    a callable to another function that raises an exception.
+    """
     raise

python_utils/formatters.py

@@ -1,3 +1,19 @@
+"""
+This module provides utility functions for formatting strings and dates.
+
+Functions:
+    camel_to_underscore(name: str) -> str:
+        Convert camel case style naming to underscore/snake case style naming.
+
+    apply_recursive(function: Callable[[str], str], data: OptionalScope = None,
+                    **kwargs: Any) -> OptionalScope:
+        Apply a function to all keys in a scope recursively.
+
+    timesince(dt: Union[datetime.datetime, datetime.timedelta],
+              default: str = 'just now') -> str:
+        Returns string representing 'time since' e.g. 3 days ago, 5 hours ago.
+"""
+
 # pyright: reportUnnecessaryIsInstance=false
 import datetime
 
@@ -5,7 +21,7 @@ from python_utils import types
 
 
 def camel_to_underscore(name: str) -> str:
-    '''Convert camel case style naming to underscore/snake case style naming
+    """Convert camel case style naming to underscore/snake case style naming.
 
     If there are existing underscores they will be collapsed with the
     to-be-added underscores. Multiple consecutive capital letters will not be
@@ -21,7 +37,7 @@ def camel_to_underscore(name: str) -> str:
     '__spam_and_bacon__'
     >>> camel_to_underscore('__SpamANDBacon__')
     '__spam_and_bacon__'
-    '''
+    """
     output: types.List[str] = []
     for i, c in enumerate(name):
         if i > 0:
@@ -47,14 +63,19 @@ def apply_recursive(
     data: types.OptionalScope = None,
     **kwargs: types.Any,
 ) -> types.OptionalScope:
-    '''
-    Apply a function to all keys in a scope recursively
+    """
+    Apply a function to all keys in a scope recursively.
 
     >>> apply_recursive(camel_to_underscore, {'SpamEggsAndBacon': 'spam'})
     {'spam_eggs_and_bacon': 'spam'}
-    >>> apply_recursive(camel_to_underscore, {'SpamEggsAndBacon': {
-    ...     'SpamEggsAndBacon': 'spam',
-    ... }})
+    >>> apply_recursive(
+    ...     camel_to_underscore,
+    ...     {
+    ...         'SpamEggsAndBacon': {
+    ...             'SpamEggsAndBacon': 'spam',
+    ...         }
+    ...     },
+    ... )
     {'spam_eggs_and_bacon': {'spam_eggs_and_bacon': 'spam'}}
 
     >>> a = {'a_b_c': 123, 'def': {'DeF': 456}}
@@ -63,7 +84,7 @@ def apply_recursive(
     {'a_b_c': 123, 'def': {'de_f': 456}}
 
     >>> apply_recursive(camel_to_underscore, None)
-    '''
+    """
     if data is None:
         return None
 
@@ -80,7 +101,7 @@ def timesince(
     dt: types.Union[datetime.datetime, datetime.timedelta],
     default: str = 'just now',
 ) -> str:
-    '''
+    """
     Returns string representing 'time since' e.g.
     3 days ago, 5 hours ago etc.
 
@@ -121,7 +142,7 @@ def timesince(
     '1 hour and 2 minutes ago'
     >>> timesince(datetime.timedelta(seconds=3721))
     '1 hour and 2 minutes ago'
-    '''
+    """
     if isinstance(dt, datetime.timedelta):
         diff = dt
     else:
@@ -140,11 +161,11 @@ def timesince(
 
     output: types.List[str] = []
     for period, singular, plural in periods:
-        if int(period):
-            if int(period) == 1:
-                output.append('%d %s' % (period, singular))
-            else:
-                output.append('%d %s' % (period, plural))
+        int_period = int(period)
+        if int_period == 1:
+            output.append(f'{int_period} {singular}')
+        elif int_period:
+            output.append(f'{int_period} {plural}')
 
     if output:
         return f'{" and ".join(output[:2])} ago'