anemoi-utils 0.4.12__py3-none-any.whl → 0.4.14__py3-none-any.whl

anemoi/utils/humanize.py

@@ -8,43 +8,44 @@
 # nor does it submit to any jurisdiction.
 
 
-"""Generate human readable strings"""
+"""Generate human readable strings."""
 
 import datetime
 import json
 import re
 import warnings
 from collections import defaultdict
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import Generator
+from typing import List
+from typing import Optional
+from typing import Tuple
+from typing import Union
 
 from anemoi.utils.dates import as_datetime
 
 
 def bytes_to_human(n: float) -> str:
-    """Convert a number of bytes to a human readable string
+    """Convert a number of bytes to a human readable string.
 
-    >>> bytes(4096)
+    >>> bytes_to_human(4096)
     '4 KiB'
 
-    >>> bytes(4000)
+    >>> bytes_to_human(4000)
     '3.9 KiB'
 
     Parameters
     ----------
     n : float
-        the number of bytes
+        The number of bytes
 
     Returns
     -------
     str
-        a human readable string
-    """
-
-    """
-
-
-
+        A human readable string
     """
-
     if n < 0:
         sign = "-"
         n -= 0
@@ -60,6 +61,18 @@ def bytes_to_human(n: float) -> str:
 
 
 def bytes(n: float) -> str:
+    """Deprecated function to convert bytes to a human readable string.
+
+    Parameters
+    ----------
+    n : float
+        The number of bytes
+
+    Returns
+    -------
+    str
+        A human readable string
+    """
     warnings.warn(
         "Function bytes is deprecated and will be removed in a future version. Use bytes_to_human instead.",
         category=DeprecationWarning,
@@ -68,8 +81,19 @@ def bytes(n: float) -> str:
     return bytes_to_human(n)
 
 
-def base2_to_human(n) -> str:
+def base2_to_human(n: float) -> str:
+    """Convert a number to a human readable string using base 2 units.
+
+    Parameters
+    ----------
+    n : float
+        The number to convert
 
+    Returns
+    -------
+    str
+        A human readable string
+    """
     u = ["", "K", "M", "G", "T", " P", "E", "Z", "Y"]
     i = 0
     while n >= 1024:
@@ -78,8 +102,19 @@ def base2_to_human(n) -> str:
     return "%g%s" % (int(n * 10 + 0.5) / 10.0, u[i])
 
 
-def base2(n) -> str:
+def base2(n: float) -> str:
+    """Deprecated function to convert a number to a human readable string using base 2 units.
 
+    Parameters
+    ----------
+    n : float
+        The number to convert
+
+    Returns
+    -------
+    str
+        A human readable string
+    """
     warnings.warn(
         "Function base2 is deprecated and will be removed in a future version. Use base2_to_human instead.",
         category=DeprecationWarning,
@@ -97,15 +132,27 @@ PERIODS = (
 )
 
 
-def _plural(count):
+def _plural(count: int) -> str:
+    """Return 's' if count is not 1, otherwise return an empty string.
+
+    Parameters
+    ----------
+    count : int
+        The count
+
+    Returns
+    -------
+    str
+        's' if count is not 1, otherwise an empty string
+    """
     if count != 1:
         return "s"
     else:
         return ""
 
 
-def seconds_to_human(seconds: float) -> str:
-    """Convert a number of seconds to a human readable string
+def seconds_to_human(seconds: Union[float, datetime.timedelta]) -> str:
+    """Convert a number of seconds to a human readable string.
 
     >>> seconds_to_human(4000)
     '1 hour 6 minutes 40 seconds'
@@ -119,7 +166,6 @@ def seconds_to_human(seconds: float) -> str:
     -------
     str
         A human readable string
-
     """
     if isinstance(seconds, datetime.timedelta):
         seconds = seconds.total_seconds()
@@ -164,6 +210,18 @@ def seconds_to_human(seconds: float) -> str:
 
 
 def seconds(seconds: float) -> str:
+    """Deprecated function to convert seconds to a human readable string.
+
+    Parameters
+    ----------
+    seconds : float
+        The number of seconds
+
+    Returns
+    -------
+    str
+        A human readable string
+    """
     warnings.warn(
         "Function seconds is deprecated and will be removed in a future version. Use seconds_to_human instead.",
         category=DeprecationWarning,
@@ -172,7 +230,21 @@ def seconds(seconds: float) -> str:
     return seconds_to_human(seconds)
 
 
-def plural(value, what):
+def plural(value: int, what: str) -> str:
+    """Return a string with the value and the pluralized form of what.
+
+    Parameters
+    ----------
+    value : int
+        The value
+    what : str
+        The string to pluralize
+
+    Returns
+    -------
+    str
+        The value and the pluralized form of what
+    """
     return f"{value:,} {what}{_plural(value)}"
 
 
@@ -202,7 +274,19 @@ MONTH = [
 ]
 
 
-def __(n):
+def __(n: int) -> str:
+    """Return the ordinal suffix for a number.
+
+    Parameters
+    ----------
+    n : int
+        The number
+
+    Returns
+    -------
+    str
+        The ordinal suffix
+    """
     if n in (11, 12, 13):
         return "th"
 
@@ -218,8 +302,10 @@ def __(n):
     return "th"
 
 
-def when(then, now=None, short=True, use_utc=False) -> str:
-    """Generate a human readable string for a date, relative to now
+def when(
+    then: datetime.datetime, now: Optional[datetime.datetime] = None, short: bool = True, use_utc: bool = False
+) -> str:
+    """Generate a human readable string for a date, relative to now.
 
     >>> when(datetime.datetime.now() - datetime.timedelta(hours=2))
     '2 hours ago'
@@ -243,7 +329,7 @@ def when(then, now=None, short=True, use_utc=False) -> str:
     now : datetime.datetime, optional
         The reference date, by default NOW
     short : bool, optional
-        Genererate shorter strings, by default True
+        Generate shorter strings, by default True
     use_utc : bool, optional
         Use UTC time, by default False
 
@@ -251,7 +337,6 @@ def when(then, now=None, short=True, use_utc=False) -> str:
     -------
     str
         A human readable string
-
     """
     last = "last"
 
@@ -344,7 +429,21 @@ def when(then, now=None, short=True, use_utc=False) -> str:
     )
 
 
-def string_distance(s, t):
+def string_distance(s: str, t: str) -> int:
+    """Calculate the Levenshtein distance between two strings.
+
+    Parameters
+    ----------
+    s : str
+        The first string
+    t : str
+        The second string
+
+    Returns
+    -------
+    int
+        The Levenshtein distance
+    """
     import numpy as np
 
     m = len(s)
@@ -369,8 +468,8 @@ def string_distance(s, t):
     return d[m, n]
 
 
-def did_you_mean(word, vocabulary) -> str:
-    """Pick the closest word in a vocabulary
+def did_you_mean(word: str, vocabulary: List[str]) -> str:
+    """Pick the closest word in a vocabulary.
 
     >>> did_you_mean("aple", ["banana", "lemon", "apple", "orange"])
     'apple'
@@ -379,7 +478,7 @@ def did_you_mean(word, vocabulary) -> str:
     ----------
     word : str
         The word to look for
-    vocabulary : list of strings
+    vocabulary : list of str
         The list of known words
 
     Returns
@@ -392,14 +491,26 @@ def did_you_mean(word, vocabulary) -> str:
     return best
 
 
-def dict_to_human(query):
+def dict_to_human(query: Dict[str, Any]) -> str:
+    """Convert a dictionary to a human readable string.
+
+    Parameters
+    ----------
+    query : dict
+        The dictionary to convert
+
+    Returns
+    -------
+    str
+        A human readable string
+    """
     lst = [f"{k}={v}" for k, v in sorted(query.items())]
 
     return list_to_human(lst)
 
 
-def list_to_human(lst, conjunction="and") -> str:
-    """Convert a list of strings to a human readable string
+def list_to_human(lst: List[str], conjunction: str = "and") -> str:
+    """Convert a list of strings to a human readable string.
 
     >>> list_to_human(["banana", "lemon", "apple", "orange"])
     'banana, lemon, apple and orange'
@@ -425,7 +536,25 @@ def list_to_human(lst, conjunction="and") -> str:
     return f" {conjunction} ".join(lst)
 
 
-def human_to_number(value, name, units, none_ok):
+def human_to_number(value: Union[str, int], name: str, units: Dict[str, int], none_ok: bool) -> Optional[int]:
+    """Convert a human readable string to a number.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str
+        The name of the value
+    units : dict
+        The units to use for conversion
+    none_ok : bool
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value
+    """
     if value is None and none_ok:
         return None
 
@@ -444,7 +573,27 @@ def human_to_number(value, name, units, none_ok):
     return value * units[unit]
 
 
-def as_number(value, name=None, units=None, none_ok=False):
+def as_number(
+    value: Union[str, int], name: Optional[str] = None, units: Optional[Dict[str, int]] = None, none_ok: bool = False
+) -> Optional[int]:
+    """Deprecated function to convert a human readable string to a number.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    units : dict, optional
+        The units to use for conversion
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value
+    """
     warnings.warn(
         "Function as_number is deprecated and will be removed in a future version. Use human_to_number instead.",
         category=DeprecationWarning,
@@ -453,12 +602,44 @@ def as_number(value, name=None, units=None, none_ok=False):
     return human_to_number(value, name, units, none_ok)
 
 
-def human_seconds(value, name=None, none_ok=False):
+def human_seconds(value: Union[str, int], name: Optional[str] = None, none_ok: bool = False) -> Optional[int]:
+    """Convert a human readable string to seconds.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value in seconds
+    """
     units = dict(s=1, m=60, h=3600, d=86400, w=86400 * 7)
     return human_to_number(value, name, units, none_ok)
 
 
-def as_seconds(value, name=None, none_ok=False):
+def as_seconds(value: Union[str, int], name: Optional[str] = None, none_ok: bool = False) -> Optional[int]:
+    """Deprecated function to convert a human readable string to seconds.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value in seconds
+    """
     warnings.warn(
         "Function as_seconds is deprecated and will be removed in a future version. Use human_seconds instead.",
         category=DeprecationWarning,
@@ -467,12 +648,44 @@ def as_seconds(value, name=None, none_ok=False):
     return human_seconds(value, name, none_ok)
 
 
-def human_to_percent(value, name=None, none_ok=False):
+def human_to_percent(value: Union[str, int], name: Optional[str] = None, none_ok: bool = False) -> Optional[int]:
+    """Convert a human readable string to a percentage.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value in percentage
+    """
     units = {"%": 1}
     return human_to_number(value, name, units, none_ok)
 
 
-def as_percent(value, name=None, none_ok=False):
+def as_percent(value: Union[str, int], name: Optional[str] = None, none_ok: bool = False) -> Optional[int]:
+    """Deprecated function to convert a human readable string to a percentage.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value in percentage
+    """
     warnings.warn(
         "Function as_percent is deprecated and will be removed in a future version. Use human_to_percent instead.",
         category=DeprecationWarning,
@@ -481,7 +694,23 @@ def as_percent(value, name=None, none_ok=False):
     return human_to_percent(value, name, none_ok)
 
 
-def human_to_bytes(value, name=None, none_ok=False):
+def human_to_bytes(value: Union[str, int], name: Optional[str] = None, none_ok: bool = False) -> Optional[int]:
+    """Convert a human readable string to bytes.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value in bytes
+    """
     units = {}
     n = 1
     for u in "KMGTP":
@@ -492,7 +721,23 @@ def human_to_bytes(value, name=None, none_ok=False):
     return human_to_number(value, name, units, none_ok)
 
 
-def as_bytes(value, name=None, none_ok=False):
+def as_bytes(value: Union[str, int], name: Optional[str] = None, none_ok: bool = False) -> Optional[int]:
+    """Deprecated function to convert a human readable string to bytes.
+
+    Parameters
+    ----------
+    value : str or int
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    int or None
+        The converted value in bytes
+    """
     warnings.warn(
         "Function as_bytes is deprecated and will be removed in a future version. Use human_to_bytes instead.",
         category=DeprecationWarning,
@@ -501,7 +746,23 @@ def as_bytes(value, name=None, none_ok=False):
     return human_to_bytes(value, name, none_ok)
 
 
-def human_to_timedelta(value, name=None, none_ok=False):
+def human_to_timedelta(value: str, name: Optional[str] = None, none_ok: bool = False) -> datetime.timedelta:
+    """Convert a human readable string to a timedelta.
+
+    Parameters
+    ----------
+    value : str
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    datetime.timedelta
+        The converted value as a timedelta
+    """
     if value is None and none_ok:
         return None
 
@@ -537,7 +798,23 @@ def human_to_timedelta(value, name=None, none_ok=False):
     )
 
 
-def as_timedelta(value, name=None, none_ok=False):
+def as_timedelta(value: str, name: Optional[str] = None, none_ok: bool = False) -> datetime.timedelta:
+    """Deprecated function to convert a human readable string to a timedelta.
+
+    Parameters
+    ----------
+    value : str
+        The value to convert
+    name : str, optional
+        The name of the value
+    none_ok : bool, optional
+        Whether None is an acceptable value
+
+    Returns
+    -------
+    datetime.timedelta
+        The converted value as a timedelta
+    """
     warnings.warn(
         "Function as_timedelta is deprecated and will be removed in a future version. Use human_to_timedelta instead.",
         category=DeprecationWarning,
@@ -546,14 +823,26 @@ def as_timedelta(value, name=None, none_ok=False):
     return human_to_timedelta(value, name, none_ok)
 
 
-def rounded_datetime(d):
+def rounded_datetime(d: datetime.datetime) -> datetime.datetime:
+    """Round a datetime to the nearest second.
+
+    Parameters
+    ----------
+    d : datetime.datetime
+        The datetime to round
+
+    Returns
+    -------
+    datetime.datetime
+        The rounded datetime
+    """
     if float(d.microsecond) / 1000.0 / 1000.0 >= 0.5:
         d = d + datetime.timedelta(seconds=1)
     d = d.replace(microsecond=0)
     return d
 
 
-def json_pretty_dump(obj, max_line_length=120, default=str) -> str:
+def json_pretty_dump(obj: Any, max_line_length: int = 120, default: Callable = str) -> str:
     """Custom JSON dump function that keeps dicts and lists on one line if they are short enough.
 
     Parameters
@@ -571,7 +860,7 @@ def json_pretty_dump(obj, max_line_length=120, default=str) -> str:
         JSON string.
     """
 
-    def _format_json(obj, indent_level=0):
+    def _format_json(obj: Any, indent_level: int = 0) -> str:
         """Helper function to format JSON objects with custom pretty-print rules.
 
         Parameters
@@ -609,19 +898,19 @@ def json_pretty_dump(obj, max_line_length=120, default=str) -> str:
     return _format_json(obj)
 
 
-def shorten_list(lst, max_length=5) -> list:
+def shorten_list(lst: Union[List[Any], Tuple[Any]], max_length: int = 5) -> Union[List[Any], Tuple[Any]]:
     """Shorten a list to a maximum length.
 
     Parameters
     ----------
-    lst : list
+    lst : list or tuple
         The list to be shortened.
     max_length : int, optional
         Maximum length of the shortened list. Default is 5.
 
     Returns
     -------
-    list
+    list or tuple
         Shortened list.
     """
     if len(lst) <= max_length:
@@ -634,7 +923,23 @@ def shorten_list(lst, max_length=5) -> list:
         return result
 
 
-def _compress_dates(dates):
+def _compress_dates(
+    dates: List[datetime.datetime],
+) -> Generator[
+    Union[List[datetime.datetime], Tuple[datetime.datetime, datetime.datetime, datetime.timedelta]], None, None
+]:
+    """Compress a list of dates into a more compact representation.
+
+    Parameters
+    ----------
+    dates : list of datetime.datetime
+        The list of dates to compress
+
+    Returns
+    -------
+    list or tuple
+        The compressed dates
+    """
     dates = sorted(dates)
     if len(dates) < 3:
         yield dates
@@ -654,7 +959,7 @@ def _compress_dates(dates):
         yield from _compress_dates([curr] + dates)
 
 
-def compress_dates(dates) -> str:
+def compress_dates(dates: List[Union[datetime.datetime, str]]) -> str:
     """Compress a list of dates into a human-readable format.
 
     Parameters
@@ -680,7 +985,7 @@ def compress_dates(dates) -> str:
     return result
 
 
-def print_dates(dates) -> None:
+def print_dates(dates: List[Union[datetime.datetime, str]]) -> None:
     """Print a list of dates in a human-readable format.
 
     Parameters
@@ -691,7 +996,7 @@ def print_dates(dates) -> None:
     print(compress_dates(dates))
 
 
-def make_list_int(value) -> list:
+def make_list_int(value: Union[str, List[int], Tuple[int], int]) -> List[int]:
     """Convert a string like "1/2/3" or "1/to/3" or "1/to/10/by/2" to a list of integers.
 
     Parameters