kisstdlib 0.0.12__tar.gz → 0.0.14__tar.gz

{kisstdlib-0.0.12 → kisstdlib-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: kisstdlib
-Version: 0.0.12
+Version: 0.0.14
 Summary: System programming with conceptually and algebraically simple primitives.
 Author-email: Jan Malakhovski <oxij@oxij.org>
 Project-URL: Homepage, https://oxij.org/software/kisstdlib/
@@ -12,10 +12,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: License :: OSI Approved :: Python Software Foundation License
 Classifier: License :: OSI Approved :: BSD License
-Requires-Python: >=3.11
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: sortedcontainers==2.4.*
+Dynamic: license-file
 
 # Table of Contents
 <details><summary>(Click me to see it.)</summary>

kisstdlib-0.0.14/VERSION

@@ -0,0 +1 @@
+0.0.14

{kisstdlib-0.0.12 → kisstdlib-0.0.14}/kisstdlib/__init__.py

@@ -32,6 +32,7 @@ from .base import *
 from .failure import *
 from .string_ext import *
 from .itertools_ext import *
+from .collections_ext import *
 from .io.stdio import *
 from .logging_ext import *
 from .signal_ext import *
@@ -63,12 +64,12 @@ def setup_kisstdlib(
     return res
 
 
-def run_kisstdlib_main(
+def run_kisstdlib_main[**PS](
     setup_logging_result: tuple[LogCounter, ANSILogHandler],
-    func: _t.Callable[AParamSpec, None],
+    func: _t.Callable[PS, None],
     /,
-    *args: AParamSpec.args,
-    **kwargs: AParamSpec.kwargs,
+    *args: PS.args,
+    **kwargs: PS.kwargs,
 ) -> None:
     """Run given function with given arguments under `with no_signals()` block while
     properly handling all exceptions in `ExceptionGroup`s,

{kisstdlib-0.0.12 → kisstdlib-0.0.14}/kisstdlib/argparse_ext.py

@@ -343,15 +343,12 @@ class BetterArgumentParser(ArgumentParser):
         return res
 
 
-_AParamSpec = _t.ParamSpec("_AParamSpec")
-
-
-def make_argparser_and_run(
+def make_argparser_and_run[**PS](
     make_argparser: _t.Callable[[bool], BetterArgumentParser],
-    func: _t.Callable[_t.Concatenate[Namespace, _AParamSpec], None],
+    func: _t.Callable[_t.Concatenate[Namespace, PS], None],
     /,
-    *args: _AParamSpec.args,
-    **kwargs: _AParamSpec.kwargs,
+    *args: PS.args,
+    **kwargs: PS.kwargs,
 ) -> None:
     """Given `make_argparser` function that produces "real" and "fake"
     `BetterArgumentParser`s, run `parse_args` with on real one, but then, if

{kisstdlib-0.0.12 → kisstdlib-0.0.14}/kisstdlib/base.py

@@ -35,23 +35,9 @@ from functools import partial, partialmethod  # pylint: disable=unused-import
 
 ### Primitive types
 
-# Placeholders
-AType = _t.TypeVar("AType")
-BType = _t.TypeVar("BType")
-CType = _t.TypeVar("CType")
-DType = _t.TypeVar("DType")
-EType = _t.TypeVar("EType")
-AParamSpec = _t.ParamSpec("AParamSpec")
-BParamSpec = _t.ParamSpec("BParamSpec")
-
 # Bytes-like object
 BytesLike = bytes | bytearray | memoryview
 
-# Numbers
-Number = Decimal | float | int
-AnyNumber = _t.TypeVar("AnyNumber", bound=Number)
-
-
 ### Common constants
 
 # OS detection
@@ -60,16 +46,23 @@ WINDOWS = _os.name == "nt"
 
 # Time lengths, in seconds
 MINUTE = 60
-HOUR = 60 * MINUTE
-DAY = 24 * HOUR
-AVG_MONTH = 30 * DAY
-AVG_YEAR = 365 * DAY
+HOUR = 3600
+DAY = 86400
+WEEK = 604800
+
+# Common metric prefixes
+MILLI = Decimal((0, (1,), -3))
+MICRO = Decimal((0, (1,), -6))
+NANO = Decimal((0, (1,), -9))
 
 # Common byte sizes
-KiB = 1024
-MiB = 1024 * KiB
-GiB = 1024 * MiB
+KB = 1000
+MB = 1000000
+GB = 1000000000
 
+KiB = 1024
+MiB = 1048576
+GiB = 1073741824
 
 ### Placeholder values
 
@@ -104,8 +97,8 @@ MISSING = Missing()
 ### Structured unions
 
 
-class Maybe(_t.Generic[AType]):
-    """Similar to `Optional[AType]`, i.e. `AType | None`, but allows
+class Maybe[T]:
+    """Similar to `Optional[T]`, i.e. `T | None`, but allows
     arbitrary nesting.
 
     E.g. `Maybe[Maybe[int]]` does not get flattened into `Maybe[int]`.
@@ -113,117 +106,118 @@ class Maybe(_t.Generic[AType]):
 
 
 @_dc.dataclass(order=True)
-class Nothing(Maybe[AType], _t.Generic[AType]):
+class Nothing[T](Maybe[T]):
     pass
 
 
 @_dc.dataclass(order=True, slots=True)
-class Just(Maybe[AType], _t.Generic[AType]):
-    just: AType
+class Just[T](Maybe[T]):
+    just: T
 
 
-class Either(_t.Generic[AType, BType]):
-    """Either a value of `AType` or a value `BType`, without flattening.
+class Either[A, B]():
+    """Either a value of type `A` or a value of type `B`, without flattening.
 
     E.g., `Either[int, int]` is not just `int`.
     """
 
 
 @_dc.dataclass(order=True, slots=True)
-class Left(Either[AType, BType], _t.Generic[AType, BType]):
-    left: AType
+class Left[A, B](Either[A, B]):
+    left: A
 
 
 @_dc.dataclass(order=True, slots=True)
-class Right(Either[AType, BType], _t.Generic[AType, BType]):
-    right: BType
+class Right[A, B](Either[A, B]):
+    right: B
 
 
 ### Operations on Numbers
 
 
-def clamp(minv: AnyNumber, maxv: AnyNumber, v: AnyNumber) -> AnyNumber:
+class SupportsCmp(_t.Protocol):
+    # `__eq__` and `__ne__` belong to `object` and are always available
+    def __lt__(self, x: int | _t.Self) -> bool: ...
+    def __le__(self, x: int | _t.Self) -> bool: ...
+    def __gt__(self, x: int | _t.Self) -> bool: ...
+    def __ge__(self, x: int | _t.Self) -> bool: ...
+
+
+class SupportsCounting(SupportsCmp, _t.Protocol):
+    def __add__(self, x: int | _t.Self) -> _t.Self: ...
+    def __sub__(self, x: int | _t.Self) -> _t.Self: ...
+
+    # because this can be implemented using the above
+    # note that from the result, only `SupportsCmp` is required
+    def __abs__(self) -> SupportsCmp: ...
+
+
+def clamp[A: (int, float, Decimal)](minv: A, maxv: A, v: A) -> A:
     return min(maxv, max(minv, v))
 
 
-def is_infinite(x: Number) -> bool:
-    return hasattr(x, "is_infinite") and x.is_infinite() or isinstance(x, float) and _math.isinf(x)
+def is_infinite(x: _t.Any) -> bool:
+    return isinstance(x, float) and _math.isinf(x) or hasattr(x, "is_infinite") and x.is_infinite()
 
 
-def add_(x: Number, y: Number) -> Number:
-    """`x + y` that always works."""
-    if isinstance(x, float) and isinstance(y, Decimal):
-        return Decimal(x) + y
-    if isinstance(x, Decimal) and isinstance(y, float):
-        return x + Decimal(y)
-    return x + y  # type: ignore
+def is_closer[A: SupportsCounting](ideal: A, a: A, b: A) -> bool:
+    """Check whether `a` is closer to `ideal` than `b` is. That is, essentially, `abs(ideal - a) <
+    abs(ideal - b)`, but with infinite `ideal` cases handled properly.
+
+    Note that the above implies that this function always returns `False` when `a == b`.
+    """
+    if is_infinite(ideal):
+        if ideal < 0:
+            return a < b
+        return b < a
+    return abs(ideal - a) < abs(ideal - b)
 
 
-def sub_(x: Number, y: Number) -> Number:
-    """`x - y` that always works."""
-    if isinstance(x, float) and isinstance(y, Decimal):
-        return Decimal(x) - y
-    if isinstance(x, Decimal) and isinstance(y, float):
-        return x - Decimal(y)
-    return x - y  # type: ignore
+### Exception handling hooks
 
 
-def mul_(x: Number, y: Number) -> Number:
-    """`x * y` that always works."""
-    if isinstance(x, float) and isinstance(y, Decimal):
-        return Decimal(x) * y
-    if isinstance(x, Decimal) and isinstance(y, float):
-        return x * Decimal(y)
-    return x * y  # type: ignore
+def raise_one(exc: Exception, /, *_args: _t.Any, **_kwargs: _t.Any) -> _t.NoReturn:
+    """Raise the given `Exception`."""
+    raise exc
 
 
-def truediv_(x: Number, y: Number) -> Number:
-    """`x / y` that always works."""
-    if isinstance(x, float) and isinstance(y, Decimal):
-        return Decimal(x) / y
-    if isinstance(x, Decimal) and isinstance(y, float):
-        return x / Decimal(y)
-    return x / y  # type: ignore
+def raise_all(excs: list[Exception], /, *_args: _t.Any, **_kwargs: _t.Any) -> _t.NoReturn:
+    """Raise give exceptions as a trivial `ExceptionGroup`."""
+    raise ExceptionGroup("multiple failures", excs)
 
 
 ### Simple functions
 
 
-def identity(x: AType, /) -> AType:
-    """Identity function."""
-    return x
+def noop(*_args: _t.Any, **_kwargs: _t.Any) -> None:
+    """A noop, with a bunch of ignored arguments."""
 
 
-def identity_(x: AType, /, *_args: _t.Any, **_kwargs: _t.Any) -> AType:
+def identity[T](x: T, /, *_args: _t.Any, **_kwargs: _t.Any) -> T:
     """Identity function, with a bunch of ignored arguments."""
     return x
 
 
-def const(x: AType, /) -> _t.Callable[[BType], AType]:
-    """Return a function that always returns `a`."""
-    return lambda y: x
+def const[A, B, **PS](x: A, /) -> _t.Callable[_t.Concatenate[B, PS], A]:
+    """Return a function that always returns `a`, with a bunch of ignored arguments."""
 
-
-def const_(x: AType, /) -> _t.Callable[_t.Concatenate[BType, BParamSpec], AType]:
-    """Return a function that always returns `a`, and has a bunch of ignored arguments."""
-
-    def sub(_y: BType, /, *_args: BParamSpec.args, **_kwargs: BParamSpec.kwargs) -> AType:
+    def sub(_y: B, /, *_args: PS.args, **_kwargs: PS.kwargs) -> A:
         return x
 
     return sub
 
 
-def fst(x: tuple[AType, BType]) -> AType:
+def fst[A, B](x: tuple[A, B]) -> A:
     """Get the first element of a given 2-elemnt tuple."""
     return x[0]
 
 
-def snd(x: tuple[AType, BType]) -> BType:
+def snd[A, B](x: tuple[A, B]) -> B:
     """Get the second element of a given 2-elemnt tuple."""
     return x[1]
 
 
-def first_def(*args: AType | None) -> AType:
+def first_def[A](*args: A | None) -> A:
     """Return first argument that is not `None`."""
     for e in args:
         if e is not None:
@@ -231,7 +225,7 @@ def first_def(*args: AType | None) -> AType:
     raise IndexError("no matching elements")
 
 
-def first_ok(*args: AType) -> AType:
+def first_ok[A](*args: A) -> A:
     """Return first `True`-like argument."""
     for e in args:
         if e:
@@ -239,19 +233,17 @@ def first_ok(*args: AType) -> AType:
     raise IndexError("no matching elements")
 
 
-def optional(b: BType, f: _t.Callable[[AType], BType], x: AType | None) -> BType:
+def optional[A, B](b: B, f: _t.Callable[[A], B], x: A | None) -> B:
     """`f(x) if x is not None else b`."""
     return f(x) if x is not None else b
 
 
-def maybe(b: BType, f: _t.Callable[[AType], BType], x: Maybe[AType]) -> BType:
+def maybe[A, B](b: B, f: _t.Callable[[A], B], x: Maybe[A]) -> B:
     """`f(x.just) if x is Just else b`."""
     return f(x.just) if isinstance(x, Just) else b
 
 
-def either(
-    fa: _t.Callable[[AType], CType], fb: _t.Callable[[BType], CType], x: Either[AType, BType]
-) -> CType:
+def either[A, B, C](fa: _t.Callable[[A], C], fb: _t.Callable[[B], C], x: Either[A, B]) -> C:
     """`fa(x.left) if x is Left`, `fb(x.right) if x is Right`, `AssertionError` otherwise."""
     if isinstance(x, Left):
         return fa(x.left)
@@ -263,22 +255,22 @@ def either(
 ### Injectors into `list`
 
 
-def singleton(x: AType) -> list[AType]:
+def singleton[A](x: A) -> list[A]:
     """`[x]`."""
     return [x]
 
 
-def optlist(p: bool, x: AType) -> list[AType]:
+def optlist[A](p: bool, x: A) -> list[A]:
     """`[x] if p else []`."""
     return [x] if p else []
 
 
-def optslist(p: bool, xs: list[AType]) -> list[AType]:
+def optslist[A](p: bool, xs: list[A]) -> list[A]:
     """`xs if p else []`."""
     return xs if p else []
 
 
-def optional2list(x: AType | None) -> list[AType]:
+def optional2list[A](x: A | None) -> list[A]:
     """`[x] if x is not None else []`."""
     return [x] if x is not None else []
 
@@ -286,63 +278,81 @@ def optional2list(x: AType | None) -> list[AType]:
 ### Functors, i.e. applying functions to elements contained in structures
 
 
-def map_optional(f: _t.Callable[[AType], BType], x: AType | None) -> BType | None:
+def map_optional[A, B](f: _t.Callable[[A], B], x: A | None) -> B | None:
     """`f(x) if x is not None else x`."""
     return f(x) if x is not None else x
 
 
-def map_optional2list(f: _t.Callable[[AType], list[BType]], x: AType | None) -> list[BType]:
+def map_optional2list[A, B](f: _t.Callable[[A], list[B]], x: A | None) -> list[B]:
     """`f(x) if x is not None else []`."""
     return f(x) if x is not None else []
 
 
-def map_maybe(f: _t.Callable[[AType], BType], x: Maybe[AType]) -> Maybe[BType]:
+def map_maybe[A, B](f: _t.Callable[[A], B], x: Maybe[A]) -> Maybe[B]:
     """`Just(f(x.just)) if x is Just else x`."""
-    return Just(f(x.just)) if isinstance(x, Just) else _t.cast(Maybe[BType], x)
+    return Just(f(x.just)) if isinstance(x, Just) else _t.cast(Maybe[B], x)
 
 
-def map_maybe2list(f: _t.Callable[[AType], list[BType]], x: Maybe[AType]) -> list[BType]:
+def map_maybe2list[A, B](f: _t.Callable[[A], list[B]], x: Maybe[A]) -> list[B]:
     """`f(x.just) if x is Just else []`."""
     return f(x.just) if isinstance(x, Just) else []
 
 
-def map_left(f: _t.Callable[[AType], CType], x: Either[AType, BType]) -> Either[CType, BType]:
+def map_left[A, B, C](f: _t.Callable[[A], C], x: Either[A, B]) -> Either[C, B]:
     """`Right(f(x.left)) if x is Left else x`."""
-    return Left(f(x.left)) if isinstance(x, Left) else _t.cast(Either[CType, BType], x)
+    return Left(f(x.left)) if isinstance(x, Left) else _t.cast(Either[C, B], x)
 
 
-def map_right(f: _t.Callable[[BType], CType], x: Either[AType, BType]) -> Either[AType, CType]:
+def map_right[A, B, C](f: _t.Callable[[B], C], x: Either[A, B]) -> Either[A, C]:
     """`Right(f(x.right)) if x is Right else x`."""
-    return Right(f(x.right)) if isinstance(x, Right) else _t.cast(Either[AType, CType], x)
+    return Right(f(x.right)) if isinstance(x, Right) else _t.cast(Either[A, C], x)
 
 
 ### Function composition
 
 
-def compose(
-    f: _t.Callable[[BType], CType], g: _t.Callable[[AType], BType]
-) -> _t.Callable[[AType], CType]:
-    return lambda x: f(g(x))
+def compose[A, B, C, **PS](
+    f: _t.Callable[[B], C], g: _t.Callable[_t.Concatenate[A, PS], B]
+) -> _t.Callable[_t.Concatenate[A, PS], C]:
+    """Compose two functions `f` and `g` while passing all the additional `PS` arguments to `g`."""
 
+    def sub(x: A, /, *args: PS.args, **kwargs: PS.kwargs) -> C:
+        return f(g(x, *args, **kwargs))
 
-def compose_pipe(
-    pipe: list[_t.Callable[_t.Concatenate[AType, AParamSpec], AType]], /
-) -> _t.Callable[_t.Concatenate[AType, AParamSpec], AType]:
-    """Compose a list of functions, similarly to how a shell pipe ("|")
-    exression does it. I.e. compose them in reverse order.
+    return sub
 
-    The mutating value gets passed as the first argument, all other
-    arguments get passed unchanged.
 
-    `compose_pipe([])` is `identity_`.
+def compose_wide[A, B, C, **PS](
+    f: _t.Callable[_t.Concatenate[B, PS], C], g: _t.Callable[_t.Concatenate[A, PS], B]
+) -> _t.Callable[_t.Concatenate[A, PS], C]:
+    """Compose two functions `f` and `g` while passing all the additional `PS` arguments to both `f`
+    and `g`.
+    """
+
+    def sub(x: A, /, *args: PS.args, **kwargs: PS.kwargs) -> C:
+        return f(g(x, *args, **kwargs), *args, **kwargs)
+
+    return sub
+
+
+def compose_pipe[A, **PS](
+    pipe: list[_t.Callable[_t.Concatenate[A, PS], A]], /
+) -> _t.Callable[_t.Concatenate[A, PS], A]:
+    """Compose a list of functions, similarly to how a shell pipe ("|") exression does it. I.e.
+    compose them in reverse order.
+
+    The mutating value gets passed as the first argument, all other arguments get passed unchanged
+    like with `compose_wide`.
+
+    `compose_pipe([])` is `identity`.
     `compose_pipe([x])` is `x`.
     """
     if len(pipe) == 0:
-        return identity_
+        return identity
     if len(pipe) == 1:
         return pipe[0]
 
-    def sub(x: AType, /, *args: AParamSpec.args, **kwargs: AParamSpec.kwargs) -> AType:
+    def sub(x: A, /, *args: PS.args, **kwargs: PS.kwargs) -> A:
         for func in pipe:
             x = func(x, *args, **kwargs)
         return x
@@ -374,17 +384,14 @@ def get_traceback(exc: BaseException, /, lines: int = 128) -> str:
     return fobj.getvalue()
 
 
-_BaseExeceptionType = _t.TypeVar("_BaseExeceptionType", bound=BaseException)
-
-
-def flat_exceptions(
-    es: BaseExceptionGroup[_BaseExeceptionType], /
-) -> _t.Iterator[_BaseExeceptionType]:
+def flat_exceptions[ExceptionType: BaseException](
+    es: BaseExceptionGroup[ExceptionType], /
+) -> _t.Iterator[ExceptionType]:
     """For simplifying some `try ... except*` expressions."""
 
     def sub(
-        excs: _BaseExeceptionType | BaseExceptionGroup[_BaseExeceptionType],
-    ) -> _t.Iterator[_BaseExeceptionType]:
+        excs: ExceptionType | BaseExceptionGroup[ExceptionType],
+    ) -> _t.Iterator[ExceptionType]:
         if isinstance(excs, BaseExceptionGroup):
             for e in excs.exceptions:
                 yield from sub(e)