thds.core 1.43.20250721144545__py3-none-any.whl → 1.44.20250721231022__py3-none-any.whl

thds/core/__init__.py

@@ -13,6 +13,7 @@ from . import (  # noqa: F401
     exit_after,
     files,
     fretry,
+    futures,
     generators,
     git,
     hash_cache,

thds/core/futures.py

@@ -0,0 +1,227 @@
+import concurrent.futures
+import typing as ty
+from dataclasses import dataclass
+from functools import partial
+
+from typing_extensions import ParamSpec
+
+from . import lazy
+
+R = ty.TypeVar("R")
+
+
+class PFuture(ty.Protocol[R]):
+    """
+    A Protocol defining the behavior of a future-like object.
+
+    This defines an interface for an object that acts as a placeholder
+    for a result that will be available later. It is structurally
+    compatible with concurrent.futures.Future but omits cancellation.
+    """
+
+    def running(self) -> bool:
+        """Return True if the future is currently executing."""
+        ...
+
+    def done(self) -> bool:
+        """Return True if the future is done (finished)."""
+        ...
+
+    def result(self, timeout: ty.Optional[float] = None) -> R:
+        """Return the result of the work item.
+
+        If the work item raised an exception, this method raises the same exception.
+        If the timeout is reached, it raises TimeoutError.
+        Other exceptions (e.g. CancelledException) may also be raised depending on the
+        implementation.
+        """
+        ...
+
+    def exception(self, timeout: ty.Optional[float] = None) -> ty.Optional[BaseException]:
+        """
+        Return the exception raised by the work item.
+
+        Returns None if the work item completed without raising.
+        If the timeout is reached, it raises TimeoutError.
+        Other exceptions (e.g. CancelledException) may also be raised depending on the
+        implementation.
+        """
+        ...
+
+    def add_done_callback(self, fn: ty.Callable[["PFuture[R]"], None]) -> None:
+        """
+        Attaches a callable that will be called when the future is done.
+
+        The callable will be called with the future object as its only
+        argument.
+        """
+        ...
+
+    def set_result(self, result: R) -> None:
+        """Set the result of the future, marking it as done."""
+        ...
+
+    def set_exception(self, exception: BaseException) -> None:
+        """Set the exception of the future, marking it as done."""
+        ...
+
+
+class LazyFuture(PFuture[R]):
+    def __init__(self, mk_future: ty.Callable[[], PFuture[R]]) -> None:
+        """mk_future should generally be serializable.
+
+        It also needs to be repeatable - i.e. if it were resolved in two different
+        processes, it should return the same 'result' (value or exception) in both.
+        """
+        self._mk_future = mk_future
+        self._lazy_future = lazy.lazy(mk_future)
+
+    def __getstate__(self) -> dict[str, ty.Any]:
+        """Return the state of the LazyFuture for serialization."""
+        return {"_mk_future": self._mk_future}
+
+    def __setstate__(self, state: dict[str, ty.Any]) -> None:
+        """Restore the state of the LazyFuture from serialization."""
+        self._mk_future = state["_mk_future"]
+        self._lazy_future = lazy.lazy(self._mk_future)
+
+    def running(self) -> bool:
+        """Return True if the future is currently executing."""
+        return self._lazy_future().running()
+
+    def done(self) -> bool:
+        """Return True if the future is done (finished)."""
+        return self._lazy_future().done()
+
+    def result(self, timeout: ty.Optional[float] = None) -> R:
+        """
+        Return the result of the work item.
+
+        If the work item raised an exception, this method raises the same
+        exception. If the timeout is reached, it raises TimeoutError.
+        """
+        return self._lazy_future().result(timeout)
+
+    def exception(self, timeout: ty.Optional[float] = None) -> ty.Optional[BaseException]:
+        """
+        Return the exception raised by the work item.
+
+        Returns None if the work item completed without raising.
+        If the timeout is reached, it raises TimeoutError.
+        """
+        return self._lazy_future().exception(timeout)
+
+    def add_done_callback(self, fn: ty.Callable[["PFuture[R]"], None]) -> None:
+        """
+        Attaches a callable that will be called when the future is done.
+
+        The callable will be called with the future object as its only
+        argument.
+        """
+        self._lazy_future().add_done_callback(fn)
+
+    def set_result(self, result: R) -> None:
+        """Set the result of the future, marking it as done."""
+        self._lazy_future().set_result(result)
+
+    def set_exception(self, exception: BaseException) -> None:
+        """Set the exception of the future, marking it as done."""
+        self._lazy_future().set_exception(exception)
+
+
+P = ParamSpec("P")
+
+
+def make_lazy(mk_future: ty.Callable[P, PFuture[R]]) -> ty.Callable[P, LazyFuture[R]]:
+    """Create a LazyFuture that will lazily resolve the given callable."""
+
+    def mk_future_with_params(*args: P.args, **kwargs: P.kwargs) -> LazyFuture[R]:
+        return LazyFuture(partial(mk_future, *args, **kwargs))
+
+    return mk_future_with_params
+
+
+@dataclass(frozen=True)
+class ResolvedFuture(PFuture[R]):
+    _result: R
+    _done: bool = True
+
+    def running(self) -> bool:
+        return False
+
+    def done(self) -> bool:
+        return self._done
+
+    def result(self, timeout: ty.Optional[float] = None) -> R:
+        return self._result
+
+    def exception(self, timeout: ty.Optional[float] = None) -> ty.Optional[BaseException]:
+        return None
+
+    def add_done_callback(self, fn: ty.Callable[["PFuture[R]"], None]) -> None:
+        fn(self)
+
+    def set_result(self, result: R) -> None:
+        raise RuntimeError("Cannot set result on a resolved future.")
+
+    def set_exception(self, exception: BaseException) -> None:
+        raise RuntimeError("Cannot set exception on a resolved future.")
+
+
+def resolved(result: R) -> ResolvedFuture[R]:
+    return ResolvedFuture(result)
+
+
+# what's below doesn't absolutely have to exist here, as it adds a 'dependency' on
+# concurrent.futures... but practically speaking I think that's a pretty safe default
+# 'actual Future' type.
+
+R1 = ty.TypeVar("R1")
+
+
+def identity(x: R) -> R:
+    return x
+
+
+def translate_done(
+    out_future: PFuture[R1],
+    translate_result: ty.Callable[[R], R1],
+    done_fut: PFuture[R],
+) -> None:
+    try:
+        result = done_fut.result()
+        out_future.set_result(translate_result(result))
+    except Exception as e:
+        out_future.set_exception(e)
+
+
+OF_R1 = ty.TypeVar("OF_R1", bound=PFuture)
+
+
+def chain_futures(
+    inner_future: PFuture[R],
+    outer_future: OF_R1,
+    translate_future: ty.Callable[[R], R1],
+) -> OF_R1:
+    """Chain two futures together with a translator in the middle."""
+    outer_done_cb = partial(translate_done, outer_future, translate_future)
+    inner_future.add_done_callback(outer_done_cb)
+    return outer_future
+
+
+def reify_future(future: PFuture[R]) -> concurrent.futures.Future[R]:
+    """Reify a PFuture into a concurrent.futures.Future."""
+    if isinstance(future, concurrent.futures.Future):
+        return future
+    return chain_futures(future, concurrent.futures.Future[R](), identity)
+
+
+def as_completed(
+    futures: ty.Iterable[PFuture[R]],
+) -> ty.Iterator[concurrent.futures.Future[R]]:
+    """Return an iterator that yields futures as they complete.
+
+    We do need to actually create Future objects here, using the add_done_callback method
+    so that the these things actually work with concurrent.futures.as_completed.
+    """
+    yield from concurrent.futures.as_completed(map(reify_future, futures))

{thds_core-1.43.20250721144545.dist-info → thds_core-1.44.20250721231022.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thds.core
-Version: 1.43.20250721144545
+Version: 1.44.20250721231022
 Summary: Core utilities.
 Author-email: Trilliant Health <info@trillianthealth.com>
 License: MIT

{thds_core-1.43.20250721144545.dist-info → thds_core-1.44.20250721231022.dist-info}/RECORD

@@ -1,4 +1,4 @@
-thds/core/__init__.py,sha256=BUX2dBk_xTCX-E_jXnDiIK4jxY97iOxEmwC1oRRz7Z4,955
+thds/core/__init__.py,sha256=p5ZTz0yURvtiJlUspnI6aMb9nIekTkzU8sqr8HrnyiM,968
 thds/core/ansi_esc.py,sha256=QZ3CptZbX4N_hyP2IgqfTbNt9tBPaqy7ReTMQIzGbrc,870
 thds/core/cache.py,sha256=nL0oAyZrhPqyBBLevnOWSWVoEBrftaG3aE6Qq6tvmAA,7153
 thds/core/calgitver.py,sha256=6ioH5MGE65l_Dp924oD5CWrLyxKgmhtn46YwGxFpHfM,2497
@@ -14,6 +14,7 @@ thds/core/exit_after.py,sha256=0lz63nz2NTiIdyBDYyRa9bQShxQKe7eISy8VhXeW4HU,3485
 thds/core/files.py,sha256=NJlPXj7BejKd_Pa06MOywVv_YapT4bVedfsJHrWX8nI,4579
 thds/core/fp.py,sha256=S9hM7YmjbmaYbe4l5jSGnzf3HWhEaItmUOv6GMQpHo8,508
 thds/core/fretry.py,sha256=PKgOxCMjcF4zsFfXFvPXpomv5J6KU6llB1EaKukugig,6942
+thds/core/futures.py,sha256=JgqEP9TFC5UVr4tpfaVePHuI-pTsKAFHDWLxkE4aDb0,7372
 thds/core/generators.py,sha256=rcdFpPj0NMJWSaSZTnBfTeZxTTORNB633Lng-BW1284,1939
 thds/core/git.py,sha256=cfdN1oXyfz7k7T2XaseTqL6Ng53B9lfKtzDLmFjojRs,2947
 thds/core/hash_cache.py,sha256=jSFijG33UUQjVSkbuACdg4KzIBaf28i7hSQXCO49Qh0,4066
@@ -72,8 +73,8 @@ thds/core/sqlite/structured.py,sha256=SvZ67KcVcVdmpR52JSd52vMTW2ALUXmlHEeD-VrzWV
 thds/core/sqlite/types.py,sha256=oUkfoKRYNGDPZRk29s09rc9ha3SCk2SKr_K6WKebBFs,1308
 thds/core/sqlite/upsert.py,sha256=BmKK6fsGVedt43iY-Lp7dnAu8aJ1e9CYlPVEQR2pMj4,5827
 thds/core/sqlite/write.py,sha256=z0219vDkQDCnsV0WLvsj94keItr7H4j7Y_evbcoBrWU,3458
-thds_core-1.43.20250721144545.dist-info/METADATA,sha256=_RqGFrTodIEiPHVauPeVXFZY7NCHr0DpCmQppCb6F8A,2216
-thds_core-1.43.20250721144545.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-thds_core-1.43.20250721144545.dist-info/entry_points.txt,sha256=bOCOVhKZv7azF3FvaWX6uxE6yrjK6FcjqhtxXvLiFY8,161
-thds_core-1.43.20250721144545.dist-info/top_level.txt,sha256=LTZaE5SkWJwv9bwOlMbIhiS-JWQEEIcjVYnJrt-CriY,5
-thds_core-1.43.20250721144545.dist-info/RECORD,,
+thds_core-1.44.20250721231022.dist-info/METADATA,sha256=ZmyLepclldKh4i06UYo3vgJHgPUVHmlDW9vFpA0Simk,2216
+thds_core-1.44.20250721231022.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+thds_core-1.44.20250721231022.dist-info/entry_points.txt,sha256=bOCOVhKZv7azF3FvaWX6uxE6yrjK6FcjqhtxXvLiFY8,161
+thds_core-1.44.20250721231022.dist-info/top_level.txt,sha256=LTZaE5SkWJwv9bwOlMbIhiS-JWQEEIcjVYnJrt-CriY,5
+thds_core-1.44.20250721231022.dist-info/RECORD,,