klaatu-python 2.4.0__tar.gz → 2.5.0__tar.gz

{klaatu_python-2.4.0 → klaatu_python-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klaatu-python
-Version: 2.4.0
+Version: 2.5.0
 Author: Robert Huselius
 Author-email: Robert Huselius <robert@huseli.us>
 License-Expression: GPL-3.0-only
@@ -13,7 +13,7 @@ Description-Content-Type: text/markdown
 
 # klaatu-python
 
-A bunch of more or less useful Python utils without any 3rd party dependencies.
+A bunch of more or less useful Python utils without _any_ 3rd party dependencies.
 
 ## Development install
 

{klaatu_python-2.4.0 → klaatu_python-2.5.0}/README.md

@@ -1,6 +1,6 @@
 # klaatu-python
 
-A bunch of more or less useful Python utils without any 3rd party dependencies.
+A bunch of more or less useful Python utils without _any_ 3rd party dependencies.
 
 ## Development install
 

{klaatu_python-2.4.0 → klaatu_python-2.5.0}/pyproject.toml

@@ -11,7 +11,7 @@ license-files = ["LICENSE"]
 name = "klaatu-python"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "2.4.0"
+version = "2.5.0"
 
 [project.urls]
 Homepage = "https://github.com/Eboreg/klaatu-python"
@@ -41,7 +41,3 @@ section-order = [
 
 [tool.ruff.format]
 skip-magic-trailing-comma = false
-
-[tool.flake8]
-max-doc-length = 79
-max-line-length = 119

{klaatu_python-2.4.0 → klaatu_python-2.5.0}/src/klaatu_python/case.py

@@ -1,8 +1,8 @@
 import re
-from abc import abstractmethod
+from abc import ABC, abstractmethod
 
 
-class CaseType:
+class CaseType(ABC):
     @staticmethod
     @abstractmethod
     def split(value: str) -> list[str]: ...

klaatu_python-2.5.0/src/klaatu_python/utils/__init__.py

@@ -0,0 +1,68 @@
+from .dicts import filter_values_not_null, group_by, group_dicts, zip_dict_lists, zip_dicts
+from .iterables import (
+    circulate,
+    first_not_null,
+    first_not_null_or_null,
+    getitem0,
+    getitem0_nullable,
+    getitem_nullable,
+    index_of_first,
+    most_common,
+    nonulls,
+    partition,
+)
+from .numbers import (
+    can_coerce_to_int,
+    coerce_between,
+    format_file_size,
+    int_to_string,
+    localize_float,
+    percent_rounded,
+    roman,
+    round_to_n,
+    rounded_percentage,
+    to_int,
+)
+from .paths import deepest_common_path, sanitize_path
+from .strings import fancy_join
+from .time import daterange, round_up_timedelta
+from .urls import append_query_to_url, strip_url_query
+from .various import get_binary_reply, is_truthy
+
+
+__all__ = [
+    "append_query_to_url",
+    "can_coerce_to_int",
+    "circulate",
+    "coerce_between",
+    "daterange",
+    "deepest_common_path",
+    "fancy_join",
+    "filter_values_not_null",
+    "first_not_null_or_null",
+    "first_not_null",
+    "format_file_size",
+    "get_binary_reply",
+    "getitem_nullable",
+    "getitem0_nullable",
+    "getitem0",
+    "group_by",
+    "group_dicts",
+    "index_of_first",
+    "int_to_string",
+    "is_truthy",
+    "localize_float",
+    "most_common",
+    "nonulls",
+    "partition",
+    "percent_rounded",
+    "roman",
+    "round_to_n",
+    "round_up_timedelta",
+    "rounded_percentage",
+    "sanitize_path",
+    "strip_url_query",
+    "to_int",
+    "zip_dict_lists",
+    "zip_dicts",
+]

klaatu_python-2.5.0/src/klaatu_python/utils/dicts.py

@@ -0,0 +1,89 @@
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from typing import TypeVar
+
+
+_T = TypeVar("_T")
+_T2 = TypeVar("_T2")
+
+
+def filter_values_not_null(d: dict[_T, _T2 | None]) -> dict[_T, _T2]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def group_by(sequence: Sequence[_T], pred: Callable[[_T], _T2]) -> dict[_T2, list[_T]]:
+    """
+    Groups `sequence` by the result of `pred` on each item. Returns dict with
+    those results as keys and sublists of `sequence` as values.
+    """
+    result: dict[_T2, list[_T]] = {}
+    for item in sequence:
+        key = pred(item)
+        if key not in result:
+            result[key] = [item]
+        else:
+            result[key].append(item)
+    return result
+
+
+def group_dicts(
+    dicts: Iterable[dict[str, _T]],
+    keys: list[str],
+    data_key: str = "data",
+) -> list[dict[str, _T | list[dict[str, _T]]]]:
+    """
+    In:
+        dicts = [
+            {"slug": "musikensmakt", "name": "Musikens Makt", "date": "2025-04-01", "count": 60},
+            {"slug": "musikensmakt", "name": "Musikens Makt", "date": "2025-04-02", "count": 64},
+            {"slug": "apanap", "name": "Apan Ap", "date": "2025-04-01", "count": 2},
+        ]
+        keys = ["slug", "name"]
+        data_key = "dätä"
+    Out: [
+        {
+            "slug": "musikensmakt",
+            "name": "Musikens Makt",
+            "dätä": [{"date": "2025-04-01", "count": 60}, {"date": "2025-04-02", "count": 64}],
+        },
+        {
+            "slug": "apanap",
+            "name": "Apan Ap",
+            "dätä": [{"date": "2025-04-01", "count": 2}],
+        },
+    ]
+    """
+    result: dict[tuple[_T, ...], list] = {}
+
+    for d in dicts:
+        dd = d.copy()
+        d_key = tuple(d[key] for key in keys)
+        if d_key not in result:
+            result[d_key] = []
+        for key in keys:
+            del dd[key]
+        result[d_key].append(dd)
+
+    return [{data_key: v, **{keys[i]: k[i] for i in range(len(keys))}} for k, v in result.items()]
+
+
+def zip_dicts(*dicts: dict) -> dict:
+    """
+    Combines dicts into one dict. On duplicate keys, dicts later in the
+    sequence have priority.
+    """
+    return {k: v for d in dicts for k, v in d.items()}
+
+
+def zip_dict_lists(dict_lists: Iterable[Iterable[dict]], strict: bool = False) -> Iterator[dict]:
+    """
+    Zips a list of dict lists and combines them into single dicts.
+    I.e. given dict_lists = [
+        [{a1: 1, a2: 2}, {b1: 3, b2: 4}],
+        [{a3: 5, a4: 6}, {b3: 7, b4: 8}],
+    ],
+    these dicts will be yielded:
+    {a1: 1, a2: 2, a3: 5, a4: 6}
+    {b1: 3, b2: 4, b3: 7, b4: 8}
+    """
+    for dicts in zip(*dict_lists, strict=strict):
+        yield zip_dicts(*dicts)

klaatu_python-2.5.0/src/klaatu_python/utils/iterables.py

@@ -0,0 +1,130 @@
+from collections.abc import Callable, Hashable, Iterable, Iterator, Sequence
+from typing import Literal, TypeVar, overload
+
+
+_T = TypeVar("_T")
+_HashableT = TypeVar("_HashableT", bound=Hashable)
+
+
+def circulate(lst: Iterable[_T], rounds: int) -> list[_T]:
+    """
+    Shifts `lst` left `rounds` times. Good for e.g. circulating colours in
+    a graph.
+    """
+    if not isinstance(lst, list):
+        lst = list(lst)
+    if lst and rounds:
+        for _ in range(rounds):
+            val = lst.pop(0)
+            lst.append(val)
+    return lst
+
+
+def first_not_null(*values: _T | None) -> _T:
+    ret = first_not_null_or_null(*values)
+    if ret is None:
+        raise TypeError("All values are None")
+    return ret
+
+
+def first_not_null_or_null(*values: _T | None) -> _T | None:
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+@overload
+def getitem0(seq: Iterable[_T], cond: Callable[[_T], bool] | None, nullable: Literal[False]) -> _T: ...
+
+
+@overload
+def getitem0(seq: Iterable[_T], cond: Callable[[_T], bool] | None, nullable: Literal[True]) -> _T | None: ...
+
+
+def getitem0(seq, cond=None, nullable=False):
+    """
+    @raises IndexError
+    """
+    try:
+        if cond is None:
+            return list(seq)[0]
+        return [item for item in seq if cond(item)][0]
+    except IndexError as e:
+        if nullable:
+            return None
+        raise e
+
+
+def getitem0_nullable(seq: Iterable[_T], cond: Callable[[_T], bool] | None = None) -> _T | None:
+    return getitem0(seq, cond, True)
+
+
+def getitem_nullable(seq: Iterable[_T], idx: int, cond: Callable[[_T], bool] | None = None) -> _T | None:
+    """
+    If `seq` has an item at position `idx`, return that item. Otherwise return
+    None. Similar to how QuerySet's first() & last() operate.
+
+    With `cond` set, it first filters `seq` for items where this function
+    evaluates as True, then tries to get item `idx` from the resulting list.
+
+    Example:
+
+    seq = [23, 43, 12, 56, 75, 1]
+    second_even = getitem_nullable(seq, 1, lambda item: item % 2 == 0)
+    # second_even == 56
+    seq = [1, 2, 3, 5, 7]
+    second_even = getitem_nullable(seq, 1, lambda item: item % 2 == 0)
+    # second_even == None
+    """
+    try:
+        if cond is None:
+            return list(seq)[idx]
+        return [item for item in seq if cond(item)][idx]
+    except IndexError:
+        return None
+
+
+def index_of_first(sequence: Sequence[_T], pred: Callable[[_T], bool]) -> int:
+    """
+    Tries to return the index of the first item in `sequence` for which the
+    function `pred` returns True. If no such item is found, return -1.
+    """
+    try:
+        return sequence.index(next(filter(pred, sequence)))
+    except StopIteration:
+        return -1
+
+
+def most_common(values: Iterable[_HashableT]) -> tuple[_HashableT | None, int]:
+    """
+    Given a non-empty iterable, this will return a 2-tuple with the most
+    commonly occurring value in said iterable, and the number of such
+    occurances.
+
+    Given an _empty_ iterable, it will return `(None, 0)`.
+    """
+    occurrences: dict[_HashableT, int] = {}
+
+    for value in values:
+        if value not in occurrences:
+            occurrences[value] = 0
+        occurrences[value] += 1
+
+    if not occurrences:
+        return None, 0
+
+    return max(occurrences.items(), key=lambda tup: tup[1])
+
+
+def nonulls(items: Iterable[_T | None]) -> list[_T]:
+    """Just filters away None values from `items`."""
+    return [item for item in items if item is not None]
+
+
+def partition(items: Sequence[_T], length: int) -> Iterator[Sequence[_T]]:
+    """Simply splits `items` into subsequences of max `length` items."""
+    offset = 0
+    while offset == 0 or offset < len(items):
+        yield items[offset : offset + length]
+        offset += length

klaatu_python-2.5.0/src/klaatu_python/utils/numbers.py

@@ -0,0 +1,165 @@
+import locale
+import re
+from locale import format_string, localeconv
+from math import floor, log10
+from typing import Any, TypeVar
+from warnings import deprecated
+
+
+_NumberT = TypeVar("_NumberT", int, float)
+
+
+KILOBYTE = pow(2, 10)
+MEGABYTE = pow(2, 20)
+GIGABYTE = pow(2, 30)
+TERABYTE = pow(2, 40)
+
+
+def can_coerce_to_int(value: Any) -> bool:
+    return to_int(value) is not None
+
+
+def coerce_between(value: _NumberT, min_value: _NumberT, max_value: _NumberT) -> _NumberT:
+    if value < min_value:
+        return min_value
+    if value > max_value:
+        return max_value
+    return value
+
+
+def format_file_size(size: int, separator: str = "") -> str:
+    if size >= TERABYTE:
+        return locale.str(round(size / TERABYTE, 1)) + separator + "T"
+    if size >= GIGABYTE:
+        return locale.str(round(size / GIGABYTE, 1)) + separator + "G"
+    if size >= MEGABYTE:
+        return locale.str(round(size / MEGABYTE, 1)) + separator + "M"
+    if size >= KILOBYTE:
+        return locale.str(round(size / KILOBYTE, 1)) + separator + "K"
+    return str(size)
+
+
+def int_to_string(value: int | None, locale: str, nbsp: bool = False) -> str:
+    """
+    Formats an integer with locale-specific thousand separators, which are at
+    least correct for Swedish and English locales. (Usage of the functions in
+    the built-in `locale` package requires you to run setlocale() multiple
+    times, which is not thread safe and may be resource heavy, so we don't do
+    that.)
+    """
+    if value is None:
+        return ""
+
+    if locale.lower().startswith("sv"):
+        separator = " "
+    else:
+        separator = ","
+
+    if separator == " " and nbsp:
+        separator = "&nbsp;"
+
+    # Neat line of code, huh? :)
+    # 1. Use absolute value to get rid of minus sign
+    # 2. Reverse str(value) in order to group characters from the end
+    # 3. Split it by groups of 3 digits
+    # 4. Remove empty values generated by re.split()
+    # 5. Re-reverse the digits in each group & join them with separator string
+    # 6. Re-reverse the order of the groups
+    # 7. Add minus sign if value was negative
+    return ("-" if value < 0 else "") + separator.join(
+        [v[::-1] for v in re.split(r"(\d{3})", str(abs(value))[::-1]) if v][::-1]
+    )
+
+
+def localize_float(
+    value: float,
+    grouping: bool = True,
+    min_decimals: int | None = None,
+    max_decimals: int | None = None,
+) -> str:
+    if max_decimals is None:
+        max_decimals = 15
+
+    if min_decimals is not None and min_decimals > max_decimals:
+        raise ValueError("min_decimals must be <= max_decimals")
+    if 15 < (min_decimals or 0) < 0:
+        raise ValueError("min_decimals must be >= 0 and <= 15")
+    if 15 < (max_decimals or 0) < 0:
+        raise ValueError("max_decimals must be >= 0 and <= 15")
+
+    decimal_separator = localeconv()["decimal_point"]
+    ret = format_string("%.*f", (max_decimals, value), grouping=grouping)
+
+    if decimal_separator in ret:
+        base, decimals = ret.split(decimal_separator)
+        decimals = decimals.rstrip("0").ljust(min_decimals or 0, "0")
+        if not decimals:
+            return base
+        return base + decimal_separator + decimals
+
+    return ret
+
+
+@deprecated("There's rounded_percentage() instead.")
+def percent_rounded(part: int | float, whole: int | float) -> int:
+    if not whole:
+        return 0
+    return round(part / whole * 100)
+
+
+def roman(n: int) -> str:
+    if n % 1:
+        raise ValueError("roman(): fractions not allowed")
+    if n >= 4000 or n < 0:
+        raise ValueError("roman(): value must be >= 0 and < 4000")
+
+    m = {
+        1000: "M",
+        900: "CM",
+        500: "D",
+        400: "CD",
+        100: "C",
+        90: "XC",
+        50: "L",
+        40: "XL",
+        10: "X",
+        9: "IX",
+        5: "V",
+        4: "IV",
+        1: "I",
+    }
+    r = ""
+
+    for k, v in m.items():
+        while n >= k:
+            r += v
+            n -= k
+
+    return r
+
+
+def round_to_n(x: int | float, n: int) -> int | float:
+    """
+    Rounds x to n significant digits. If the result is a whole number, it is
+    cast to int, otherwise float is returned.
+    """
+    if x == 0:
+        return x
+    result = round(x, -int(floor(log10(abs(x)))) + (n - 1))
+    return int(result) if not result % 1 else result
+
+
+def rounded_percentage(part: int | float, whole: int | float, digits: int = 3) -> int | float:
+    """
+    Percentage rounded to `digits` significant digits. Also division-by-zero
+    safe!
+    """
+    return round_to_n((part / whole) * 100, digits) if whole != 0 else 0
+
+
+def to_int(value: Any, default: int | None = None) -> int | None:
+    """Like int() but returns a default value instead of raising exception."""
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return default

klaatu_python-2.5.0/src/klaatu_python/utils/paths.py

@@ -0,0 +1,63 @@
+import itertools
+import re
+from pathlib import Path
+
+
+def deepest_common_path(path1: Path, *paths: Path) -> Path:
+    """
+    Finds and returns the deepest (as in "deep in the directory structure")
+    path that all parameters have in common.
+
+    Example:
+    >>> deepest_common_path(Path("/usr/local/bin/"), Path("/usr/share/"))
+    PosixPath('/usr')
+    """
+    path1 = path1.resolve()
+    paths = tuple(p.resolve() for p in paths)
+
+    # Returned iterator will contain None unless all paths are identical:
+    if all(itertools.accumulate([path1, *paths], lambda p1, p2: p1 if p1 == p2 else None)):
+        return path1
+
+    paths_parts = [[p, *p.parents] for p in paths]
+
+    for part in [path1, *path1.parents]:
+        if all(part in parts for parts in paths_parts):
+            return part
+
+    raise ValueError("No common paths")
+
+
+def sanitize_path(s: str) -> str:
+    """
+    Returns a string that _should_ work as a path on modern operating systems.
+    Forgot where I got all the rules from, though.
+    """
+    def repl(m: re.Match[str]):
+        c = m.group()
+        # Different kinds of quotation marks:
+        if c in '\u2019\u2018\u201a\u201b\u201c\u201d\u201e\u201f\u2039\u203a\u2e42"«»':
+            return "'"
+        # Different kinds of dashes:
+        if c in "\u2010\u2011\u2012\u2013\u2014\u2015":
+            return "-"
+        # Ellipsis:
+        if c == "\u2026":
+            return "..."
+        # Don't bother replacing these:
+        if c in "¿¡":
+            return ""
+        if c.isalnum() or c in ",;-_.'()=&%$#£¢€¥°@!<>[]{}€ ":
+            return c
+        return " - "
+
+    # Basic character replacement:
+    s = re.sub(".", repl, s)
+    # Replace multiple spaces with single space:
+    s = re.sub(" {2,}", " ", s)
+    # Replace trailing " - " with empty string:
+    s = re.sub(" - $", "", s)
+    # Replace leading " - " with empty string:
+    s = re.sub("^ - ", "", s)
+
+    return s

klaatu_python-2.5.0/src/klaatu_python/utils/strings.py

@@ -0,0 +1,16 @@
+from collections.abc import Iterable
+
+
+def fancy_join(parts: Iterable, operator: str = "and", oxford_comma: bool = True):
+    strings = [str(part) for part in parts]
+
+    if len(strings) == 0:
+        return ""
+    if len(strings) == 1:
+        return str(strings[0])
+    if len(strings) == 2:
+        return f"{strings[0]} {operator} {strings[1]}"
+
+    last_part = f"{',' if oxford_comma else ''} {operator} {strings.pop()}"
+
+    return ", ".join(strings) + last_part

klaatu_python-2.5.0/src/klaatu_python/utils/time.py

@@ -0,0 +1,25 @@
+from collections.abc import Iterator
+from datetime import date, timedelta
+from math import ceil
+
+
+def daterange(start_date: date, end_date: date) -> Iterator[date]:
+    """
+    Iterates the dates between `start_date` (inclusive) and `end_date`
+    (exclusive).
+    """
+    for n in range(int((end_date - start_date).days)):
+        yield start_date + timedelta(days=n)
+
+
+def round_up_timedelta(td: timedelta) -> timedelta:
+    """
+    If td > 30 min, round up to nearest hour. Otherwise, to nearest 10
+    minute mark. Could be extended for higher time units, but nevermind now.
+    """
+    td_minutes = td.total_seconds() / 60
+    if td_minutes > 30:
+        return timedelta(hours=ceil(td_minutes / 60))
+    if td_minutes >= 10:
+        return timedelta(minutes=int(td_minutes / 10) * 10 + 10)
+    return timedelta(minutes=10)

klaatu_python-2.5.0/src/klaatu_python/utils/urls.py

@@ -0,0 +1,28 @@
+from urllib.parse import parse_qs, urlencode, urlsplit, urlunsplit
+
+
+def append_query_to_url(url: str, params: dict, conditional_params: dict | None = None, safe: str = "") -> str:
+    """
+    Adds GET query from `params` to `url`, or appends it if there already is
+    one.
+
+    `conditional_params` will only be used if GET params with those keys are
+    not already present in the original url or in `params`.
+
+    Return the new url.
+    """
+    parts = urlsplit(url)
+    conditional_params = conditional_params or {}
+    qs = {
+        **conditional_params,
+        **parse_qs(parts.query),
+        **params,
+    }
+    parts = parts._replace(query=urlencode(qs, doseq=True, safe=safe))
+    return urlunsplit(parts)
+
+
+def strip_url_query(url: str) -> str:
+    """Just returns `url` stripped of any GET parameters."""
+    parts = urlsplit(url)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, "", parts.fragment))

klaatu_python-2.5.0/src/klaatu_python/utils/various.py

@@ -0,0 +1,28 @@
+from typing import Any
+
+
+def get_binary_reply(prompt: str, default: bool | None = None) -> bool:
+    if default:
+        prompt += " [Y/n] "
+    elif default is None:
+        prompt += " [y/n] "
+    else:
+        prompt += " [y/N] "
+
+    while True:
+        reply = input(prompt).lower().strip()
+        if reply == "" and default is not None:
+            return default
+        if reply in ("y", "n"):
+            return reply == "y"
+        print("Wrong answer, try again.")
+
+
+def is_truthy(value: Any) -> bool:
+    """
+    Basically does `bool(value)`, except it also returns False for string
+    values "false", "no", and "0" (case insensitive).
+    """
+    if isinstance(value, str) and value.lower() in ("false", "no", "0"):
+        return False
+    return bool(value)

klaatu_python-2.4.0/src/klaatu_python/utils.py

@@ -1,436 +0,0 @@
-import itertools
-import re
-from collections.abc import Callable, Hashable, Iterable, Iterator, Sequence
-from datetime import date, timedelta
-from locale import format_string, localeconv
-from math import ceil, floor, log10
-from pathlib import Path
-from typing import Any, Literal, TypeVar, overload
-from urllib.parse import parse_qs, urlencode, urlsplit, urlunsplit
-
-
-_T = TypeVar("_T")
-_NT = TypeVar("_NT", int, float)
-_HashableT = TypeVar("_HashableT", bound=Hashable)
-
-
-def append_query_to_url(url: str, params: dict, conditional_params: dict | None = None, safe: str = "") -> str:
-    """
-    Adds GET query from `params` to `url`, or appends it if there already is
-    one.
-
-    `conditional_params` will only be used if GET params with those keys are
-    not already present in the original url or in `params`.
-
-    Return the new url.
-    """
-    parts = urlsplit(url)
-    conditional_params = conditional_params or {}
-    qs = {
-        **conditional_params,
-        **parse_qs(parts.query),
-        **params,
-    }
-    parts = parts._replace(query=urlencode(qs, doseq=True, safe=safe))
-    return urlunsplit(parts)
-
-
-def can_coerce_to_int(value: Any) -> bool:
-    return to_int(value) is not None
-
-
-def circulate(lst: Iterable[_T], rounds: int) -> list[_T]:
-    """
-    Shifts `lst` left `rounds` times. Good for e.g. circulating colours in
-    a graph.
-    """
-    if not isinstance(lst, list):
-        lst = list(lst)
-    if lst and rounds:
-        for _ in range(rounds):
-            val = lst.pop(0)
-            lst.append(val)
-    return lst
-
-
-def coerce_between(value: _NT, min_value: _NT, max_value: _NT) -> _NT:
-    if value < min_value:
-        return min_value
-    if value > max_value:
-        return max_value
-    return value
-
-
-def daterange(start_date: date, end_date: date) -> Iterator[date]:
-    """
-    Iterates the dates between `start_date` (inclusive) and `end_date`
-    (exclusive).
-    """
-    for n in range(int((end_date - start_date).days)):
-        yield start_date + timedelta(days=n)
-
-
-def deepest_common_path(path1: Path, *paths: Path) -> Path:
-    """
-    Finds and returns the deepest (as in "deep in the directory structure")
-    path that all parameters have in common.
-
-    Example:
-    >>> deepest_common_path(Path("/usr/local/bin/"), Path("/usr/share/"))
-    PosixPath('/usr')
-    """
-    path1 = path1.resolve()
-    paths = tuple(p.resolve() for p in paths)
-
-    # Returned iterator will contain None unless all paths are identical:
-    if all(itertools.accumulate([path1, *paths], lambda p1, p2: p1 if p1 == p2 else None)):
-        return path1
-
-    paths_parts = [[p, *p.parents] for p in paths]
-
-    for part in [path1, *path1.parents]:
-        if all(part in parts for parts in paths_parts):
-            return part
-
-    raise ValueError("No common paths")
-
-
-def filter_values_not_null(d: dict) -> dict:
-    return {k: v for k, v in d.items() if v is not None}
-
-
-def first_not_null(*values: _T | None) -> _T:
-    ret = first_not_null_or_null(*values)
-    if ret is None:
-        raise TypeError("All values are None")
-    return ret
-
-
-def first_not_null_or_null(*values: _T | None) -> _T | None:
-    for value in values:
-        if value is not None:
-            return value
-    return None
-
-
-def getitem_nullable(seq: Iterable[_T], idx: int, cond: Callable[[_T], bool] | None = None) -> _T | None:
-    """
-    If `seq` has an item at position `idx`, return that item. Otherwise return
-    None. Similar to how QuerySet's first() & last() operate.
-
-    With `cond` set, it first filters `seq` for items where this function
-    evaluates as True, then tries to get item `idx` from the resulting list.
-
-    Example:
-
-    seq = [23, 43, 12, 56, 75, 1]
-    second_even = getitem_nullable(seq, 1, lambda item: item % 2 == 0)
-    # second_even == 56
-    seq = [1, 2, 3, 5, 7]
-    second_even = getitem_nullable(seq, 1, lambda item: item % 2 == 0)
-    # second_even == None
-    """
-    try:
-        if cond is None:
-            return list(seq)[idx]
-        return [item for item in seq if cond(item)][idx]
-    except IndexError:
-        return None
-
-
-@overload
-def getitem0(seq: Iterable[_T], cond: Callable[[_T], bool] | None, nullable: Literal[False]) -> _T: ...
-
-
-@overload
-def getitem0(seq: Iterable[_T], cond: Callable[[_T], bool] | None, nullable: Literal[True]) -> _T | None: ...
-
-
-def getitem0(seq, cond=None, nullable=False):
-    """
-    @raises IndexError
-    """
-    try:
-        if cond is None:
-            return list(seq)[0]
-        return [item for item in seq if cond(item)][0]
-    except IndexError as e:
-        if nullable:
-            return None
-        raise e
-
-
-def getitem0_nullable(seq: Iterable[_T], cond: Callable[[_T], bool] | None = None) -> _T | None:
-    return getitem0(seq, cond, True)
-
-
-def group_by(sequence: Sequence[_T], pred: Callable[[_T], Any]) -> dict[Any, list[_T]]:
-    """
-    Groups `sequence` by the result of `pred` on each item. Returns dict with
-    those results as keys and sublists of `sequence` as values.
-    """
-    result: dict[Any, list[_T]] = {}
-    for item in sequence:
-        key = pred(item)
-        if key not in result:
-            result[key] = [item]
-        else:
-            result[key].append(item)
-    return result
-
-
-def group_dicts(
-    dicts: Iterable[dict[str, _T]],
-    keys: list[str],
-    data_key: str = "data",
-) -> list[dict[str, _T | list[dict[str, _T]]]]:
-    """
-    In:
-        dicts = [
-            {"slug": "musikensmakt", "name": "Musikens Makt", "date": "2025-04-01", "count": 60},
-            {"slug": "musikensmakt", "name": "Musikens Makt", "date": "2025-04-02", "count": 64},
-            {"slug": "apanap", "name": "Apan Ap", "date": "2025-04-01", "count": 2},
-        ]
-        keys = ["slug", "name"]
-        data_key = "dätä"
-    Out: [
-        {
-            "slug": "musikensmakt",
-            "name": "Musikens Makt",
-            "dätä": [{"date": "2025-04-01", "count": 60}, {"date": "2025-04-02", "count": 64}],
-        },
-        {
-            "slug": "apanap",
-            "name": "Apan Ap",
-            "dätä": [{"date": "2025-04-01", "count": 2}],
-        },
-    ]
-    """
-    result: dict[tuple[_T, ...], list] = {}
-
-    for d in dicts:
-        dd = d.copy()
-        d_key = tuple(d[key] for key in keys)
-        if d_key not in result:
-            result[d_key] = []
-        for key in keys:
-            del dd[key]
-        result[d_key].append(dd)
-
-    return [{data_key: v, **{keys[i]: k[i] for i in range(len(keys))}} for k, v in result.items()]
-
-
-def index_of_first(sequence: Sequence[_T], pred: Callable[[_T], bool]) -> int:
-    """
-    Tries to return the index of the first item in `sequence` for which the
-    function `pred` returns True. If no such item is found, return -1.
-    """
-    try:
-        return sequence.index(next(filter(pred, sequence)))
-    except StopIteration:
-        return -1
-
-
-def int_to_string(value: int | None, locale: str, nbsp: bool = False) -> str:
-    """
-    Formats an integer with locale-specific thousand separators, which are at
-    least correct for Swedish and English locales. (Usage of the functions in
-    the built-in `locale` package requires you to run setlocale() multiple
-    times, which is not thread safe and may be resource heavy, so we don't do
-    that.)
-    """
-    if value is None:
-        return ""
-    if locale.lower().startswith("sv"):
-        separator = " "
-    else:
-        separator = ","
-    if separator == " " and nbsp:
-        separator = "&nbsp;"
-    # Neat line of code, huh? :)
-    # 1. Use absolute value to get rid of minus sign
-    # 2. Reverse str(value) in order to group characters from the end
-    # 3. Split it by groups of 3 digits
-    # 4. Remove empty values generated by re.split()
-    # 5. Re-reverse the digits in each group & join them with separator string
-    # 6. Re-reverse the order of the groups
-    # 7. Add minus sign if value was negative
-    return ("-" if value < 0 else "") + separator.join(
-        [v[::-1] for v in re.split(r"(\d{3})", str(abs(value))[::-1]) if v][::-1]
-    )
-
-
-def is_truthy(value: Any) -> bool:
-    """
-    Basically does `bool(value)`, except it also returns False for string
-    values "false", "no", and "0" (case insensitive).
-    """
-    if isinstance(value, str) and value.lower() in ("false", "no", "0"):
-        return False
-    return bool(value)
-
-
-def localize_float(
-    value: float,
-    grouping: bool = True,
-    min_decimals: int | None = None,
-    max_decimals: int | None = None,
-) -> str:
-    if max_decimals is None:
-        max_decimals = 15
-
-    if min_decimals is not None and min_decimals > max_decimals:
-        raise ValueError("min_decimals must be <= max_decimals")
-    if 15 < (min_decimals or 0) < 0:
-        raise ValueError("min_decimals must be >= 0 and <= 15")
-    if 15 < (max_decimals or 0) < 0:
-        raise ValueError("max_decimals must be >= 0 and <= 15")
-
-    decimal_separator = localeconv()["decimal_point"]
-    ret = format_string("%.*f", (max_decimals, value), grouping=grouping)
-
-    if decimal_separator in ret:
-        base, decimals = ret.split(decimal_separator)
-        decimals = decimals.rstrip("0").ljust(min_decimals or 0, "0")
-        if not decimals:
-            return base
-        return base + decimal_separator + decimals
-
-    return ret
-
-
-def most_common(values: Iterable[_HashableT]) -> tuple[_HashableT | None, int]:
-    """
-    Given a non-empty iterable, this will return a 2-tuple with the most
-    commonly occurring value in said iterable, and the number of such
-    occurances.
-
-    Given an _empty_ iterable, it will return `(None, 0)`.
-    """
-    occurrences: dict[_HashableT, int] = {}
-
-    for value in values:
-        if value not in occurrences:
-            occurrences[value] = 0
-        occurrences[value] += 1
-
-    if not occurrences:
-        return None, 0
-
-    return max(occurrences.items(), key=lambda tup: tup[1])
-
-
-def nonulls(items: Iterable[_T | None]) -> list[_T]:
-    """Just filters away None values from `items`."""
-    return [item for item in items if item is not None]
-
-
-def partition(items: Sequence[_T], length: int) -> Iterator[Sequence[_T]]:
-    """Simply splits `items` into subsequences of max `length` items."""
-    offset = 0
-    while offset == 0 or offset < len(items):
-        yield items[offset : offset + length]
-        offset += length
-
-
-def percent_rounded(part: int | float, whole: int | float) -> int:
-    if not whole:
-        return 0
-    return round(part / whole * 100)
-
-
-def roman(n: int):
-    if n % 1:
-        raise ValueError("roman(): fractions not allowed")
-    if n >= 4000 or n < 0:
-        raise ValueError("roman(): value must be >= 0 and < 4000")
-
-    m = {
-        1000: "M",
-        900: "CM",
-        500: "D",
-        400: "CD",
-        100: "C",
-        90: "XC",
-        50: "L",
-        40: "XL",
-        10: "X",
-        9: "IX",
-        5: "V",
-        4: "IV",
-        1: "I",
-    }
-    r = ""
-
-    for k, v in m.items():
-        while n >= k:
-            r += v
-            n -= k
-
-    return r
-
-
-def round_to_n(x: int | float, n: int) -> int | float:
-    """
-    Rounds x to n significant digits. If the result is a whole number, it is
-    cast to int, otherwise float is returned.
-    """
-    if x == 0:
-        return x
-    result = round(x, -int(floor(log10(abs(x)))) + (n - 1))
-    return int(result) if not result % 1 else result
-
-
-def round_up_timedelta(td: timedelta) -> timedelta:
-    """
-    If td > 30 min, round up to nearest hour. Otherwise, to nearest 10
-    minute mark. Could be extended for higher time units, but nevermind now.
-    """
-    td_minutes = td.total_seconds() / 60
-    if td_minutes > 30:
-        return timedelta(hours=ceil(td_minutes / 60))
-    if td_minutes >= 10:
-        return timedelta(minutes=int(td_minutes / 10) * 10 + 10)
-    return timedelta(minutes=10)
-
-
-def rounded_percentage(part: int | float, whole: int | float, digits=3) -> int | float:
-    """Percentage rounded to `digits` significant digits."""
-    return round_to_n((part / whole) * 100, digits) if whole != 0 else 0
-
-
-def strip_url_query(url: str) -> str:
-    """Just returns `url` stripped of any GET parameters."""
-    parts = urlsplit(url)
-    return urlunsplit((parts.scheme, parts.netloc, parts.path, "", parts.fragment))
-
-
-def to_int(value: Any, default: int | None = None) -> int | None:
-    """Like int() but returns a default value instead of raising exception."""
-    try:
-        return int(value)
-    except (ValueError, TypeError):
-        return default
-
-
-def zip_dicts(*dicts: dict) -> dict:
-    """
-    Combines dicts into one dict. On duplicate keys, dicts later in the
-    sequence have priority.
-    """
-    return {k: v for d in dicts for k, v in d.items()}
-
-
-def zip_dict_lists(dict_lists: Sequence[Sequence[dict]], strict: bool = False) -> Iterator[dict]:
-    """
-    Zips a list of dict lists and combines them into single dicts.
-    I.e. given dict_lists = [
-        [{a1: 1, a2: 2}, {b1: 3, b2: 4}],
-        [{a3: 5, a4: 6}, {b3: 7, b4: 8}],
-    ],
-    these dicts will be yielded:
-    {a1: 1, a2: 2, a3: 5, a4: 6}
-    {b1: 3, b2: 4, b3: 7, b4: 8}
-    """
-    for dicts in zip(*dict_lists, strict=strict):
-        yield zip_dicts(*dicts)